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