[Summary view] [Print] [Text view]

   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.