RE: How to load a "loadable object" that has a non-default file extension ?
[perl.git] / pod / perlfaq8.pod
1 =head1 NAME
2
3 perlfaq8 - System Interaction ($Revision: 10183 $)
4
5 =head1 DESCRIPTION
6
7 This section of the Perl FAQ covers questions involving operating
8 system interaction.  Topics include interprocess communication (IPC),
9 control over the user-interface (keyboard, screen and pointing
10 devices), and most anything else not related to data manipulation.
11
12 Read the FAQs and documentation specific to the port of perl to your
13 operating system (eg, L<perlvms>, L<perlplan9>, ...).  These should
14 contain more detailed information on the vagaries of your perl.
15
16 =head2 How do I find out which operating system I'm running under?
17
18 The $^O variable ($OSNAME if you use English) contains an indication of
19 the name of the operating system (not its release number) that your perl
20 binary was built for.
21
22 =head2 How come exec() doesn't return?
23
24 Because that's what it does: it replaces your currently running
25 program with a different one.  If you want to keep going (as is
26 probably the case if you're asking this question) use system()
27 instead.
28
29 =head2 How do I do fancy stuff with the keyboard/screen/mouse?
30
31 How you access/control keyboards, screens, and pointing devices
32 ("mice") is system-dependent.  Try the following modules:
33
34 =over 4
35
36 =item Keyboard
37
38         Term::Cap               Standard perl distribution
39         Term::ReadKey           CPAN
40         Term::ReadLine::Gnu     CPAN
41         Term::ReadLine::Perl    CPAN
42         Term::Screen            CPAN
43
44 =item Screen
45
46         Term::Cap               Standard perl distribution
47         Curses                  CPAN
48         Term::ANSIColor         CPAN
49
50 =item Mouse
51
52         Tk                      CPAN
53
54 =back
55
56 Some of these specific cases are shown as examples in other answers
57 in this section of the perlfaq.
58
59 =head2 How do I print something out in color?
60
61 In general, you don't, because you don't know whether
62 the recipient has a color-aware display device.  If you
63 know that they have an ANSI terminal that understands
64 color, you can use the Term::ANSIColor module from CPAN:
65
66         use Term::ANSIColor;
67         print color("red"), "Stop!\n", color("reset");
68         print color("green"), "Go!\n", color("reset");
69
70 Or like this:
71
72         use Term::ANSIColor qw(:constants);
73         print RED, "Stop!\n", RESET;
74         print GREEN, "Go!\n", RESET;
75
76 =head2 How do I read just one key without waiting for a return key?
77
78 Controlling input buffering is a remarkably system-dependent matter.
79 On many systems, you can just use the B<stty> command as shown in
80 L<perlfunc/getc>, but as you see, that's already getting you into
81 portability snags.
82
83         open(TTY, "+</dev/tty") or die "no tty: $!";
84         system "stty  cbreak </dev/tty >/dev/tty 2>&1";
85         $key = getc(TTY);               # perhaps this works
86         # OR ELSE
87         sysread(TTY, $key, 1);  # probably this does
88         system "stty -cbreak </dev/tty >/dev/tty 2>&1";
89
90 The Term::ReadKey module from CPAN offers an easy-to-use interface that
91 should be more efficient than shelling out to B<stty> for each key.
92 It even includes limited support for Windows.
93
94         use Term::ReadKey;
95         ReadMode('cbreak');
96         $key = ReadKey(0);
97         ReadMode('normal');
98
99 However, using the code requires that you have a working C compiler
100 and can use it to build and install a CPAN module.  Here's a solution
101 using the standard POSIX module, which is already on your systems
102 (assuming your system supports POSIX).
103
104         use HotKey;
105         $key = readkey();
106
107 And here's the HotKey module, which hides the somewhat mystifying calls
108 to manipulate the POSIX termios structures.
109
110         # HotKey.pm
111         package HotKey;
112
113         @ISA = qw(Exporter);
114         @EXPORT = qw(cbreak cooked readkey);
115
116         use strict;
117         use POSIX qw(:termios_h);
118         my ($term, $oterm, $echo, $noecho, $fd_stdin);
119
120         $fd_stdin = fileno(STDIN);
121         $term     = POSIX::Termios->new();
122         $term->getattr($fd_stdin);
123         $oterm     = $term->getlflag();
124
125         $echo     = ECHO | ECHOK | ICANON;
126         $noecho   = $oterm & ~$echo;
127
128         sub cbreak {
129                 $term->setlflag($noecho);  # ok, so i don't want echo either
130                 $term->setcc(VTIME, 1);
131                 $term->setattr($fd_stdin, TCSANOW);
132         }
133
134         sub cooked {
135                 $term->setlflag($oterm);
136                 $term->setcc(VTIME, 0);
137                 $term->setattr($fd_stdin, TCSANOW);
138         }
139
140         sub readkey {
141                 my $key = '';
142                 cbreak();
143                 sysread(STDIN, $key, 1);
144                 cooked();
145                 return $key;
146         }
147
148         END { cooked() }
149
150         1;
151
152 =head2 How do I check whether input is ready on the keyboard?
153
154 The easiest way to do this is to read a key in nonblocking mode with the
155 Term::ReadKey module from CPAN, passing it an argument of -1 to indicate
156 not to block:
157
158         use Term::ReadKey;
159
160         ReadMode('cbreak');
161
162         if (defined ($char = ReadKey(-1)) ) {
163                 # input was waiting and it was $char
164         } else {
165                 # no input was waiting
166         }
167
168         ReadMode('normal');                  # restore normal tty settings
169
170 =head2 How do I clear the screen?
171
172 If you only have do so infrequently, use C<system>:
173
174         system("clear");
175
176 If you have to do this a lot, save the clear string
177 so you can print it 100 times without calling a program
178 100 times:
179
180         $clear_string = `clear`;
181         print $clear_string;
182
183 If you're planning on doing other screen manipulations, like cursor
184 positions, etc, you might wish to use Term::Cap module:
185
186         use Term::Cap;
187         $terminal = Term::Cap->Tgetent( {OSPEED => 9600} );
188         $clear_string = $terminal->Tputs('cl');
189
190 =head2 How do I get the screen size?
191
192 If you have Term::ReadKey module installed from CPAN,
193 you can use it to fetch the width and height in characters
194 and in pixels:
195
196         use Term::ReadKey;
197         ($wchar, $hchar, $wpixels, $hpixels) = GetTerminalSize();
198
199 This is more portable than the raw C<ioctl>, but not as
200 illustrative:
201
202         require 'sys/ioctl.ph';
203         die "no TIOCGWINSZ " unless defined &TIOCGWINSZ;
204         open(TTY, "+</dev/tty")                     or die "No tty: $!";
205         unless (ioctl(TTY, &TIOCGWINSZ, $winsize='')) {
206                 die sprintf "$0: ioctl TIOCGWINSZ (%08x: $!)\n", &TIOCGWINSZ;
207         }
208         ($row, $col, $xpixel, $ypixel) = unpack('S4', $winsize);
209         print "(row,col) = ($row,$col)";
210         print "  (xpixel,ypixel) = ($xpixel,$ypixel)" if $xpixel || $ypixel;
211         print "\n";
212
213 =head2 How do I ask the user for a password?
214
215 (This question has nothing to do with the web.  See a different
216 FAQ for that.)
217
218 There's an example of this in L<perlfunc/crypt>).  First, you put the
219 terminal into "no echo" mode, then just read the password normally.
220 You may do this with an old-style ioctl() function, POSIX terminal
221 control (see L<POSIX> or its documentation the Camel Book), or a call
222 to the B<stty> program, with varying degrees of portability.
223
224 You can also do this for most systems using the Term::ReadKey module
225 from CPAN, which is easier to use and in theory more portable.
226
227         use Term::ReadKey;
228
229         ReadMode('noecho');
230         $password = ReadLine(0);
231
232 =head2 How do I read and write the serial port?
233
234 This depends on which operating system your program is running on.  In
235 the case of Unix, the serial ports will be accessible through files in
236 /dev; on other systems, device names will doubtless differ.
237 Several problem areas common to all device interaction are the
238 following:
239
240 =over 4
241
242 =item lockfiles
243
244 Your system may use lockfiles to control multiple access.  Make sure
245 you follow the correct protocol.  Unpredictable behavior can result
246 from multiple processes reading from one device.
247
248 =item open mode
249
250 If you expect to use both read and write operations on the device,
251 you'll have to open it for update (see L<perlfunc/"open"> for
252 details).  You may wish to open it without running the risk of
253 blocking by using sysopen() and C<O_RDWR|O_NDELAY|O_NOCTTY> from the
254 Fcntl module (part of the standard perl distribution).  See
255 L<perlfunc/"sysopen"> for more on this approach.
256
257 =item end of line
258
259 Some devices will be expecting a "\r" at the end of each line rather
260 than a "\n".  In some ports of perl, "\r" and "\n" are different from
261 their usual (Unix) ASCII values of "\012" and "\015".  You may have to
262 give the numeric values you want directly, using octal ("\015"), hex
263 ("0x0D"), or as a control-character specification ("\cM").
264
265         print DEV "atv1\012";   # wrong, for some devices
266         print DEV "atv1\015";   # right, for some devices
267
268 Even though with normal text files a "\n" will do the trick, there is
269 still no unified scheme for terminating a line that is portable
270 between Unix, DOS/Win, and Macintosh, except to terminate I<ALL> line
271 ends with "\015\012", and strip what you don't need from the output.
272 This applies especially to socket I/O and autoflushing, discussed
273 next.
274
275 =item flushing output
276
277 If you expect characters to get to your device when you print() them,
278 you'll want to autoflush that filehandle.  You can use select()
279 and the C<$|> variable to control autoflushing (see L<perlvar/$E<verbar>>
280 and L<perlfunc/select>, or L<perlfaq5>, "How do I flush/unbuffer an
281 output filehandle?  Why must I do this?"):
282
283         $oldh = select(DEV);
284         $| = 1;
285         select($oldh);
286
287 You'll also see code that does this without a temporary variable, as in
288
289         select((select(DEV), $| = 1)[0]);
290
291 Or if you don't mind pulling in a few thousand lines
292 of code just because you're afraid of a little $| variable:
293
294         use IO::Handle;
295         DEV->autoflush(1);
296
297 As mentioned in the previous item, this still doesn't work when using
298 socket I/O between Unix and Macintosh.  You'll need to hard code your
299 line terminators, in that case.
300
301 =item non-blocking input
302
303 If you are doing a blocking read() or sysread(), you'll have to
304 arrange for an alarm handler to provide a timeout (see
305 L<perlfunc/alarm>).  If you have a non-blocking open, you'll likely
306 have a non-blocking read, which means you may have to use a 4-arg
307 select() to determine whether I/O is ready on that device (see
308 L<perlfunc/"select">.
309
310 =back
311
312 While trying to read from his caller-id box, the notorious Jamie Zawinski
313 C<< <jwz@netscape.com> >>, after much gnashing of teeth and fighting with sysread,
314 sysopen, POSIX's tcgetattr business, and various other functions that
315 go bump in the night, finally came up with this:
316
317         sub open_modem {
318                 use IPC::Open2;
319                 my $stty = `/bin/stty -g`;
320                 open2( \*MODEM_IN, \*MODEM_OUT, "cu -l$modem_device -s2400 2>&1");
321                 # starting cu hoses /dev/tty's stty settings, even when it has
322                 # been opened on a pipe...
323                 system("/bin/stty $stty");
324                 $_ = <MODEM_IN>;
325                 chomp;
326                 if ( !m/^Connected/ ) {
327                         print STDERR "$0: cu printed `$_' instead of `Connected'\n";
328                 }
329         }
330
331 =head2 How do I decode encrypted password files?
332
333 You spend lots and lots of money on dedicated hardware, but this is
334 bound to get you talked about.
335
336 Seriously, you can't if they are Unix password files--the Unix
337 password system employs one-way encryption.  It's more like hashing
338 than encryption.  The best you can do is check whether something else
339 hashes to the same string.  You can't turn a hash back into the
340 original string. Programs like Crack can forcibly (and intelligently)
341 try to guess passwords, but don't (can't) guarantee quick success.
342
343 If you're worried about users selecting bad passwords, you should
344 proactively check when they try to change their password (by modifying
345 passwd(1), for example).
346
347 =head2 How do I start a process in the background?
348
349 Several modules can start other processes that do not block
350 your Perl program.  You can use IPC::Open3, Parallel::Jobs,
351 IPC::Run, and some of the POE modules.  See CPAN for more
352 details.
353
354 You could also use
355
356         system("cmd &")
357
358 or you could use fork as documented in L<perlfunc/"fork">, with
359 further examples in L<perlipc>.  Some things to be aware of, if you're
360 on a Unix-like system:
361
362 =over 4
363
364 =item STDIN, STDOUT, and STDERR are shared
365
366 Both the main process and the backgrounded one (the "child" process)
367 share the same STDIN, STDOUT and STDERR filehandles.  If both try to
368 access them at once, strange things can happen.  You may want to close
369 or reopen these for the child.  You can get around this with
370 C<open>ing a pipe (see L<perlfunc/"open">) but on some systems this
371 means that the child process cannot outlive the parent.
372
373 =item Signals
374
375 You'll have to catch the SIGCHLD signal, and possibly SIGPIPE too.
376 SIGCHLD is sent when the backgrounded process finishes.  SIGPIPE is
377 sent when you write to a filehandle whose child process has closed (an
378 untrapped SIGPIPE can cause your program to silently die).  This is
379 not an issue with C<system("cmd&")>.
380
381 =item Zombies
382
383 You have to be prepared to "reap" the child process when it finishes.
384
385         $SIG{CHLD} = sub { wait };
386
387         $SIG{CHLD} = 'IGNORE';
388
389 You can also use a double fork. You immediately wait() for your
390 first child, and the init daemon will wait() for your grandchild once
391 it exits.
392
393         unless ($pid = fork) {
394             unless (fork) {
395                 exec "what you really wanna do";
396                 die "exec failed!";
397             }
398             exit 0;
399         }
400         waitpid($pid, 0);
401
402 See L<perlipc/"Signals"> for other examples of code to do this.
403 Zombies are not an issue with C<system("prog &")>.
404
405 =back
406
407 =head2 How do I trap control characters/signals?
408
409 You don't actually "trap" a control character.  Instead, that character
410 generates a signal which is sent to your terminal's currently
411 foregrounded process group, which you then trap in your process.
412 Signals are documented in L<perlipc/"Signals"> and the
413 section on "Signals" in the Camel.
414
415 You can set the values of the %SIG hash to be the functions you want
416 to handle the signal.  After perl catches the signal, it looks in %SIG
417 for a key with the same name as the signal, then calls the subroutine
418 value for that key.
419
420         # as an anonymous subroutine
421
422         $SIG{INT} = sub { syswrite(STDERR, "ouch\n", 5 ) };
423
424         # or a reference to a function
425
426         $SIG{INT} = \&ouch;
427
428         # or the name of the function as a string
429
430         $SIG{INT} = "ouch";
431
432 Perl versions before 5.8 had in its C source code signal handlers which
433 would catch the signal and possibly run a Perl function that you had set
434 in %SIG.  This violated the rules of signal handling at that level
435 causing perl to dump core. Since version 5.8.0, perl looks at %SIG
436 *after* the signal has been caught, rather than while it is being caught.
437 Previous versions of this answer were incorrect.
438
439 =head2 How do I modify the shadow password file on a Unix system?
440
441 If perl was installed correctly and your shadow library was written
442 properly, the getpw*() functions described in L<perlfunc> should in
443 theory provide (read-only) access to entries in the shadow password
444 file.  To change the file, make a new shadow password file (the format
445 varies from system to system--see L<passwd> for specifics) and use
446 pwd_mkdb(8) to install it (see L<pwd_mkdb> for more details).
447
448 =head2 How do I set the time and date?
449
450 Assuming you're running under sufficient permissions, you should be
451 able to set the system-wide date and time by running the date(1)
452 program.  (There is no way to set the time and date on a per-process
453 basis.)  This mechanism will work for Unix, MS-DOS, Windows, and NT;
454 the VMS equivalent is C<set time>.
455
456 However, if all you want to do is change your time zone, you can
457 probably get away with setting an environment variable:
458
459         $ENV{TZ} = "MST7MDT";              # unixish
460         $ENV{'SYS$TIMEZONE_DIFFERENTIAL'}="-5" # vms
461         system "trn comp.lang.perl.misc";
462
463 =head2 How can I sleep() or alarm() for under a second?
464 X<Time::HiRes> X<BSD::Itimer> X<sleep> X<select>
465
466 If you want finer granularity than the 1 second that the C<sleep()>
467 function provides, the easiest way is to use the C<select()> function as
468 documented in L<perlfunc/"select">.  Try the C<Time::HiRes> and
469 the C<BSD::Itimer> modules (available from CPAN, and starting from
470 Perl 5.8 C<Time::HiRes> is part of the standard distribution).
471
472 =head2 How can I measure time under a second?
473 X<Time::HiRes> X<BSD::Itimer> X<sleep> X<select>
474
475 (contributed by brian d foy)
476
477 The C<Time::HiRes> module (part of the standard distribution as of
478 Perl 5.8) measures time with the C<gettimeofday()> system call, which
479 returns the time in microseconds since the epoch. If you can't install
480 C<Time::HiRes> for older Perls and you are on a Unixish system, you
481 may be able to call C<gettimeofday(2)> directly. See
482 L<perlfunc/syscall>.
483
484 =head2 How can I do an atexit() or setjmp()/longjmp()? (Exception handling)
485
486 Release 5 of Perl added the END block, which can be used to simulate
487 atexit().  Each package's END block is called when the program or
488 thread ends (see L<perlmod> manpage for more details).
489
490 For example, you can use this to make sure your filter program
491 managed to finish its output without filling up the disk:
492
493         END {
494                 close(STDOUT) || die "stdout close failed: $!";
495         }
496
497 The END block isn't called when untrapped signals kill the program,
498 though, so if you use END blocks you should also use
499
500         use sigtrap qw(die normal-signals);
501
502 Perl's exception-handling mechanism is its eval() operator.  You can
503 use eval() as setjmp and die() as longjmp.  For details of this, see
504 the section on signals, especially the time-out handler for a blocking
505 flock() in L<perlipc/"Signals"> or the section on "Signals" in
506 the Camel Book.
507
508 If exception handling is all you're interested in, try the
509 exceptions.pl library (part of the standard perl distribution).
510
511 If you want the atexit() syntax (and an rmexit() as well), try the
512 AtExit module available from CPAN.
513
514 =head2 Why doesn't my sockets program work under System V (Solaris)?  What does the error message "Protocol not supported" mean?
515
516 Some Sys-V based systems, notably Solaris 2.X, redefined some of the
517 standard socket constants.  Since these were constant across all
518 architectures, they were often hardwired into perl code.  The proper
519 way to deal with this is to "use Socket" to get the correct values.
520
521 Note that even though SunOS and Solaris are binary compatible, these
522 values are different.  Go figure.
523
524 =head2 How can I call my system's unique C functions from Perl?
525
526 In most cases, you write an external module to do it--see the answer
527 to "Where can I learn about linking C with Perl? [h2xs, xsubpp]".
528 However, if the function is a system call, and your system supports
529 syscall(), you can use the syscall function (documented in
530 L<perlfunc>).
531
532 Remember to check the modules that came with your distribution, and
533 CPAN as well--someone may already have written a module to do it. On
534 Windows, try Win32::API.  On Macs, try Mac::Carbon.  If no module
535 has an interface to the C function, you can inline a bit of C in your
536 Perl source with Inline::C.
537
538 =head2 Where do I get the include files to do ioctl() or syscall()?
539
540 Historically, these would be generated by the h2ph tool, part of the
541 standard perl distribution.  This program converts cpp(1) directives
542 in C header files to files containing subroutine definitions, like
543 &SYS_getitimer, which you can use as arguments to your functions.
544 It doesn't work perfectly, but it usually gets most of the job done.
545 Simple files like F<errno.h>, F<syscall.h>, and F<socket.h> were fine,
546 but the hard ones like F<ioctl.h> nearly always need to hand-edited.
547 Here's how to install the *.ph files:
548
549         1.  become super-user
550         2.  cd /usr/include
551         3.  h2ph *.h */*.h
552
553 If your system supports dynamic loading, for reasons of portability and
554 sanity you probably ought to use h2xs (also part of the standard perl
555 distribution).  This tool converts C header files to Perl extensions.
556 See L<perlxstut> for how to get started with h2xs.
557
558 If your system doesn't support dynamic loading, you still probably
559 ought to use h2xs.  See L<perlxstut> and L<ExtUtils::MakeMaker> for
560 more information (in brief, just use B<make perl> instead of a plain
561 B<make> to rebuild perl with a new static extension).
562
563 =head2 Why do setuid perl scripts complain about kernel problems?
564
565 Some operating systems have bugs in the kernel that make setuid
566 scripts inherently insecure.  Perl gives you a number of options
567 (described in L<perlsec>) to work around such systems.
568
569 =head2 How can I open a pipe both to and from a command?
570
571 The IPC::Open2 module (part of the standard perl distribution) is an
572 easy-to-use approach that internally uses pipe(), fork(), and exec() to do
573 the job.  Make sure you read the deadlock warnings in its documentation,
574 though (see L<IPC::Open2>).  See
575 L<perlipc/"Bidirectional Communication with Another Process"> and
576 L<perlipc/"Bidirectional Communication with Yourself">
577
578 You may also use the IPC::Open3 module (part of the standard perl
579 distribution), but be warned that it has a different order of
580 arguments from IPC::Open2 (see L<IPC::Open3>).
581
582 =head2 Why can't I get the output of a command with system()?
583
584 You're confusing the purpose of system() and backticks (``).  system()
585 runs a command and returns exit status information (as a 16 bit value:
586 the low 7 bits are the signal the process died from, if any, and
587 the high 8 bits are the actual exit value).  Backticks (``) run a
588 command and return what it sent to STDOUT.
589
590         $exit_status   = system("mail-users");
591         $output_string = `ls`;
592
593 =head2 How can I capture STDERR from an external command?
594
595 There are three basic ways of running external commands:
596
597         system $cmd;            # using system()
598         $output = `$cmd`;               # using backticks (``)
599         open (PIPE, "cmd |");   # using open()
600
601 With system(), both STDOUT and STDERR will go the same place as the
602 script's STDOUT and STDERR, unless the system() command redirects them.
603 Backticks and open() read B<only> the STDOUT of your command.
604
605 You can also use the open3() function from IPC::Open3.  Benjamin
606 Goldberg provides some sample code:
607
608 To capture a program's STDOUT, but discard its STDERR:
609
610         use IPC::Open3;
611         use File::Spec;
612         use Symbol qw(gensym);
613         open(NULL, ">", File::Spec->devnull);
614         my $pid = open3(gensym, \*PH, ">&NULL", "cmd");
615         while( <PH> ) { }
616         waitpid($pid, 0);
617
618 To capture a program's STDERR, but discard its STDOUT:
619
620         use IPC::Open3;
621         use File::Spec;
622         use Symbol qw(gensym);
623         open(NULL, ">", File::Spec->devnull);
624         my $pid = open3(gensym, ">&NULL", \*PH, "cmd");
625         while( <PH> ) { }
626         waitpid($pid, 0);
627
628 To capture a program's STDERR, and let its STDOUT go to our own STDERR:
629
630         use IPC::Open3;
631         use Symbol qw(gensym);
632         my $pid = open3(gensym, ">&STDERR", \*PH, "cmd");
633         while( <PH> ) { }
634         waitpid($pid, 0);
635
636 To read both a command's STDOUT and its STDERR separately, you can
637 redirect them to temp files, let the command run, then read the temp
638 files:
639
640         use IPC::Open3;
641         use Symbol qw(gensym);
642         use IO::File;
643         local *CATCHOUT = IO::File->new_tmpfile;
644         local *CATCHERR = IO::File->new_tmpfile;
645         my $pid = open3(gensym, ">&CATCHOUT", ">&CATCHERR", "cmd");
646         waitpid($pid, 0);
647         seek $_, 0, 0 for \*CATCHOUT, \*CATCHERR;
648         while( <CATCHOUT> ) {}
649         while( <CATCHERR> ) {}
650
651 But there's no real need for *both* to be tempfiles... the following
652 should work just as well, without deadlocking:
653
654         use IPC::Open3;
655         use Symbol qw(gensym);
656         use IO::File;
657         local *CATCHERR = IO::File->new_tmpfile;
658         my $pid = open3(gensym, \*CATCHOUT, ">&CATCHERR", "cmd");
659         while( <CATCHOUT> ) {}
660         waitpid($pid, 0);
661         seek CATCHERR, 0, 0;
662         while( <CATCHERR> ) {}
663
664 And it'll be faster, too, since we can begin processing the program's
665 stdout immediately, rather than waiting for the program to finish.
666
667 With any of these, you can change file descriptors before the call:
668
669         open(STDOUT, ">logfile");
670         system("ls");
671
672 or you can use Bourne shell file-descriptor redirection:
673
674         $output = `$cmd 2>some_file`;
675         open (PIPE, "cmd 2>some_file |");
676
677 You can also use file-descriptor redirection to make STDERR a
678 duplicate of STDOUT:
679
680         $output = `$cmd 2>&1`;
681         open (PIPE, "cmd 2>&1 |");
682
683 Note that you I<cannot> simply open STDERR to be a dup of STDOUT
684 in your Perl program and avoid calling the shell to do the redirection.
685 This doesn't work:
686
687         open(STDERR, ">&STDOUT");
688         $alloutput = `cmd args`;  # stderr still escapes
689
690 This fails because the open() makes STDERR go to where STDOUT was
691 going at the time of the open().  The backticks then make STDOUT go to
692 a string, but don't change STDERR (which still goes to the old
693 STDOUT).
694
695 Note that you I<must> use Bourne shell (sh(1)) redirection syntax in
696 backticks, not csh(1)!  Details on why Perl's system() and backtick
697 and pipe opens all use the Bourne shell are in the
698 F<versus/csh.whynot> article in the "Far More Than You Ever Wanted To
699 Know" collection in http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz .  To
700 capture a command's STDERR and STDOUT together:
701
702         $output = `cmd 2>&1`;                       # either with backticks
703         $pid = open(PH, "cmd 2>&1 |");              # or with an open pipe
704         while (<PH>) { }                            #    plus a read
705
706 To capture a command's STDOUT but discard its STDERR:
707
708         $output = `cmd 2>/dev/null`;                # either with backticks
709         $pid = open(PH, "cmd 2>/dev/null |");       # or with an open pipe
710         while (<PH>) { }                            #    plus a read
711
712 To capture a command's STDERR but discard its STDOUT:
713
714         $output = `cmd 2>&1 1>/dev/null`;           # either with backticks
715         $pid = open(PH, "cmd 2>&1 1>/dev/null |");  # or with an open pipe
716         while (<PH>) { }                            #    plus a read
717
718 To exchange a command's STDOUT and STDERR in order to capture the STDERR
719 but leave its STDOUT to come out our old STDERR:
720
721         $output = `cmd 3>&1 1>&2 2>&3 3>&-`;        # either with backticks
722         $pid = open(PH, "cmd 3>&1 1>&2 2>&3 3>&-|");# or with an open pipe
723         while (<PH>) { }                            #    plus a read
724
725 To read both a command's STDOUT and its STDERR separately, it's easiest
726 to redirect them separately to files, and then read from those files
727 when the program is done:
728
729         system("program args 1>program.stdout 2>program.stderr");
730
731 Ordering is important in all these examples.  That's because the shell
732 processes file descriptor redirections in strictly left to right order.
733
734         system("prog args 1>tmpfile 2>&1");
735         system("prog args 2>&1 1>tmpfile");
736
737 The first command sends both standard out and standard error to the
738 temporary file.  The second command sends only the old standard output
739 there, and the old standard error shows up on the old standard out.
740
741 =head2 Why doesn't open() return an error when a pipe open fails?
742
743 If the second argument to a piped open() contains shell
744 metacharacters, perl fork()s, then exec()s a shell to decode the
745 metacharacters and eventually run the desired program.  If the program
746 couldn't be run, it's the shell that gets the message, not Perl. All
747 your Perl program can find out is whether the shell itself could be
748 successfully started.  You can still capture the shell's STDERR and
749 check it for error messages.  See L<"How can I capture STDERR from an
750 external command?"> elsewhere in this document, or use the
751 IPC::Open3 module.
752
753 If there are no shell metacharacters in the argument of open(), Perl
754 runs the command directly, without using the shell, and can correctly
755 report whether the command started.
756
757 =head2 What's wrong with using backticks in a void context?
758
759 Strictly speaking, nothing.  Stylistically speaking, it's not a good
760 way to write maintainable code.  Perl has several operators for
761 running external commands.  Backticks are one; they collect the output
762 from the command for use in your program.  The C<system> function is
763 another; it doesn't do this.
764
765 Writing backticks in your program sends a clear message to the readers
766 of your code that you wanted to collect the output of the command.
767 Why send a clear message that isn't true?
768
769 Consider this line:
770
771         `cat /etc/termcap`;
772
773 You forgot to check C<$?> to see whether the program even ran
774 correctly.  Even if you wrote
775
776         print `cat /etc/termcap`;
777
778 this code could and probably should be written as
779
780         system("cat /etc/termcap") == 0
781         or die "cat program failed!";
782
783 which will echo the cat command's output as it is generated, instead
784 of waiting until the program has completed to print it out. It also
785 checks the return value.
786
787 C<system> also provides direct control over whether shell wildcard
788 processing may take place, whereas backticks do not.
789
790 =head2 How can I call backticks without shell processing?
791
792 This is a bit tricky.  You can't simply write the command
793 like this:
794
795         @ok = `grep @opts '$search_string' @filenames`;
796
797 As of Perl 5.8.0, you can use C<open()> with multiple arguments.
798 Just like the list forms of C<system()> and C<exec()>, no shell
799 escapes happen.
800
801         open( GREP, "-|", 'grep', @opts, $search_string, @filenames );
802         chomp(@ok = <GREP>);
803         close GREP;
804
805 You can also:
806
807         my @ok = ();
808         if (open(GREP, "-|")) {
809                 while (<GREP>) {
810                         chomp;
811                         push(@ok, $_);
812                 }
813                 close GREP;
814         } else {
815                 exec 'grep', @opts, $search_string, @filenames;
816         }
817
818 Just as with C<system()>, no shell escapes happen when you C<exec()> a
819 list. Further examples of this can be found in L<perlipc/"Safe Pipe
820 Opens">.
821
822 Note that if you're using Windows, no solution to this vexing issue is
823 even possible.  Even if Perl were to emulate C<fork()>, you'd still be
824 stuck, because Windows does not have an argc/argv-style API.
825
826 =head2 Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)?
827
828 Some stdio's set error and eof flags that need clearing.  The
829 POSIX module defines clearerr() that you can use.  That is the
830 technically correct way to do it.  Here are some less reliable
831 workarounds:
832
833 =over 4
834
835 =item 1
836
837 Try keeping around the seekpointer and go there, like this:
838
839         $where = tell(LOG);
840         seek(LOG, $where, 0);
841
842 =item 2
843
844 If that doesn't work, try seeking to a different part of the file and
845 then back.
846
847 =item 3
848
849 If that doesn't work, try seeking to a different part of
850 the file, reading something, and then seeking back.
851
852 =item 4
853
854 If that doesn't work, give up on your stdio package and use sysread.
855
856 =back
857
858 =head2 How can I convert my shell script to perl?
859
860 Learn Perl and rewrite it.  Seriously, there's no simple converter.
861 Things that are awkward to do in the shell are easy to do in Perl, and
862 this very awkwardness is what would make a shell->perl converter
863 nigh-on impossible to write.  By rewriting it, you'll think about what
864 you're really trying to do, and hopefully will escape the shell's
865 pipeline datastream paradigm, which while convenient for some matters,
866 causes many inefficiencies.
867
868 =head2 Can I use perl to run a telnet or ftp session?
869
870 Try the Net::FTP, TCP::Client, and Net::Telnet modules (available from
871 CPAN).  http://www.cpan.org/scripts/netstuff/telnet.emul.shar
872 will also help for emulating the telnet protocol, but Net::Telnet is
873 quite probably easier to use..
874
875 If all you want to do is pretend to be telnet but don't need
876 the initial telnet handshaking, then the standard dual-process
877 approach will suffice:
878
879         use IO::Socket;             # new in 5.004
880         $handle = IO::Socket::INET->new('www.perl.com:80')
881             or die "can't connect to port 80 on www.perl.com: $!";
882         $handle->autoflush(1);
883         if (fork()) {               # XXX: undef means failure
884             select($handle);
885             print while <STDIN>;    # everything from stdin to socket
886         } else {
887             print while <$handle>;  # everything from socket to stdout
888         }
889         close $handle;
890         exit;
891
892 =head2 How can I write expect in Perl?
893
894 Once upon a time, there was a library called chat2.pl (part of the
895 standard perl distribution), which never really got finished.  If you
896 find it somewhere, I<don't use it>.  These days, your best bet is to
897 look at the Expect module available from CPAN, which also requires two
898 other modules from CPAN, IO::Pty and IO::Stty.
899
900 =head2 Is there a way to hide perl's command line from programs such as "ps"?
901
902 First of all note that if you're doing this for security reasons (to
903 avoid people seeing passwords, for example) then you should rewrite
904 your program so that critical information is never given as an
905 argument.  Hiding the arguments won't make your program completely
906 secure.
907
908 To actually alter the visible command line, you can assign to the
909 variable $0 as documented in L<perlvar>.  This won't work on all
910 operating systems, though.  Daemon programs like sendmail place their
911 state there, as in:
912
913         $0 = "orcus [accepting connections]";
914
915 =head2 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?
916
917 =over 4
918
919 =item Unix
920
921 In the strictest sense, it can't be done--the script executes as a
922 different process from the shell it was started from.  Changes to a
923 process are not reflected in its parent--only in any children
924 created after the change.  There is shell magic that may allow you to
925 fake it by eval()ing the script's output in your shell; check out the
926 comp.unix.questions FAQ for details.
927
928 =back
929
930 =head2 How do I close a process's filehandle without waiting for it to complete?
931
932 Assuming your system supports such things, just send an appropriate signal
933 to the process (see L<perlfunc/"kill">).  It's common to first send a TERM
934 signal, wait a little bit, and then send a KILL signal to finish it off.
935
936 =head2 How do I fork a daemon process?
937
938 If by daemon process you mean one that's detached (disassociated from
939 its tty), then the following process is reported to work on most
940 Unixish systems.  Non-Unix users should check their Your_OS::Process
941 module for other solutions.
942
943 =over 4
944
945 =item *
946
947 Open /dev/tty and use the TIOCNOTTY ioctl on it.  See L<tty>
948 for details.  Or better yet, you can just use the POSIX::setsid()
949 function, so you don't have to worry about process groups.
950
951 =item *
952
953 Change directory to /
954
955 =item *
956
957 Reopen STDIN, STDOUT, and STDERR so they're not connected to the old
958 tty.
959
960 =item *
961
962 Background yourself like this:
963
964         fork && exit;
965
966 =back
967
968 The Proc::Daemon module, available from CPAN, provides a function to
969 perform these actions for you.
970
971 =head2 How do I find out if I'm running interactively or not?
972
973 Good question. Sometimes C<-t STDIN> and C<-t STDOUT> can give clues,
974 sometimes not.
975
976         if (-t STDIN && -t STDOUT) {
977                 print "Now what? ";
978                 }
979
980 On POSIX systems, you can test whether your own process group matches
981 the current process group of your controlling terminal as follows:
982
983         use POSIX qw/getpgrp tcgetpgrp/;
984
985         # Some POSIX systems, such as Linux, can be
986         # without a /dev/tty at boot time.
987         if (!open(TTY, "/dev/tty")) {
988                 print "no tty\n";
989         } else {
990                 $tpgrp = tcgetpgrp(fileno(*TTY));
991                 $pgrp = getpgrp();
992                 if ($tpgrp == $pgrp) {
993                         print "foreground\n";
994                 } else {
995                         print "background\n";
996                 }
997         }
998
999 =head2 How do I timeout a slow event?
1000
1001 Use the alarm() function, probably in conjunction with a signal
1002 handler, as documented in L<perlipc/"Signals"> and the section on
1003 "Signals" in the Camel.  You may instead use the more flexible
1004 Sys::AlarmCall module available from CPAN.
1005
1006 The alarm() function is not implemented on all versions of Windows.
1007 Check the documentation for your specific version of Perl.
1008
1009 =head2 How do I set CPU limits?
1010 X<BSD::Resource> X<limit> X<CPU>
1011
1012 (contributed by Xho)
1013
1014 Use the C<BSD::Resource> module from CPAN. As an example:
1015
1016         use BSD::Resource;
1017         setrlimit(RLIMIT_CPU,10,20) or die $!;
1018
1019 This sets the soft and hard limits to 10 and 20 seconds, respectively.
1020 After 10 seconds of time spent running on the CPU (not "wall" time),
1021 the process will be sent a signal (XCPU on some systems) which, if not
1022 trapped, will cause the process to terminate.  If that signal is
1023 trapped, then after 10 more seconds (20 seconds in total) the process
1024 will be killed with a non-trappable signal.
1025
1026 See the C<BSD::Resource> and your systems documentation for the gory
1027 details.
1028
1029 =head2 How do I avoid zombies on a Unix system?
1030
1031 Use the reaper code from L<perlipc/"Signals"> to call wait() when a
1032 SIGCHLD is received, or else use the double-fork technique described
1033 in L<perlfaq8/"How do I start a process in the background?">.
1034
1035 =head2 How do I use an SQL database?
1036
1037 The DBI module provides an abstract interface to most database
1038 servers and types, including Oracle, DB2, Sybase, mysql, Postgresql,
1039 ODBC, and flat files.  The DBI module accesses each database type
1040 through a database driver, or DBD.  You can see a complete list of
1041 available drivers on CPAN: http://www.cpan.org/modules/by-module/DBD/ .
1042 You can read more about DBI on http://dbi.perl.org .
1043
1044 Other modules provide more specific access: Win32::ODBC, Alzabo, iodbc,
1045 and others found on CPAN Search: http://search.cpan.org .
1046
1047 =head2 How do I make a system() exit on control-C?
1048
1049 You can't.  You need to imitate the system() call (see L<perlipc> for
1050 sample code) and then have a signal handler for the INT signal that
1051 passes the signal on to the subprocess.  Or you can check for it:
1052
1053         $rc = system($cmd);
1054         if ($rc & 127) { die "signal death" }
1055
1056 =head2 How do I open a file without blocking?
1057
1058 If you're lucky enough to be using a system that supports
1059 non-blocking reads (most Unixish systems do), you need only to use the
1060 O_NDELAY or O_NONBLOCK flag from the Fcntl module in conjunction with
1061 sysopen():
1062
1063         use Fcntl;
1064         sysopen(FH, "/foo/somefile", O_WRONLY|O_NDELAY|O_CREAT, 0644)
1065                 or die "can't open /foo/somefile: $!":
1066
1067 =head2 How do I tell the difference between errors from the shell and perl?
1068
1069 (answer contributed by brian d foy)
1070
1071 When you run a Perl script, something else is running the script for you,
1072 and that something else may output error messages.  The script might
1073 emit its own warnings and error messages.  Most of the time you cannot
1074 tell who said what.
1075
1076 You probably cannot fix the thing that runs perl, but you can change how
1077 perl outputs its warnings by defining a custom warning and die functions.
1078
1079 Consider this script, which has an error you may not notice immediately.
1080
1081         #!/usr/locl/bin/perl
1082
1083         print "Hello World\n";
1084
1085 I get an error when I run this from my shell (which happens to be
1086 bash).  That may look like perl forgot it has a print() function,
1087 but my shebang line is not the path to perl, so the shell runs the
1088 script, and I get the error.
1089
1090         $ ./test
1091         ./test: line 3: print: command not found
1092
1093 A quick and dirty fix involves a little bit of code, but this may be all
1094 you need to figure out the problem.
1095
1096         #!/usr/bin/perl -w
1097
1098         BEGIN {
1099         $SIG{__WARN__} = sub{ print STDERR "Perl: ", @_; };
1100         $SIG{__DIE__}  = sub{ print STDERR "Perl: ", @_; exit 1};
1101         }
1102
1103         $a = 1 + undef;
1104         $x / 0;
1105         __END__
1106
1107 The perl message comes out with "Perl" in front.  The BEGIN block
1108 works at compile time so all of the compilation errors and warnings
1109 get the "Perl:" prefix too.
1110
1111         Perl: Useless use of division (/) in void context at ./test line 9.
1112         Perl: Name "main::a" used only once: possible typo at ./test line 8.
1113         Perl: Name "main::x" used only once: possible typo at ./test line 9.
1114         Perl: Use of uninitialized value in addition (+) at ./test line 8.
1115         Perl: Use of uninitialized value in division (/) at ./test line 9.
1116         Perl: Illegal division by zero at ./test line 9.
1117         Perl: Illegal division by zero at -e line 3.
1118
1119 If I don't see that "Perl:", it's not from perl.
1120
1121 You could also just know all the perl errors, and although there are
1122 some people who may know all of them, you probably don't.  However, they
1123 all should be in the perldiag manpage. If you don't find the error in
1124 there, it probably isn't a perl error.
1125
1126 Looking up every message is not the easiest way, so let perl to do it
1127 for you.  Use the diagnostics pragma with turns perl's normal messages
1128 into longer discussions on the topic.
1129
1130         use diagnostics;
1131
1132 If you don't get a paragraph or two of expanded discussion, it
1133 might not be perl's message.
1134
1135 =head2 How do I install a module from CPAN?
1136
1137 The easiest way is to have a module also named CPAN do it for you.
1138 This module comes with perl version 5.004 and later.
1139
1140         $ perl -MCPAN -e shell
1141
1142         cpan shell -- CPAN exploration and modules installation (v1.59_54)
1143         ReadLine support enabled
1144
1145         cpan> install Some::Module
1146
1147 To manually install the CPAN module, or any well-behaved CPAN module
1148 for that matter, follow these steps:
1149
1150 =over 4
1151
1152 =item 1
1153
1154 Unpack the source into a temporary area.
1155
1156 =item 2
1157
1158         perl Makefile.PL
1159
1160 =item 3
1161
1162         make
1163
1164 =item 4
1165
1166         make test
1167
1168 =item 5
1169
1170         make install
1171
1172 =back
1173
1174 If your version of perl is compiled without dynamic loading, then you
1175 just need to replace step 3 (B<make>) with B<make perl> and you will
1176 get a new F<perl> binary with your extension linked in.
1177
1178 See L<ExtUtils::MakeMaker> for more details on building extensions.
1179 See also the next question, "What's the difference between require
1180 and use?".
1181
1182 =head2 What's the difference between require and use?
1183
1184 Perl offers several different ways to include code from one file into
1185 another.  Here are the deltas between the various inclusion constructs:
1186
1187         1)  do $file is like eval `cat $file`, except the former
1188         1.1: searches @INC and updates %INC.
1189         1.2: bequeaths an *unrelated* lexical scope on the eval'ed code.
1190
1191         2)  require $file is like do $file, except the former
1192         2.1: checks for redundant loading, skipping already loaded files.
1193         2.2: raises an exception on failure to find, compile, or execute $file.
1194
1195         3)  require Module is like require "Module.pm", except the former
1196         3.1: translates each "::" into your system's directory separator.
1197         3.2: primes the parser to disambiguate class Module as an indirect object.
1198
1199         4)  use Module is like require Module, except the former
1200         4.1: loads the module at compile time, not run-time.
1201         4.2: imports symbols and semantics from that package to the current one.
1202
1203 In general, you usually want C<use> and a proper Perl module.
1204
1205 =head2 How do I keep my own module/library directory?
1206
1207 When you build modules, tell Perl where to install the modules.
1208
1209 For C<Makefile.PL>-based distributions, use the PREFIX and LIB options
1210 when generating Makefiles:
1211
1212         perl Makefile.PL PREFIX=/mydir/perl LIB=/mydir/perl/lib
1213
1214 You can set this in your CPAN.pm configuration so modules automatically install
1215 in your private library directory when you use the CPAN.pm shell:
1216
1217         % cpan
1218         cpan> o conf makepl_arg PREFIX=/mydir/perl,LIB=/mydir/perl/lib
1219         cpan> o conf commit
1220
1221 For C<Build.PL>-based distributions, use the --install_base option:
1222
1223         perl Build.PL --install_base /mydir/perl 
1224
1225 You can configure CPAN.pm to automatically use this option too:
1226
1227         % cpan
1228         cpan> o conf mbuild_arg --install_base /mydir/perl
1229         cpan> o conf commit
1230
1231 =head2 How do I add the directory my program lives in to the module/library search path?
1232
1233 (contributed by brian d foy)
1234
1235 If you know the directory already, you can add it to C<@INC> as you would
1236 for any other directory. You might <use lib> if you know the directory
1237 at compile time:
1238
1239         use lib $directory;
1240         
1241 The trick in this task is to find the directory. Before your script does
1242 anything else (such as a C<chdir>), you can get the current working
1243 directory with the C<Cwd> module, which comes with Perl:
1244
1245         BEGIN {
1246                 use Cwd;
1247                 our $directory = cwd;
1248                 }
1249         
1250         use lib $directory;
1251         
1252 You can do a similar thing with the value of C<$0>, which holds the
1253 script name. That might hold a relative path, but C<rel2abs> can turn
1254 it into an absolute path. Once you have the 
1255
1256         BEGIN { 
1257                 use File::Spec::Functions qw(rel2abs);
1258                 use File::Basename qw(dirname);
1259                 
1260                 my $path   = rel2abs( $0 );
1261                 our $directory = dirname( $path );
1262                 }
1263                 
1264         use lib $directory;
1265
1266 The C<FindBin> module, which comes with Perl, might work. It searches
1267 through C<$ENV{PATH}> (so your script has to be in one of those
1268 directories). You can then use that directory (in C<$FindBin::Bin>)
1269 to locate nearby directories you want to add:
1270
1271         use FindBin;
1272         use lib "$FindBin::Bin/../lib";
1273
1274 =head2 How do I add a directory to my include path (@INC) at runtime?
1275
1276 Here are the suggested ways of modifying your include path, including
1277 environment variables, run-time switches, and in-code statements:
1278
1279 =over 4
1280
1281 =item the PERLLIB environment variable
1282
1283         $ export PERLLIB=/path/to/my/dir
1284         $ perl program.pl
1285
1286 =item the PERL5LIB environment variable
1287
1288         $ export PERL5LIB=/path/to/my/dir
1289         $ perl program.pl
1290
1291 =item the perl -Idir command line flag
1292
1293         $ perl -I/path/to/my/dir program.pl
1294
1295 =item the use lib pragma:
1296
1297         use lib "$ENV{HOME}/myown_perllib";
1298
1299 =back
1300
1301 The last is particularly useful because it knows about machine
1302 dependent architectures.  The lib.pm pragmatic module was first
1303 included with the 5.002 release of Perl.
1304
1305 =head2 What is socket.ph and where do I get it?
1306
1307 It's a Perl 4 style file defining values for system networking
1308 constants.  Sometimes it is built using h2ph when Perl is installed,
1309 but other times it is not.  Modern programs C<use Socket;> instead.
1310
1311 =head1 REVISION
1312
1313 Revision: $Revision: 10183 $
1314
1315 Date: $Date: 2007-11-07 09:35:12 +0100 (Wed, 07 Nov 2007) $
1316
1317 See L<perlfaq> for source control details and availability.
1318
1319 =head1 AUTHOR AND COPYRIGHT
1320
1321 Copyright (c) 1997-2007 Tom Christiansen, Nathan Torkington, and
1322 other authors as noted. All rights reserved.
1323
1324 This documentation is free; you can redistribute it and/or modify it
1325 under the same terms as Perl itself.
1326
1327 Irrespective of its distribution, all code examples in this file
1328 are hereby placed into the public domain.  You are permitted and
1329 encouraged to use this code in your own programs for fun
1330 or for profit as you see fit.  A simple comment in the code giving
1331 credit would be courteous but is not required.