IPC::Run - Run subprocesses w/ piping, redirection, and pseudo-ttys use IPC::Run ( qw( run ), # Batch mode API qw( harness start pump finish ), # Intermittent API qw( io timer timeout ), # Helper objects. ) ; my @cat = qw( cat in.txt - ) ; ## Running a command with stdin closed, output redirected ## to scalars and a 10 second timeout: run \@cat, \undef, \$out, \$err, timeout( 10 ) or die "cat returned $?"; ## Redirecting stdin from various scalars: $in = "input" ; run \@cat, \$in, \$out, \$err, ... ; run \@cat, \"input", \$out, \$err, ... ; run \@cat, \<<TOHERE, \$out, \$err, ... ; input TOHERE ## I/O redirection using functions, filenames. You can mix ## techniques, too. run \@cat, \&in, \&out, \&err ... ; run \@cat, '<', $in_filename, '>', $out_name, '2>', $err_name ... ; ## Redirecting using psuedo-terminals. run \@cat, '<pty<', \$in, '>pty>', \$out_and_err ; run \@cat, '<pty<', \&in, '>pty>', \&out_and_err ; # Incrementally read from / write to scalars. Note that $in_q # is a queue that is drained as it is used, which is not the # way run() treats inputs. $h is for "harness". my $h = start( \@cat, \$in_q, \$out_q, \$err_q, timeout( name => "process timeout", 10 ), $stall_timeout = timeout( name => "stall timeout", 5 ), ) ; $in_q .= "some input\n" ; $stall_timeout->start ; pump $h until $out_q =~ /input/ ; warn $err_q ; $err_q = '' ; $out_q = '' ; $stall_timeout->start ; $in_q .= "some more input\n" ; pump $h until $out_q =~ /input/ ; warn $err_q ; $err_q = '' ; $in_q .= "some final input\n" ; $h->timeout( "1:00" ) ; $stall_timeout->start ; finish $h or die "cat returned $?" ; warn $err_q ; print $out_q ; # Piping between children run \@cat, '|', [qw(gzip)] ; # Multiple children simultaneously (run() blocks until all # children exit, use start() for background execution): run [qw(foo1)], '&', [qw(foo2)] ; # Spawning a subroutine (only on systems with true fork()/exec()) run \&child_sub, \$in, \$out ; # Calling \&set_up_child in the child before it executes the # command (only works on systems with true fork() & exec()) run \@cat, \$in, \$out, init => \&set_up_child ; # Append output to named files run( \@cat, '>>', $out_f_name, '2>>', $err_f_name ) ; # Read from / write to file handles you open and close open IN, '<in.txt' or die $! ; 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', \*IN, '>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 ) ; IPC::Run allows you run and interact with child processes, files, pipes, and pseudo-ttys. Both event-loop and procedural techniques 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.

Harnesses
Child processes and I/O handles are gathered in to a harness, then run until the processing is finished or aborted.

run() vs. start(); pump(); finish();
There are two modes you can run harnesses in: incremental and batch. In incremental mode, you use start() and pump() to activate the harness and interact with it, then switch to batch mode and use run() or finish() to let the harness run to completion. In batch mode, you just use run() or start() and finish() and let things run to completion. In batch mode, all data to be sent to the harness is set up in advance, the harness is run and all output is collected from it, then any child processes are waited for: run \@cmd, \<<IN, \$out ; blah IN Incremental mode is provided by start(), pump(), and finish(): my $h = start \@cat, \$in_q, \$out_q, \$err_q ; $in_q = "first input\n" ; pump $h while length $in_q ; warn $err_q if length $err_q ; $err_q = '' ; $in_q = "second input\n" ; pump $h until $out_q =~ /second input/ ; $h->finish ; You can compile the harness with harness() prior to start()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. You may call timeout() at any time in this process. If it is called before start() (or the first pump(), if start() is omitted), then the timer is started just after all the child processes have been fork()ed or spawn()ed. If you call it once the children have been start()ed, the timeout timer is restarted. So this sequence: my $h = harness \@cat, \$in_q, \$out_q, \$err_q ; $h->timeout( 10 ) ; sleep 11 ; # No effect: timer not running yet start $h ; $in_q = "foo\n" ; pump $h until ! length $in_q ; ## 10 (or little more) may pass til this line. $in_q = "bar\n" ; $h->timeout( 1 ) ; ## Timer is now running, but will elapse after 1 second pump $h until ! length $in_q ; ## 1 seconds (or a little more) may pass til this line. $h->timeout( 30 ) ; $h->finish ; The timeout does not include the time it takes to wait for the children to exit, either.

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. the IPC::Run::IO manpage objects may be passed in as well, whether or not child processes are also specified: run io( "infile", ">", \$in ), io( "outfile", "<", \$in ) ; as can the IPC::Run::Timer manpage 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, parseing 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 descriptors 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. 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_q ; $in_q = "line 1\n" ; pump $h ; $in_q .= "line 2\n" ; pump $h ; $in_q .= "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. 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<' and '>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 suprising. 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
Psuedo-terminals are not pipes, though they are similar. Here are some differences to watch out for. 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. 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. 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. The pseudo terminal redirects both stdin and stdout unless you specify a file desciptor. If you want to grab stderr separately, do this: start \@cmd, '<pty<', \$in, '>pty>', \$out, '2>', \$err ; 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 >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. >pipe, N>pipe P Pipe opens H for caller to read, write, close. 'N' and 'M' are placehodlers 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). 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, \<<TOHERE ; 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, "<foo" ; 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_q ; 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 the Coprocesses entry elsewhere in this document below for more information. The <pipe operator opens the write half of a pipe on the filehandle glob reference it takes as an argument: $h = start \@cat, '<pipe', \*IN ; 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. 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. This duplicates output descriptor number n (default is 1 if n is ommitted) from descriptor number m. This duplicates input descriptor number n (default is 0 if n is ommitted) from descriptor number m This closes descriptor number n (default is 0 if n is ommitted). The following commands are equivalent: run \@cmd, \undef ; run \@cmd, '<&-' ; run \@cmd, '<in.txt', '<&-' ; Doing run \@cmd, \$in, '<&-' ; ## SIGPIPE recipe. is dangerous: the parent will get a SIGPIPE if $in is not empty. 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. 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 fuinctions new_appender() and new_chunker() rather than using \& syntax: run( \@cmd '<', new_appender( "\n" ), $in, '>', new_chunker, $out, ) ;

