1IPC::Run(3)           User Contributed Perl Documentation          IPC::Run(3)
2
3
4

NAME

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

SYNOPSIS

10          ## First,a command to run:
11             my @cat = qw( cat );
12
13          ## Using run() instead of system():
14             use IPC::Run qw( run timeout );
15
16             run \@cat, \$in, \$out, \$err, timeout( 10 ) or die "cat: $?";
17
18             # Can do I/O to sub refs and filenames, too:
19             run \@cat, '<', "in.txt", \&out, \&err or die "cat: $?";
20             run \@cat, '<', "in.txt", '>>', "out.txt", '2>>', "err.txt";
21
22
23             # Redirecting using pseudo-terminals instead of pipes.
24             run \@cat, '<pty<', \$in,  '>pty>', \$out_and_err;
25
26          ## Scripting subprocesses (like Expect):
27
28             use IPC::Run qw( start pump finish timeout );
29
30             # Incrementally read from / write to scalars.
31             # $in is drained as it is fed to cat's stdin,
32             # $out accumulates cat's stdout
33             # $err accumulates cat's stderr
34             # $h is for "harness".
35             my $h = start \@cat, \$in, \$out, \$err, timeout( 10 );
36
37             $in .= "some input\n";
38             pump $h until $out =~ /input\n/g;
39
40             $in .= "some more input\n";
41             pump $h until $out =~ /\G.*more input\n/;
42
43             $in .= "some final input\n";
44             finish $h or die "cat returned $?";
45
46             warn $err if $err;
47             print $out;         ## All of cat's output
48
49          # Piping between children
50             run \@cat, '|', \@gzip;
51
52          # Multiple children simultaneously (run() blocks until all
53          # children exit, use start() for background execution):
54             run \@foo1, '&', \@foo2;
55
56          # Calling \&set_up_child in the child before it executes the
57          # command (only works on systems with true fork() & exec())
58          # exceptions thrown in set_up_child() will be propagated back
59          # to the parent and thrown from run().
60             run \@cat, \$in, \$out,
61                init => \&set_up_child;
62
63          # Read from / write to file handles you open and close
64             open IN,  '<in.txt'  or die $!;
65             open OUT, '>out.txt' or die $!;
66             print OUT "preamble\n";
67             run \@cat, \*IN, \*OUT or die "cat returned $?";
68             print OUT "postamble\n";
69             close IN;
70             close OUT;
71
72          # Create pipes for you to read / write (like IPC::Open2 & 3).
73             $h = start
74                \@cat,
75                   '<pipe', \*IN, # may also be a lexical filehandle e.g. \my $infh
76                   '>pipe', \*OUT,
77                   '2>pipe', \*ERR
78                or die "cat returned $?";
79             print IN "some input\n";
80             close IN;
81             print <OUT>, <ERR>;
82             finish $h;
83
84          # Mixing input and output modes
85             run \@cat, 'in.txt', \&catch_some_out, \*ERR_LOG;
86
87          # Other redirection constructs
88             run \@cat, '>&', \$out_and_err;
89             run \@cat, '2>&1';
90             run \@cat, '0<&3';
91             run \@cat, '<&-';
92             run \@cat, '3<', \$in3;
93             run \@cat, '4>', \$out4;
94             # etc.
95
96          # Passing options:
97             run \@cat, 'in.txt', debug => 1;
98
99          # Call this system's shell, returns TRUE on 0 exit code
100          # THIS IS THE OPPOSITE SENSE OF system()'s RETURN VALUE
101             run "cat a b c" or die "cat returned $?";
102
103          # Launch a sub process directly, no shell.  Can't do redirection
104          # with this form, it's here to behave like system() with an
105          # inverted result.
106             $r = run "cat a b c";
107
108          # Read from a file in to a scalar
109             run io( "filename", 'r', \$recv );
110             run io( \*HANDLE,   'r', \$recv );
111

DESCRIPTION

