NAME

    IPC::Run - system() and background procs w/ piping, redirs, ptys (Unix,

    Win32)

SYNOPSIS

       ## First,a command to run:

          my @cat = qw( cat );

       ## Using run() instead of system():

          use IPC::Run qw( run timeout );

          run \@cat, \$in, \$out, \$err, timeout( 10 ) or die "cat: $?"

          # Can do I/O to sub refs and filenames, too:

          run \@cat, '<', "in.txt", \&out, \&err or die "cat: $?"

          run \@cat, '<', "in.txt", '>>', "out.txt", '2>>', "err.txt";

          # Redirecting using pseudo-terminals instead of pipes.

          run \@cat, '<pty<', \$in,  '>pty>', \$out_and_err;

       ## Scripting subprocesses (like Expect):

          use IPC::Run qw( start pump finish timeout );

          # Incrementally read from / write to scalars. 

          # $in is drained as it is fed to cat's stdin,

          # $out accumulates cat's stdout

          # $err accumulates cat's stderr

          # $h is for "harness".

          my $h = start \@cat, \$in, \$out, \$err, timeout( 10 );

          $in .= "some input\n";

          pump $h until $out =~ /input\n/g;

          $in .= "some more input\n";

          pump $h until $out =~ /\G.*more input\n/;

          $in .= "some final input\n";

          finish $h or die "cat returned $?";

          warn $err if $err; 

          print $out;         ## All of cat's output

       # Piping between children

          run \@cat, '|', \@gzip;

       # Multiple children simultaneously (run() blocks until all

       # children exit, use start() for background execution):

          run \@foo1, '&', \@foo2;

       # Calling \&set_up_child in the child before it executes the

       # command (only works on systems with true fork() & exec())

       # exceptions thrown in set_up_child() will be propagated back

       # to the parent and thrown from run().

          run \@cat, \$in, \$out,

             init => \&set_up_child;

       # Read from / write to file handles you open and close

          open IN,  '

          open OUT, '>out.txt' or die $!;

          print OUT "preamble\n";

          run \@cat, \*IN, \*OUT or die "cat returned $?";

          print OUT "postamble\n";

          close IN;

          close OUT;

       # Create pipes for you to read / write (like IPC::Open2 & 3).

          $h = start

             \@cat,

                '

                '>pipe', \*OUT,

                '2>pipe', \*ERR 

             or die "cat returned $?";

          print IN "some input\n";

          close IN;

          print <OUT>, <ERR>;

          finish $h;

       # Mixing input and output modes

          run \@cat, 'in.txt', \&catch_some_out, \*ERR_LOG );

       # Other redirection constructs

          run \@cat, '>&', \$out_and_err;

          run \@cat, '2>&1;;

          run \@cat, '0<&3;;

          run \@cat, '<&-;;

          run \@cat, '3<', \$in3;

          run \@cat, '4>', \$out4;

          # etc.

       # Passing options:

          run \@cat, 'in.txt', debug => 1;

       # Call this system's shell, returns TRUE on 0 exit code

       # THIS IS THE OPPOSITE SENSE OF system()'s RETURN VALUE

          run "cat a b c" or die "cat returned $?";

       # Launch a sub process directly, no shell.  Can't do redirection

       # with this form, it's here to behave like system() with an

       # inverted result.

          $r = run "cat a b c";

       # Read from a file in to a scalar

          run io( "filename", 'r', \$recv );

          run io( \*HANDLE,   'r', \$recv );

