NAME

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,  '<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, # may also be a lexical filehandle e.g. \my $infh
            '>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

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.

   run \@cmd, \<<IN, \$out;
   blah
   IN

   ## To precompile harnesses and run them later:
   my $h = harness \@cmd, \<<IN, \$out;
   blah
   IN

   run $h;

   ## 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 $?";

   $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;

   $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 );

   my $out = "x" x 10_000;
   $out = "";

   ## 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;
 }

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

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

   run "echo 'hi there'";

   run \@cmd;
   run \@cmd1, '|', \@cmd2;
   run \@cmd1, '&', \@cmd2;
   run \&sub1;
   run \&sub1, '|', \&sub2;
   run \&sub1, '&', \&sub2;

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

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

   run \@cmd,  \undef,            \$out;
   run \@cmd,  \$in,              \$out;
   run \@cmd1, \&in, '|', \@cmd2, \*OUT;
   run \@cmd1, \*IN, '|', \@cmd2, \&out;

   run \@cmd, '<', \undef, '>',  \$out;
   run \@cmd, '<', \undef, '>&', \$out_and_err;
   run(
      \@cmd1,
         '<', \$in,
      '|', \@cmd2,
         \$out
   );

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

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

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

   $in = "Hello World.\n";
   run \@cat, \$in, \$out;
   print $out;

   $h = start \@cat, \$in;
   $in = "line 1\n";
   pump $h;
   $in .= "line 2\n";
   pump $h;
   $in .= "line 3\n";
   finish $h;

OBSTINATE CHILDREN

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 surprising.

PSEUDO TERMINALS

   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.

   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 or lexical filehandle opened by IPC::Run as the parent end of a pipe, but read
      and written to and closed by the caller (like IPC::Open3).

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

   $h = start io( $io, '>', \$recv );

   $h = harness \@cmd, '&', io( "file", '<', \$send );

   run \@cat, \$in, debug => 1;

   run debug => 1, \@cat, \$in;

RETURN VALUES

   $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.

ROUTINES

FILTERS

binary

   run \@cmd, ">", binary, \$out;
   run \@cmd, ">", binary, \$out;  ## Any TRUE value to enable
   run \@cmd, ">", binary 0, \$out;  ## Any FALSE value to disable
    

This is a constructor for a "binmode" "filter" that tells IPC::Run to keep the carriage returns that would ordinarily be edited out for you (binmode is usually off). This is not a real filter, but an option masquerading as a filter.

It's not named "binmode" because you're likely to want to call Perl's binmode in programs that are piping binary data around.

new_chunker

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;
         }
      }
   };
    

new_appender

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;
      }
   };
    

new_string_source

TODO: Needs confirmation. Was previously undocumented. in this module.

This is a filter which is exportable. Returns a sub which appends the data passed in to the output buffer and returns 1 if data was appended. 0 if it was an empty string and undef if no data was passed.

NOTE: Any additional variables passed to new_string_source will be passed to the sub every time it's called and appended to the output.

new_string_sink

TODO: Needs confirmation. Was previously undocumented.

This is a filter which is exportable. Returns a sub which pops the data out of the input stream and pushes it onto the string.

io

Takes a filename or filehandle, a redirection operator, optional filters, and a source or destination (depends on the redirection operator). Returns an IPC::Run::IO object suitable for harness()ing (including via start() or run()).

This is shorthand for

   require IPC::Run::IO;

      ... IPC::Run::IO->new(...) ...
    

timer

   $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 "timeout" for building timers that throw exceptions on expiration.

See "timer" in IPC::Run::Timer for details.

timeout

   $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 "timer" for building non-fatal timers.

See "timer" in IPC::Run::Timer for details.

FILTER IMPLEMENTATION FUNCTIONS

input_avail

Returns TRUE if input is available. If none is available, then &get_more_input is called and its result is 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.

"input_avail" is usually used as part of a return expression:

   return input_avail && do {
      ## process the input just gotten
      1;
   };
    

This technique allows input_avail 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;
    

get_more_input

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 "input_avail" for more information.

TODO

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 ActiveState on Win32, although it does work on cygwin under Win32 (thought the tests whine a bit). 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 untested, and 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 independent sets of processes in to one 'meta-harness'.

Allow a harness to be passed in place of an \@cmd. This would allow multiple harnesses to be aggregated.

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.

Win32 LIMITATIONS

Fails on Win9X

If you want Win9X support, you'll have to debug it or fund me because I don't use that system any more. The Win32 subsysem has been extended to use temporary files in simple run() invocations and these may actually work on Win9X too, but I don't have time to work on it.

May deadlock on Win2K (but not WinNT4 or WinXPPro)

Spawning more than one subprocess on Win2K causes a deadlock I haven't figured out yet, but simple uses of run() often work. Passes all tests on WinXPPro and WinNT.

no support yet for <pty< and >pty>

These are likely to be implemented as "<" and ">" with binmode on, not sure.

no support for file descriptors higher than 2 (stderr)

Win32 only allows passing explicit fds 0, 1, and 2. If you really, really need to pass file handles, us Win32API:: GetOsFHandle() or ::FdGetOsFHandle() to get the integer handle and pass it to the child process using the command line, environment, stdin, intermediary file, or other IPC mechanism. Then use that handle in the child (Win32API.pm provides ways to reconstitute Perl file handles from Win32 file handles).

no support for subroutine subprocesses (CODE refs)

Can't fork(), so the subroutines would have no context, and closures certainly have no meaning

Perhaps with Win32 fork() emulation, this can be supported in a limited fashion, but there are other very serious problems with that: all parent fds get dup()ed in to the thread emulating the forked process, and that keeps the parent from being able to close all of the appropriate fds.

no support for init => sub {} routines.

Win32 processes are created from scratch, there is no way to do an init routine that will affect the running child. Some limited support might be implemented one day, do chdir() and %ENV changes can be made.

signals

Win32 does not fully support signals. signal() is likely to cause errors unless sending a signal that Perl emulates, and "kill_kill()" is immediately fatal (there is no grace period).

helper processes

IPC::Run uses helper processes, one per redirected file, to adapt between the anonymous pipe connected to the child and the TCP socket connected to the parent. This is a waste of resources and will change in the future to either use threads (instead of helper processes) or a WaitForMultipleObjects call (instead of select). Please contact me if you can help with the WaitForMultipleObjects() approach; I haven't figured out how to get at it without C code.

shutdown pause

There seems to be a pause of up to 1 second between when a child program exits and the corresponding sockets indicate that they are closed in the parent. Not sure why.

binmode

binmode is not supported yet. The underpinnings are implemented, just ask if you need it.

IPC::Run::IO

IPC::Run::IO objects can be used on Unix to read or write arbitrary files. On Win32, they will need to use the same helper processes to adapt from non-select()able filehandles to select()able ones (or perhaps WaitForMultipleObjects() will work with them, not sure).

startup race conditions

There seems to be an occasional race condition between child process startup and pipe closings. It seems like if the child is not fully created by the time CreateProcess returns and we close the TCP socket being handed to it, the parent socket can also get closed. This is seen with the Win32 pumper applications, not the "real" child process being spawned.

I assume this is because the kernel hasn't gotten around to incrementing the reference count on the child's end (since the child was slow in starting), so the parent's closing of the child end causes the socket to be closed, thus closing the parent socket.

Being a race condition, it's hard to reproduce, but I encountered it while testing this code on a drive share to a samba box. In this case, it takes t/run.t a long time to spawn it's child processes (the parent hangs in the first select for several seconds until the child emits any debugging output).

I have not seen it on local drives, and can't reproduce it at will, unfortunately. The symptom is a "bad file descriptor in select()" error, and, by turning on debugging, it's possible to see that select() is being called on a no longer open file descriptor that was returned from the _socket() routine in Win32Helper. There's a new confess() that checks for this ("PARENT_HANDLE no longer open"), but I haven't been able to reproduce it (typically).

LIMITATIONS

PTYs don't seem to be non-blocking on some versions of Solaris. Here's a test script contributed by Borislav Deianov <borislav@ensim.com> to see if you have the problem. If it dies, you have the problem.

   #!/usr/bin/perl

   use IPC::Run qw(run);
   use Fcntl;
   use IO::Pty;

   sub makecmd {
       return ['perl', '-e', 
               '<STDIN>, print "\n" x '.$_[0].'; while(<STDIN>){last if /end/}'];
   }

   #pipe R, W;
   #fcntl(W, F_SETFL, O_NONBLOCK);
   #while (syswrite(W, "\n", 1)) { $pipebuf++ };
   #print "pipe buffer size is $pipebuf\n";
   my $pipebuf=4096;
   my $in = "\n" x ($pipebuf * 2) . "end\n";
   my $out;

   $SIG{ALRM} = sub { die "Never completed!\n" };

   print "reading from scalar via pipe...";
   alarm( 2 );
   run(makecmd($pipebuf * 2), '<', \$in, '>', \$out);
   alarm( 0 );
   print "done\n";

   print "reading from code via pipe... ";
   alarm( 2 );
   run(makecmd($pipebuf * 3), '<', sub { $t = $in; undef $in; $t}, '>', \$out);
   alarm( 0 );
   print "done\n";

   $pty = IO::Pty->new();
   $pty->blocking(0);
   $slave = $pty->slave();
   while ($pty->syswrite("\n", 1)) { $ptybuf++ };
   print "pty buffer size is $ptybuf\n";
   $in = "\n" x ($ptybuf * 3) . "end\n";

   print "reading via pty... ";
   alarm( 2 );
   run(makecmd($ptybuf * 3), '<pty<', \$in, '>', \$out);
   alarm(0);
   print "done\n";

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.

WARNING: Function coprocesses ("run \&foo, ...") suffer from two limitations. The first is that it is difficult to close all filehandles the child inherits from the parent, since there is no way to scan all open FILEHANDLEs in Perl and it both painful and a bit dangerous to close all open file descriptors with "POSIX::close()". Painful because we can't tell which fds are open at the POSIX level, either, so we'd have to scan all possible fds and close any that we don't want open (normally "exec()" closes any non-inheritable but we don't "exec()" for &sub processes.

The second problem is that Perl's DESTROY subs and other on-exit cleanup gets run in the child process. If objects are instantiated in the parent before the child is forked, the DESTROY will get run once in the parent and once in the child. When coprocess subs exit, POSIX::_exit is called to work around this, but it means that objects that are still referred to at that time are not cleaned up. So setting package vars or closure vars to point to objects that rely on DESTROY to affect things outside the process (files, etc), will lead to bugs.

I goofed on the syntax: "<pipe" vs. "<pty<" and ">filename" are both oddities.

TODO

Allow one harness to "adopt" another:

   $new_h = harness \@cmd2;
   $h->adopt( $new_h );
    

Close all filehandles not explicitly marked to stay open.

The problem with this one is that there's no good way to scan all open FILEHANDLEs in Perl, yet you don't want child processes inheriting handles willy-nilly.

INSPIRATION

The shell-like 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.

SUPPORT

<https://github.com/toddr/IPC-Run/issues>

AUTHORS

Barrie Slaymaker <barries@slaysys.com>

COPYRIGHT

Copyright 1999 Barrie Slaymaker.

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the README file.