113       IPC::Run allows you to run and interact with child processes using
114       files, pipes, and pseudo-ttys.  Both system()-style and scripted usages
115       are supported and may be mixed.  Likewise, functional and OO API styles
116       are both supported and may be mixed.
117
118       Various redirection operators reminiscent of those seen on common Unix
119       and DOS command lines are provided.
120
121       Before digging in to the details a few LIMITATIONS are important enough
122       to be mentioned right up front:
123
124       Win32 Support
125           Win32 support is working but EXPERIMENTAL, but does pass all
126           relevant tests on NT 4.0.  See "Win32 LIMITATIONS".
127
128       pty Support
129           If you need pty support, IPC::Run should work well enough most of
130           the time, but IO::Pty is being improved, and IPC::Run will be
131           improved to use IO::Pty's new features when it is release.
132
133           The basic problem is that the pty needs to initialize itself before
134           the parent writes to the master pty, or the data written gets lost.
135           So IPC::Run does a sleep(1) in the parent after forking to
136           (hopefully) give the child a chance to run.  This is a kludge that
137           works well on non heavily loaded systems :(.
138
139           ptys are not supported yet under Win32, but will be emulated...
140
141       Debugging Tip
142           You may use the environment variable "IPCRUNDEBUG" to see what's
143           going on under the hood:
144
145              $ IPCRUNDEBUG=basic   myscript     # prints minimal debugging
146              $ IPCRUNDEBUG=data    myscript     # prints all data reads/writes
147              $ IPCRUNDEBUG=details myscript     # prints lots of low-level details
148              $ IPCRUNDEBUG=gory    myscript     # (Win32 only) prints data moving through
149                                                 # the helper processes.
150
151       We now return you to your regularly scheduled documentation.
152
153   Harnesses
154       Child processes and I/O handles are gathered in to a harness, then
155       started and run until the processing is finished or aborted.
156
157   run() vs. start(); pump(); finish();
158       There are two modes you can run harnesses in: run() functions as an
159       enhanced system(), and start()/pump()/finish() allow for background
160       processes and scripted interactions with them.
161
162       When using run(), all data to be sent to the harness is set up in
163       advance (though one can feed subprocesses input from subroutine refs to
164       get around this limitation). The harness is run and all output is
165       collected from it, then any child processes are waited for:
166
167          run \@cmd, \<<IN, \$out;
168          blah
169          IN
170
171          ## To precompile harnesses and run them later:
172          my $h = harness \@cmd, \<<IN, \$out;
173          blah
174          IN
175
176          run $h;
177
178       The background and scripting API is provided by start(), pump(), and
179       finish(): start() creates a harness if need be (by calling harness())
180       and launches any subprocesses, pump() allows you to poll them for
181       activity, and finish() then monitors the harnessed activities until
182       they complete.
183
184          ## Build the harness, open all pipes, and launch the subprocesses
185          my $h = start \@cat, \$in, \$out;
186          $in = "first input\n";
187
188          ## Now do I/O.  start() does no I/O.
189          pump $h while length $in;  ## Wait for all input to go
190
191          ## Now do some more I/O.
192          $in = "second input\n";
193          pump $h until $out =~ /second input/;
194
195          ## Clean up
196          finish $h or die "cat returned $?";
197
198       You can optionally compile the harness with harness() prior to
199       start()ing or run()ing, and you may omit start() between harness() and
200       pump().  You might want to do these things if you compile your
201       harnesses ahead of time.
202
203   Using regexps to match output
204       As shown in most of the scripting examples, the read-to-scalar facility
205       for gathering subcommand's output is often used with regular
206       expressions to detect stopping points.  This is because subcommand
207       output often arrives in dribbles and drabs, often only a character or
208       line at a time.  This output is input for the main program and piles up
209       in variables like the $out and $err in our examples.
210
211       Regular expressions can be used to wait for appropriate output in
212       several ways.  The "cat" example in the previous section demonstrates
213       how to pump() until some string appears in the output.  Here's an
214       example that uses "smb" to fetch files from a remote server:
215
216          $h = harness \@smbclient, \$in, \$out;
217
218          $in = "cd /src\n";
219          $h->pump until $out =~ /^smb.*> \Z/m;
220          die "error cding to /src:\n$out" if $out =~ "ERR";
221          $out = '';
222
223          $in = "mget *\n";
224          $h->pump until $out =~ /^smb.*> \Z/m;
225          die "error retrieving files:\n$out" if $out =~ "ERR";
226
227          $in = "quit\n";
228          $h->finish;
229
230       Notice that we carefully clear $out after the first command/response
231       cycle? That's because IPC::Run does not delete $out when we continue,
232       and we don't want to trip over the old output in the second
233       command/response cycle.
234
235       Say you want to accumulate all the output in $out and analyze it
236       afterwards.  Perl offers incremental regular expression matching using
237       the "m//gc" and pattern matching idiom and the "\G" assertion.
238       IPC::Run is careful not to disturb the current "pos()" value for
239       scalars it appends data to, so we could modify the above so as not to
240       destroy $out by adding a couple of "/gc" modifiers.  The "/g" keeps us
241       from tripping over the previous prompt and the "/c" keeps us from
242       resetting the prior match position if the expected prompt doesn't
243       materialize immediately:
244
245          $h = harness \@smbclient, \$in, \$out;
246
247          $in = "cd /src\n";
248          $h->pump until $out =~ /^smb.*> \Z/mgc;
249          die "error cding to /src:\n$out" if $out =~ "ERR";
250
251          $in = "mget *\n";
252          $h->pump until $out =~ /^smb.*> \Z/mgc;
253          die "error retrieving files:\n$out" if $out =~ "ERR";
254
255          $in = "quit\n";
256          $h->finish;
257
258          analyze( $out );
259
260       When using this technique, you may want to preallocate $out to have
261       plenty of memory or you may find that the act of growing $out each time
262       new input arrives causes an "O(length($out)^2)" slowdown as $out grows.
263       Say we expect no more than 10,000 characters of input at the most.  To
264       preallocate memory to $out, do something like:
265
266          my $out = "x" x 10_000;
267          $out = "";
268
269       "perl" will allocate at least 10,000 characters' worth of space, then
270       mark the $out as having 0 length without freeing all that yummy RAM.
271
272   Timeouts and Timers
273       More than likely, you don't want your subprocesses to run forever, and
274       sometimes it's nice to know that they're going a little slowly.
275       Timeouts throw exceptions after a some time has elapsed, timers merely
276       cause pump() to return after some time has elapsed.  Neither is
277       reset/restarted automatically.
278
279       Timeout objects are created by calling timeout( $interval ) and passing
280       the result to run(), start() or harness().  The timeout period starts
281       ticking just after all the child processes have been fork()ed or
282       spawn()ed, and are polled for expiration in run(), pump() and finish().
283       If/when they expire, an exception is thrown.  This is typically useful
284       to keep a subprocess from taking too long.
285
286       If a timeout occurs in run(), all child processes will be terminated
287       and all file/pipe/ptty descriptors opened by run() will be closed.
288       File descriptors opened by the parent process and passed in to run()
289       are not closed in this event.
290
291       If a timeout occurs in pump(), pump_nb(), or finish(), it's up to you
292       to decide whether to kill_kill() all the children or to implement some
293       more graceful fallback.  No I/O will be closed in pump(), pump_nb() or
294       finish() by such an exception (though I/O is often closed down in those
295       routines during the natural course of events).
296
297       Often an exception is too harsh.  timer( $interval ) creates timer
298       objects that merely prevent pump() from blocking forever.  This can be
299       useful for detecting stalled I/O or printing a soothing message or "."
300       to pacify an anxious user.
301
302       Timeouts and timers can both be restarted at any time using the timer's
303       start() method (this is not the start() that launches subprocesses).
304       To restart a timer, you need to keep a reference to the timer:
305
306          ## Start with a nice long timeout to let smbclient connect.  If
307          ## pump or finish take too long, an exception will be thrown.
308
309        my $h;
310        eval {
311          $h = harness \@smbclient, \$in, \$out, \$err, ( my $t = timeout 30 );
312          sleep 11;  # No effect: timer not running yet
313
314          start $h;
315          $in = "cd /src\n";
316          pump $h until ! length $in;
317
318          $in = "ls\n";
319          ## Now use a short timeout, since this should be faster
320          $t->start( 5 );
321          pump $h until ! length $in;
322
323          $t->start( 10 );  ## Give smbclient a little while to shut down.
324          $h->finish;
325        };
326        if ( $@ ) {
327          my $x = $@;    ## Preserve $@ in case another exception occurs
328          $h->kill_kill; ## kill it gently, then brutally if need be, or just
329                          ## brutally on Win32.
330          die $x;
331        }
332
333       Timeouts and timers are not checked once the subprocesses are shut
334       down; they will not expire in the interval between the last valid
335       process and when IPC::Run scoops up the processes' result codes, for
336       instance.
337
338   Spawning synchronization, child exception propagation
339       start() pauses the parent until the child executes the command or CODE
340       reference and propagates any exceptions thrown (including exec()
341       failure) back to the parent.  This has several pleasant effects: any
342       exceptions thrown in the child, including exec() failure, come flying
343       out of start() or run() as though they had occurred in the parent.
344
345       This includes exceptions your code thrown from init subs.  In this
346       example:
347
348          eval {
349             run \@cmd, init => sub { die "blast it! foiled again!" };
350          };
351          print $@;
352
353       the exception "blast it! foiled again" will be thrown from the child
354       process (preventing the exec()) and printed by the parent.
355
356       In situations like
357
358          run \@cmd1, "|", \@cmd2, "|", \@cmd3;
359
360       @cmd1 will be initted and exec()ed before @cmd2, and @cmd2 before
361       @cmd3.  This can save time and prevent oddball errors emitted by later
362       commands when earlier commands fail to execute.  Note that IPC::Run
363       doesn't start any commands unless it can find the executables
364       referenced by all commands.  These executables must pass both the "-f"
365       and "-x" tests described in perlfunc.
366
367       Another nice effect is that init() subs can take their time doing
368       things and there will be no problems caused by a parent continuing to
369       execute before a child's init() routine is complete.  Say the init()
370       routine needs to open a socket or a temp file that the parent wants to
371       connect to; without this synchronization, the parent will need to
372       implement a retry loop to wait for the child to run, since often, the
373       parent gets a lot of things done before the child's first timeslice is
374       allocated.
375
376       This is also quite necessary for pseudo-tty initialization, which needs
377       to take place before the parent writes to the child via pty.  Writes
378       that occur before the pty is set up can get lost.
379
380       A final, minor, nicety is that debugging output from the child will be
381       emitted before the parent continues on, making for much clearer
382       debugging output in complex situations.
383
384       The only drawback I can conceive of is that the parent can't continue
385       to operate while the child is being initted.  If this ever becomes a
386       problem in the field, we can implement an option to avoid this
387       behavior, but I don't expect it to.
388
389       Win32: executing CODE references isn't supported on Win32, see "Win32
390       LIMITATIONS" for details.
391
392   Syntax
393       run(), start(), and harness() can all take a harness specification as
394       input.  A harness specification is either a single string to be passed
395       to the systems' shell:
396
397          run "echo 'hi there'";
398
399       or a list of commands, io operations, and/or timers/timeouts to
400       execute.  Consecutive commands must be separated by a pipe operator '|'
401       or an '&'.  External commands are passed in as array references, and,
402       on systems supporting fork(), Perl code may be passed in as subs:
403
404          run \@cmd;
405          run \@cmd1, '|', \@cmd2;
406          run \@cmd1, '&', \@cmd2;
407          run \&sub1;
408          run \&sub1, '|', \&sub2;
409          run \&sub1, '&', \&sub2;
410
411       '|' pipes the stdout of \@cmd1 the stdin of \@cmd2, just like a shell
412       pipe.  '&' does not.  Child processes to the right of a '&' will have
413       their stdin closed unless it's redirected-to.
414
415       IPC::Run::IO objects may be passed in as well, whether or not child
416       processes are also specified:
417
418          run io( "infile", ">", \$in ), io( "outfile", "<", \$in );
419
420       as can IPC::Run::Timer objects:
421
422          run \@cmd, io( "outfile", "<", \$in ), timeout( 10 );
423
424       Commands may be followed by scalar, sub, or i/o handle references for
425       redirecting child process input & output:
426
427          run \@cmd,  \undef,            \$out;
428          run \@cmd,  \$in,              \$out;
429          run \@cmd1, \&in, '|', \@cmd2, \*OUT;
430          run \@cmd1, \*IN, '|', \@cmd2, \&out;
431
432       This is known as succinct redirection syntax, since run(), start() and
433       harness(), figure out which file descriptor to redirect and how.  File
434       descriptor 0 is presumed to be an input for the child process, all
435       others are outputs.  The assumed file descriptor always starts at 0,
436       unless the command is being piped to, in which case it starts at 1.
437
438       To be explicit about your redirects, or if you need to do more complex
439       things, there's also a redirection operator syntax:
440
441          run \@cmd, '<', \undef, '>',  \$out;
442          run \@cmd, '<', \undef, '>&', \$out_and_err;
443          run(
444             \@cmd1,
445                '<', \$in,
446             '|', \@cmd2,
447                \$out
448          );
449
450       Operator syntax is required if you need to do something other than
451       simple redirection to/from scalars or subs, like duping or closing file
452       descriptors or redirecting to/from a named file.  The operators are
453       covered in detail below.
454
455       After each \@cmd (or \&foo), parsing begins in succinct mode and
456       toggles to operator syntax mode when an operator (ie plain scalar, not
457       a ref) is seen.  Once in operator syntax mode, parsing only reverts to
458       succinct mode when a '|' or '&' is seen.
459
460       In succinct mode, each parameter after the \@cmd specifies what to do
461       with the next highest file descriptor. These File descriptor start with
462       0 (stdin) unless stdin is being piped to ("'|', \@cmd"), in which case
463       they start with 1 (stdout).  Currently, being on the left of a pipe
464       ("\@cmd, \$out, \$err, '|'") does not cause stdout to be skipped,
465       though this may change since it's not as DWIMerly as it could be.  Only
466       stdin is assumed to be an input in succinct mode, all others are
467       assumed to be outputs.
468
469       If no piping or redirection is specified for a child, it will inherit
470       the parent's open file handles as dictated by your system's close-on-
471       exec behavior and the $^F flag, except that processes after a '&' will
472       not inherit the parent's stdin. Also note that $^F does not affect file
473       descriptors obtained via POSIX, since it only applies to full-fledged
474       Perl file handles.  Such processes will have their stdin closed unless
475       it has been redirected-to.
476
477       If you want to close a child processes stdin, you may do any of:
478
479          run \@cmd, \undef;
480          run \@cmd, \"";
481          run \@cmd, '<&-';
482          run \@cmd, '0<&-';
483
484       Redirection is done by placing redirection specifications immediately
485       after a command or child subroutine:
486
487          run \@cmd1,      \$in, '|', \@cmd2,      \$out;
488          run \@cmd1, '<', \$in, '|', \@cmd2, '>', \$out;
489
490       If you omit the redirection operators, descriptors are counted starting
491       at 0.  Descriptor 0 is assumed to be input, all others are outputs.  A
492       leading '|' consumes descriptor 0, so this works as expected.
493
494          run \@cmd1, \$in, '|', \@cmd2, \$out;
495
496       The parameter following a redirection operator can be a scalar ref, a
497       subroutine ref, a file name, an open filehandle, or a closed
498       filehandle.
499
500       If it's a scalar ref, the child reads input from or sends output to
501       that variable:
502
503          $in = "Hello World.\n";
504          run \@cat, \$in, \$out;
505          print $out;
506
507       Scalars used in incremental (start()/pump()/finish()) applications are
508       treated as queues: input is removed from input scalers, resulting in
509       them dwindling to '', and output is appended to output scalars.  This
510       is not true of harnesses run() in batch mode.
511
512       It's usually wise to append new input to be sent to the child to the
513       input queue, and you'll often want to zap output queues to '' before
514       pumping.
515
516          $h = start \@cat, \$in;
517          $in = "line 1\n";
518          pump $h;
519          $in .= "line 2\n";
520          pump $h;
521          $in .= "line 3\n";
522          finish $h;
523
524       The final call to finish() must be there: it allows the child
525       process(es) to run to completion and waits for their exit values.
526

OBSTINATE CHILDREN

528       Interactive applications are usually optimized for human use.  This can
529       help or hinder trying to interact with them through modules like
530       IPC::Run.  Frequently, programs alter their behavior when they detect
531       that stdin, stdout, or stderr are not connected to a tty, assuming that
532       they are being run in batch mode.  Whether this helps or hurts depends
533       on which optimizations change.  And there's often no way of telling
534       what a program does in these areas other than trial and error and
535       occasionally, reading the source.  This includes different versions and
536       implementations of the same program.
537
538       All hope is not lost, however.  Most programs behave in reasonably
539       tractable manners, once you figure out what it's trying to do.
540
541       Here are some of the issues you might need to be aware of.
542
543       ยท   fflush()ing stdout and stderr
544
545           This lets the user see stdout and stderr immediately.  Many
546           programs undo this optimization if stdout is not a tty, making them
547           harder to manage by things like IPC::Run.
548
549           Many programs decline to fflush stdout or stderr if they do not
550           detect a tty there.  Some ftp commands do this, for instance.
551
552           If this happens to you, look for a way to force interactive
553           behavior, like a command line switch or command.  If you can't, you
554           will need to use a pseudo terminal ('<pty<' and '>pty>').
555
556       ยท   false prompts
557
558           Interactive programs generally do not guarantee that output from
559           user commands won't contain a prompt string.  For example, your
560           shell prompt might be a '$', and a file named '$' might be the only
561           file in a directory listing.
562
563           This can make it hard to guarantee that your output parser won't be
564           fooled into early termination of results.
565
566           To help work around this, you can see if the program can alter it's
567           prompt, and use something you feel is never going to occur in
568           actual practice.
569
570           You should also look for your prompt to be the only thing on a
571           line:
572
573              pump $h until $out =~ /^<SILLYPROMPT>\s?\z/m;
574
575           (use "(?!\n)\Z" in place of "\z" on older perls).
576
577           You can also take the approach that IPC::ChildSafe takes and emit a
578           command with known output after each 'real' command you issue, then
579           look for this known output.  See new_appender() and new_chunker()
580           for filters that can help with this task.
581
582           If it's not convenient or possibly to alter a prompt or use a known
583           command/response pair, you might need to autodetect the prompt in
584           case the local version of the child program is different then the
585           one you tested with, or if the user has control over the look &
586           feel of the prompt.
587
588       ยท   Refusing to accept input unless stdin is a tty.
589
590           Some programs, for security reasons, will only accept certain types
591           of input from a tty.  su, notable, will not prompt for a password
592           unless it's connected to a tty.
593
594           If this is your situation, use a pseudo terminal ('<pty<' and
595           '>pty>').
596
597       ยท   Not prompting unless connected to a tty.
598
599           Some programs don't prompt unless stdin or stdout is a tty.  See if
600           you can turn prompting back on.  If not, see if you can come up
601           with a command that you can issue after every real command and look
602           for it's output, as IPC::ChildSafe does.   There are two filters
603           included with IPC::Run that can help with doing this: appender and
604           chunker (see new_appender() and new_chunker()).
605
606       ยท   Different output format when not connected to a tty.
607
608           Some commands alter their formats to ease machine parsability when
609           they aren't connected to a pipe.  This is actually good, but can be
610           surprising.
611

PSEUDO TERMINALS

613       On systems providing pseudo terminals under /dev, IPC::Run can use
614       IO::Pty (available on CPAN) to provide a terminal environment to
615       subprocesses.  This is necessary when the subprocess really wants to
616       think it's connected to a real terminal.
617
618   CAVEATS
619       Pseudo-terminals are not pipes, though they are similar.  Here are some
620       differences to watch out for.
621
622       Echoing
623           Sending to stdin will cause an echo on stdout, which occurs before
624           each line is passed to the child program.  There is currently no
625           way to disable this, although the child process can and should
626           disable it for things like passwords.
627
628       Shutdown
629           IPC::Run cannot close a pty until all output has been collected.
630           This means that it is not possible to send an EOF to stdin by half-
631           closing the pty, as we can when using a pipe to stdin.
632
633           This means that you need to send the child process an exit command
634           or signal, or run() / finish() will time out.  Be careful not to
635           expect a prompt after sending the exit command.
636
637       Command line editing
638           Some subprocesses, notable shells that depend on the user's prompt
639           settings, will reissue the prompt plus the command line input so
640           far once for each character.
641
642       '>pty>' means '&>pty>', not '1>pty>'
643           The pseudo terminal redirects both stdout and stderr unless you
644           specify a file descriptor.  If you want to grab stderr separately,
645           do this:
646
647              start \@cmd, '<pty<', \$in, '>pty>', \$out, '2>', \$err;
648
649       stdin, stdout, and stderr not inherited
650           Child processes harnessed to a pseudo terminal have their stdin,
651           stdout, and stderr completely closed before any redirection
652           operators take effect.  This casts of the bonds of the controlling
653           terminal.  This is not done when using pipes.
654
655           Right now, this affects all children in a harness that has a pty in
656           use, even if that pty would not affect a particular child.  That's
657           a bug and will be fixed.  Until it is, it's best not to mix-and-
658           match children.
659
660   Redirection Operators
661          Operator       SHNP   Description
662          ========       ====   ===========
663          <, N<          SHN    Redirects input to a child's fd N (0 assumed)
664
665          >, N>          SHN    Redirects output from a child's fd N (1 assumed)
666          >>, N>>        SHN    Like '>', but appends to scalars or named files
667          >&, &>         SHN    Redirects stdout & stderr from a child process
668
669          <pty, N<pty    S      Like '<', but uses a pseudo-tty instead of a pipe
670          >pty, N>pty    S      Like '>', but uses a pseudo-tty instead of a pipe
671
672          N<&M                  Dups input fd N to input fd M
673          M>&N                  Dups output fd N to input fd M
674          N<&-                  Closes fd N
675
676          <pipe, N<pipe     P   Pipe opens H for caller to read, write, close.
677          >pipe, N>pipe     P   Pipe opens H for caller to read, write, close.
678
679       'N' and 'M' are placeholders for integer file descriptor numbers.  The
680       terms 'input' and 'output' are from the child process's perspective.
681
682       The SHNP field indicates what parameters an operator can take:
683
684          S: \$scalar or \&function references.  Filters may be used with
685             these operators (and only these).
686          H: \*HANDLE or IO::Handle for caller to open, and close
687          N: "file name".
688          P: \*HANDLE or lexical filehandle opened by IPC::Run as the parent end of a pipe, but read
689             and written to and closed by the caller (like IPC::Open3).
690
691       Redirecting input: [n]<, [n]<pipe
692           You can input the child reads on file descriptor number n to come
693           from a scalar variable, subroutine, file handle, or a named file.
694           If stdin is not redirected, the parent's stdin is inherited.
695
696              run \@cat, \undef          ## Closes child's stdin immediately
697                 or die "cat returned $?";
698
699              run \@cat, \$in;
700
701              run \@cat, \<<TOHERE;
702              blah
703              TOHERE
704
705              run \@cat, \&input;       ## Calls &input, feeding data returned
706                                         ## to child's.  Closes child's stdin
707                                         ## when undef is returned.
708
709           Redirecting from named files requires you to use the input
710           redirection operator:
711
712              run \@cat, '<.profile';
713              run \@cat, '<', '.profile';
714
715              open IN, "<foo";
716              run \@cat, \*IN;
717              run \@cat, *IN{IO};
718
719           The form used second example here is the safest, since filenames
720           like "0" and "&more\n" won't confuse &run:
721
722           You can't do either of
723
724              run \@a, *IN;      ## INVALID
725              run \@a, '<', *IN; ## BUGGY: Reads file named like "*main::A"
726
727           because perl passes a scalar containing a string that looks like
728           "*main::A" to &run, and &run can't tell the difference between that
729           and a redirection operator or a file name.  &run guarantees that
730           any scalar you pass after a redirection operator is a file name.
731
732           If your child process will take input from file descriptors other
733           than 0 (stdin), you can use a redirection operator with any of the
734           valid input forms (scalar ref, sub ref, etc.):
735
736              run \@cat, '3<', \$in3;
737
738           When redirecting input from a scalar ref, the scalar ref is used as
739           a queue.  This allows you to use &harness and pump() to feed
740           incremental bits of input to a coprocess.  See "Coprocesses" below
741           for more information.
742
743           The <pipe operator opens the write half of a pipe on the filehandle
744           glob reference it takes as an argument:
745
746              $h = start \@cat, '<pipe', \*IN;
747              print IN "hello world\n";
748              pump $h;
749              close IN;
750              finish $h;
751
752           Unlike the other '<' operators, IPC::Run does nothing further with
753           it: you are responsible for it.  The previous example is
754           functionally equivalent to:
755
756              pipe( \*R, \*IN ) or die $!;
757              $h = start \@cat, '<', \*IN;
758              print IN "hello world\n";
759              pump $h;
760              close IN;
761              finish $h;
762
763           This is like the behavior of IPC::Open2 and IPC::Open3.
764
765           Win32: The handle returned is actually a socket handle, so you can
766           use select() on it.
767
768       Redirecting output: [n]>, [n]>>, [n]>&[m], [n]>pipe
769           You can redirect any output the child emits to a scalar variable,
770           subroutine, file handle, or file name.  You can have &run truncate
771           or append to named files or scalars.  If you are redirecting stdin
772           as well, or if the command is on the receiving end of a pipeline
773           ('|'), you can omit the redirection operator:
774
775              @ls = ( 'ls' );
776              run \@ls, \undef, \$out
777                 or die "ls returned $?";
778
779              run \@ls, \undef, \&out;  ## Calls &out each time some output
780                                         ## is received from the child's
781                                         ## when undef is returned.
782
783              run \@ls, \undef, '2>ls.err';
784              run \@ls, '2>', 'ls.err';
785
786           The two parameter form guarantees that the filename will not be
787           interpreted as a redirection operator:
788
789              run \@ls, '>', "&more";
790              run \@ls, '2>', ">foo\n";
791
792           You can pass file handles you've opened for writing:
793
794              open( *OUT, ">out.txt" );
795              open( *ERR, ">err.txt" );
796              run \@cat, \*OUT, \*ERR;
797
798           Passing a scalar reference and a code reference requires a little
799           more work, but allows you to capture all of the output in a scalar
800           or each piece of output by a callback:
801
802           These two do the same things:
803
804              run( [ 'ls' ], '2>', sub { $err_out .= $_[0] } );
805
806           does the same basic thing as:
807
808              run( [ 'ls' ], '2>', \$err_out );
809
810           The subroutine will be called each time some data is read from the
811           child.
812
813           The >pipe operator is different in concept than the other '>'
814           operators, although it's syntax is similar:
815
816              $h = start \@cat, $in, '>pipe', \*OUT, '2>pipe', \*ERR;
817              $in = "hello world\n";
818              finish $h;
819              print <OUT>;
820              print <ERR>;
821              close OUT;
822              close ERR;
823
824           causes two pipe to be created, with one end attached to cat's
825           stdout and stderr, respectively, and the other left open on OUT and
826           ERR, so that the script can manually read(), select(), etc. on
827           them.  This is like the behavior of IPC::Open2 and IPC::Open3.
828
829           Win32: The handle returned is actually a socket handle, so you can
830           use select() on it.
831
832       Duplicating output descriptors: >&m, n>&m
833           This duplicates output descriptor number n (default is 1 if n is
834           omitted) from descriptor number m.
835
836       Duplicating input descriptors: <&m, n<&m
837           This duplicates input descriptor number n (default is 0 if n is
838           omitted) from descriptor number m
839
840       Closing descriptors: <&-, 3<&-
841           This closes descriptor number n (default is 0 if n is omitted).
842           The following commands are equivalent:
843
844              run \@cmd, \undef;
845              run \@cmd, '<&-';
846              run \@cmd, '<in.txt', '<&-';
847
848           Doing
849
850              run \@cmd, \$in, '<&-';    ## SIGPIPE recipe.
851
852           is dangerous: the parent will get a SIGPIPE if $in is not empty.
853
854       Redirecting both stdout and stderr: &>, >&, &>pipe, >pipe&
855           The following pairs of commands are equivalent:
856
857              run \@cmd, '>&', \$out;       run \@cmd, '>', \$out,     '2>&1';
858              run \@cmd, '>&', 'out.txt';   run \@cmd, '>', 'out.txt', '2>&1';
859
860           etc.
861
862           File descriptor numbers are not permitted to the left or the right
863           of these operators, and the '&' may occur on either end of the
864           operator.
865
866           The '&>pipe' and '>pipe&' variants behave like the '>pipe'
867           operator, except that both stdout and stderr write to the created
868           pipe.
869
870       Redirection Filters
871           Both input redirections and output redirections that use scalars or
872           subs as endpoints may have an arbitrary number of filter subs
873           placed between them and the child process.  This is useful if you
874           want to receive output in chunks, or if you want to massage each
875           chunk of data sent to the child.  To use this feature, you must use
876           operator syntax:
877
878              run(
879                 \@cmd
880                    '<', \&in_filter_2, \&in_filter_1, $in,
881                    '>', \&out_filter_1, \&in_filter_2, $out,
882              );
883
884           This capability is not provided for IO handles or named files.
885
886           Two filters are provided by IPC::Run: appender and chunker.
887           Because these may take an argument, you need to use the constructor
888           functions new_appender() and new_chunker() rather than using \&
889           syntax:
890
891              run(
892                 \@cmd
893                    '<', new_appender( "\n" ), $in,
894                    '>', new_chunker, $out,
895              );
896
897   Just doing I/O
898       If you just want to do I/O to a handle or file you open yourself, you
899       may specify a filehandle or filename instead of a command in the
900       harness specification:
901
902          run io( "filename", '>', \$recv );
903
904          $h = start io( $io, '>', \$recv );
905
906          $h = harness \@cmd, '&', io( "file", '<', \$send );
907
908   Options
909       Options are passed in as name/value pairs:
910
911          run \@cat, \$in, debug => 1;
912
913       If you pass the debug option, you may want to pass it in first, so you
914       can see what parsing is going on:
915
916          run debug => 1, \@cat, \$in;
917
918       debug
919           Enables debugging output in parent and child.  Debugging info is
920           emitted to the STDERR that was present when IPC::Run was first
921           "use()"ed (it's "dup()"ed out of the way so that it can be
922           redirected in children without having debugging output emitted on
923           it).
924

RETURN VALUES

926       harness() and start() return a reference to an IPC::Run harness.  This
927       is blessed in to the IPC::Run package, so you may make later calls to
928       functions as members if you like:
929
930          $h = harness( ... );
931          $h->start;
932          $h->pump;
933          $h->finish;
934
935          $h = start( .... );
936          $h->pump;
937          ...
938
939       Of course, using method call syntax lets you deal with any IPC::Run
940       subclasses that might crop up, but don't hold your breath waiting for
941       any.
942
943       run() and finish() return TRUE when all subcommands exit with a 0
944       result code.  This is the opposite of perl's system() command.
945
946       All routines raise exceptions (via die()) when error conditions are
947       recognized.  A non-zero command result is not treated as an error
948       condition, since some commands are tests whose results are reported in
949       their exit codes.
950

ROUTINES

952           run Run takes a harness or harness specification and runs it,
953               pumping all input to the child(ren), closing the input pipes
954               when no more input is available, collecting all output that
955               arrives, until the pipes delivering output are closed, then
956               waiting for the children to exit and reaping their result
957               codes.
958
959               You may think of "run( ... )" as being like
960
961                  start( ... )->finish();
962
963               , though there is one subtle difference: run() does not set
964               \$input_scalars to '' like finish() does.  If an exception is
965               thrown from run(), all children will be killed off "gently",
966               and then "annihilated" if they do not go gently (in to that
967               dark night. sorry).
968
969               If any exceptions are thrown, this does a "kill_kill" before
970               propagating them.
971
972           signal
973                  ## To send it a specific signal by name ("USR1"):
974                  signal $h, "USR1";
975                  $h->signal ( "USR1" );
976
977               If $signal is provided and defined, sends a signal to all child
978               processes.  Try not to send numeric signals, use "KILL" instead
979               of 9, for instance.  Numeric signals aren't portable.
980
981               Throws an exception if $signal is undef.
982
983               This will not clean up the harness, "finish" it if you kill it.
984
985               Normally TERM kills a process gracefully (this is what the
986               command line utility "kill" does by default), INT is sent by
987               one of the keys "^C", "Backspace" or "<Del>", and "QUIT" is
988               used to kill a process and make it coredump.
989
990               The "HUP" signal is often used to get a process to "restart",
991               rereading config files, and "USR1" and "USR2" for really
992               application-specific things.
993
994               Often, running "kill -l" (that's a lower case "L") on the
995               command line will list the signals present on your operating
996               system.
997
998               WARNING: The signal subsystem is not at all portable.  We *may*
999               offer to simulate "TERM" and "KILL" on some operating systems,
1000               submit code to me if you want this.
1001
1002               WARNING 2: Up to and including perl v5.6.1, doing almost
1003               anything in a signal handler could be dangerous.  The most safe
1004               code avoids all mallocs and system calls, usually by
1005               preallocating a flag before entering the signal handler,
1006               altering the flag's value in the handler, and responding to the
1007               changed value in the main system:
1008
1009                  my $got_usr1 = 0;
1010                  sub usr1_handler { ++$got_signal }
1011
1012                  $SIG{USR1} = \&usr1_handler;
1013                  while () { sleep 1; print "GOT IT" while $got_usr1--; }
1014
1015               Even this approach is perilous if ++ and -- aren't atomic on
1016               your system (I've never heard of this on any modern CPU large
1017               enough to run perl).
1018
1019           kill_kill
1020                  ## To kill off a process:
1021                  $h->kill_kill;
1022                  kill_kill $h;
1023
1024                  ## To specify the grace period other than 30 seconds:
1025                  kill_kill $h, grace => 5;
1026
1027                  ## To send QUIT instead of KILL if a process refuses to die:
1028                  kill_kill $h, coup_d_grace => "QUIT";
1029
1030               Sends a "TERM", waits for all children to exit for up to 30
1031               seconds, then sends a "KILL" to any that survived the "TERM".
1032
1033               Will wait for up to 30 more seconds for the OS to successfully
1034               "KILL" the processes.
1035
1036               The 30 seconds may be overridden by setting the "grace" option,
1037               this overrides both timers.
1038
1039               The harness is then cleaned up.
1040
1041               The doubled name indicates that this function may kill again
1042               and avoids colliding with the core Perl "kill" function.
1043
1044               Returns a 1 if the "TERM" was sufficient, or a 0 if "KILL" was
1045               required.  Throws an exception if "KILL" did not permit the
1046               children to be reaped.
1047
1048               NOTE: The grace period is actually up to 1 second longer than
1049               that given.  This is because the granularity of "time" is 1
1050               second.  Let me know if you need finer granularity, we can
1051               leverage Time::HiRes here.
1052
1053               Win32: Win32 does not know how to send real signals, so "TERM"
1054               is a full-force kill on Win32.  Thus all talk of grace periods,
1055               etc. do not apply to Win32.
1056
1057           harness
1058               Takes a harness specification and returns a harness.  This
1059               harness is blessed in to IPC::Run, allowing you to use method
1060               call syntax for run(), start(), et al if you like.
1061
1062               harness() is provided so that you can pre-build harnesses if
1063               you would like to, but it's not required..
1064
1065               You may proceed to run(), start() or pump() after calling
1066               harness() (pump() calls start() if need be).  Alternatively,
1067               you may pass your harness specification to run() or start() and
1068               let them harness() for you.  You can't pass harness
1069               specifications to pump(), though.
1070
1071           close_terminal
1072               This is used as (or in) an init sub to cast off the bonds of a
1073               controlling terminal.  It must precede all other redirection
1074               ops that affect STDIN, STDOUT, or STDERR to be guaranteed
1075               effective.
1076
1077           start
1078                  $h = start(
1079                     \@cmd, \$in, \$out, ...,
1080                     timeout( 30, name => "process timeout" ),
1081                     $stall_timeout = timeout( 10, name => "stall timeout"   ),
1082                  );
1083
1084                  $h = start \@cmd, '<', \$in, '|', \@cmd2, ...;
1085
1086               start() accepts a harness or harness specification and returns
1087               a harness after building all of the pipes and launching (via
1088               fork()/exec(), or, maybe someday, spawn()) all the child
1089               processes.  It does not send or receive any data on the pipes,
1090               see pump() and finish() for that.
1091
1092               You may call harness() and then pass it's result to start() if
1093               you like, but you only need to if it helps you structure or
1094               tune your application.  If you do call harness(), you may skip
1095               start() and proceed directly to pump.
1096
1097               start() also starts all timers in the harness.  See
1098               IPC::Run::Timer for more information.
1099
1100               start() flushes STDOUT and STDERR to help you avoid duplicate
1101               output.  It has no way of asking Perl to flush all your open
1102               filehandles, so you are going to need to flush any others you
1103               have open.  Sorry.
1104
1105               Here's how if you don't want to alter the state of $| for your
1106               filehandle:
1107
1108                  $ofh = select HANDLE; $of = $|; $| = 1; $| = $of; select $ofh;
1109
1110               If you don't mind leaving output unbuffered on HANDLE, you can
1111               do the slightly shorter
1112
1113                  $ofh = select HANDLE; $| = 1; select $ofh;
1114
1115               Or, you can use IO::Handle's flush() method:
1116
1117                  use IO::Handle;
1118                  flush HANDLE;
1119
1120               Perl needs the equivalent of C's fflush( (FILE *)NULL ).
1121
1122           adopt
1123               Experimental feature. NOT FUNCTIONAL YET, NEED TO CLOSE FDS
1124               BETTER IN CHILDREN.  SEE t/adopt.t for a test suite.
1125
1126           pump
1127                  pump $h;
1128                  $h->pump;
1129
1130               Pump accepts a single parameter harness.  It blocks until it
1131               delivers some input or receives some output.  It returns TRUE
1132               if there is still input or output to be done, FALSE otherwise.
1133
1134               pump() will automatically call start() if need be, so you may
1135               call harness() then proceed to pump() if that helps you
1136               structure your application.
1137
1138               If pump() is called after all harnessed activities have
1139               completed, a "process ended prematurely" exception to be
1140               thrown.  This allows for simple scripting of external
1141               applications without having to add lots of error handling code
1142               at each step of the script:
1143
1144                  $h = harness \@smbclient, \$in, \$out, $err;
1145
1146                  $in = "cd /foo\n";
1147                  $h->pump until $out =~ /^smb.*> \Z/m;
1148                  die "error cding to /foo:\n$out" if $out =~ "ERR";
1149                  $out = '';
1150
1151                  $in = "mget *\n";
1152                  $h->pump until $out =~ /^smb.*> \Z/m;
1153                  die "error retrieving files:\n$out" if $out =~ "ERR";
1154
1155                  $h->finish;
1156
1157                  warn $err if $err;
1158
1159           pump_nb
1160                  pump_nb $h;
1161                  $h->pump_nb;
1162
1163               "pump() non-blocking", pumps if anything's ready to be pumped,
1164               returns immediately otherwise.  This is useful if you're doing
1165               some long-running task in the foreground, but don't want to
1166               starve any child processes.
1167
1168           pumpable
1169               Returns TRUE if calling pump() won't throw an immediate
1170               "process ended prematurely" exception.  This means that there
1171               are open I/O channels or active processes. May yield the parent
1172               processes' time slice for 0.01 second if all pipes are to the
1173               child and all are paused.  In this case we can't tell if the
1174               child is dead, so we yield the processor and then attempt to
1175               reap the child in a nonblocking way.
1176
1177           reap_nb
1178               Attempts to reap child processes, but does not block.
1179
1180               Does not currently take any parameters, one day it will allow
1181               specific children to be reaped.
1182
1183               Only call this from a signal handler if your "perl" is recent
1184               enough to have safe signal handling (5.6.1 did not, IIRC, but
1185               it was being discussed on perl5-porters).  Calling this (or
1186               doing any significant work) in a signal handler on older
1187               "perl"s is asking for seg faults.
1188
1189           finish
1190               This must be called after the last start() or pump() call for a
1191               harness, or your system will accumulate defunct processes and
1192               you may "leak" file descriptors.
1193
1194               finish() returns TRUE if all children returned 0 (and were not
1195               signaled and did not coredump, ie ! $?), and FALSE otherwise
1196               (this is like run(), and the opposite of system()).
1197
1198               Once a harness has been finished, it may be run() or start()ed
1199               again, including by pump()s auto-start.
1200
1201               If this throws an exception rather than a normal exit, the
1202               harness may be left in an unstable state, it's best to kill the
1203               harness to get rid of all the child processes, etc.
1204
1205               Specifically, if a timeout expires in finish(), finish() will
1206               not kill all the children.  Call "<$h-"kill_kill>> in this case
1207               if you care.  This differs from the behavior of "run".
1208
1209           result
1210                  $h->result;
1211
1212               Returns the first non-zero result code (ie $? >> 8).  See
1213               "full_result" to get the $? value for a child process.
1214
1215               To get the result of a particular child, do:
1216
1217                  $h->result( 0 );  # first child's $? >> 8
1218                  $h->result( 1 );  # second child
1219
1220               or
1221
1222                  ($h->results)[0]
1223                  ($h->results)[1]
1224
1225               Returns undef if no child processes were spawned and no child
1226               number was specified.  Throws an exception if an out-of-range
1227               child number is passed.
1228
1229           results
1230               Returns a list of child exit values.  See "full_results" if you
1231               want to know if a signal killed the child.
1232
1233               Throws an exception if the harness is not in a finished state.
1234
1235           full_result
1236                  $h->full_result;
1237
1238               Returns the first non-zero $?.  See "result" to get the first
1239               $? >> 8 value for a child process.
1240
1241               To get the result of a particular child, do:
1242
1243                  $h->full_result( 0 );  # first child's $?
1244                  $h->full_result( 1 );  # second child
1245
1246               or
1247
1248                  ($h->full_results)[0]
1249                  ($h->full_results)[1]
1250
1251               Returns undef if no child processes were spawned and no child
1252               number was specified.  Throws an exception if an out-of-range
1253               child number is passed.
1254
1255           full_results
1256               Returns a list of child exit values as returned by "wait".  See
1257               "results" if you don't care about coredumps or signals.
1258
1259               Throws an exception if the harness is not in a finished state.
1260

FILTERS

1262       These filters are used to modify input our output between a child
1263       process and a scalar or subroutine endpoint.
1264
1265       binary
1266              run \@cmd, ">", binary, \$out;
1267              run \@cmd, ">", binary, \$out;  ## Any TRUE value to enable
1268              run \@cmd, ">", binary 0, \$out;  ## Any FALSE value to disable
1269
1270           This is a constructor for a "binmode" "filter" that tells IPC::Run
1271           to keep the carriage returns that would ordinarily be edited out
1272           for you (binmode is usually off).  This is not a real filter, but
1273           an option masquerading as a filter.
1274
1275           It's not named "binmode" because you're likely to want to call
1276           Perl's binmode in programs that are piping binary data around.
1277
1278       new_chunker
1279           This breaks a stream of data in to chunks, based on an optional
1280           scalar or regular expression parameter.  The default is the Perl
1281           input record separator in $/, which is a newline be default.
1282
1283              run \@cmd, '>', new_chunker, \&lines_handler;
1284              run \@cmd, '>', new_chunker( "\r\n" ), \&lines_handler;
1285
1286           Because this uses $/ by default, you should always pass in a
1287           parameter if you are worried about other code (modules, etc)
1288           modifying $/.
1289
1290           If this filter is last in a filter chain that dumps in to a scalar,
1291           the scalar must be set to '' before a new chunk will be written to
1292           it.
1293
1294           As an example of how a filter like this can be written, here's a
1295           chunker that splits on newlines:
1296
1297              sub line_splitter {
1298                 my ( $in_ref, $out_ref ) = @_;
1299
1300                 return 0 if length $$out_ref;
1301
1302                 return input_avail && do {
1303                    while (1) {
1304                       if ( $$in_ref =~ s/\A(.*?\n)// ) {
1305                          $$out_ref .= $1;
1306                          return 1;
1307                       }
1308                       my $hmm = get_more_input;
1309                       unless ( defined $hmm ) {
1310                          $$out_ref = $$in_ref;
1311                          $$in_ref = '';
1312                          return length $$out_ref ? 1 : 0;
1313                       }
1314                       return 0 if $hmm eq 0;
1315                    }
1316                 }
1317              };
1318
1319       new_appender
1320           This appends a fixed string to each chunk of data read from the
1321           source scalar or sub.  This might be useful if you're writing
1322           commands to a child process that always must end in a fixed string,
1323           like "\n":
1324
1325              run( \@cmd,
1326                 '<', new_appender( "\n" ), \&commands,
1327              );
1328
1329           Here's a typical filter sub that might be created by
1330           new_appender():
1331
1332              sub newline_appender {
1333                 my ( $in_ref, $out_ref ) = @_;
1334
1335                 return input_avail && do {
1336                    $$out_ref = join( '', $$out_ref, $$in_ref, "\n" );
1337                    $$in_ref = '';
1338                    1;
1339                 }
1340              };
1341
1342       new_string_source
1343           TODO: Needs confirmation. Was previously undocumented. in this
1344           module.
1345
1346           This is a filter which is exportable. Returns a sub which appends
1347           the data passed in to the output buffer and returns 1 if data was
1348           appended. 0 if it was an empty string and undef if no data was
1349           passed.
1350
1351           NOTE: Any additional variables passed to new_string_source will be
1352           passed to the sub every time it's called and appended to the
1353           output.
1354
1355       new_string_sink
1356           TODO: Needs confirmation. Was previously undocumented.
1357
1358           This is a filter which is exportable. Returns a sub which pops the
1359           data out of the input stream and pushes it onto the string.
1360
1361       io  Takes a filename or filehandle, a redirection operator, optional
1362           filters, and a source or destination (depends on the redirection
1363           operator).  Returns an IPC::Run::IO object suitable for
1364           harness()ing (including via start() or run()).
1365
1366           This is shorthand for
1367
1368              require IPC::Run::IO;
1369
1370                 ... IPC::Run::IO->new(...) ...
1371
1372       timer
1373              $h = start( \@cmd, \$in, \$out, $t = timer( 5 ) );
1374
1375              pump $h until $out =~ /expected stuff/ || $t->is_expired;
1376
1377           Instantiates a non-fatal timer.  pump() returns once each time a
1378           timer expires.  Has no direct effect on run(), but you can pass a
1379           subroutine to fire when the timer expires.
1380
1381           See "timeout" for building timers that throw exceptions on
1382           expiration.
1383
1384           See "timer" in IPC::Run::Timer for details.
1385
1386       timeout
1387              $h = start( \@cmd, \$in, \$out, $t = timeout( 5 ) );
1388
1389              pump $h until $out =~ /expected stuff/;
1390
1391           Instantiates a timer that throws an exception when it expires.  If
1392           you don't provide an exception, a default exception that matches
1393           /^IPC::Run: .*timed out/ is thrown by default.  You can pass in
1394           your own exception scalar or reference:
1395
1396              $h = start(
1397                 \@cmd, \$in, \$out,
1398                 $t = timeout( 5, exception => 'slowpoke' ),
1399              );
1400
1401           or set the name used in debugging message and in the default
1402           exception string:
1403
1404              $h = start(
1405                 \@cmd, \$in, \$out,
1406                 timeout( 50, name => 'process timer' ),
1407                 $stall_timer = timeout( 5, name => 'stall timer' ),
1408              );
1409
1410              pump $h until $out =~ /started/;
1411
1412              $in = 'command 1';
1413              $stall_timer->start;
1414              pump $h until $out =~ /command 1 finished/;
1415
1416              $in = 'command 2';
1417              $stall_timer->start;
1418              pump $h until $out =~ /command 2 finished/;
1419
1420              $in = 'very slow command 3';
1421              $stall_timer->start( 10 );
1422              pump $h until $out =~ /command 3 finished/;
1423
1424              $stall_timer->start( 5 );
1425              $in = 'command 4';
1426              pump $h until $out =~ /command 4 finished/;
1427
1428              $stall_timer->reset; # Prevent restarting or expirng
1429              finish $h;
1430
1431           See "timer" for building non-fatal timers.
1432
1433           See "timer" in IPC::Run::Timer for details.
1434

FILTER IMPLEMENTATION FUNCTIONS

1436       These functions are for use from within filters.
1437
1438       input_avail
1439           Returns TRUE if input is available.  If none is available, then
1440           &get_more_input is called and its result is returned.
1441
1442           This is usually used in preference to &get_more_input so that the
1443           calling filter removes all data from the $in_ref before more data
1444           gets read in to $in_ref.
1445
1446           "input_avail" is usually used as part of a return expression:
1447
1448              return input_avail && do {
1449                 ## process the input just gotten
1450                 1;
1451              };
1452
1453           This technique allows input_avail to return the undef or 0 that a
1454           filter normally returns when there's no input to process.  If a
1455           filter stores intermediate values, however, it will need to react
1456           to an undef:
1457
1458              my $got = input_avail;
1459              if ( ! defined $got ) {
1460                 ## No more input ever, flush internal buffers to $out_ref
1461              }
1462              return $got unless $got;
1463              ## Got some input, move as much as need be
1464              return 1 if $added_to_out_ref;
1465
1466       get_more_input
1467           This is used to fetch more input in to the input variable.  It
1468           returns undef if there will never be any more input, 0 if there is
1469           none now, but there might be in the future, and TRUE if more input
1470           was gotten.
1471
1472           "get_more_input" is usually used as part of a return expression,
1473           see "input_avail" for more information.
1474

TODO

1476       These will be addressed as needed and as time allows.
1477
1478       Stall timeout.
1479
1480       Expose a list of child process objects.  When I do this, each child
1481       process is likely to be blessed into IPC::Run::Proc.
1482
1483       $kid->abort(), $kid->kill(), $kid->signal( $num_or_name ).
1484
1485       Write tests for /(full_)?results?/ subs.
1486
1487       Currently, pump() and run() only work on systems where select() works
1488       on the filehandles returned by pipe().  This does *not* include
1489       ActiveState on Win32, although it does work on cygwin under Win32
1490       (thought the tests whine a bit).  I'd like to rectify that, suggestions
1491       and patches welcome.
1492
1493       Likewise start() only fully works on fork()/exec() machines (well, just
1494       fork() if you only ever pass perl subs as subprocesses).  There's some
1495       scaffolding for calling Open3::spawn_with_handles(), but that's
1496       untested, and not that useful with limited select().
1497
1498       Support for "\@sub_cmd" as an argument to a command which gets replaced
1499       with /dev/fd or the name of a temporary file containing foo's output.
1500       This is like <(sub_cmd ...) found in bash and csh (IIRC).
1501
1502       Allow multiple harnesses to be combined as independent sets of
1503       processes in to one 'meta-harness'.
1504
1505       Allow a harness to be passed in place of an \@cmd.  This would allow
1506       multiple harnesses to be aggregated.
1507
1508       Ability to add external file descriptors w/ filter chains and
1509       endpoints.
1510
1511       Ability to add timeouts and timing generators (i.e. repeating
1512       timeouts).
1513
1514       High resolution timeouts.
1515

Win32 LIMITATIONS

1517       Fails on Win9X
1518           If you want Win9X support, you'll have to debug it or fund me
1519           because I don't use that system any more.  The Win32 subsysem has
1520           been extended to use temporary files in simple run() invocations
1521           and these may actually work on Win9X too, but I don't have time to
1522           work on it.
1523
1524       May deadlock on Win2K (but not WinNT4 or WinXPPro)
1525           Spawning more than one subprocess on Win2K causes a deadlock I
1526           haven't figured out yet, but simple uses of run() often work.
1527           Passes all tests on WinXPPro and WinNT.
1528
1529       no support yet for <pty< and >pty>
1530           These are likely to be implemented as "<" and ">" with binmode on,
1531           not sure.
1532
1533       no support for file descriptors higher than 2 (stderr)
1534           Win32 only allows passing explicit fds 0, 1, and 2.  If you really,
1535           really need to pass file handles, us Win32API:: GetOsFHandle() or
1536           ::FdGetOsFHandle() to get the integer handle and pass it to the
1537           child process using the command line, environment, stdin,
1538           intermediary file, or other IPC mechanism.  Then use that handle in
1539           the child (Win32API.pm provides ways to reconstitute Perl file
1540           handles from Win32 file handles).
1541
1542       no support for subroutine subprocesses (CODE refs)
1543           Can't fork(), so the subroutines would have no context, and
1544           closures certainly have no meaning
1545
1546           Perhaps with Win32 fork() emulation, this can be supported in a
1547           limited fashion, but there are other very serious problems with
1548           that: all parent fds get dup()ed in to the thread emulating the
1549           forked process, and that keeps the parent from being able to close
1550           all of the appropriate fds.
1551
1552       no support for init => sub {} routines.
1553           Win32 processes are created from scratch, there is no way to do an
1554           init routine that will affect the running child.  Some limited
1555           support might be implemented one day, do chdir() and %ENV changes
1556           can be made.
1557
1558       signals
1559           Win32 does not fully support signals.  signal() is likely to cause
1560           errors unless sending a signal that Perl emulates, and
1561           "kill_kill()" is immediately fatal (there is no grace period).
1562
1563       helper processes
1564           IPC::Run uses helper processes, one per redirected file, to adapt
1565           between the anonymous pipe connected to the child and the TCP
1566           socket connected to the parent.  This is a waste of resources and
1567           will change in the future to either use threads (instead of helper
1568           processes) or a WaitForMultipleObjects call (instead of select).
1569           Please contact me if you can help with the WaitForMultipleObjects()
1570           approach; I haven't figured out how to get at it without C code.
1571
1572       shutdown pause
1573           There seems to be a pause of up to 1 second between when a child
1574           program exits and the corresponding sockets indicate that they are
1575           closed in the parent.  Not sure why.
1576
1577       binmode
1578           binmode is not supported yet.  The underpinnings are implemented,
1579           just ask if you need it.
1580
1581       IPC::Run::IO
1582           IPC::Run::IO objects can be used on Unix to read or write arbitrary
1583           files.  On Win32, they will need to use the same helper processes
1584           to adapt from non-select()able filehandles to select()able ones (or
1585           perhaps WaitForMultipleObjects() will work with them, not sure).
1586
1587       startup race conditions
1588           There seems to be an occasional race condition between child
1589           process startup and pipe closings.  It seems like if the child is
1590           not fully created by the time CreateProcess returns and we close
1591           the TCP socket being handed to it, the parent socket can also get
1592           closed.  This is seen with the Win32 pumper applications, not the
1593           "real" child process being spawned.
1594
1595           I assume this is because the kernel hasn't gotten around to
1596           incrementing the reference count on the child's end (since the
1597           child was slow in starting), so the parent's closing of the child
1598           end causes the socket to be closed, thus closing the parent socket.
1599
1600           Being a race condition, it's hard to reproduce, but I encountered
1601           it while testing this code on a drive share to a samba box.  In
1602           this case, it takes t/run.t a long time to spawn it's child
1603           processes (the parent hangs in the first select for several seconds
1604           until the child emits any debugging output).
1605
1606           I have not seen it on local drives, and can't reproduce it at will,
1607           unfortunately.  The symptom is a "bad file descriptor in select()"
1608           error, and, by turning on debugging, it's possible to see that
1609           select() is being called on a no longer open file descriptor that
1610           was returned from the _socket() routine in Win32Helper.  There's a
1611           new confess() that checks for this ("PARENT_HANDLE no longer
1612           open"), but I haven't been able to reproduce it (typically).
1613

LIMITATIONS

1615       On Unix, requires a system that supports "waitpid( $pid, WNOHANG )" so
1616       it can tell if a child process is still running.
1617
1618       PTYs don't seem to be non-blocking on some versions of Solaris. Here's
1619       a test script contributed by Borislav Deianov <borislav@ensim.com> to
1620       see if you have the problem.  If it dies, you have the problem.
1621
1622          #!/usr/bin/perl
1623
1624          use IPC::Run qw(run);
1625          use Fcntl;
1626          use IO::Pty;
1627
1628          sub makecmd {
1629              return ['perl', '-e',
1630                      '<STDIN>, print "\n" x '.$_[0].'; while(<STDIN>){last if /end/}'];
1631          }
1632
1633          #pipe R, W;
1634          #fcntl(W, F_SETFL, O_NONBLOCK);
1635          #while (syswrite(W, "\n", 1)) { $pipebuf++ };
1636          #print "pipe buffer size is $pipebuf\n";
1637          my $pipebuf=4096;
1638          my $in = "\n" x ($pipebuf * 2) . "end\n";
1639          my $out;
1640
1641          $SIG{ALRM} = sub { die "Never completed!\n" };
1642
1643          print "reading from scalar via pipe...";
1644          alarm( 2 );
1645          run(makecmd($pipebuf * 2), '<', \$in, '>', \$out);
1646          alarm( 0 );
1647          print "done\n";
1648
1649          print "reading from code via pipe... ";
1650          alarm( 2 );
1651          run(makecmd($pipebuf * 3), '<', sub { $t = $in; undef $in; $t}, '>', \$out);
1652          alarm( 0 );
1653          print "done\n";
1654
1655          $pty = IO::Pty->new();
1656          $pty->blocking(0);
1657          $slave = $pty->slave();
1658          while ($pty->syswrite("\n", 1)) { $ptybuf++ };
1659          print "pty buffer size is $ptybuf\n";
1660          $in = "\n" x ($ptybuf * 3) . "end\n";
1661
1662          print "reading via pty... ";
1663          alarm( 2 );
1664          run(makecmd($ptybuf * 3), '<pty<', \$in, '>', \$out);
1665          alarm(0);
1666          print "done\n";
1667
1668       No support for ';', '&&', '||', '{ ... }', etc: use perl's, since run()
1669       returns TRUE when the command exits with a 0 result code.
1670
1671       Does not provide shell-like string interpolation.
1672
1673       No support for "cd", "setenv", or "export": do these in an init() sub
1674
1675          run(
1676             \cmd,
1677                ...
1678                init => sub {
1679                   chdir $dir or die $!;
1680                   $ENV{FOO}='BAR'
1681                }
1682          );
1683
1684       Timeout calculation does not allow absolute times, or specification of
1685       days, months, etc.
1686
1687       WARNING: Function coprocesses ("run \&foo, ...") suffer from two
1688       limitations.  The first is that it is difficult to close all
1689       filehandles the child inherits from the parent, since there is no way
1690       to scan all open FILEHANDLEs in Perl and it both painful and a bit
1691       dangerous to close all open file descriptors with "POSIX::close()".
1692       Painful because we can't tell which fds are open at the POSIX level,
1693       either, so we'd have to scan all possible fds and close any that we
1694       don't want open (normally "exec()" closes any non-inheritable but we
1695       don't "exec()" for &sub processes.
1696
1697       The second problem is that Perl's DESTROY subs and other on-exit
1698       cleanup gets run in the child process.  If objects are instantiated in
1699       the parent before the child is forked, the DESTROY will get run once in
1700       the parent and once in the child.  When coprocess subs exit,
1701       POSIX::_exit is called to work around this, but it means that objects
1702       that are still referred to at that time are not cleaned up.  So setting
1703       package vars or closure vars to point to objects that rely on DESTROY
1704       to affect things outside the process (files, etc), will lead to bugs.
1705
1706       I goofed on the syntax: "<pipe" vs. "<pty<" and ">filename" are both
1707       oddities.
1708

TODO

1710       Allow one harness to "adopt" another:
1711              $new_h = harness \@cmd2;
1712              $h->adopt( $new_h );
1713
1714       Close all filehandles not explicitly marked to stay open.
1715           The problem with this one is that there's no good way to scan all
1716           open FILEHANDLEs in Perl, yet you don't want child processes
1717           inheriting handles willy-nilly.
1718

INSPIRATION

1720       Well, select() and waitpid() badly needed wrapping, and open3() isn't
1721       open-minded enough for me.
1722
1723       The shell-like API inspired by a message Russ Allbery sent to
1724       perl5-porters, which included:
1725
1726          I've thought for some time that it would be
1727          nice to have a module that could handle full Bourne shell pipe syntax
1728          internally, with fork and exec, without ever invoking a shell.  Something
1729          that you could give things like:
1730
1731          pipeopen (PIPE, [ qw/cat file/ ], '|', [ 'analyze', @args ], '>&3');
1732
1733       Message ylln51p2b6.fsf@windlord.stanford.edu, on 2000/02/04.
1734

SUPPORT

1736       Bugs should always be submitted via the GitHub bug tracker
1737
1738       <https://github.com/toddr/IPC-Run/issues>
1739

AUTHORS

1741       Adam Kennedy <adamk@cpan.org>
1742
1743       Barrie Slaymaker <barries@slaysys.com>
1744
1746       Some parts copyright 2008 - 2009 Adam Kennedy.
1747
1748       Copyright 1999 Barrie Slaymaker.
1749
1750       You may distribute under the terms of either the GNU General Public
1751       License or the Artistic License, as specified in the README file.
1752
1753
1754
1755perl v5.32.0                      2020-07-28                       IPC::Run(3)
Impressum