DESCRIPTION

    IPC::Run allows you to run and interact with child processes using

    files, pipes, and pseudo-ttys. Both system()-style and scripted usages

    are supported and may be mixed. Likewise, functional and OO API styles

    are both supported and may be mixed.

    Various redirection operators reminiscent of those seen on common Unix

    and DOS command lines are provided.

    Before digging in to the details a few LIMITATIONS are important enough

    to be mentioned right up front:

    Win32 Support

        Win32 support is working but EXPERIMENTAL, but does pass all

        relevant tests on NT 4.0. See "Win32 LIMITATIONS".

    pty Support

        If you need pty support, IPC::Run should work well enough most of

        the time, but IO::Pty is being improved, and IPC::Run will be

        improved to use IO::Pty's new features when it is release.

        The basic problem is that the pty needs to initialize itself before

        the parent writes to the master pty, or the data written gets lost.

        So IPC::Run does a sleep(1) in the parent after forking to

        (hopefully) give the child a chance to run. This is a kludge that

        works well on non heavily loaded systems :(.

        ptys are not supported yet under Win32, but will be emulated...

    Debugging Tip

        You may use the environment variable "IPCRUNDEBUG" to see what's

        going on under the hood:

           $ IPCRUNDEBUG=basic   myscript     # prints minimal debugging

           $ IPCRUNDEBUG=data    myscript     # prints all data reads/writes

           $ IPCRUNDEBUG=details myscript     # prints lots of low-level details

           $ IPCRUNDEBUG=gory    myscript     # (Win32 only) prints data moving through

                                              # the helper processes.

    We now return you to your regularly scheduled documentation.

  Harnesses

    Child processes and I/O handles are gathered in to a harness, then

    started and run until the processing is finished or aborted.

  run() vs. start(); pump(); finish();

    There are two modes you can run harnesses in: run() functions as an

    enhanced system(), and start()/pump()/finish() allow for background

    processes and scripted interactions with them.

    When using run(), all data to be sent to the harness is set up in

    advance (though one can feed subprocesses input from subroutine refs to

    get around this limitation). The harness is run and all output is

    collected from it, then any child processes are waited for:

       run \@cmd, \<

       blah

       IN

       ## To precompile harnesses and run them later:

       my $h = harness \@cmd, \<

       blah

       IN

       run $h;

    The background and scripting API is provided by start(), pump(), and

    finish(): start() creates a harness if need be (by calling harness())

    and launches any subprocesses, pump() allows you to poll them for

    activity, and finish() then monitors the harnessed activities until they

    complete.

       ## Build the harness, open all pipes, and launch the subprocesses

       my $h = start \@cat, \$in, \$out;

       $in = "first input\n";

       ## Now do I/O.  start() does no I/O.

       pump $h while length $in;  ## Wait for all input to go

       ## Now do some more I/O.

       $in = "second input\n";

       pump $h until $out =~ /second input/;

       ## Clean up

       finish $h or die "cat returned $?";

    You can optionally compile the harness with harness() prior to

    start()ing or run()ing, and you may omit start() between harness() and

    pump(). You might want to do these things if you compile your harnesses

    ahead of time.

  Using regexps to match output

    As shown in most of the scripting examples, the read-to-scalar facility

    for gathering subcommand's output is often used with regular expressions

    to detect stopping points. This is because subcommand output often

    arrives in dribbles and drabs, often only a character or line at a time.

    This output is input for the main program and piles up in variables like

    the $out and $err in our examples.

    Regular expressions can be used to wait for appropriate output in

    several ways. The "cat" example in the previous section demonstrates how

    to pump() until some string appears in the output. Here's an example

    that uses "smb" to fetch files from a remote server:

       $h = harness \@smbclient, \$in, \$out;

       $in = "cd /src\n";

       $h->pump until $out =~ /^smb.*> \Z/m;

       die "error cding to /src:\n$out" if $out =~ "ERR";

       $out = '';

       $in = "mget *\n";

       $h->pump until $out =~ /^smb.*> \Z/m;

       die "error retrieving files:\n$out" if $out =~ "ERR";

       $in = "quit\n";

       $h->finish;

    Notice that we carefully clear $out after the first command/response

    cycle? That's because IPC::Run does not delete $out when we continue,

    and we don't want to trip over the old output in the second

    command/response cycle.

    Say you want to accumulate all the output in $out and analyze it

    afterwards. Perl offers incremental regular expression matching using

    the "m//gc" and pattern matching idiom and the "\G" assertion. IPC::Run

    is careful not to disturb the current "pos()" value for scalars it

    appends data to, so we could modify the above so as not to destroy $out

    by adding a couple of "/gc" modifiers. The "/g" keeps us from tripping

    over the previous prompt and the "/c" keeps us from resetting the prior

    match position if the expected prompt doesn't materialize immediately:

       $h = harness \@smbclient, \$in, \$out;

       $in = "cd /src\n";

       $h->pump until $out =~ /^smb.*> \Z/mgc;

       die "error cding to /src:\n$out" if $out =~ "ERR";

       $in = "mget *\n";

       $h->pump until $out =~ /^smb.*> \Z/mgc;

       die "error retrieving files:\n$out" if $out =~ "ERR";

       $in = "quit\n";

       $h->finish;

       analyze( $out );

    When using this technique, you may want to preallocate $out to have

    plenty of memory or you may find that the act of growing $out each time

    new input arrives causes an "O(length($out)^2)" slowdown as $out grows.

    Say we expect no more than 10,000 characters of input at the most. To

    preallocate memory to $out, do something like:

       my $out = "x" x 10_000;

       $out = "";

    "perl" will allocate at least 10,000 characters' worth of space, then

    mark the $out as having 0 length without freeing all that yummy RAM.

  Timeouts and Timers

    More than likely, you don't want your subprocesses to run forever, and

    sometimes it's nice to know that they're going a little slowly. Timeouts

    throw exceptions after a some time has elapsed, timers merely cause

    pump() to return after some time has elapsed. Neither is reset/restarted

    automatically.

    Timeout objects are created by calling timeout( $interval ) and passing

    the result to run(), start() or harness(). The timeout period starts

    ticking just after all the child processes have been fork()ed or

    spawn()ed, and are polled for expiration in run(), pump() and finish().

    If/when they expire, an exception is thrown. This is typically useful to

    keep a subprocess from taking too long.

    If a timeout occurs in run(), all child processes will be terminated and

    all file/pipe/ptty descriptors opened by run() will be closed. File

    descriptors opened by the parent process and passed in to run() are not

    closed in this event.

    If a timeout occurs in pump(), pump_nb(), or finish(), it's up to you to

    decide whether to kill_kill() all the children or to implement some more

    graceful fallback. No I/O will be closed in pump(), pump_nb() or

    finish() by such an exception (though I/O is often closed down in those

    routines during the natural course of events).

    Often an exception is too harsh. timer( $interval ) creates timer

    objects that merely prevent pump() from blocking forever. This can be

    useful for detecting stalled I/O or printing a soothing message or "."

    to pacify an anxious user.

    Timeouts and timers can both be restarted at any time using the timer's

    start() method (this is not the start() that launches subprocesses). To

    restart a timer, you need to keep a reference to the timer:

       ## Start with a nice long timeout to let smbclient connect.  If

       ## pump or finish take too long, an exception will be thrown.

     my $h;

     eval {

       $h = harness \@smbclient, \$in, \$out, \$err, ( my $t = timeout 30 );

       sleep 11;  # No effect: timer not running yet

       start $h;

       $in = "cd /src\n";

       pump $h until ! length $in;

       $in = "ls\n";

       ## Now use a short timeout, since this should be faster

       $t->start( 5 );

       pump $h until ! length $in;

       $t->start( 10 );  ## Give smbclient a little while to shut down.

       $h->finish;

     };

     if ( $@ ) {

       my $x = $@;    ## Preserve $@ in case another exception occurs

       $h->kill_kill; ## kill it gently, then brutally if need be, or just

                       ## brutally on Win32.

       die $x;

     }

    Timeouts and timers are *not* checked once the subprocesses are shut

    down; they will not expire in the interval between the last valid

    process and when IPC::Run scoops up the processes' result codes, for

    instance.

  Spawning synchronization, child exception propagation

    start() pauses the parent until the child executes the command or CODE

    reference and propagates any exceptions thrown (including exec()

    failure) back to the parent. This has several pleasant effects: any

    exceptions thrown in the child, including exec() failure, come flying

    out of start() or run() as though they had occurred in the parent.

    This includes exceptions your code thrown from init subs. In this

    example:

       eval {

          run \@cmd, init => sub { die "blast it! foiled again!" };

       };

       print $@;

    the exception "blast it! foiled again" will be thrown from the child

    process (preventing the exec()) and printed by the parent.

    In situations like

       run \@cmd1, "|", \@cmd2, "|", \@cmd3;

    @cmd1 will be initted and exec()ed before @cmd2, and @cmd2 before @cmd3.

    This can save time and prevent oddball errors emitted by later commands

    when earlier commands fail to execute. Note that IPC::Run doesn't start

    any commands unless it can find the executables referenced by all

    commands. These executables must pass both the "-f" and "-x" tests

    described in perlfunc.

    Another nice effect is that init() subs can take their time doing things

    and there will be no problems caused by a parent continuing to execute

    before a child's init() routine is complete. Say the init() routine

    needs to open a socket or a temp file that the parent wants to connect

    to; without this synchronization, the parent will need to implement a

    retry loop to wait for the child to run, since often, the parent gets a

    lot of things done before the child's first timeslice is allocated.

    This is also quite necessary for pseudo-tty initialization, which needs

    to take place before the parent writes to the child via pty. Writes that

    occur before the pty is set up can get lost.

    A final, minor, nicety is that debugging output from the child will be

    emitted before the parent continues on, making for much clearer

    debugging output in complex situations.

    The only drawback I can conceive of is that the parent can't continue to

    operate while the child is being initted. If this ever becomes a problem

    in the field, we can implement an option to avoid this behavior, but I

    don't expect it to.

    Win32: executing CODE references isn't supported on Win32, see "Win32

    LIMITATIONS" for details.

  Syntax

    run(), start(), and harness() can all take a harness specification as

    input. A harness specification is either a single string to be passed to

    the systems' shell:

       run "echo 'hi there'";

    or a list of commands, io operations, and/or timers/timeouts to execute.

    Consecutive commands must be separated by a pipe operator '|' or an '&'.

    External commands are passed in as array references, and, on systems

    supporting fork(), Perl code may be passed in as subs:

       run \@cmd;

       run \@cmd1, '|', \@cmd2;

       run \@cmd1, '&', \@cmd2;

       run \&sub1;

       run \&sub1, '|', \&sub2;

       run \&sub1, '&', \&sub2;

    '|' pipes the stdout of \@cmd1 the stdin of \@cmd2, just like a shell

    pipe. '&' does not. Child processes to the right of a '&' will have

    their stdin closed unless it's redirected-to.

    IPC::Run::IO objects may be passed in as well, whether or not child

    processes are also specified:

       run io( "infile", ">", \$in ), io( "outfile", "<", \$in );

    as can IPC::Run::Timer objects:

       run \@cmd, io( "outfile", "<", \$in ), timeout( 10 );

    Commands may be followed by scalar, sub, or i/o handle references for

    redirecting child process input & output:

       run \@cmd,  \undef,            \$out;

       run \@cmd,  \$in,              \$out;

       run \@cmd1, \&in, '|', \@cmd2, \*OUT;

       run \@cmd1, \*IN, '|', \@cmd2, \&out;

    This is known as succinct redirection syntax, since run(), start() and

    harness(), figure out which file descriptor to redirect and how. File

    descriptor 0 is presumed to be an input for the child process, all

    others are outputs. The assumed file descriptor always starts at 0,

    unless the command is being piped to, in which case it starts at 1.

    To be explicit about your redirects, or if you need to do more complex

    things, there's also a redirection operator syntax:

       run \@cmd, '<', \undef, '>',  \$out;

       run \@cmd, '<', \undef, '>&', \$out_and_err;

       run(

          \@cmd1,

             '<', \$in,

          '|', \@cmd2,

             \$out

       );

    Operator syntax is required if you need to do something other than

    simple redirection to/from scalars or subs, like duping or closing file

    descriptors or redirecting to/from a named file. The operators are

    covered in detail below.

    After each \@cmd (or \&foo), parsing begins in succinct mode and toggles

    to operator syntax mode when an operator (ie plain scalar, not a ref) is

    seen. Once in operator syntax mode, parsing only reverts to succinct

    mode when a '|' or '&' is seen.

    In succinct mode, each parameter after the \@cmd specifies what to do

    with the next highest file descriptor. These File descriptor start with

    0 (stdin) unless stdin is being piped to ("'|', \@cmd"), in which case

    they start with 1 (stdout). Currently, being on the left of a pipe

    ("\@cmd, \$out, \$err, '|'") does *not* cause stdout to be skipped,

    though this may change since it's not as DWIMerly as it could be. Only

    stdin is assumed to be an input in succinct mode, all others are assumed

    to be outputs.

    If no piping or redirection is specified for a child, it will inherit

    the parent's open file handles as dictated by your system's

    close-on-exec behavior and the $^F flag, except that processes after a

    '&' will not inherit the parent's stdin. Also note that $^F does not

    affect file descriptors obtained via POSIX, since it only applies to

    full-fledged Perl file handles. Such processes will have their stdin

    closed unless it has been redirected-to.

    If you want to close a child processes stdin, you may do any of:

       run \@cmd, \undef;

       run \@cmd, \"";

       run \@cmd, '<&-;;

       run \@cmd, '0<&-;;

    Redirection is done by placing redirection specifications immediately

    after a command or child subroutine:

       run \@cmd1,      \$in, '|', \@cmd2,      \$out;

       run \@cmd1, '<', \$in, '|', \@cmd2, '>', \$out;

    If you omit the redirection operators, descriptors are counted starting

    at 0. Descriptor 0 is assumed to be input, all others are outputs. A

    leading '|' consumes descriptor 0, so this works as expected.

       run \@cmd1, \$in, '|', \@cmd2, \$out;

    The parameter following a redirection operator can be a scalar ref, a

    subroutine ref, a file name, an open filehandle, or a closed filehandle.

    If it's a scalar ref, the child reads input from or sends output to that

    variable:

       $in = "Hello World.\n";

       run \@cat, \$in, \$out;

       print $out;

    Scalars used in incremental (start()/pump()/finish()) applications are

    treated as queues: input is removed from input scalers, resulting in

    them dwindling to '', and output is appended to output scalars. This is

    not true of harnesses run() in batch mode.

    It's usually wise to append new input to be sent to the child to the

    input queue, and you'll often want to zap output queues to '' before

    pumping.

       $h = start \@cat, \$in;

       $in = "line 1\n";

       pump $h;

       $in .= "line 2\n";

       pump $h;

       $in .= "line 3\n";

       finish $h;

    The final call to finish() must be there: it allows the child

    process(es) to run to completion and waits for their exit values.

OBSTINATE CHILDREN

    Interactive applications are usually optimized for human use. This can

    help or hinder trying to interact with them through modules like

    IPC::Run. Frequently, programs alter their behavior when they detect

    that stdin, stdout, or stderr are not connected to a tty, assuming that

    they are being run in batch mode. Whether this helps or hurts depends on

    which optimizations change. And there's often no way of telling what a

    program does in these areas other than trial and error and occasionally,

    reading the source. This includes different versions and implementations

    of the same program.

    All hope is not lost, however. Most programs behave in reasonably

    tractable manners, once you figure out what it's trying to do.

    Here are some of the issues you might need to be aware of.

    *   fflush()ing stdout and stderr

        This lets the user see stdout and stderr immediately. Many programs

        undo this optimization if stdout is not a tty, making them harder to

        manage by things like IPC::Run.

        Many programs decline to fflush stdout or stderr if they do not

        detect a tty there. Some ftp commands do this, for instance.

        If this happens to you, look for a way to force interactive

        behavior, like a command line switch or command. If you can't, you

        will need to use a pseudo terminal ('<pty<' and '>pty>').

    *   false prompts

        Interactive programs generally do not guarantee that output from

        user commands won't contain a prompt string. For example, your shell

        prompt might be a '$', and a file named '$' might be the only file

        in a directory listing.

        This can make it hard to guarantee that your output parser won't be

        fooled into early termination of results.

        To help work around this, you can see if the program can alter it's

        prompt, and use something you feel is never going to occur in actual

        practice.

        You should also look for your prompt to be the only thing on a line:

           pump $h until $out =~ /^<SILLYPROMPT>\s?\z/m;

        (use "(?!\n)\Z" in place of "\z" on older perls).

        You can also take the approach that IPC::ChildSafe takes and emit a

        command with known output after each 'real' command you issue, then

        look for this known output. See new_appender() and new_chunker() for

        filters that can help with this task.

        If it's not convenient or possibly to alter a prompt or use a known

        command/response pair, you might need to autodetect the prompt in

        case the local version of the child program is different then the

        one you tested with, or if the user has control over the look & feel

        of the prompt.

    *   Refusing to accept input unless stdin is a tty.

        Some programs, for security reasons, will only accept certain types

        of input from a tty. su, notable, will not prompt for a password

        unless it's connected to a tty.

        If this is your situation, use a pseudo terminal ('

        '>pty>').

    *   Not prompting unless connected to a tty.

        Some programs don't prompt unless stdin or stdout is a tty. See if

        you can turn prompting back on. If not, see if you can come up with

        a command that you can issue after every real command and look for

        it's output, as IPC::ChildSafe does. There are two filters included

        with IPC::Run that can help with doing this: appender and chunker

        (see new_appender() and new_chunker()).

    *   Different output format when not connected to a tty.

        Some commands alter their formats to ease machine parsability when

        they aren't connected to a pipe. This is actually good, but can be

        surprising.

PSEUDO TERMINALS

    On systems providing pseudo terminals under /dev, IPC::Run can use

    IO::Pty (available on CPAN) to provide a terminal environment to

    subprocesses. This is necessary when the subprocess really wants to

    think it's connected to a real terminal.

  CAVEATS

    Pseudo-terminals are not pipes, though they are similar. Here are some

    differences to watch out for.

    Echoing

        Sending to stdin will cause an echo on stdout, which occurs before

        each line is passed to the child program. There is currently no way

        to disable this, although the child process can and should disable

        it for things like passwords.

    Shutdown

        IPC::Run cannot close a pty until all output has been collected.

        This means that it is not possible to send an EOF to stdin by

        half-closing the pty, as we can when using a pipe to stdin.

        This means that you need to send the child process an exit command

        or signal, or run() / finish() will time out. Be careful not to

        expect a prompt after sending the exit command.

    Command line editing

        Some subprocesses, notable shells that depend on the user's prompt

        settings, will reissue the prompt plus the command line input so far

        once for each character.

    '>pty>' means '&>pty>', not '1>pty>'

        The pseudo terminal redirects both stdout and stderr unless you

        specify a file descriptor. If you want to grab stderr separately, do

        this:

           start \@cmd, '<pty<', \$in, '>pty>', \$out, '2>', \$err;

    stdin, stdout, and stderr not inherited

        Child processes harnessed to a pseudo terminal have their stdin,

        stdout, and stderr completely closed before any redirection

        operators take effect. This casts of the bonds of the controlling

        terminal. This is not done when using pipes.

        Right now, this affects all children in a harness that has a pty in

        use, even if that pty would not affect a particular child. That's a

        bug and will be fixed. Until it is, it's best not to mix-and-match

        children.

  Redirection Operators

       Operator       SHNP   Description

       ========       ====   ===========

       <, N<          SHN    Redirects input to a child's fd N (0 assumed)

       >, N>          SHN    Redirects output from a child's fd N (1 assumed)

       >>, N>>        SHN    Like '>', but appends to scalars or named files

       >&, &>         SHN    Redirects stdout & stderr from a child process

       >pty, N>pty    S      Like '>', but uses a pseudo-tty instead of a pipe

       N<&M                  Dups input fd N to input fd M

       M>&N                  Dups output fd N to input fd M

       N<&-                  Closes fd N

       >pipe, N>pipe     P   Pipe opens H for caller to read, write, close.

    'N' and 'M' are placeholders for integer file descriptor numbers. The

    terms 'input' and 'output' are from the child process's perspective.

    The SHNP field indicates what parameters an operator can take:

       S: \$scalar or \&function references.  Filters may be used with

          these operators (and only these).

       H: \*HANDLE or IO::Handle for caller to open, and close

       N: "file name".

       P: \*HANDLE opened by IPC::Run as the parent end of a pipe, but read

          and written to and closed by the caller (like IPC::Open3).

    Redirecting input: [n]<, [n]

        You can input the child reads on file descriptor number n to come

        from a scalar variable, subroutine, file handle, or a named file. If

        stdin is not redirected, the parent's stdin is inherited.

           run \@cat, \undef          ## Closes child's stdin immediately

              or die "cat returned $?"; 

           run \@cat, \$in;

           run \@cat, \<

           blah

           TOHERE

           run \@cat, \&input;       ## Calls &input, feeding data returned

                                      ## to child's.  Closes child's stdin

                                      ## when undef is returned.

        Redirecting from named files requires you to use the input

        redirection operator:

           run \@cat, '<.profile';

           run \@cat, '<', '.profile';

           open IN, "

           run \@cat, \*IN;

           run \@cat, *IN{IO};

        The form used second example here is the safest, since filenames

        like "0" and "&more\n" won't confuse &run:

        You can't do either of

           run \@a, *IN;      ## INVALID

           run \@a, '<', *IN; ## BUGGY: Reads file named like "*main::A"

        because perl passes a scalar containing a string that looks like

        "*main::A" to &run, and &run can't tell the difference between that

        and a redirection operator or a file name. &run guarantees that any

        scalar you pass after a redirection operator is a file name.

        If your child process will take input from file descriptors other

        than 0 (stdin), you can use a redirection operator with any of the

        valid input forms (scalar ref, sub ref, etc.):

           run \@cat, '3<', \$in3;

        When redirecting input from a scalar ref, the scalar ref is used as

        a queue. This allows you to use &harness and pump() to feed

        incremental bits of input to a coprocess. See "Coprocesses" below

        for more information.

        The 

        glob reference it takes as an argument:

           $h = start \@cat, '

           print IN "hello world\n";

           pump $h;

           close IN;

           finish $h;

        Unlike the other '<' operators, IPC::Run does nothing further with

        it: you are responsible for it. The previous example is functionally

        equivalent to:

           pipe( \*R, \*IN ) or die $!;

           $h = start \@cat, '<', \*IN;

           print IN "hello world\n";

           pump $h;

           close IN;

           finish $h;

        This is like the behavior of IPC::Open2 and IPC::Open3.

        Win32: The handle returned is actually a socket handle, so you can

        use select() on it.

    Redirecting output: [n]>, [n]>>, [n]>&[m], [n]>pipe

        You can redirect any output the child emits to a scalar variable,

        subroutine, file handle, or file name. You can have &run truncate or

        append to named files or scalars. If you are redirecting stdin as

        well, or if the command is on the receiving end of a pipeline ('|'),

        you can omit the redirection operator:

           @ls = ( 'ls' );

           run \@ls, \undef, \$out

              or die "ls returned $?"; 

           run \@ls, \undef, \&out;  ## Calls &out each time some output

                                      ## is received from the child's 

                                      ## when undef is returned.

           run \@ls, \undef, '2>ls.err';

           run \@ls, '2>', 'ls.err';

        The two parameter form guarantees that the filename will not be

        interpreted as a redirection operator:

           run \@ls, '>', "&more";

           run \@ls, '2>', ">foo\n";

        You can pass file handles you've opened for writing:

           open( *OUT, ">out.txt" );

           open( *ERR, ">err.txt" );

           run \@cat, \*OUT, \*ERR;

        Passing a scalar reference and a code reference requires a little

        more work, but allows you to capture all of the output in a scalar

        or each piece of output by a callback:

        These two do the same things:

           run( [ 'ls' ], '2>', sub { $err_out .= $_[0] } );

        does the same basic thing as:

           run( [ 'ls' ], '2>', \$err_out );

        The subroutine will be called each time some data is read from the

        child.

        The >pipe operator is different in concept than the other '>'

        operators, although it's syntax is similar:

           $h = start \@cat, $in, '>pipe', \*OUT, '2>pipe', \*ERR;

           $in = "hello world\n";

           finish $h;

           print <OUT>;

           print <ERR>;

           close OUT;

           close ERR;

        causes two pipe to be created, with one end attached to cat's stdout

        and stderr, respectively, and the other left open on OUT and ERR, so

        that the script can manually read(), select(), etc. on them. This is

        like the behavior of IPC::Open2 and IPC::Open3.

        Win32: The handle returned is actually a socket handle, so you can

        use select() on it.

    Duplicating output descriptors: >&m, n>&m

        This duplicates output descriptor number n (default is 1 if n is

        omitted) from descriptor number m.

    Duplicating input descriptors: <&m, n<&m

        This duplicates input descriptor number n (default is 0 if n is

        omitted) from descriptor number m

    Closing descriptors: <&-, 3<&-

        This closes descriptor number n (default is 0 if n is omitted). The

        following commands are equivalent:

           run \@cmd, \undef;

           run \@cmd, '<&-;;

           run \@cmd, '

        Doing

           run \@cmd, \$in, '<&-;;    ## SIGPIPE recipe.

        is dangerous: the parent will get a SIGPIPE if $in is not empty.

    Redirecting both stdout and stderr: &>, >&, &>pipe, >pipe&

        The following pairs of commands are equivalent:

           run \@cmd, '>&', \$out;       run \@cmd, '>', \$out,     '2>&1;;

           run \@cmd, '>&', 'out.txt';   run \@cmd, '>', 'out.txt', '2>&1;;

        etc.

        File descriptor numbers are not permitted to the left or the right

        of these operators, and the '&' may occur on either end of the

        operator.

        The '&>pipe' and '>pipe&' variants behave like the '>pipe' operator,

        except that both stdout and stderr write to the created pipe.

    Redirection Filters

        Both input redirections and output redirections that use scalars or

        subs as endpoints may have an arbitrary number of filter subs placed

        between them and the child process. This is useful if you want to

        receive output in chunks, or if you want to massage each chunk of

        data sent to the child. To use this feature, you must use operator

        syntax:

           run(

              \@cmd

                 '<', \&in_filter_2, \&in_filter_1, $in,

                 '>', \&out_filter_1, \&in_filter_2, $out,

           );

        This capability is not provided for IO handles or named files.

        Two filters are provided by IPC::Run: appender and chunker. Because

        these may take an argument, you need to use the constructor

        functions new_appender() and new_chunker() rather than using \&

        syntax: