diff options
Diffstat (limited to 'upstream/archlinux/man1/perlfaq8.1perl')
| -rw-r--r-- | upstream/archlinux/man1/perlfaq8.1perl | 1579 |
1 files changed, 1579 insertions, 0 deletions
diff --git a/upstream/archlinux/man1/perlfaq8.1perl b/upstream/archlinux/man1/perlfaq8.1perl new file mode 100644 index 00000000..cd4c4e27 --- /dev/null +++ b/upstream/archlinux/man1/perlfaq8.1perl @@ -0,0 +1,1579 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "PERLFAQ8 1perl" +.TH PERLFAQ8 1perl 2024-02-11 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +perlfaq8 \- System Interaction +.SH VERSION +.IX Header "VERSION" +version 5.20210520 +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This section of the Perl FAQ covers questions involving operating +system interaction. Topics include interprocess communication (IPC), +control over the user-interface (keyboard, screen and pointing +devices), and most anything else not related to data manipulation. +.PP +Read the FAQs and documentation specific to the port of perl to your +operating system (eg, perlvms, perlplan9, ...). These should +contain more detailed information on the vagaries of your perl. +.SS "How do I find out which operating system I'm running under?" +.IX Subsection "How do I find out which operating system I'm running under?" +The \f(CW$^O\fR variable (\f(CW$OSNAME\fR if you use \f(CW\*(C`English\*(C'\fR) contains an +indication of the name of the operating system (not its release +number) that your perl binary was built for. +.SS "How come \fBexec()\fP doesn't return?" +.IX Xref "exec system fork open pipe" +.IX Subsection "How come exec() doesn't return?" +(contributed by brian d foy) +.PP +The \f(CW\*(C`exec\*(C'\fR function's job is to turn your process into another +command and never to return. If that's not what you want to do, don't +use \f(CW\*(C`exec\*(C'\fR. :) +.PP +If you want to run an external command and still keep your Perl process +going, look at a piped \f(CW\*(C`open\*(C'\fR, \f(CW\*(C`fork\*(C'\fR, or \f(CW\*(C`system\*(C'\fR. +.SS "How do I do fancy stuff with the keyboard/screen/mouse?" +.IX Subsection "How do I do fancy stuff with the keyboard/screen/mouse?" +How you access/control keyboards, screens, and pointing devices +("mice") is system-dependent. Try the following modules: +.IP Keyboard 4 +.IX Item "Keyboard" +.Vb 5 +\& Term::Cap Standard perl distribution +\& Term::ReadKey CPAN +\& Term::ReadLine::Gnu CPAN +\& Term::ReadLine::Perl CPAN +\& Term::Screen CPAN +.Ve +.IP Screen 4 +.IX Item "Screen" +.Vb 3 +\& Term::Cap Standard perl distribution +\& Curses CPAN +\& Term::ANSIColor CPAN +.Ve +.IP Mouse 4 +.IX Item "Mouse" +.Vb 4 +\& Tk CPAN +\& Wx CPAN +\& Gtk2 CPAN +\& Qt4 kdebindings4 package +.Ve +.PP +Some of these specific cases are shown as examples in other answers +in this section of the perlfaq. +.SS "How do I print something out in color?" +.IX Subsection "How do I print something out in color?" +In general, you don't, because you don't know whether +the recipient has a color-aware display device. If you +know that they have an ANSI terminal that understands +color, you can use the Term::ANSIColor module from CPAN: +.PP +.Vb 3 +\& use Term::ANSIColor; +\& print color("red"), "Stop!\en", color("reset"); +\& print color("green"), "Go!\en", color("reset"); +.Ve +.PP +Or like this: +.PP +.Vb 3 +\& use Term::ANSIColor qw(:constants); +\& print RED, "Stop!\en", RESET; +\& print GREEN, "Go!\en", RESET; +.Ve +.SS "How do I read just one key without waiting for a return key?" +.IX Subsection "How do I read just one key without waiting for a return key?" +Controlling input buffering is a remarkably system-dependent matter. +On many systems, you can just use the \fBstty\fR command as shown in +"getc" in perlfunc, but as you see, that's already getting you into +portability snags. +.PP +.Vb 6 +\& open(TTY, "+</dev/tty") or die "no tty: $!"; +\& system "stty cbreak </dev/tty >/dev/tty 2>&1"; +\& $key = getc(TTY); # perhaps this works +\& # OR ELSE +\& sysread(TTY, $key, 1); # probably this does +\& system "stty \-cbreak </dev/tty >/dev/tty 2>&1"; +.Ve +.PP +The Term::ReadKey module from CPAN offers an easy-to-use interface that +should be more efficient than shelling out to \fBstty\fR for each key. +It even includes limited support for Windows. +.PP +.Vb 4 +\& use Term::ReadKey; +\& ReadMode(\*(Aqcbreak\*(Aq); +\& $key = ReadKey(0); +\& ReadMode(\*(Aqnormal\*(Aq); +.Ve +.PP +However, using the code requires that you have a working C compiler +and can use it to build and install a CPAN module. Here's a solution +using the standard POSIX module, which is already on your system +(assuming your system supports POSIX). +.PP +.Vb 2 +\& use HotKey; +\& $key = readkey(); +.Ve +.PP +And here's the \f(CW\*(C`HotKey\*(C'\fR module, which hides the somewhat mystifying calls +to manipulate the POSIX termios structures. +.PP +.Vb 2 +\& # HotKey.pm +\& package HotKey; +\& +\& use strict; +\& use warnings; +\& +\& use parent \*(AqExporter\*(Aq; +\& our @EXPORT = qw(cbreak cooked readkey); +\& +\& use POSIX qw(:termios_h); +\& my ($term, $oterm, $echo, $noecho, $fd_stdin); +\& +\& $fd_stdin = fileno(STDIN); +\& $term = POSIX::Termios\->new(); +\& $term\->getattr($fd_stdin); +\& $oterm = $term\->getlflag(); +\& +\& $echo = ECHO | ECHOK | ICANON; +\& $noecho = $oterm & ~$echo; +\& +\& sub cbreak { +\& $term\->setlflag($noecho); # ok, so i don\*(Aqt want echo either +\& $term\->setcc(VTIME, 1); +\& $term\->setattr($fd_stdin, TCSANOW); +\& } +\& +\& sub cooked { +\& $term\->setlflag($oterm); +\& $term\->setcc(VTIME, 0); +\& $term\->setattr($fd_stdin, TCSANOW); +\& } +\& +\& sub readkey { +\& my $key = \*(Aq\*(Aq; +\& cbreak(); +\& sysread(STDIN, $key, 1); +\& cooked(); +\& return $key; +\& } +\& +\& END { cooked() } +\& +\& 1; +.Ve +.SS "How do I check whether input is ready on the keyboard?" +.IX Subsection "How do I check whether input is ready on the keyboard?" +The easiest way to do this is to read a key in nonblocking mode with the +Term::ReadKey module from CPAN, passing it an argument of \-1 to indicate +not to block: +.PP +.Vb 1 +\& use Term::ReadKey; +\& +\& ReadMode(\*(Aqcbreak\*(Aq); +\& +\& if (defined (my $char = ReadKey(\-1)) ) { +\& # input was waiting and it was $char +\& } else { +\& # no input was waiting +\& } +\& +\& ReadMode(\*(Aqnormal\*(Aq); # restore normal tty settings +.Ve +.SS "How do I clear the screen?" +.IX Subsection "How do I clear the screen?" +(contributed by brian d foy) +.PP +To clear the screen, you just have to print the special sequence +that tells the terminal to clear the screen. Once you have that +sequence, output it when you want to clear the screen. +.PP +You can use the Term::ANSIScreen module to get the special +sequence. Import the \f(CW\*(C`cls\*(C'\fR function (or the \f(CW\*(C`:screen\*(C'\fR tag): +.PP +.Vb 2 +\& use Term::ANSIScreen qw(cls); +\& my $clear_screen = cls(); +\& +\& print $clear_screen; +.Ve +.PP +The Term::Cap module can also get the special sequence if you want +to deal with the low-level details of terminal control. The \f(CW\*(C`Tputs\*(C'\fR +method returns the string for the given capability: +.PP +.Vb 1 +\& use Term::Cap; +\& +\& my $terminal = Term::Cap\->Tgetent( { OSPEED => 9600 } ); +\& my $clear_screen = $terminal\->Tputs(\*(Aqcl\*(Aq); +\& +\& print $clear_screen; +.Ve +.PP +On Windows, you can use the Win32::Console module. After creating +an object for the output filehandle you want to affect, call the +\&\f(CW\*(C`Cls\*(C'\fR method: +.PP +.Vb 1 +\& Win32::Console; +\& +\& my $OUT = Win32::Console\->new(STD_OUTPUT_HANDLE); +\& my $clear_string = $OUT\->Cls; +\& +\& print $clear_screen; +.Ve +.PP +If you have a command-line program that does the job, you can call +it in backticks to capture whatever it outputs so you can use it +later: +.PP +.Vb 1 +\& my $clear_string = \`clear\`; +\& +\& print $clear_string; +.Ve +.SS "How do I get the screen size?" +.IX Subsection "How do I get the screen size?" +If you have Term::ReadKey module installed from CPAN, +you can use it to fetch the width and height in characters +and in pixels: +.PP +.Vb 2 +\& use Term::ReadKey; +\& my ($wchar, $hchar, $wpixels, $hpixels) = GetTerminalSize(); +.Ve +.PP +This is more portable than the raw \f(CW\*(C`ioctl\*(C'\fR, but not as +illustrative: +.PP +.Vb 10 +\& require \*(Aq./sys/ioctl.ph\*(Aq; +\& die "no TIOCGWINSZ " unless defined &TIOCGWINSZ; +\& open(my $tty_fh, "+</dev/tty") or die "No tty: $!"; +\& unless (ioctl($tty_fh, &TIOCGWINSZ, $winsize=\*(Aq\*(Aq)) { +\& die sprintf "$0: ioctl TIOCGWINSZ (%08x: $!)\en", &TIOCGWINSZ; +\& } +\& my ($row, $col, $xpixel, $ypixel) = unpack(\*(AqS4\*(Aq, $winsize); +\& print "(row,col) = ($row,$col)"; +\& print " (xpixel,ypixel) = ($xpixel,$ypixel)" if $xpixel || $ypixel; +\& print "\en"; +.Ve +.SS "How do I ask the user for a password?" +.IX Subsection "How do I ask the user for a password?" +(This question has nothing to do with the web. See a different +FAQ for that.) +.PP +There's an example of this in "crypt" in perlfunc. First, you put the +terminal into "no echo" mode, then just read the password normally. +You may do this with an old-style \f(CWioctl()\fR function, POSIX terminal +control (see POSIX or its documentation the Camel Book), or a call +to the \fBstty\fR program, with varying degrees of portability. +.PP +You can also do this for most systems using the Term::ReadKey module +from CPAN, which is easier to use and in theory more portable. +.PP +.Vb 1 +\& use Term::ReadKey; +\& +\& ReadMode(\*(Aqnoecho\*(Aq); +\& my $password = ReadLine(0); +.Ve +.SS "How do I read and write the serial port?" +.IX Subsection "How do I read and write the serial port?" +This depends on which operating system your program is running on. In +the case of Unix, the serial ports will be accessible through files in +\&\f(CW\*(C`/dev\*(C'\fR; on other systems, device names will doubtless differ. +Several problem areas common to all device interaction are the +following: +.IP lockfiles 4 +.IX Item "lockfiles" +Your system may use lockfiles to control multiple access. Make sure +you follow the correct protocol. Unpredictable behavior can result +from multiple processes reading from one device. +.IP "open mode" 4 +.IX Item "open mode" +If you expect to use both read and write operations on the device, +you'll have to open it for update (see "open" in perlfunc for +details). You may wish to open it without running the risk of +blocking by using \f(CWsysopen()\fR and \f(CW\*(C`O_RDWR|O_NDELAY|O_NOCTTY\*(C'\fR from the +Fcntl module (part of the standard perl distribution). See +"sysopen" in perlfunc for more on this approach. +.IP "end of line" 4 +.IX Item "end of line" +Some devices will be expecting a "\er" at the end of each line rather +than a "\en". In some ports of perl, "\er" and "\en" are different from +their usual (Unix) ASCII values of "\e015" and "\e012". You may have to +give the numeric values you want directly, using octal ("\e015"), hex +("0x0D"), or as a control-character specification ("\ecM"). +.Sp +.Vb 2 +\& print DEV "atv1\e012"; # wrong, for some devices +\& print DEV "atv1\e015"; # right, for some devices +.Ve +.Sp +Even though with normal text files a "\en" will do the trick, there is +still no unified scheme for terminating a line that is portable +between Unix, DOS/Win, and Macintosh, except to terminate \fIALL\fR line +ends with "\e015\e012", and strip what you don't need from the output. +This applies especially to socket I/O and autoflushing, discussed +next. +.IP "flushing output" 4 +.IX Item "flushing output" +If you expect characters to get to your device when you \f(CWprint()\fR them, +you'll want to autoflush that filehandle. You can use \f(CWselect()\fR +and the \f(CW$|\fR variable to control autoflushing (see "$|" in perlvar +and "select" in perlfunc, or perlfaq5, "How do I flush/unbuffer an +output filehandle? Why must I do this?"): +.Sp +.Vb 3 +\& my $old_handle = select($dev_fh); +\& $| = 1; +\& select($old_handle); +.Ve +.Sp +You'll also see code that does this without a temporary variable, as in +.Sp +.Vb 1 +\& select((select($deb_handle), $| = 1)[0]); +.Ve +.Sp +Or if you don't mind pulling in a few thousand lines +of code just because you're afraid of a little \f(CW$|\fR variable: +.Sp +.Vb 2 +\& use IO::Handle; +\& $dev_fh\->autoflush(1); +.Ve +.Sp +As mentioned in the previous item, this still doesn't work when using +socket I/O between Unix and Macintosh. You'll need to hard code your +line terminators, in that case. +.IP "non-blocking input" 4 +.IX Item "non-blocking input" +If you are doing a blocking \f(CWread()\fR or \f(CWsysread()\fR, you'll have to +arrange for an alarm handler to provide a timeout (see +"alarm" in perlfunc). If you have a non-blocking open, you'll likely +have a non-blocking read, which means you may have to use a 4\-arg +\&\f(CWselect()\fR to determine whether I/O is ready on that device (see +"select" in perlfunc. +.PP +While trying to read from his caller-id box, the notorious Jamie +Zawinski \f(CW\*(C`<jwz@netscape.com>\*(C'\fR, after much gnashing of teeth and +fighting with \f(CW\*(C`sysread\*(C'\fR, \f(CW\*(C`sysopen\*(C'\fR, POSIX's \f(CW\*(C`tcgetattr\*(C'\fR business, +and various other functions that go bump in the night, finally came up +with this: +.PP +.Vb 10 +\& sub open_modem { +\& use IPC::Open2; +\& my $stty = \`/bin/stty \-g\`; +\& open2( \e*MODEM_IN, \e*MODEM_OUT, "cu \-l$modem_device \-s2400 2>&1"); +\& # starting cu hoses /dev/tty\*(Aqs stty settings, even when it has +\& # been opened on a pipe... +\& system("/bin/stty $stty"); +\& $_ = <MODEM_IN>; +\& chomp; +\& if ( !m/^Connected/ ) { +\& print STDERR "$0: cu printed \`$_\*(Aq instead of \`Connected\*(Aq\en"; +\& } +\& } +.Ve +.SS "How do I decode encrypted password files?" +.IX Subsection "How do I decode encrypted password files?" +You spend lots and lots of money on dedicated hardware, but this is +bound to get you talked about. +.PP +Seriously, you can't if they are Unix password files\-\-the Unix +password system employs one-way encryption. It's more like hashing +than encryption. The best you can do is check whether something else +hashes to the same string. You can't turn a hash back into the +original string. Programs like Crack can forcibly (and intelligently) +try to guess passwords, but don't (can't) guarantee quick success. +.PP +If you're worried about users selecting bad passwords, you should +proactively check when they try to change their password (by modifying +\&\fBpasswd\fR\|(1), for example). +.SS "How do I start a process in the background?" +.IX Subsection "How do I start a process in the background?" +(contributed by brian d foy) +.PP +There's not a single way to run code in the background so you don't +have to wait for it to finish before your program moves on to other +tasks. Process management depends on your particular operating system, +and many of the techniques are covered in perlipc. +.PP +Several CPAN modules may be able to help, including IPC::Open2 or +IPC::Open3, IPC::Run, Parallel::Jobs, +Parallel::ForkManager, POE, Proc::Background, and +Win32::Process. There are many other modules you might use, so +check those namespaces for other options too. +.PP +If you are on a Unix-like system, you might be able to get away with a +system call where you put an \f(CW\*(C`&\*(C'\fR on the end of the command: +.PP +.Vb 1 +\& system("cmd &") +.Ve +.PP +You can also try using \f(CW\*(C`fork\*(C'\fR, as described in perlfunc (although +this is the same thing that many of the modules will do for you). +.IP "STDIN, STDOUT, and STDERR are shared" 4 +.IX Item "STDIN, STDOUT, and STDERR are shared" +Both the main process and the backgrounded one (the "child" process) +share the same STDIN, STDOUT and STDERR filehandles. If both try to +access them at once, strange things can happen. You may want to close +or reopen these for the child. You can get around this with +\&\f(CW\*(C`open\*(C'\fRing a pipe (see "open" in perlfunc) but on some systems this +means that the child process cannot outlive the parent. +.IP Signals 4 +.IX Item "Signals" +You'll have to catch the SIGCHLD signal, and possibly SIGPIPE too. +SIGCHLD is sent when the backgrounded process finishes. SIGPIPE is +sent when you write to a filehandle whose child process has closed (an +untrapped SIGPIPE can cause your program to silently die). This is +not an issue with \f(CWsystem("cmd&")\fR. +.IP Zombies 4 +.IX Item "Zombies" +You have to be prepared to "reap" the child process when it finishes. +.Sp +.Vb 1 +\& $SIG{CHLD} = sub { wait }; +\& +\& $SIG{CHLD} = \*(AqIGNORE\*(Aq; +.Ve +.Sp +You can also use a double fork. You immediately \f(CWwait()\fR for your +first child, and the init daemon will \f(CWwait()\fR for your grandchild once +it exits. +.Sp +.Vb 8 +\& unless ($pid = fork) { +\& unless (fork) { +\& exec "what you really wanna do"; +\& die "exec failed!"; +\& } +\& exit 0; +\& } +\& waitpid($pid, 0); +.Ve +.Sp +See "Signals" in perlipc for other examples of code to do this. +Zombies are not an issue with \f(CW\*(C`system("prog &")\*(C'\fR. +.SS "How do I trap control characters/signals?" +.IX Subsection "How do I trap control characters/signals?" +You don't actually "trap" a control character. Instead, that character +generates a signal which is sent to your terminal's currently +foregrounded process group, which you then trap in your process. +Signals are documented in "Signals" in perlipc and the +section on "Signals" in the Camel. +.PP +You can set the values of the \f(CW%SIG\fR hash to be the functions you want +to handle the signal. After perl catches the signal, it looks in \f(CW%SIG\fR +for a key with the same name as the signal, then calls the subroutine +value for that key. +.PP +.Vb 1 +\& # as an anonymous subroutine +\& +\& $SIG{INT} = sub { syswrite(STDERR, "ouch\en", 5 ) }; +\& +\& # or a reference to a function +\& +\& $SIG{INT} = \e&ouch; +\& +\& # or the name of the function as a string +\& +\& $SIG{INT} = "ouch"; +.Ve +.PP +Perl versions before 5.8 had in its C source code signal handlers which +would catch the signal and possibly run a Perl function that you had set +in \f(CW%SIG\fR. This violated the rules of signal handling at that level +causing perl to dump core. Since version 5.8.0, perl looks at \f(CW%SIG\fR +\&\fBafter\fR the signal has been caught, rather than while it is being caught. +Previous versions of this answer were incorrect. +.SS "How do I modify the shadow password file on a Unix system?" +.IX Subsection "How do I modify the shadow password file on a Unix system?" +If perl was installed correctly and your shadow library was written +properly, the \f(CW\*(C`getpw*()\*(C'\fR functions described in perlfunc should in +theory provide (read-only) access to entries in the shadow password +file. To change the file, make a new shadow password file (the format +varies from system to system\-\-see \fBpasswd\fR\|(1) for specifics) and use +\&\f(CWpwd_mkdb(8)\fR to install it (see \fBpwd_mkdb\fR\|(8) for more details). +.SS "How do I set the time and date?" +.IX Subsection "How do I set the time and date?" +Assuming you're running under sufficient permissions, you should be +able to set the system-wide date and time by running the \f(CWdate(1)\fR +program. (There is no way to set the time and date on a per-process +basis.) This mechanism will work for Unix, MS-DOS, Windows, and NT; +the VMS equivalent is \f(CW\*(C`set time\*(C'\fR. +.PP +However, if all you want to do is change your time zone, you can +probably get away with setting an environment variable: +.PP +.Vb 3 +\& $ENV{TZ} = "MST7MDT"; # Unixish +\& $ENV{\*(AqSYS$TIMEZONE_DIFFERENTIAL\*(Aq}="\-5" # vms +\& system(\*(Aqtrn\*(Aq, \*(Aqcomp.lang.perl.misc\*(Aq); +.Ve +.SS "How can I \fBsleep()\fP or \fBalarm()\fP for under a second?" +.IX Xref "Time::HiRes BSD::Itimer sleep select" +.IX Subsection "How can I sleep() or alarm() for under a second?" +If you want finer granularity than the 1 second that the \f(CWsleep()\fR +function provides, the easiest way is to use the \f(CWselect()\fR function as +documented in "select" in perlfunc. Try the Time::HiRes and +the BSD::Itimer modules (available from CPAN, and starting from +Perl 5.8 Time::HiRes is part of the standard distribution). +.SS "How can I measure time under a second?" +.IX Xref "Time::HiRes BSD::Itimer sleep select" +.IX Subsection "How can I measure time under a second?" +(contributed by brian d foy) +.PP +The Time::HiRes module (part of the standard distribution as of +Perl 5.8) measures time with the \f(CWgettimeofday()\fR system call, which +returns the time in microseconds since the epoch. If you can't install +Time::HiRes for older Perls and you are on a Unixish system, you +may be able to call \f(CWgettimeofday(2)\fR directly. See +"syscall" in perlfunc. +.SS "How can I do an \fBatexit()\fP or \fBsetjmp()\fP/\fBlongjmp()\fP? (Exception handling)" +.IX Subsection "How can I do an atexit() or setjmp()/longjmp()? (Exception handling)" +You can use the \f(CW\*(C`END\*(C'\fR block to simulate \f(CWatexit()\fR. Each package's +\&\f(CW\*(C`END\*(C'\fR block is called when the program or thread ends. See the perlmod +manpage for more details about \f(CW\*(C`END\*(C'\fR blocks. +.PP +For example, you can use this to make sure your filter program managed +to finish its output without filling up the disk: +.PP +.Vb 3 +\& END { +\& close(STDOUT) || die "stdout close failed: $!"; +\& } +.Ve +.PP +The \f(CW\*(C`END\*(C'\fR block isn't called when untrapped signals kill the program, +though, so if you use \f(CW\*(C`END\*(C'\fR blocks you should also use +.PP +.Vb 1 +\& use sigtrap qw(die normal\-signals); +.Ve +.PP +Perl's exception-handling mechanism is its \f(CWeval()\fR operator. You +can use \f(CWeval()\fR as \f(CW\*(C`setjmp\*(C'\fR and \f(CWdie()\fR as \f(CW\*(C`longjmp\*(C'\fR. For +details of this, see the section on signals, especially the time-out +handler for a blocking \f(CWflock()\fR in "Signals" in perlipc or the +section on "Signals" in \fIProgramming Perl\fR. +.PP +If exception handling is all you're interested in, use one of the +many CPAN modules that handle exceptions, such as Try::Tiny. +.PP +If you want the \f(CWatexit()\fR syntax (and an \f(CWrmexit()\fR as well), try the +\&\f(CW\*(C`AtExit\*(C'\fR module available from CPAN. +.SS "Why doesn't my sockets program work under System V (Solaris)? What does the error message ""Protocol not supported"" mean?" +.IX Subsection "Why doesn't my sockets program work under System V (Solaris)? What does the error message ""Protocol not supported"" mean?" +Some Sys-V based systems, notably Solaris 2.X, redefined some of the +standard socket constants. Since these were constant across all +architectures, they were often hardwired into perl code. The proper +way to deal with this is to "use Socket" to get the correct values. +.PP +Note that even though SunOS and Solaris are binary compatible, these +values are different. Go figure. +.SS "How can I call my system's unique C functions from Perl?" +.IX Subsection "How can I call my system's unique C functions from Perl?" +In most cases, you write an external module to do it\-\-see the answer +to "Where can I learn about linking C with Perl? [h2xs, xsubpp]". +However, if the function is a system call, and your system supports +\&\f(CWsyscall()\fR, you can use the \f(CW\*(C`syscall\*(C'\fR function (documented in +perlfunc). +.PP +Remember to check the modules that came with your distribution, and +CPAN as well\-\-someone may already have written a module to do it. On +Windows, try Win32::API. On Macs, try Mac::Carbon. If no module +has an interface to the C function, you can inline a bit of C in your +Perl source with Inline::C. +.SS "Where do I get the include files to do \fBioctl()\fP or \fBsyscall()\fP?" +.IX Subsection "Where do I get the include files to do ioctl() or syscall()?" +Historically, these would be generated by the h2ph tool, part of the +standard perl distribution. This program converts \f(CWcpp(1)\fR directives +in C header files to files containing subroutine definitions, like +\&\f(CWSYS_getitimer()\fR, which you can use as arguments to your functions. +It doesn't work perfectly, but it usually gets most of the job done. +Simple files like \fIerrno.h\fR, \fIsyscall.h\fR, and \fIsocket.h\fR were fine, +but the hard ones like \fIioctl.h\fR nearly always need to be hand-edited. +Here's how to install the *.ph files: +.PP +.Vb 3 +\& 1. Become the super\-user +\& 2. cd /usr/include +\& 3. h2ph *.h */*.h +.Ve +.PP +If your system supports dynamic loading, for reasons of portability and +sanity you probably ought to use h2xs (also part of the standard perl +distribution). This tool converts C header files to Perl extensions. +See perlxstut for how to get started with h2xs. +.PP +If your system doesn't support dynamic loading, you still probably +ought to use h2xs. See perlxstut and ExtUtils::MakeMaker for +more information (in brief, just use \fBmake perl\fR instead of a plain +\&\fBmake\fR to rebuild perl with a new static extension). +.SS "Why do setuid perl scripts complain about kernel problems?" +.IX Subsection "Why do setuid perl scripts complain about kernel problems?" +Some operating systems have bugs in the kernel that make setuid +scripts inherently insecure. Perl gives you a number of options +(described in perlsec) to work around such systems. +.SS "How can I open a pipe both to and from a command?" +.IX Subsection "How can I open a pipe both to and from a command?" +The IPC::Open2 module (part of the standard perl distribution) is +an easy-to-use approach that internally uses \f(CWpipe()\fR, \f(CWfork()\fR, and +\&\f(CWexec()\fR to do the job. Make sure you read the deadlock warnings in +its documentation, though (see IPC::Open2). See +"Bidirectional Communication with Another Process" in perlipc and +"Bidirectional Communication with Yourself" in perlipc +.PP +You may also use the IPC::Open3 module (part of the standard perl +distribution), but be warned that it has a different order of +arguments from IPC::Open2 (see IPC::Open3). +.SS "Why can't I get the output of a command with \fBsystem()\fP?" +.IX Subsection "Why can't I get the output of a command with system()?" +You're confusing the purpose of \f(CWsystem()\fR and backticks (``). \f(CWsystem()\fR +runs a command and returns exit status information (as a 16 bit value: +the low 7 bits are the signal the process died from, if any, and +the high 8 bits are the actual exit value). Backticks (``) run a +command and return what it sent to STDOUT. +.PP +.Vb 2 +\& my $exit_status = system("mail\-users"); +\& my $output_string = \`ls\`; +.Ve +.SS "How can I capture STDERR from an external command?" +.IX Subsection "How can I capture STDERR from an external command?" +There are three basic ways of running external commands: +.PP +.Vb 3 +\& system $cmd; # using system() +\& my $output = \`$cmd\`; # using backticks (\`\`) +\& open (my $pipe_fh, "$cmd |"); # using open() +.Ve +.PP +With \f(CWsystem()\fR, both STDOUT and STDERR will go the same place as the +script's STDOUT and STDERR, unless the \f(CWsystem()\fR command redirects them. +Backticks and \f(CWopen()\fR read \fBonly\fR the STDOUT of your command. +.PP +You can also use the \f(CWopen3()\fR function from IPC::Open3. Benjamin +Goldberg provides some sample code: +.PP +To capture a program's STDOUT, but discard its STDERR: +.PP +.Vb 7 +\& use IPC::Open3; +\& use File::Spec; +\& my $in = \*(Aq\*(Aq; +\& open(NULL, ">", File::Spec\->devnull); +\& my $pid = open3($in, \e*PH, ">&NULL", "cmd"); +\& while( <PH> ) { } +\& waitpid($pid, 0); +.Ve +.PP +To capture a program's STDERR, but discard its STDOUT: +.PP +.Vb 7 +\& use IPC::Open3; +\& use File::Spec; +\& my $in = \*(Aq\*(Aq; +\& open(NULL, ">", File::Spec\->devnull); +\& my $pid = open3($in, ">&NULL", \e*PH, "cmd"); +\& while( <PH> ) { } +\& waitpid($pid, 0); +.Ve +.PP +To capture a program's STDERR, and let its STDOUT go to our own STDERR: +.PP +.Vb 5 +\& use IPC::Open3; +\& my $in = \*(Aq\*(Aq; +\& my $pid = open3($in, ">&STDERR", \e*PH, "cmd"); +\& while( <PH> ) { } +\& waitpid($pid, 0); +.Ve +.PP +To read both a command's STDOUT and its STDERR separately, you can +redirect them to temp files, let the command run, then read the temp +files: +.PP +.Vb 10 +\& use IPC::Open3; +\& use IO::File; +\& my $in = \*(Aq\*(Aq; +\& local *CATCHOUT = IO::File\->new_tmpfile; +\& local *CATCHERR = IO::File\->new_tmpfile; +\& my $pid = open3($in, ">&CATCHOUT", ">&CATCHERR", "cmd"); +\& waitpid($pid, 0); +\& seek $_, 0, 0 for \e*CATCHOUT, \e*CATCHERR; +\& while( <CATCHOUT> ) {} +\& while( <CATCHERR> ) {} +.Ve +.PP +But there's no real need for \fBboth\fR to be tempfiles... the following +should work just as well, without deadlocking: +.PP +.Vb 9 +\& use IPC::Open3; +\& my $in = \*(Aq\*(Aq; +\& use IO::File; +\& local *CATCHERR = IO::File\->new_tmpfile; +\& my $pid = open3($in, \e*CATCHOUT, ">&CATCHERR", "cmd"); +\& while( <CATCHOUT> ) {} +\& waitpid($pid, 0); +\& seek CATCHERR, 0, 0; +\& while( <CATCHERR> ) {} +.Ve +.PP +And it'll be faster, too, since we can begin processing the program's +stdout immediately, rather than waiting for the program to finish. +.PP +With any of these, you can change file descriptors before the call: +.PP +.Vb 2 +\& open(STDOUT, ">logfile"); +\& system("ls"); +.Ve +.PP +or you can use Bourne shell file-descriptor redirection: +.PP +.Vb 2 +\& $output = \`$cmd 2>some_file\`; +\& open (PIPE, "cmd 2>some_file |"); +.Ve +.PP +You can also use file-descriptor redirection to make STDERR a +duplicate of STDOUT: +.PP +.Vb 2 +\& $output = \`$cmd 2>&1\`; +\& open (PIPE, "cmd 2>&1 |"); +.Ve +.PP +Note that you \fIcannot\fR simply open STDERR to be a dup of STDOUT +in your Perl program and avoid calling the shell to do the redirection. +This doesn't work: +.PP +.Vb 2 +\& open(STDERR, ">&STDOUT"); +\& $alloutput = \`cmd args\`; # stderr still escapes +.Ve +.PP +This fails because the \f(CWopen()\fR makes STDERR go to where STDOUT was +going at the time of the \f(CWopen()\fR. The backticks then make STDOUT go to +a string, but don't change STDERR (which still goes to the old +STDOUT). +.PP +Note that you \fImust\fR use Bourne shell (\f(CWsh(1)\fR) redirection syntax in +backticks, not \f(CWcsh(1)\fR! Details on why Perl's \f(CWsystem()\fR and backtick +and pipe opens all use the Bourne shell are in the +\&\fIversus/csh.whynot\fR article in the "Far More Than You Ever Wanted To +Know" collection in <http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz> . To +capture a command's STDERR and STDOUT together: +.PP +.Vb 3 +\& $output = \`cmd 2>&1\`; # either with backticks +\& $pid = open(PH, "cmd 2>&1 |"); # or with an open pipe +\& while (<PH>) { } # plus a read +.Ve +.PP +To capture a command's STDOUT but discard its STDERR: +.PP +.Vb 3 +\& $output = \`cmd 2>/dev/null\`; # either with backticks +\& $pid = open(PH, "cmd 2>/dev/null |"); # or with an open pipe +\& while (<PH>) { } # plus a read +.Ve +.PP +To capture a command's STDERR but discard its STDOUT: +.PP +.Vb 3 +\& $output = \`cmd 2>&1 1>/dev/null\`; # either with backticks +\& $pid = open(PH, "cmd 2>&1 1>/dev/null |"); # or with an open pipe +\& while (<PH>) { } # plus a read +.Ve +.PP +To exchange a command's STDOUT and STDERR in order to capture the STDERR +but leave its STDOUT to come out our old STDERR: +.PP +.Vb 3 +\& $output = \`cmd 3>&1 1>&2 2>&3 3>&\-\`; # either with backticks +\& $pid = open(PH, "cmd 3>&1 1>&2 2>&3 3>&\-|");# or with an open pipe +\& while (<PH>) { } # plus a read +.Ve +.PP +To read both a command's STDOUT and its STDERR separately, it's easiest +to redirect them separately to files, and then read from those files +when the program is done: +.PP +.Vb 1 +\& system("program args 1>program.stdout 2>program.stderr"); +.Ve +.PP +Ordering is important in all these examples. That's because the shell +processes file descriptor redirections in strictly left to right order. +.PP +.Vb 2 +\& system("prog args 1>tmpfile 2>&1"); +\& system("prog args 2>&1 1>tmpfile"); +.Ve +.PP +The first command sends both standard out and standard error to the +temporary file. The second command sends only the old standard output +there, and the old standard error shows up on the old standard out. +.SS "Why doesn't \fBopen()\fP return an error when a pipe open fails?" +.IX Subsection "Why doesn't open() return an error when a pipe open fails?" +If the second argument to a piped \f(CWopen()\fR contains shell +metacharacters, perl \f(CWfork()\fRs, then \f(CWexec()\fRs a shell to decode the +metacharacters and eventually run the desired program. If the program +couldn't be run, it's the shell that gets the message, not Perl. All +your Perl program can find out is whether the shell itself could be +successfully started. You can still capture the shell's STDERR and +check it for error messages. See "How can I capture STDERR from an +external command?" elsewhere in this document, or use the +IPC::Open3 module. +.PP +If there are no shell metacharacters in the argument of \f(CWopen()\fR, Perl +runs the command directly, without using the shell, and can correctly +report whether the command started. +.SS "What's wrong with using backticks in a void context?" +.IX Subsection "What's wrong with using backticks in a void context?" +Strictly speaking, nothing. Stylistically speaking, it's not a good +way to write maintainable code. Perl has several operators for +running external commands. Backticks are one; they collect the output +from the command for use in your program. The \f(CW\*(C`system\*(C'\fR function is +another; it doesn't do this. +.PP +Writing backticks in your program sends a clear message to the readers +of your code that you wanted to collect the output of the command. +Why send a clear message that isn't true? +.PP +Consider this line: +.PP +.Vb 1 +\& \`cat /etc/termcap\`; +.Ve +.PP +You forgot to check \f(CW$?\fR to see whether the program even ran +correctly. Even if you wrote +.PP +.Vb 1 +\& print \`cat /etc/termcap\`; +.Ve +.PP +this code could and probably should be written as +.PP +.Vb 2 +\& system("cat /etc/termcap") == 0 +\& or die "cat program failed!"; +.Ve +.PP +which will echo the cat command's output as it is generated, instead +of waiting until the program has completed to print it out. It also +checks the return value. +.PP +\&\f(CW\*(C`system\*(C'\fR also provides direct control over whether shell wildcard +processing may take place, whereas backticks do not. +.SS "How can I call backticks without shell processing?" +.IX Subsection "How can I call backticks without shell processing?" +This is a bit tricky. You can't simply write the command +like this: +.PP +.Vb 1 +\& @ok = \`grep @opts \*(Aq$search_string\*(Aq @filenames\`; +.Ve +.PP +As of Perl 5.8.0, you can use \f(CWopen()\fR with multiple arguments. +Just like the list forms of \f(CWsystem()\fR and \f(CWexec()\fR, no shell +escapes happen. +.PP +.Vb 3 +\& open( GREP, "\-|", \*(Aqgrep\*(Aq, @opts, $search_string, @filenames ); +\& chomp(@ok = <GREP>); +\& close GREP; +.Ve +.PP +You can also: +.PP +.Vb 10 +\& my @ok = (); +\& if (open(GREP, "\-|")) { +\& while (<GREP>) { +\& chomp; +\& push(@ok, $_); +\& } +\& close GREP; +\& } else { +\& exec \*(Aqgrep\*(Aq, @opts, $search_string, @filenames; +\& } +.Ve +.PP +Just as with \f(CWsystem()\fR, no shell escapes happen when you \f(CWexec()\fR a +list. Further examples of this can be found in "Safe Pipe +Opens" in perlipc. +.PP +Note that if you're using Windows, no solution to this vexing issue is +even possible. Even though Perl emulates \f(CWfork()\fR, you'll still be +stuck, because Windows does not have an argc/argv\-style API. +.SS "Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)?" +.IX Subsection "Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)?" +This happens only if your perl is compiled to use stdio instead of +perlio, which is the default. Some (maybe all?) stdios set error and +eof flags that you may need to clear. The POSIX module defines +\&\f(CWclearerr()\fR that you can use. That is the technically correct way to +do it. Here are some less reliable workarounds: +.IP 1. 4 +Try keeping around the seekpointer and go there, like this: +.Sp +.Vb 2 +\& my $where = tell($log_fh); +\& seek($log_fh, $where, 0); +.Ve +.IP 2. 4 +If that doesn't work, try seeking to a different part of the file and +then back. +.IP 3. 4 +If that doesn't work, try seeking to a different part of +the file, reading something, and then seeking back. +.IP 4. 4 +If that doesn't work, give up on your stdio package and use sysread. +.SS "How can I convert my shell script to perl?" +.IX Subsection "How can I convert my shell script to perl?" +Learn Perl and rewrite it. Seriously, there's no simple converter. +Things that are awkward to do in the shell are easy to do in Perl, and +this very awkwardness is what would make a shell\->perl converter +nigh-on impossible to write. By rewriting it, you'll think about what +you're really trying to do, and hopefully will escape the shell's +pipeline datastream paradigm, which while convenient for some matters, +causes many inefficiencies. +.SS "Can I use perl to run a telnet or ftp session?" +.IX Subsection "Can I use perl to run a telnet or ftp session?" +Try the Net::FTP, TCP::Client, and Net::Telnet modules +(available from CPAN). +<http://www.cpan.org/scripts/netstuff/telnet.emul.shar> will also help +for emulating the telnet protocol, but Net::Telnet is quite +probably easier to use. +.PP +If all you want to do is pretend to be telnet but don't need +the initial telnet handshaking, then the standard dual-process +approach will suffice: +.PP +.Vb 12 +\& use IO::Socket; # new in 5.004 +\& my $handle = IO::Socket::INET\->new(\*(Aqwww.perl.com:80\*(Aq) +\& or die "can\*(Aqt connect to port 80 on www.perl.com $!"; +\& $handle\->autoflush(1); +\& if (fork()) { # XXX: undef means failure +\& select($handle); +\& print while <STDIN>; # everything from stdin to socket +\& } else { +\& print while <$handle>; # everything from socket to stdout +\& } +\& close $handle; +\& exit; +.Ve +.SS "How can I write expect in Perl?" +.IX Subsection "How can I write expect in Perl?" +Once upon a time, there was a library called \fIchat2.pl\fR (part of the +standard perl distribution), which never really got finished. If you +find it somewhere, \fIdon't use it\fR. These days, your best bet is to +look at the Expect module available from CPAN, which also requires two +other modules from CPAN, IO::Pty and IO::Stty. +.SS "Is there a way to hide perl's command line from programs such as ""ps""?" +.IX Subsection "Is there a way to hide perl's command line from programs such as ""ps""?" +First of all note that if you're doing this for security reasons (to +avoid people seeing passwords, for example) then you should rewrite +your program so that critical information is never given as an +argument. Hiding the arguments won't make your program completely +secure. +.PP +To actually alter the visible command line, you can assign to the +variable \f(CW$0\fR as documented in perlvar. This won't work on all +operating systems, though. Daemon programs like sendmail place their +state there, as in: +.PP +.Vb 1 +\& $0 = "orcus [accepting connections]"; +.Ve +.SS "I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible?" +.IX Subsection "I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible?" +.IP Unix 4 +.IX Item "Unix" +In the strictest sense, it can't be done\-\-the script executes as a +different process from the shell it was started from. Changes to a +process are not reflected in its parent\-\-only in any children +created after the change. There is shell magic that may allow you to +fake it by \f(CWeval()\fRing the script's output in your shell; check out the +comp.unix.questions FAQ for details. +.SS "How do I close a process's filehandle without waiting for it to complete?" +.IX Subsection "How do I close a process's filehandle without waiting for it to complete?" +Assuming your system supports such things, just send an appropriate signal +to the process (see "kill" in perlfunc). It's common to first send a TERM +signal, wait a little bit, and then send a KILL signal to finish it off. +.SS "How do I fork a daemon process?" +.IX Subsection "How do I fork a daemon process?" +If by daemon process you mean one that's detached (disassociated from +its tty), then the following process is reported to work on most +Unixish systems. Non-Unix users should check their Your_OS::Process +module for other solutions. +.IP \(bu 4 +Open /dev/tty and use the TIOCNOTTY ioctl on it. See \fBtty\fR\|(1) +for details. Or better yet, you can just use the \f(CWPOSIX::setsid()\fR +function, so you don't have to worry about process groups. +.IP \(bu 4 +Change directory to / +.IP \(bu 4 +Reopen STDIN, STDOUT, and STDERR so they're not connected to the old +tty. +.IP \(bu 4 +Background yourself like this: +.Sp +.Vb 1 +\& fork && exit; +.Ve +.PP +The Proc::Daemon module, available from CPAN, provides a function to +perform these actions for you. +.SS "How do I find out if I'm running interactively or not?" +.IX Subsection "How do I find out if I'm running interactively or not?" +(contributed by brian d foy) +.PP +This is a difficult question to answer, and the best answer is +only a guess. +.PP +What do you really want to know? If you merely want to know if one of +your filehandles is connected to a terminal, you can try the \f(CW\*(C`\-t\*(C'\fR +file test: +.PP +.Vb 3 +\& if( \-t STDOUT ) { +\& print "I\*(Aqm connected to a terminal!\en"; +\& } +.Ve +.PP +However, you might be out of luck if you expect that means there is a +real person on the other side. With the Expect module, another +program can pretend to be a person. The program might even come close +to passing the Turing test. +.PP +The IO::Interactive module does the best it can to give you an +answer. Its \f(CW\*(C`is_interactive\*(C'\fR function returns an output filehandle; +that filehandle points to standard output if the module thinks the +session is interactive. Otherwise, the filehandle is a null handle +that simply discards the output: +.PP +.Vb 1 +\& use IO::Interactive; +\& +\& print { is_interactive } "I might go to standard output!\en"; +.Ve +.PP +This still doesn't guarantee that a real person is answering your +prompts or reading your output. +.PP +If you want to know how to handle automated testing for your +distribution, you can check the environment. The CPAN +Testers, for instance, set the value of \f(CW\*(C`AUTOMATED_TESTING\*(C'\fR: +.PP +.Vb 3 +\& unless( $ENV{AUTOMATED_TESTING} ) { +\& print "Hello interactive tester!\en"; +\& } +.Ve +.SS "How do I timeout a slow event?" +.IX Subsection "How do I timeout a slow event?" +Use the \f(CWalarm()\fR function, probably in conjunction with a signal +handler, as documented in "Signals" in perlipc and the section on +"Signals" in the Camel. You may instead use the more flexible +Sys::AlarmCall module available from CPAN. +.PP +The \f(CWalarm()\fR function is not implemented on all versions of Windows. +Check the documentation for your specific version of Perl. +.SS "How do I set CPU limits?" +.IX Xref "BSD::Resource limit CPU" +.IX Subsection "How do I set CPU limits?" +(contributed by Xho) +.PP +Use the BSD::Resource module from CPAN. As an example: +.PP +.Vb 2 +\& use BSD::Resource; +\& setrlimit(RLIMIT_CPU,10,20) or die $!; +.Ve +.PP +This sets the soft and hard limits to 10 and 20 seconds, respectively. +After 10 seconds of time spent running on the CPU (not "wall" time), +the process will be sent a signal (XCPU on some systems) which, if not +trapped, will cause the process to terminate. If that signal is +trapped, then after 10 more seconds (20 seconds in total) the process +will be killed with a non-trappable signal. +.PP +See the BSD::Resource and your systems documentation for the gory +details. +.SS "How do I avoid zombies on a Unix system?" +.IX Subsection "How do I avoid zombies on a Unix system?" +Use the reaper code from "Signals" in perlipc to call \f(CWwait()\fR when a +SIGCHLD is received, or else use the double-fork technique described +in "How do I start a process in the background?" in perlfaq8. +.SS "How do I use an SQL database?" +.IX Subsection "How do I use an SQL database?" +The DBI module provides an abstract interface to most database +servers and types, including Oracle, DB2, Sybase, mysql, Postgresql, +ODBC, and flat files. The DBI module accesses each database type +through a database driver, or DBD. You can see a complete list of +available drivers on CPAN: <http://www.cpan.org/modules/by\-module/DBD/> . +You can read more about DBI on <http://dbi.perl.org/> . +.PP +Other modules provide more specific access: Win32::ODBC, Alzabo, +\&\f(CW\*(C`iodbc\*(C'\fR, and others found on CPAN Search: <https://metacpan.org/> . +.SS "How do I make a \fBsystem()\fP exit on control-C?" +.IX Subsection "How do I make a system() exit on control-C?" +You can't. You need to imitate the \f(CWsystem()\fR call (see perlipc for +sample code) and then have a signal handler for the INT signal that +passes the signal on to the subprocess. Or you can check for it: +.PP +.Vb 2 +\& $rc = system($cmd); +\& if ($rc & 127) { die "signal death" } +.Ve +.SS "How do I open a file without blocking?" +.IX Subsection "How do I open a file without blocking?" +If you're lucky enough to be using a system that supports +non-blocking reads (most Unixish systems do), you need only to use the +\&\f(CW\*(C`O_NDELAY\*(C'\fR or \f(CW\*(C`O_NONBLOCK\*(C'\fR flag from the \f(CW\*(C`Fcntl\*(C'\fR module in conjunction with +\&\f(CWsysopen()\fR: +.PP +.Vb 3 +\& use Fcntl; +\& sysopen(my $fh, "/foo/somefile", O_WRONLY|O_NDELAY|O_CREAT, 0644) +\& or die "can\*(Aqt open /foo/somefile: $!": +.Ve +.SS "How do I tell the difference between errors from the shell and perl?" +.IX Subsection "How do I tell the difference between errors from the shell and perl?" +(answer contributed by brian d foy) +.PP +When you run a Perl script, something else is running the script for you, +and that something else may output error messages. The script might +emit its own warnings and error messages. Most of the time you cannot +tell who said what. +.PP +You probably cannot fix the thing that runs perl, but you can change how +perl outputs its warnings by defining a custom warning and die functions. +.PP +Consider this script, which has an error you may not notice immediately. +.PP +.Vb 1 +\& #!/usr/locl/bin/perl +\& +\& print "Hello World\en"; +.Ve +.PP +I get an error when I run this from my shell (which happens to be +bash). That may look like perl forgot it has a \f(CWprint()\fR function, +but my shebang line is not the path to perl, so the shell runs the +script, and I get the error. +.PP +.Vb 2 +\& $ ./test +\& ./test: line 3: print: command not found +.Ve +.PP +A quick and dirty fix involves a little bit of code, but this may be all +you need to figure out the problem. +.PP +.Vb 1 +\& #!/usr/bin/perl \-w +\& +\& BEGIN { +\& $SIG{_\|_WARN_\|_} = sub{ print STDERR "Perl: ", @_; }; +\& $SIG{_\|_DIE_\|_} = sub{ print STDERR "Perl: ", @_; exit 1}; +\& } +\& +\& $a = 1 + undef; +\& $x / 0; +\& _\|_END_\|_ +.Ve +.PP +The perl message comes out with "Perl" in front. The \f(CW\*(C`BEGIN\*(C'\fR block +works at compile time so all of the compilation errors and warnings +get the "Perl:" prefix too. +.PP +.Vb 7 +\& Perl: Useless use of division (/) in void context at ./test line 9. +\& Perl: Name "main::a" used only once: possible typo at ./test line 8. +\& Perl: Name "main::x" used only once: possible typo at ./test line 9. +\& Perl: Use of uninitialized value in addition (+) at ./test line 8. +\& Perl: Use of uninitialized value in division (/) at ./test line 9. +\& Perl: Illegal division by zero at ./test line 9. +\& Perl: Illegal division by zero at \-e line 3. +.Ve +.PP +If I don't see that "Perl:", it's not from perl. +.PP +You could also just know all the perl errors, and although there are +some people who may know all of them, you probably don't. However, they +all should be in the perldiag manpage. If you don't find the error in +there, it probably isn't a perl error. +.PP +Looking up every message is not the easiest way, so let perl to do it +for you. Use the diagnostics pragma with turns perl's normal messages +into longer discussions on the topic. +.PP +.Vb 1 +\& use diagnostics; +.Ve +.PP +If you don't get a paragraph or two of expanded discussion, it +might not be perl's message. +.SS "How do I install a module from CPAN?" +.IX Subsection "How do I install a module from CPAN?" +(contributed by brian d foy) +.PP +The easiest way is to have a module also named CPAN do it for you by using +the \f(CW\*(C`cpan\*(C'\fR command that comes with Perl. You can give it a list of modules +to install: +.PP +.Vb 1 +\& $ cpan IO::Interactive Getopt::Whatever +.Ve +.PP +If you prefer \f(CW\*(C`CPANPLUS\*(C'\fR, it's just as easy: +.PP +.Vb 1 +\& $ cpanp i IO::Interactive Getopt::Whatever +.Ve +.PP +If you want to install a distribution from the current directory, you can +tell \f(CW\*(C`CPAN.pm\*(C'\fR to install \f(CW\*(C`.\*(C'\fR (the full stop): +.PP +.Vb 1 +\& $ cpan . +.Ve +.PP +See the documentation for either of those commands to see what else +you can do. +.PP +If you want to try to install a distribution by yourself, resolving +all dependencies on your own, you follow one of two possible build +paths. +.PP +For distributions that use \fIMakefile.PL\fR: +.PP +.Vb 2 +\& $ perl Makefile.PL +\& $ make test install +.Ve +.PP +For distributions that use \fIBuild.PL\fR: +.PP +.Vb 3 +\& $ perl Build.PL +\& $ ./Build test +\& $ ./Build install +.Ve +.PP +Some distributions may need to link to libraries or other third-party +code and their build and installation sequences may be more complicated. +Check any \fIREADME\fR or \fIINSTALL\fR files that you may find. +.SS "What's the difference between require and use?" +.IX Subsection "What's the difference between require and use?" +(contributed by brian d foy) +.PP +Perl runs \f(CW\*(C`require\*(C'\fR statement at run-time. Once Perl loads, compiles, +and runs the file, it doesn't do anything else. The \f(CW\*(C`use\*(C'\fR statement +is the same as a \f(CW\*(C`require\*(C'\fR run at compile-time, but Perl also calls the +\&\f(CW\*(C`import\*(C'\fR method for the loaded package. These two are the same: +.PP +.Vb 1 +\& use MODULE qw(import list); +\& +\& BEGIN { +\& require MODULE; +\& MODULE\->import(import list); +\& } +.Ve +.PP +However, you can suppress the \f(CW\*(C`import\*(C'\fR by using an explicit, empty +import list. Both of these still happen at compile-time: +.PP +.Vb 1 +\& use MODULE (); +\& +\& BEGIN { +\& require MODULE; +\& } +.Ve +.PP +Since \f(CW\*(C`use\*(C'\fR will also call the \f(CW\*(C`import\*(C'\fR method, the actual value +for \f(CW\*(C`MODULE\*(C'\fR must be a bareword. That is, \f(CW\*(C`use\*(C'\fR cannot load files +by name, although \f(CW\*(C`require\*(C'\fR can: +.PP +.Vb 1 +\& require "$ENV{HOME}/lib/Foo.pm"; # no @INC searching! +.Ve +.PP +See the entry for \f(CW\*(C`use\*(C'\fR in perlfunc for more details. +.SS "How do I keep my own module/library directory?" +.IX Subsection "How do I keep my own module/library directory?" +When you build modules, tell Perl where to install the modules. +.PP +If you want to install modules for your own use, the easiest way might +be local::lib, which you can download from CPAN. It sets various +installation settings for you, and uses those same settings within +your programs. +.PP +If you want more flexibility, you need to configure your CPAN client +for your particular situation. +.PP +For \f(CW\*(C`Makefile.PL\*(C'\fR\-based distributions, use the INSTALL_BASE option +when generating Makefiles: +.PP +.Vb 1 +\& perl Makefile.PL INSTALL_BASE=/mydir/perl +.Ve +.PP +You can set this in your \f(CW\*(C`CPAN.pm\*(C'\fR configuration so modules +automatically install in your private library directory when you use +the CPAN.pm shell: +.PP +.Vb 3 +\& % cpan +\& cpan> o conf makepl_arg INSTALL_BASE=/mydir/perl +\& cpan> o conf commit +.Ve +.PP +For \f(CW\*(C`Build.PL\*(C'\fR\-based distributions, use the \-\-install_base option: +.PP +.Vb 1 +\& perl Build.PL \-\-install_base /mydir/perl +.Ve +.PP +You can configure \f(CW\*(C`CPAN.pm\*(C'\fR to automatically use this option too: +.PP +.Vb 3 +\& % cpan +\& cpan> o conf mbuild_arg "\-\-install_base /mydir/perl" +\& cpan> o conf commit +.Ve +.PP +INSTALL_BASE tells these tools to put your modules into +\&\fI/mydir/perl/lib/perl5\fR. See "How do I add a directory to my +include path (@INC) at runtime?" for details on how to run your newly +installed modules. +.PP +There is one caveat with INSTALL_BASE, though, since it acts +differently from the PREFIX and LIB settings that older versions of +ExtUtils::MakeMaker advocated. INSTALL_BASE does not support +installing modules for multiple versions of Perl or different +architectures under the same directory. You should consider whether you +really want that and, if you do, use the older PREFIX and LIB +settings. See the ExtUtils::Makemaker documentation for more details. +.SS "How do I add the directory my program lives in to the module/library search path?" +.IX Subsection "How do I add the directory my program lives in to the module/library search path?" +(contributed by brian d foy) +.PP +If you know the directory already, you can add it to \f(CW@INC\fR as you would +for any other directory. You might \f(CW\*(C`use lib\*(C'\fR if you know the directory +at compile time: +.PP +.Vb 1 +\& use lib $directory; +.Ve +.PP +The trick in this task is to find the directory. Before your script does +anything else (such as a \f(CW\*(C`chdir\*(C'\fR), you can get the current working +directory with the \f(CW\*(C`Cwd\*(C'\fR module, which comes with Perl: +.PP +.Vb 4 +\& BEGIN { +\& use Cwd; +\& our $directory = cwd; +\& } +\& +\& use lib $directory; +.Ve +.PP +You can do a similar thing with the value of \f(CW$0\fR, which holds the +script name. That might hold a relative path, but \f(CW\*(C`rel2abs\*(C'\fR can turn +it into an absolute path. Once you have the +.PP +.Vb 3 +\& BEGIN { +\& use File::Spec::Functions qw(rel2abs); +\& use File::Basename qw(dirname); +\& +\& my $path = rel2abs( $0 ); +\& our $directory = dirname( $path ); +\& } +\& +\& use lib $directory; +.Ve +.PP +The FindBin module, which comes with Perl, might work. It finds the +directory of the currently running script and puts it in \f(CW$Bin\fR, which +you can then use to construct the right library path: +.PP +.Vb 1 +\& use FindBin qw($Bin); +.Ve +.PP +You can also use local::lib to do much of the same thing. Install +modules using local::lib's settings then use the module in your +program: +.PP +.Vb 1 +\& use local::lib; # sets up a local lib at ~/perl5 +.Ve +.PP +See the local::lib documentation for more details. +.SS "How do I add a directory to my include path (@INC) at runtime?" +.IX Subsection "How do I add a directory to my include path (@INC) at runtime?" +Here are the suggested ways of modifying your include path, including +environment variables, run-time switches, and in-code statements: +.ie n .IP "the ""PERLLIB"" environment variable" 4 +.el .IP "the \f(CWPERLLIB\fR environment variable" 4 +.IX Item "the PERLLIB environment variable" +.Vb 2 +\& $ export PERLLIB=/path/to/my/dir +\& $ perl program.pl +.Ve +.ie n .IP "the ""PERL5LIB"" environment variable" 4 +.el .IP "the \f(CWPERL5LIB\fR environment variable" 4 +.IX Item "the PERL5LIB environment variable" +.Vb 2 +\& $ export PERL5LIB=/path/to/my/dir +\& $ perl program.pl +.Ve +.ie n .IP "the ""perl \-Idir"" command line flag" 4 +.el .IP "the \f(CWperl \-Idir\fR command line flag" 4 +.IX Item "the perl -Idir command line flag" +.Vb 1 +\& $ perl \-I/path/to/my/dir program.pl +.Ve +.ie n .IP "the ""lib"" pragma:" 4 +.el .IP "the \f(CWlib\fR pragma:" 4 +.IX Item "the lib pragma:" +.Vb 1 +\& use lib "$ENV{HOME}/myown_perllib"; +.Ve +.IP "the local::lib module:" 4 +.IX Item "the local::lib module:" +.Vb 1 +\& use local::lib; +\& +\& use local::lib "~/myown_perllib"; +.Ve +.SS "Where are modules installed?" +.IX Subsection "Where are modules installed?" +Modules are installed on a case-by-case basis (as provided by the methods +described in the previous section), and in the operating system. All of these +paths are stored in \f(CW@INC\fR, which you can display with the one-liner +.PP +.Vb 1 +\& perl \-e \*(Aqprint join("\en",@INC,"")\*(Aq +.Ve +.PP +The same information is displayed at the end of the output from the command +.PP +.Vb 1 +\& perl \-V +.Ve +.PP +To find out where a module's source code is located, use +.PP +.Vb 1 +\& perldoc \-l Encode +.Ve +.PP +to display the path to the module. In some cases (for example, the \f(CW\*(C`AutoLoader\*(C'\fR +module), this command will show the path to a separate \f(CW\*(C`pod\*(C'\fR file; the module +itself should be in the same directory, with a 'pm' file extension. +.SS "What is socket.ph and where do I get it?" +.IX Subsection "What is socket.ph and where do I get it?" +It's a Perl 4 style file defining values for system networking +constants. Sometimes it is built using h2ph when Perl is installed, +but other times it is not. Modern programs should use \f(CW\*(C`use Socket;\*(C'\fR +instead. +.SH "AUTHOR AND COPYRIGHT" +.IX Header "AUTHOR AND COPYRIGHT" +Copyright (c) 1997\-2010 Tom Christiansen, Nathan Torkington, and +other authors as noted. All rights reserved. +.PP +This documentation is free; you can redistribute it and/or modify it +under the same terms as Perl itself. +.PP +Irrespective of its distribution, all code examples in this file +are hereby placed into the public domain. You are permitted and +encouraged to use this code in your own programs for fun +or for profit as you see fit. A simple comment in the code giving +credit would be courteous but is not required. |