Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1579 insertions, 0 deletions

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