Just doing I/O
If you just want to do I/O to a handle or file you open yourself, you may specify a filehandle or filename instead of a command in the harness specification: run io( "filename", '>', \$recv ) ; $h = start io( $io, '>', \$recv ) ; $h = harness \@cmd, '&', io( "file", '<', \$send ) ;

Options
Options are passed in as name/value pairs: run \@cat, \$in, debug => 1 ; If you pass the debug option, you may want to pass it in first, so you can see what parsing is going on: run debug => 1, \@cat, \$in ; Enables debugging output in parent and child. Children emit debugging info over a separate, dedicated pipe to the parent, so you must pump(), pump_nb(), or finish() if you use start(). This pipe is not created unless debugging is enabled. harness() and start() return a reference to an IPC::Run harness. This is blessed in to the IPC::Run package, so you may make later calls to functions as members if you like: $h = harness( ... ) ; $h->start ; $h->pump ; $h->finish ; $h = start( .... ) ; $h->pump ; ... Of course, using method call syntax lets you deal with any IPC::Run subclasses that might crop up, but don't hold your breath waiting for any. run() and finish() return TRUE when all subcommands exit with a 0 result code. This is the opposite of perl's system() command. All routines raise exceptions (via die()) when error conditions are recognized. A non-zero command result is not treated as an error condition, since some commands are tests whose results are reported in their exit codes. Run takes a harness or harness specification and runs it, pumping all input to the child(ren), closing the input pipes when no more input is available, collecting all output that arrives, until the pipes delivering output are closed, then waiting for the children to exit and reaping their result codes. You may think of `run( ... )' as being like start( ... )->finish() ; , though there is one subtle difference: run() does not set \$input_scalars to '' like finish() does. Takes a harness specification and returns a harness. This harness is blessed in to IPC::Run, allowing you to use method call syntax for run(), start(), et al if you like. harness() is provided so that you can pre-build harnesses if you would like to, but it's not required.. You may proceed to run(), start() or pump() after calling harness() (pump() calls start() if need be). Alternatively, you may pass your harness specification to run() or start() and let them harness() for you. You can't pass harness specifications to pump(), though. This is used as (or in) an init sub to cast off the bonds of a controlling terminal. It must precede all other redirection ops that affect STDIN, STDOUT, or STDERR to be guaranteed effective. $h = start( \@cmd, \$in, \$out, ..., timeout( 30, name => "process timeout" ), $stall_timeout = timeout( 10, name => "stall timeout" ), ) ; $h = start \@cmd, '<', \$in, '|', \@cmd2, ... ; start() accepts a harness or harness specification and returns a harness after building all of the pipes and launching (via fork()/exec(), or, maybe someday, spawn()) all the child processes. It does not send or receive any data on the pipes, see pump() and finish() for that. You may call harness() and then pass it's result to start() if you like, but you only need to if it helps you structure or tune your application. If you do call harness(), you may skip start() and proceed directly to pump. start() also starts all timers in the harness. See the IPC::Run::Timer manpage for more information. start() flushes STDOUT and STDERR to help you avoid duplicate output. It has no way of asking Perl to flush all your open filehandles, so you are going to need to flush any others you have open. Sorry. Here's how if you don't want to alter the state of $| for your filehandle: $ofh = select HANDLE ; $of = $| ; $| = 1 ; $| = $of ; select $ofh; If you don't mind leaving output unbuffered on HANDLE, you can do the slightly shorter $ofh = select HANDLE ; $| = 1 ; select $ofh; Or, you can use IO::Handle's flush() method: use IO::Handle ; flush HANDLE ; Perl needs the equivalent of C's fflush( (FILE *)NULL ). pump $h ; $h->pump ; Pump accepts a single parameter harness. It blocks until it delivers some input or recieves some output. It returns TRUE if there is still input or output to be done, FALSE otherwise. pump() will automatically call start() if need be, so you may call harness() then proceed to pump() if that helps you structure your application. Calling pump() when there is no more i/o do be done causes a "process ended prematurely" exception to be thrown. This allows fairly simple scripting of external applications without having to add lots of error handling code at each step of the script: $h = harness \@smbclient, \$in_q, \$out_q, $err_q ; $in_q = "cd /foo\n" ; $h->pump until $out_q =~ /^smb.*> \Z/m ; die "error cding to /foo:\n$out_q" if $out_q =~ "ERR" ; $out_q = '' ; $in_q = "mget *\n" ; $h->pump until $out_q =~ /^smb.*> \Z/m ; die "error retrieving files:\n$out_q" if $out_q =~ "ERR" ; $h->finish ; warn $err_q if $err_q ; pump_nb $h ; $h->pump_nb ; "pump() non-blocking", pumps if anything's ready to be pumped, returns immediately otherwise. This is useful if you're doing some long-running task in the foreground, but don't want to starve any child processes. Returns TRUE if calling pump() won't throw an immediate "process ended prematurely" exception. Reflects the value returned from the last call to pump(). This must be called after the last start() or pump() call for a harness, or your system will accumulate defunct processes and you may "leak" file descriptors. finish() returns TRUE if all children returned 0 (and were not signaled and did not coredump, ie ! $?), and FALSE otherwise (this is like run(), and the opposite of system()). Once a harness has been finished, it may be run() or start()ed again, including by pump()s auto-start. $h->result ; Returns the first non-zero result code (ie $? >> 8). See the full_result entry elsewhere in this document to get the $? value for a child process. To get the result of a particular child, do: $h->result( 0 ) ; # first child's $? >> 8 $h->result( 1 ) ; # second child or ($h->results)[0] ($h->results)[1] Returns undef if no child processes were spawned and no child number was specified. Throws an exception if an out-of-range child number is passed. Returns a list of child exit values. See the full_results entry elsewhere in this document if you want to know if a signal killed the child. Throws an exception if the harness is not in a finished state. $h->full_result ; Returns the first non-zero $?. See the result entry elsewhere in this document to get the first $? >> 8 value for a child process. To get the result of a particular child, do: $h->full_result( 0 ) ; # first child's $? >> 8 $h->full_result( 1 ) ; # second child or ($h->full_results)[0] ($h->full_results)[1] Returns undef if no child processes were spawned and no child number was specified. Throws an exception if an out-of-range child number is passed. Returns a list of child exit values as returned by `wait'. See the results entry elsewhere in this document if you don't care about coredumps or signals. Throws an exception if the harness is not in a finished state. These filters are used to modify input our output between a child process and a scalar or subroutine endpoint. This breaks a stream of data in to chunks, based on an optional scalar or regular expression parameter. The default is the Perl input record separator in $/, which is a newline be default. run( \@cmd, '>', new_chunker, \&lines_handler, ) ; run( \@cmd, '>', new_chunker( "\r\n" ), \&lines_handler, ) ; Because this uses $/ by default, you should always pass in a parameter if you are worried about other code (modules, etc) modifying $/. If this filter is last in a filter chain that dumps in to a scalar, the scalar must be set to '' before a new chunk will be written to it. As an example of how a filter like this can be written, here's a chunker that splits on newlines: sub line_splitter { my ( $in_ref, $out_ref ) = @_ ; return 0 if length $$out_ref ; return input_avail && do { while (1) { if ( $$in_ref =~ s/\A(.*?\n)// ) { $$out_ref .= $1 ; return 1 ; } my $hmm = get_more_input ; unless ( defined $hmm ) { $$out_ref = $$in_ref ; $$in_ref = '' ; return length $$out_ref ? 1 : 0 ; } return 0 if $hmm eq 0 ; } } } ; This appends a fixed string to each chunk of data read from the source scalar or sub. This might be useful if you're writing commands to a child process that always must end in a fixed string, like "\n": run( \@cmd, '<', new_appender( "\n" ), \&commands, ) ; Here's a typical filter sub that might be created by new_appender(): sub newline_appender { my ( $in_ref, $out_ref ) = @_ ; return input_avail && do { $$out_ref = join( '', $$out_ref, $$in_ref, "\n" ) ; $$in_ref = '' ; 1 ; } } ; $h = start( \@cmd, \$in, \$out, $t = timer( 5 ) ) ; pump $h until $out =~ /expected stuff/ || $t->is_expired ; Instantiates a non-fatal timer. pump() returns once each time a timer expires. Has no direct effect on run(), but you can pass a subroutine to fire when the timer expires. See the timeout entry elsewhere in this document for building timers that throw exceptions on expiration. See the timer entry in the IPC::Run::Timer manpage for details. $h = start( \@cmd, \$in, \$out, $t = timeout( 5 ) ) ; pump $h until $out =~ /expected stuff/ ; Instantiates a timer that throws an exception when it expires. If you don't provide an exception, a default exception that matches /^IPC::Run: .*timed out/ is thrown by default. You can pass in your own exception scalar or reference: $h = start( \@cmd, \$in, \$out, $t = timeout( 5, exception => 'slowpoke' ), ) ; or set the name used in debugging message and in the default exception string: $h = start( \@cmd, \$in, \$out, timeout( 50, name => 'process timer' ), $stall_timer = timeout( 5, name => 'stall timer' ), ) ; pump $h until $out =~ /started/ ; $in = 'command 1' ; $stall_timer->start ; pump $h until $out =~ /command 1 finished/ ; $in = 'command 2' ; $stall_timer->start ; pump $h until $out =~ /command 2 finished/ ; $in = 'very slow command 3' ; $stall_timer->start( 10 ) ; pump $h until $out =~ /command 3 finished/ ; $stall_timer->start( 5 ) ; $in = 'command 4' ; pump $h until $out =~ /command 4 finished/ ; $stall_timer->reset; # Prevent restarting or expirng finish $h ; See the timer entry elsewhere in this document for building non-fatal timers. See the timer entry in the IPC::Run::Timer manpage for details. These functions are for use from within filters. Returns TRUE if input is available. If none is available, then &get_more_input is called and it's result returned. This is usually used in preference to &get_more_input so that the calling filter removes all data from the $in_ref before more data gets read in to $in_ref. `get_more_input' is usually used as part of a return expression: return input_avail && do { ## process the input just gotten 1 ; } ; This technique allows get_more_input to return the undef or 0 that a filter normally returns when there's no input to process. If a filter stores intermediate values, however, it will need to react to an undef: my $got = input_avail ; if ( ! defined $got ) { ## No more input ever, flush internal buffers to $out_ref } return $got unless $got ; ## Got some input, move as much as need be return 1 if $added_to_out_ref ; This is used to fetch more input in to the input variable. It returns undef if there will never be any more input, 0 if there is none now, but there might be in the future, and TRUE if more input was gotten. `get_more_input' is usually used as part of a return expression, see the input_avail entry elsewhere in this document for more information. my @tests = filter_tests( "foo", "in", "out", \&filter ) ; $_->() for ( @tests ) ; This creates a list of test subs that can be used to test most filters for basic functionality. The first parameter is the name of the filter to be tested, the second is sample input, the third is the test(s) to apply to the output(s), and the rest of the parameters are the filters to be linked and tested. If the filter chain is to be fed multiple inputs in sequence, the second parameter should be a reference to an array of thos inputs: my @tests = filter_tests( "foo", [qw(1 2 3)], "123", \&filter ) ; If the filter chain should produce a sequence of outputs, then the thrid parameter should be a reference to an array of those outputs: my @tests = filter_tests( "foo", "1\n\2\n", [ qr/^1$/, qr/^2$/ ], new_chunker ) ; See t/run.t and t/filter.t for an example of this in practice. These will be addressed as needed and as time allows. Stall timeout. Expose a list of child process objects. When I do this, each child process is likely to be blessed into IPC::Run::Proc. $kid->abort(), $kid->kill(), $kid->signal( $num_or_name ). Write tests for /(full_)?results?/ subs. Currently, pump() and run() only work on systems where select() works on the filehandles returned by pipe(). This does *not* include Win32. I'd like to rectify that, suggestions and patches welcome. Likewise start() only fully works on fork()/exec() machines (well, just fork() if you only ever pass perl subs as subprocesses). There's some scaffolding for calling Open3::spawn_with_handles(), but that's not that useful with limited select(). Support for `\@sub_cmd' as an argument to a command which gets replaced with /dev/fd or the name of a temporary file containing foo's output. This is like <(sub_cmd ...) found in bash and csh (IIRC). Allow multiple harnesses to be combined as independant sets of processes in to one 'meta-harness'. Allow a harness to be passed in place of an \@cmd. Ability to add external file descriptors w/ filter chains and endpoints. Ability to add timeouts and timing generators (i.e. repeating timeouts). High resolution timeouts. No support for ';', '&&', '||', '{ ... }', etc: use perl's, since run() returns TRUE when the command exits with a 0 result code. Does not provide shell-like string interpolation. No support for `cd', `setenv', or `export': do these in an init() sub run( \cmd, ... init => sub { chdir $dir or die $! ; $ENV{FOO}='BAR' } ) ; Timeout calculation does not allow absolute times, or specification of days, months, etc. Well, select() and waitpid() badly needed wrapping, and open3() isn't open-minded enough for me. API inspired by a message Russ Allbery sent to perl5-porters, which included: I've thought for some time that it would be nice to have a module that could handle full Bourne shell pipe syntax internally, with fork and exec, without ever invoking a shell. Something that you could give things like: pipeopen (PIPE, [ qw/cat file/ ], '|', [ 'analyze', @args ], '>&3'); Message ylln51p2b6.fsf@windlord.stanford.edu, on 2000/02/04. Barrie Slaymaker <barries@slaysys.com>, with numerous suggestions by p5p.