This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
s/\bthe the\b/the/g *.pod
[perl5.git] / pod / perlfaq8.pod
CommitLineData
68dc0745
PP
1=head1 NAME
2
5e3006a4 3perlfaq8 - System Interaction ($Revision: 1.26 $, $Date: 1998/08/05 12:20:28 $)
68dc0745
PP
4
5=head1 DESCRIPTION
6
7This section of the Perl FAQ covers questions involving operating
8system interaction. This involves interprocess communication (IPC),
9control over the user-interface (keyboard, screen and pointing
10devices), and most anything else not related to data manipulation.
11
12Read the FAQs and documentation specific to the port of perl to your
46fc3d4c 13operating system (eg, L<perlvms>, L<perlplan9>, ...). These should
68dc0745
PP
14contain 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
c8db1d39 18The $^O variable ($OSNAME if you use English) contains the operating
68dc0745
PP
19system that your perl binary was built for.
20
21=head2 How come exec() doesn't return?
22
23Because that's what it does: it replaces your currently running
24program with a different one. If you want to keep going (as is
25probably the case if you're asking this question) use system()
26instead.
27
28=head2 How do I do fancy stuff with the keyboard/screen/mouse?
29
30How you access/control keyboards, screens, and pointing devices
31("mice") is system-dependent. Try the following modules:
32
33=over 4
34
35=item Keyboard
36
37 Term::Cap Standard perl distribution
38 Term::ReadKey CPAN
39 Term::ReadLine::Gnu CPAN
40 Term::ReadLine::Perl CPAN
41 Term::Screen CPAN
42
43=item Screen
44
45 Term::Cap Standard perl distribution
46 Curses CPAN
47 Term::ANSIColor CPAN
48
49=item Mouse
50
51 Tk CPAN
52
53=back
54
c8db1d39
TC
55Some of these specific cases are shown below.
56
57=head2 How do I print something out in color?
58
59In general, you don't, because you don't know whether
60the recipient has a color-aware display device. If you
61know that they have an ANSI terminal that understands
62color, you can use the Term::ANSIColor module from CPAN:
63
64 use Term::ANSIColor;
65 print color("red"), "Stop!\n", color("reset");
66 print color("green"), "Go!\n", color("reset");
67
68Or like this:
69
70 use Term::ANSIColor qw(:constants);
71 print RED, "Stop!\n", RESET;
72 print GREEN, "Go!\n", RESET;
73
74=head2 How do I read just one key without waiting for a return key?
75
76Controlling input buffering is a remarkably system-dependent matter.
77If most systems, you can just use the B<stty> command as shown in
78L<perlfunc/getc>, but as you see, that's already getting you into
79portability snags.
80
81 open(TTY, "+</dev/tty") or die "no tty: $!";
82 system "stty cbreak </dev/tty >/dev/tty 2>&1";
83 $key = getc(TTY); # perhaps this works
84 # OR ELSE
85 sysread(TTY, $key, 1); # probably this does
86 system "stty -cbreak </dev/tty >/dev/tty 2>&1";
87
88The Term::ReadKey module from CPAN offers an easy-to-use interface that
89should be more efficient than shelling out to B<stty> for each key.
90It even includes limited support for Windows.
91
92 use Term::ReadKey;
93 ReadMode('cbreak');
94 $key = ReadKey(0);
95 ReadMode('normal');
96
97However, that requires that you have a working C compiler and can use it
98to build and install a CPAN module. Here's a solution using
99the standard POSIX module, which is already on your systems (assuming
100your system supports POSIX).
101
102 use HotKey;
103 $key = readkey();
104
105And here's the HotKey module, which hides the somewhat mystifying calls
106to manipulate the POSIX termios structures.
107
108 # HotKey.pm
109 package HotKey;
110
111 @ISA = qw(Exporter);
112 @EXPORT = qw(cbreak cooked readkey);
113
114 use strict;
115 use POSIX qw(:termios_h);
116 my ($term, $oterm, $echo, $noecho, $fd_stdin);
117
118 $fd_stdin = fileno(STDIN);
119 $term = POSIX::Termios->new();
120 $term->getattr($fd_stdin);
121 $oterm = $term->getlflag();
122
123 $echo = ECHO | ECHOK | ICANON;
124 $noecho = $oterm & ~$echo;
125
126 sub cbreak {
127 $term->setlflag($noecho); # ok, so i don't want echo either
128 $term->setcc(VTIME, 1);
129 $term->setattr($fd_stdin, TCSANOW);
130 }
131
132 sub cooked {
133 $term->setlflag($oterm);
134 $term->setcc(VTIME, 0);
135 $term->setattr($fd_stdin, TCSANOW);
136 }
137
138 sub readkey {
139 my $key = '';
140 cbreak();
141 sysread(STDIN, $key, 1);
142 cooked();
143 return $key;
144 }
145
146 END { cooked() }
147
148 1;
149
150=head2 How do I check whether input is ready on the keyboard?
151
152The easiest way to do this is to read a key in nonblocking mode with the
153Term::ReadKey module from CPAN, passing it an argument of -1 to indicate
154not to block:
155
156 use Term::ReadKey;
157
158 ReadMode('cbreak');
159
160 if (defined ($char = ReadKey(-1)) ) {
161 # input was waiting and it was $char
162 } else {
163 # no input was waiting
164 }
165
166 ReadMode('normal'); # restore normal tty settings
167
168=head2 How do I clear the screen?
169
170If you only have to so infrequently, use C<system>:
171
172 system("clear");
173
174If you have to do this a lot, save the clear string
175so you can print it 100 times without calling a program
176100 times:
177
178 $clear_string = `clear`;
179 print $clear_string;
180
181If you're planning on doing other screen manipulations, like cursor
182positions, etc, you might wish to use Term::Cap module:
183
184 use Term::Cap;
185 $terminal = Term::Cap->Tgetent( {OSPEED => 9600} );
186 $clear_string = $terminal->Tputs('cl');
187
188=head2 How do I get the screen size?
189
190If you have Term::ReadKey module installed from CPAN,
191you can use it to fetch the width and height in characters
192and in pixels:
193
194 use Term::ReadKey;
195 ($wchar, $hchar, $wpixels, $hpixels) = GetTerminalSize();
196
197This is more portable than the raw C<ioctl>, but not as
198illustrative:
199
200 require 'sys/ioctl.ph';
201 die "no TIOCGWINSZ " unless defined &TIOCGWINSZ;
202 open(TTY, "+</dev/tty") or die "No tty: $!";
203 unless (ioctl(TTY, &TIOCGWINSZ, $winsize='')) {
204 die sprintf "$0: ioctl TIOCGWINSZ (%08x: $!)\n", &TIOCGWINSZ;
205 }
206 ($row, $col, $xpixel, $ypixel) = unpack('S4', $winsize);
207 print "(row,col) = ($row,$col)";
208 print " (xpixel,ypixel) = ($xpixel,$ypixel)" if $xpixel || $ypixel;
209 print "\n";
210
68dc0745
PP
211=head2 How do I ask the user for a password?
212
213(This question has nothing to do with the web. See a different
214FAQ for that.)
215
216There's an example of this in L<perlfunc/crypt>). First, you put
217the terminal into "no echo" mode, then just read the password
218normally. You may do this with an old-style ioctl() function, POSIX
219terminal control (see L<POSIX>, and Chapter 7 of the Camel), or a call
220to the B<stty> program, with varying degrees of portability.
221
222You can also do this for most systems using the Term::ReadKey module
223from CPAN, which is easier to use and in theory more portable.
224
c8db1d39
TC
225 use Term::ReadKey;
226
227 ReadMode('noecho');
228 $password = ReadLine(0);
229
68dc0745
PP
230=head2 How do I read and write the serial port?
231
232This depends on which operating system your program is running on. In
233the case of Unix, the serial ports will be accessible through files in
234/dev; on other systems, the devices names will doubtless differ.
235Several problem areas common to all device interaction are the
236following
237
238=over 4
239
240=item lockfiles
241
242Your system may use lockfiles to control multiple access. Make sure
243you follow the correct protocol. Unpredictable behaviour can result
244from multiple processes reading from one device.
245
246=item open mode
247
248If you expect to use both read and write operations on the device,
249you'll have to open it for update (see L<perlfunc/"open"> for
250details). You may wish to open it without running the risk of
251blocking by using sysopen() and C<O_RDWR|O_NDELAY|O_NOCTTY> from the
252Fcntl module (part of the standard perl distribution). See
253L<perlfunc/"sysopen"> for more on this approach.
254
255=item end of line
256
257Some devices will be expecting a "\r" at the end of each line rather
258than a "\n". In some ports of perl, "\r" and "\n" are different from
259their usual (Unix) ASCII values of "\012" and "\015". You may have to
260give the numeric values you want directly, using octal ("\015"), hex
261("0x0D"), or as a control-character specification ("\cM").
262
263 print DEV "atv1\012"; # wrong, for some devices
264 print DEV "atv1\015"; # right, for some devices
265
266Even though with normal text files, a "\n" will do the trick, there is
267still no unified scheme for terminating a line that is portable
46fc3d4c 268between Unix, DOS/Win, and Macintosh, except to terminate I<ALL> line
68dc0745
PP
269ends with "\015\012", and strip what you don't need from the output.
270This applies especially to socket I/O and autoflushing, discussed
271next.
272
273=item flushing output
274
275If you expect characters to get to your device when you print() them,
c8db1d39
TC
276you'll want to autoflush that filehandle. You can use select()
277and the C<$|> variable to control autoflushing (see L<perlvar/$|>
278and L<perlfunc/select>):
68dc0745
PP
279
280 $oldh = select(DEV);
281 $| = 1;
282 select($oldh);
283
284You'll also see code that does this without a temporary variable, as in
285
286 select((select(DEV), $| = 1)[0]);
287
c8db1d39
TC
288Or if you don't mind pulling in a few thousand lines
289of code just because you're afraid of a little $| variable:
290
291 use IO::Handle;
292 DEV->autoflush(1);
293
68dc0745
PP
294As mentioned in the previous item, this still doesn't work when using
295socket I/O between Unix and Macintosh. You'll need to hardcode your
296line terminators, in that case.
297
298=item non-blocking input
299
300If you are doing a blocking read() or sysread(), you'll have to
301arrange for an alarm handler to provide a timeout (see
302L<perlfunc/alarm>). If you have a non-blocking open, you'll likely
303have a non-blocking read, which means you may have to use a 4-arg
304select() to determine whether I/O is ready on that device (see
305L<perlfunc/"select">.
306
307=back
308
c8db1d39
TC
309While trying to read from his caller-id box, the notorious Jamie Zawinski
310<jwz@netscape.com>, after much gnashing of teeth and fighting with sysread,
311sysopen, POSIX's tcgetattr business, and various other functions that
312go bump in the night, finally came up with this:
313
314 sub open_modem {
315 use IPC::Open2;
316 my $stty = `/bin/stty -g`;
317 open2( \*MODEM_IN, \*MODEM_OUT, "cu -l$modem_device -s2400 2>&1");
318 # starting cu hoses /dev/tty's stty settings, even when it has
319 # been opened on a pipe...
320 system("/bin/stty $stty");
321 $_ = <MODEM_IN>;
322 chop;
323 if ( !m/^Connected/ ) {
324 print STDERR "$0: cu printed `$_' instead of `Connected'\n";
325 }
326 }
327
328
68dc0745
PP
329=head2 How do I decode encrypted password files?
330
331You spend lots and lots of money on dedicated hardware, but this is
332bound to get you talked about.
333
334Seriously, you can't if they are Unix password files - the Unix
c8db1d39
TC
335password system employs one-way encryption. It's more like hashing than
336encryption. The best you can check is whether something else hashes to
337the same string. You can't turn a hash back into the original string.
338Programs like Crack
339can forcibly (and intelligently) try to guess passwords, but don't
340(can't) guarantee quick success.
68dc0745
PP
341
342If you're worried about users selecting bad passwords, you should
343proactively check when they try to change their password (by modifying
344passwd(1), for example).
345
346=head2 How do I start a process in the background?
347
348You could use
349
350 system("cmd &")
351
352or you could use fork as documented in L<perlfunc/"fork">, with
353further examples in L<perlipc>. Some things to be aware of, if you're
354on a Unix-like system:
355
356=over 4
357
c8db1d39 358=item STDIN, STDOUT, and STDERR are shared
68dc0745
PP
359
360Both the main process and the backgrounded one (the "child" process)
361share the same STDIN, STDOUT and STDERR filehandles. If both try to
362access them at once, strange things can happen. You may want to close
363or reopen these for the child. You can get around this with
364C<open>ing a pipe (see L<perlfunc/"open">) but on some systems this
365means that the child process cannot outlive the parent.
366
367=item Signals
368
369You'll have to catch the SIGCHLD signal, and possibly SIGPIPE too.
370SIGCHLD is sent when the backgrounded process finishes. SIGPIPE is
371sent when you write to a filehandle whose child process has closed (an
372untrapped SIGPIPE can cause your program to silently die). This is
373not an issue with C<system("cmd&")>.
374
375=item Zombies
376
377You have to be prepared to "reap" the child process when it finishes
378
379 $SIG{CHLD} = sub { wait };
380
381See L<perlipc/"Signals"> for other examples of code to do this.
382Zombies are not an issue with C<system("prog &")>.
383
384=back
385
386=head2 How do I trap control characters/signals?
387
c8db1d39
TC
388You don't actually "trap" a control character. Instead, that character
389generates a signal which is sent to your terminal's currently
390foregrounded process group, which you then trap in your process.
391Signals are documented in L<perlipc/"Signals"> and chapter 6 of the Camel.
68dc0745 392
46fc3d4c 393Be warned that very few C libraries are re-entrant. Therefore, if you
68dc0745
PP
394attempt to print() in a handler that got invoked during another stdio
395operation your internal structures will likely be in an
396inconsistent state, and your program will dump core. You can
397sometimes avoid this by using syswrite() instead of print().
398
399Unless you're exceedingly careful, the only safe things to do inside a
400signal handler are: set a variable and exit. And in the first case,
401you should only set a variable in such a way that malloc() is not
402called (eg, by setting a variable that already has a value).
403
404For example:
405
406 $Interrupted = 0; # to ensure it has a value
407 $SIG{INT} = sub {
408 $Interrupted++;
409 syswrite(STDERR, "ouch\n", 5);
410 }
411
412However, because syscalls restart by default, you'll find that if
413you're in a "slow" call, such as E<lt>FHE<gt>, read(), connect(), or
414wait(), that the only way to terminate them is by "longjumping" out;
46fc3d4c 415that is, by raising an exception. See the time-out handler for a
68dc0745
PP
416blocking flock() in L<perlipc/"Signals"> or chapter 6 of the Camel.
417
418=head2 How do I modify the shadow password file on a Unix system?
419
c8db1d39
TC
420If perl was installed correctly, and your shadow library was written
421properly, the getpw*() functions described in L<perlfunc> should in
422theory provide (read-only) access to entries in the shadow password
423file. To change the file, make a new shadow password file (the format
424varies from system to system - see L<passwd(5)> for specifics) and use
68dc0745
PP
425pwd_mkdb(8) to install it (see L<pwd_mkdb(5)> for more details).
426
427=head2 How do I set the time and date?
428
429Assuming you're running under sufficient permissions, you should be
430able to set the system-wide date and time by running the date(1)
431program. (There is no way to set the time and date on a per-process
432basis.) This mechanism will work for Unix, MS-DOS, Windows, and NT;
433the VMS equivalent is C<set time>.
434
435However, if all you want to do is change your timezone, you can
436probably get away with setting an environment variable:
437
438 $ENV{TZ} = "MST7MDT"; # unixish
439 $ENV{'SYS$TIMEZONE_DIFFERENTIAL'}="-5" # vms
c8db1d39 440 system "trn comp.lang.perl.misc";
68dc0745
PP
441
442=head2 How can I sleep() or alarm() for under a second?
443
444If you want finer granularity than the 1 second that the sleep()
445function provides, the easiest way is to use the select() function as
446documented in L<perlfunc/"select">. If your system has itimers and
447syscall() support, you can check out the old example in
448http://www.perl.com/CPAN/doc/misc/ancient/tutorial/eg/itimers.pl .
449
450=head2 How can I measure time under a second?
451
368c9434
JT
452The Time::HiRes module (available from CPAN) provides this
453functionality for some systems.
68dc0745 454
7b8d334a 455In general, you may not be able to. But if your system supports both the
68dc0745
PP
456syscall() function in Perl as well as a system call like gettimeofday(2),
457then you may be able to do something like this:
458
459 require 'sys/syscall.ph';
460
461 $TIMEVAL_T = "LL";
462
463 $done = $start = pack($TIMEVAL_T, ());
464
465 syscall( &SYS_gettimeofday, $start, 0)) != -1
466 or die "gettimeofday: $!";
467
468 ##########################
469 # DO YOUR OPERATION HERE #
470 ##########################
471
472 syscall( &SYS_gettimeofday, $done, 0) != -1
473 or die "gettimeofday: $!";
474
475 @start = unpack($TIMEVAL_T, $start);
476 @done = unpack($TIMEVAL_T, $done);
477
478 # fix microseconds
479 for ($done[1], $start[1]) { $_ /= 1_000_000 }
480
481 $delta_time = sprintf "%.4f", ($done[0] + $done[1] )
482 -
483 ($start[0] + $start[1] );
484
485=head2 How can I do an atexit() or setjmp()/longjmp()? (Exception handling)
486
487Release 5 of Perl added the END block, which can be used to simulate
488atexit(). Each package's END block is called when the program or
c8db1d39
TC
489thread ends (see L<perlmod> manpage for more details).
490
491For example, you can use this to make sure your filter program
492managed to finish its output without filling up the disk:
493
494 END {
495 close(STDOUT) || die "stdout close failed: $!";
496 }
497
498The END block isn't called when untrapped signals kill the program, though, so if
499you use END blocks you should also use
68dc0745
PP
500
501 use sigtrap qw(die normal-signals);
502
503Perl's exception-handling mechanism is its eval() operator. You can
504use eval() as setjmp and die() as longjmp. For details of this, see
46fc3d4c 505the section on signals, especially the time-out handler for a blocking
68dc0745
PP
506flock() in L<perlipc/"Signals"> and chapter 6 of the Camel.
507
508If exception handling is all you're interested in, try the
509exceptions.pl library (part of the standard perl distribution).
510
511If you want the atexit() syntax (and an rmexit() as well), try the
512AtExit 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
516Some Sys-V based systems, notably Solaris 2.X, redefined some of the
517standard socket constants. Since these were constant across all
518architectures, they were often hardwired into perl code. The proper
519way to deal with this is to "use Socket" to get the correct values.
520
521Note that even though SunOS and Solaris are binary compatible, these
522values are different. Go figure.
523
524=head2 How can I call my system's unique C functions from Perl?
525
526In most cases, you write an external module to do it - see the answer
527to "Where can I learn about linking C with Perl? [h2xs, xsubpp]".
528However, if the function is a system call, and your system supports
529syscall(), you can use the syscall function (documented in
530L<perlfunc>).
531
532Remember to check the modules that came with your distribution, and
533CPAN as well - someone may already have written a module to do it.
534
535=head2 Where do I get the include files to do ioctl() or syscall()?
536
537Historically, these would be generated by the h2ph tool, part of the
538standard perl distribution. This program converts cpp(1) directives
539in C header files to files containing subroutine definitions, like
540&SYS_getitimer, which you can use as arguments to your functions.
541It doesn't work perfectly, but it usually gets most of the job done.
542Simple files like F<errno.h>, F<syscall.h>, and F<socket.h> were fine,
543but the hard ones like F<ioctl.h> nearly always need to hand-edited.
544Here's how to install the *.ph files:
545
46fc3d4c 546 1. become super-user
68dc0745
PP
547 2. cd /usr/include
548 3. h2ph *.h */*.h
549
550If your system supports dynamic loading, for reasons of portability and
551sanity you probably ought to use h2xs (also part of the standard perl
552distribution). This tool converts C header files to Perl extensions.
553See L<perlxstut> for how to get started with h2xs.
554
555If your system doesn't support dynamic loading, you still probably
556ought to use h2xs. See L<perlxstut> and L<ExtUtils::MakeMaker> for
557more information (in brief, just use B<make perl> instead of a plain
558B<make> to rebuild perl with a new static extension).
559
560=head2 Why do setuid perl scripts complain about kernel problems?
561
562Some operating systems have bugs in the kernel that make setuid
563scripts inherently insecure. Perl gives you a number of options
564(described in L<perlsec>) to work around such systems.
565
566=head2 How can I open a pipe both to and from a command?
567
568The IPC::Open2 module (part of the standard perl distribution) is an
c8db1d39
TC
569easy-to-use approach that internally uses pipe(), fork(), and exec() to do
570the job. Make sure you read the deadlock warnings in its documentation,
571though (see L<IPC::Open2>). See L<perlipc/"Bidirectional Communication
572with Another Process"> and L<perlipc/"Bidirectional Communication with
573Yourself">
574
575You may also use the IPC::Open3 module (part of the standard perl
576distribution), but be warned that it has a different order of
577arguments from IPC::Open2 (see L<IPC::Open3>).
68dc0745 578
3fe9a6f1
PP
579=head2 Why can't I get the output of a command with system()?
580
46fc3d4c
PP
581You're confusing the purpose of system() and backticks (``). system()
582runs a command and returns exit status information (as a 16 bit value:
c8db1d39 583the low 7 bits are the signal the process died from, if any, and
46fc3d4c 584the high 8 bits are the actual exit value). Backticks (``) run a
3fe9a6f1
PP
585command and return what it sent to STDOUT.
586
46fc3d4c
PP
587 $exit_status = system("mail-users");
588 $output_string = `ls`;
3fe9a6f1 589
68dc0745
PP
590=head2 How can I capture STDERR from an external command?
591
592There are three basic ways of running external commands:
593
594 system $cmd; # using system()
595 $output = `$cmd`; # using backticks (``)
596 open (PIPE, "cmd |"); # using open()
597
598With system(), both STDOUT and STDERR will go the same place as the
599script's versions of these, unless the command redirects them.
600Backticks and open() read B<only> the STDOUT of your command.
601
602With any of these, you can change file descriptors before the call:
603
604 open(STDOUT, ">logfile");
605 system("ls");
606
607or you can use Bourne shell file-descriptor redirection:
608
609 $output = `$cmd 2>some_file`;
610 open (PIPE, "cmd 2>some_file |");
611
612You can also use file-descriptor redirection to make STDERR a
613duplicate of STDOUT:
614
615 $output = `$cmd 2>&1`;
616 open (PIPE, "cmd 2>&1 |");
617
618Note that you I<cannot> simply open STDERR to be a dup of STDOUT
619in your Perl program and avoid calling the shell to do the redirection.
620This doesn't work:
621
622 open(STDERR, ">&STDOUT");
623 $alloutput = `cmd args`; # stderr still escapes
624
625This fails because the open() makes STDERR go to where STDOUT was
626going at the time of the open(). The backticks then make STDOUT go to
627a string, but don't change STDERR (which still goes to the old
628STDOUT).
629
630Note that you I<must> use Bourne shell (sh(1)) redirection syntax in
631backticks, not csh(1)! Details on why Perl's system() and backtick
632and pipe opens all use the Bourne shell are in
633http://www.perl.com/CPAN/doc/FMTEYEWTK/versus/csh.whynot .
c8db1d39 634To capture a command's STDERR and STDOUT together:
68dc0745 635
c8db1d39
TC
636 $output = `cmd 2>&1`; # either with backticks
637 $pid = open(PH, "cmd 2>&1 |"); # or with an open pipe
638 while (<PH>) { } # plus a read
639
640To capture a command's STDOUT but discard its STDERR:
641
642 $output = `cmd 2>/dev/null`; # either with backticks
643 $pid = open(PH, "cmd 2>/dev/null |"); # or with an open pipe
644 while (<PH>) { } # plus a read
645
646To capture a command's STDERR but discard its STDOUT:
647
648 $output = `cmd 2>&1 1>/dev/null`; # either with backticks
649 $pid = open(PH, "cmd 2>&1 1>/dev/null |"); # or with an open pipe
650 while (<PH>) { } # plus a read
651
652To exchange a command's STDOUT and STDERR in order to capture the STDERR
653but leave its STDOUT to come out our old STDERR:
654
655 $output = `cmd 3>&1 1>&2 2>&3 3>&-`; # either with backticks
656 $pid = open(PH, "cmd 3>&1 1>&2 2>&3 3>&-|");# or with an open pipe
657 while (<PH>) { } # plus a read
658
659To read both a command's STDOUT and its STDERR separately, it's easiest
660and safest to redirect them separately to files, and then read from those
661files when the program is done:
662
663 system("program args 1>/tmp/program.stdout 2>/tmp/program.stderr");
664
665Ordering is important in all these examples. That's because the shell
666processes file descriptor redirections in strictly left to right order.
667
668 system("prog args 1>tmpfile 2>&1");
669 system("prog args 2>&1 1>tmpfile");
670
671The first command sends both standard out and standard error to the
672temporary file. The second command sends only the old standard output
673there, and the old standard error shows up on the old standard out.
68dc0745
PP
674
675=head2 Why doesn't open() return an error when a pipe open fails?
676
677It does, but probably not how you expect it to. On systems that
c8db1d39 678follow the standard fork()/exec() paradigm (such as Unix), it works like
68dc0745
PP
679this: open() causes a fork(). In the parent, open() returns with the
680process ID of the child. The child exec()s the command to be piped
681to/from. The parent can't know whether the exec() was successful or
682not - all it can return is whether the fork() succeeded or not. To
683find out if the command succeeded, you have to catch SIGCHLD and
3fe9a6f1
PP
684wait() to get the exit status. You should also catch SIGPIPE if
685you're writing to the child -- you may not have found out the exec()
686failed by the time you write. This is documented in L<perlipc>.
68dc0745
PP
687
688On systems that follow the spawn() paradigm, open() I<might> do what
689you expect - unless perl uses a shell to start your command. In this
690case the fork()/exec() description still applies.
691
692=head2 What's wrong with using backticks in a void context?
693
694Strictly speaking, nothing. Stylistically speaking, it's not a good
695way to write maintainable code because backticks have a (potentially
696humungous) return value, and you're ignoring it. It's may also not be very
697efficient, because you have to read in all the lines of output, allocate
698memory for them, and then throw it away. Too often people are lulled
699to writing:
700
701 `cp file file.bak`;
702
703And now they think "Hey, I'll just always use backticks to run programs."
704Bad idea: backticks are for capturing a program's output; the system()
705function is for running programs.
706
707Consider this line:
708
709 `cat /etc/termcap`;
710
711You haven't assigned the output anywhere, so it just wastes memory
712(for a little while). Plus you forgot to check C<$?> to see whether
713the program even ran correctly. Even if you wrote
714
715 print `cat /etc/termcap`;
716
717In most cases, this could and probably should be written as
718
719 system("cat /etc/termcap") == 0
720 or die "cat program failed!";
721
722Which will get the output quickly (as its generated, instead of only
c8db1d39 723at the end) and also check the return value.
68dc0745
PP
724
725system() also provides direct control over whether shell wildcard
726processing may take place, whereas backticks do not.
727
728=head2 How can I call backticks without shell processing?
729
730This is a bit tricky. Instead of writing
731
732 @ok = `grep @opts '$search_string' @filenames`;
733
734You have to do this:
735
736 my @ok = ();
737 if (open(GREP, "-|")) {
738 while (<GREP>) {
739 chomp;
740 push(@ok, $_);
741 }
742 close GREP;
743 } else {
744 exec 'grep', @opts, $search_string, @filenames;
745 }
746
747Just as with system(), no shell escapes happen when you exec() a list.
748
c8db1d39
TC
749There are more examples of this L<perlipc/"Safe Pipe Opens">.
750
54310121 751=head2 Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)?
68dc0745
PP
752
753Because some stdio's set error and eof flags that need clearing. The
754POSIX module defines clearerr() that you can use. That is the
755technically correct way to do it. Here are some less reliable
756workarounds:
757
758=over 4
759
760=item 1
761
762Try keeping around the seekpointer and go there, like this:
763
764 $where = tell(LOG);
765 seek(LOG, $where, 0);
766
767=item 2
768
769If that doesn't work, try seeking to a different part of the file and
770then back.
771
772=item 3
773
774If that doesn't work, try seeking to a different part of
775the file, reading something, and then seeking back.
776
777=item 4
778
779If that doesn't work, give up on your stdio package and use sysread.
780
781=back
782
783=head2 How can I convert my shell script to perl?
784
785Learn Perl and rewrite it. Seriously, there's no simple converter.
786Things that are awkward to do in the shell are easy to do in Perl, and
787this very awkwardness is what would make a shell->perl converter
788nigh-on impossible to write. By rewriting it, you'll think about what
789you're really trying to do, and hopefully will escape the shell's
46fc3d4c 790pipeline datastream paradigm, which while convenient for some matters,
68dc0745
PP
791causes many inefficiencies.
792
793=head2 Can I use perl to run a telnet or ftp session?
794
46fc3d4c
PP
795Try the Net::FTP, TCP::Client, and Net::Telnet modules (available from
796CPAN). http://www.perl.com/CPAN/scripts/netstuff/telnet.emul.shar
797will also help for emulating the telnet protocol, but Net::Telnet is
798quite probably easier to use..
799
800If all you want to do is pretend to be telnet but don't need
801the initial telnet handshaking, then the standard dual-process
802approach will suffice:
803
804 use IO::Socket; # new in 5.004
805 $handle = IO::Socket::INET->new('www.perl.com:80')
806 || die "can't connect to port 80 on www.perl.com: $!";
807 $handle->autoflush(1);
808 if (fork()) { # XXX: undef means failure
809 select($handle);
810 print while <STDIN>; # everything from stdin to socket
811 } else {
812 print while <$handle>; # everything from socket to stdout
813 }
814 close $handle;
815 exit;
68dc0745
PP
816
817=head2 How can I write expect in Perl?
818
819Once upon a time, there was a library called chat2.pl (part of the
c8db1d39
TC
820standard perl distribution), which never really got finished. If you
821find it somewhere, I<don't use it>. These days, your best bet is to
822look at the Expect module available from CPAN, which also requires two
823other modules from CPAN, IO::Pty and IO::Stty.
68dc0745
PP
824
825=head2 Is there a way to hide perl's command line from programs such as "ps"?
826
827First of all note that if you're doing this for security reasons (to
828avoid people seeing passwords, for example) then you should rewrite
829your program so that critical information is never given as an
830argument. Hiding the arguments won't make your program completely
831secure.
832
833To actually alter the visible command line, you can assign to the
834variable $0 as documented in L<perlvar>. This won't work on all
835operating systems, though. Daemon programs like sendmail place their
836state there, as in:
837
838 $0 = "orcus [accepting connections]";
839
840=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?
841
842=over 4
843
844=item Unix
845
846In the strictest sense, it can't be done -- the script executes as a
847different process from the shell it was started from. Changes to a
848process are not reflected in its parent, only in its own children
849created after the change. There is shell magic that may allow you to
850fake it by eval()ing the script's output in your shell; check out the
92c2ed05 851comp.unix.questions FAQ for details.
68dc0745 852
68dc0745
PP
853=back
854
855=head2 How do I close a process's filehandle without waiting for it to complete?
856
857Assuming your system supports such things, just send an appropriate signal
858to the process (see L<perlfunc/"kill">. It's common to first send a TERM
859signal, wait a little bit, and then send a KILL signal to finish it off.
860
861=head2 How do I fork a daemon process?
862
863If by daemon process you mean one that's detached (disassociated from
864its tty), then the following process is reported to work on most
865Unixish systems. Non-Unix users should check their Your_OS::Process
866module for other solutions.
867
868=over 4
869
870=item *
871
b5a41e52 872Open /dev/tty and use the TIOCNOTTY ioctl on it. See L<tty(4)>
c8db1d39
TC
873for details. Or better yet, you can just use the POSIX::setsid()
874function, so you don't have to worry about process groups.
68dc0745
PP
875
876=item *
877
878Change directory to /
879
880=item *
881
882Reopen STDIN, STDOUT, and STDERR so they're not connected to the old
883tty.
884
885=item *
886
887Background yourself like this:
888
889 fork && exit;
890
891=back
892
893=head2 How do I make my program run with sh and csh?
894
895See the F<eg/nih> script (part of the perl source distribution).
896
68dc0745
PP
897=head2 How do I find out if I'm running interactively or not?
898
899Good question. Sometimes C<-t STDIN> and C<-t STDOUT> can give clues,
900sometimes not.
901
902 if (-t STDIN && -t STDOUT) {
903 print "Now what? ";
904 }
905
906On POSIX systems, you can test whether your own process group matches
907the current process group of your controlling terminal as follows:
908
909 use POSIX qw/getpgrp tcgetpgrp/;
910 open(TTY, "/dev/tty") or die $!;
911 $tpgrp = tcgetpgrp(TTY);
912 $pgrp = getpgrp();
913 if ($tpgrp == $pgrp) {
914 print "foreground\n";
915 } else {
916 print "background\n";
917 }
918
919=head2 How do I timeout a slow event?
920
921Use the alarm() function, probably in conjunction with a signal
922handler, as documented L<perlipc/"Signals"> and chapter 6 of the
923Camel. You may instead use the more flexible Sys::AlarmCall module
924available from CPAN.
925
926=head2 How do I set CPU limits?
927
928Use the BSD::Resource module from CPAN.
929
930=head2 How do I avoid zombies on a Unix system?
931
932Use the reaper code from L<perlipc/"Signals"> to call wait() when a
933SIGCHLD is received, or else use the double-fork technique described
934in L<perlfunc/fork>.
935
936=head2 How do I use an SQL database?
937
938There are a number of excellent interfaces to SQL databases. See the
939DBD::* modules available from
940http://www.perl.com/CPAN/modules/dbperl/DBD .
c8db1d39
TC
941A lot of information on this can be found at
942http://www.hermetica.com/technologia/perl/DBI/index.html .
68dc0745
PP
943
944=head2 How do I make a system() exit on control-C?
945
946You can't. You need to imitate the system() call (see L<perlipc> for
947sample code) and then have a signal handler for the INT signal that
c8db1d39
TC
948passes the signal on to the subprocess. Or you can check for it:
949
950 $rc = system($cmd);
951 if ($rc & 127) { die "signal death" }
68dc0745
PP
952
953=head2 How do I open a file without blocking?
954
955If you're lucky enough to be using a system that supports
956non-blocking reads (most Unixish systems do), you need only to use the
957O_NDELAY or O_NONBLOCK flag from the Fcntl module in conjunction with
958sysopen():
959
960 use Fcntl;
961 sysopen(FH, "/tmp/somefile", O_WRONLY|O_NDELAY|O_CREAT, 0644)
962 or die "can't open /tmp/somefile: $!":
963
964=head2 How do I install a CPAN module?
965
966The easiest way is to have the CPAN module do it for you. This module
967comes with perl version 5.004 and later. To manually install the CPAN
968module, or any well-behaved CPAN module for that matter, follow these
969steps:
970
971=over 4
972
973=item 1
974
975Unpack the source into a temporary area.
976
977=item 2
978
979 perl Makefile.PL
980
981=item 3
982
983 make
984
985=item 4
986
987 make test
988
989=item 5
990
991 make install
992
993=back
994
995If your version of perl is compiled without dynamic loading, then you
996just need to replace step 3 (B<make>) with B<make perl> and you will
997get a new F<perl> binary with your extension linked in.
998
c8db1d39
TC
999See L<ExtUtils::MakeMaker> for more details on building extensions.
1000See also the next question.
1001
1002=head2 What's the difference between require and use?
1003
1004Perl offers several different ways to include code from one file into
1005another. Here are the deltas between the various inclusion constructs:
1006
1007 1) do $file is like eval `cat $file`, except the former:
5e3006a4 1008 1.1: searches @INC and updates %INC.
c8db1d39
TC
1009 1.2: bequeaths an *unrelated* lexical scope on the eval'ed code.
1010
1011 2) require $file is like do $file, except the former:
1012 2.1: checks for redundant loading, skipping already loaded files.
1013 2.2: raises an exception on failure to find, compile, or execute $file.
1014
1015 3) require Module is like require "Module.pm", except the former:
1016 3.1: translates each "::" into your system's directory separator.
1017 3.2: primes the parser to disambiguate class Module as an indirect object.
1018
1019 4) use Module is like require Module, except the former:
1020 4.1: loads the module at compile time, not run-time.
1021 4.2: imports symbols and semantics from that package to the current one.
1022
1023In general, you usually want C<use> and a proper Perl module.
46fc3d4c
PP
1024
1025=head2 How do I keep my own module/library directory?
1026
1027When you build modules, use the PREFIX option when generating
1028Makefiles:
1029
1030 perl Makefile.PL PREFIX=/u/mydir/perl
1031
1032then either set the PERL5LIB environment variable before you run
1033scripts that use the modules/libraries (see L<perlrun>) or say
1034
1035 use lib '/u/mydir/perl';
1036
1037See Perl's L<lib> for more information.
1038
1039=head2 How do I add the directory my program lives in to the module/library search path?
1040
1041 use FindBin;
7b8d334a 1042 use lib "$FindBin::Bin";
46fc3d4c
PP
1043 use your_own_modules;
1044
1045=head2 How do I add a directory to my include path at runtime?
1046
1047Here are the suggested ways of modifying your include path:
1048
1049 the PERLLIB environment variable
1050 the PERL5LIB environment variable
1051 the perl -Idir commpand line flag
1052 the use lib pragma, as in
1053 use lib "$ENV{HOME}/myown_perllib";
1054
1055The latter is particularly useful because it knows about machine
1056dependent architectures. The lib.pm pragmatic module was first
1057included with the 5.002 release of Perl.
68dc0745 1058
fc36a67e
PP
1059=head1 AUTHOR AND COPYRIGHT
1060
5a964f20
TC
1061Copyright (c) 1997, 1998 Tom Christiansen and Nathan Torkington.
1062All rights reserved.
1063
1064When included as part of the Standard Version of Perl, or as part of
1065its complete documentation whether printed or otherwise, this work
1066may be distributed only under the terms of Perl's Artistic License.
1067Any distribution of this file or derivatives thereof I<outside>
1068of that package require that special arrangements be made with
1069copyright holder.
1070
1071Irrespective of its distribution, all code examples in this file
1072are hereby placed into the public domain. You are permitted and
1073encouraged to use this code in your own programs for fun
1074or for profit as you see fit. A simple comment in the code giving
1075credit would be courteous but is not required.