1IPC::Run(3) User Contributed Perl Documentation IPC::Run(3)
2
6 IPC::Run - system() and background procs w/ piping, redirs, ptys (Unix,
7 Win32)
8
10 ## First,a command to run:
11 my @cat = qw( cat );
12 ## Using run() instead of system():
14 use IPC::Run qw( run timeout );
15 run \@cmd, \$in, \$out, \$err, timeout( 10 ) or die "cat: $?"
17 # Can do I/O to sub refs and filenames, too:
19 run \@cmd, '<', "in.txt", \&out, \&err or die "cat: $?"
20 run \@cat, '<', "in.txt", '>>', "out.txt", '2>>', "err.txt";
21 # Redirecting using psuedo-terminals instad of pipes.
24 run \@cat, '<pty<', \$in, '>pty>', \$out_and_err;
25 ## Scripting subprocesses (like Expect):
27 use IPC::Run qw( start pump finish timeout );
29 # 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 $in .= "some input\n";
38 pump $h until $out =~ /input\n/g;
39 $in .= "some more input\n";
41 pump $h until $out =~ /\G.*more input\n/;
42 $in .= "some final input\n";
44 finish $h or die "cat returned $?";
45 warn $err if $err;
47 print $out; ## All of cat's output
48 # Piping between children
50 run \@cat, '|', \@gzip;
51 # Multiple children simultaneously (run() blocks until all
53 # children exit, use start() for background execution):
54 run \@foo1, '&', \@foo2;
55 # 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 # 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 # Create pipes for you to read / write (like IPC::Open2 & 3).
73 $h = start
74 \@cat,
75 '<pipe', \*IN,
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 # Mixing input and output modes
85 run \@cat, 'in.txt', \&catch_some_out, \*ERR_LOG );
86 # 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 # Passing options:
97 run \@cat, 'in.txt', debug => 1;
98 # 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 # 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 # Read from a file in to a scalar
109 run io( "filename", 'r', \$recv );
110 run io( \*HANDLE, 'r', \$recv );
111
113 IPC::Run allows you run and interact with child processes using files,
114 pipes, and pseudo-ttys. Both system()-style and scripted usages are
115 supported and may be mixed. Likewise, functional and OO API styles are
116 both supported and may be mixed.
117 Various redirection operators reminiscent of those seen on common Unix
119 and DOS command lines are provided.
120 Before digging in to the details a few LIMITATIONS are important enough
122 to be mentioned right up front:
123 Win32 Support
125 Win32 support is working but EXPERIMENTAL, but does pass all
126 relevant tests on NT 4.0. See "Win32 LIMITATIONS".
127 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 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 ptys are not supported yet under Win32, but will be emulated...
140 Debugging Tip
142 You may use the environment variable "IPCRUNDEBUG" to see what's
143 going on under the hood:
144 $ 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 We now return you to your regularly scheduled documentation.
152 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 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 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 run \@cmd, \<<IN, \$out;
168 blah
169 IN
170 ## To precompile harnesses and run them later:
172 my $h = harness \@cmd, \<<IN, \$out;
173 blah
174 IN
175 run $h;
177 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 ## Build the harness, open all pipes, and launch the subprocesses
185 my $h = start \@cat, \$in, \$out;
186 $in = "first input\n";
187 ## Now do I/O. start() does no I/O.
189 pump $h while length $in; ## Wait for all input to go
190 ## Now do some more I/O.
192 $in = "second input\n";
193 pump $h until $out =~ /second input/;
194 ## Clean up
196 finish $h or die "cat returned $?";
197 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 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 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 $h = harness \@smbclient, \$in, \$out;
217 $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 $in = "mget *\n";
224 $h->pump until $out =~ /^smb.*> \Z/m;
225 die "error retrieving files:\n$out" if $out =~ "ERR";
226 $in = "quit\n";
228 $h->finish;
229 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 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 $h = harness \@smbclient, \$in, \$out;
246 $in = "cd /src\n";
248 $h->pump until $out =~ /^smb.*> \Z/mgc;
249 die "error cding to /src:\n$out" if $out =~ "ERR";
250 $in = "mget *\n";
252 $h->pump until $out =~ /^smb.*> \Z/mgc;
253 die "error retrieving files:\n$out" if $out =~ "ERR";
254 $in = "quit\n";
256 $h->finish;
257 analyze( $out );
259 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 my $out = "x" x 10_000;
267 $out = "";
268 "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 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 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 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 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 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 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 ## Start with a nice long timeout to let smbclient connect. If
307 ## pump or finish take too long, an exception will be thrown.
308 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 start $h;
315 $in = "cd /src\n";
316 pump $h until ! length $in;
317 $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 $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 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 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 ocurred in the parent.
344 This includes exceptions your code thrown from init subs. In this
346 example:
347 eval {
349 run \@cmd, init => sub { die "blast it! foiled again!" };
350 };
351 print $@;
352 the exception "blast it! foiled again" will be thrown from the child
354 process (preventing the exec()) and printed by the parent.
355 In situations like
357 run \@cmd1, "|", \@cmd2, "|", \@cmd3;
359 @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 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 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 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 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 Win32: executing CODE references isn't supported on Win32, see "Win32
390 LIMITATIONS" for details.
391 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 run "echo 'hi there'";
398 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 run \@cmd;
405 run \@cmd1, '|', \@cmd2;
406 run \@cmd1, '&', \@cmd2;
407 run \&sub1;
408 run \&sub1, '|', \&sub2;
409 run \&sub1, '&', \&sub2;
410 '|' 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 IPC::Run::IO objects may be passed in as well, whether or not child
416 processes are also specified:
417 run io( "infile", ">", \$in ), io( "outfile", "<", \$in );
419 as can IPC::Run::Timer objects:
421 run \@cmd, io( "outfile", "<", \$in ), timeout( 10 );
423 Commands may be followed by scalar, sub, or i/o handle references for
425 redirecting child process input & output:
426 run \@cmd, \undef, \$out;
428 run \@cmd, \$in, \$out;
429 run \@cmd1, \&in, '|', \@cmd2, \*OUT;
430 run \@cmd1, \*IN, '|', \@cmd2, \&out;
431 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 To be explicit about your redirects, or if you need to do more complex
439 things, there's also a redirection operator syntax:
440 run \@cmd, '<', \undef, '>', \$out;
442 run \@cmd, '<', \undef, '>&', \$out_and_err;
443 run(
444 \@cmd1,
445 '<', \$in,
446 '|', \@cmd2,
447 \$out
448 );
449 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 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 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 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 desciptors 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 If you want to close a child processes stdin, you may do any of:
478 run \@cmd, \undef;
480 run \@cmd, \"";
481 run \@cmd, '<&-';
482 run \@cmd, '0<&-';
483 Redirection is done by placing redirection specifications immediately
485 after a command or child subroutine:
486 run \@cmd1, \$in, '|', \@cmd2, \$out;
488 run \@cmd1, '<', \$in, '|', \@cmd2, '>', \$out;
489 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 run \@cmd1, \$in, '|', \@cmd2, \$out;
495 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 If it's a scalar ref, the child reads input from or sends output to
501 that variable:
502 $in = "Hello World.\n";
504 run \@cat, \$in, \$out;
505 print $out;
506 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 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 $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 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
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 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 Here are some of the issues you might need to be aware of.
542 ยท fflush()ing stdout and stderr
544 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 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 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 ยท false prompts
557 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 This can make it hard to guarantee that your output parser won't be
564 fooled into early termination of results.
565 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 You should also look for your prompt to be the only thing on a
571 line:
572 pump $h until $out =~ /^<SILLYPROMPT>\s?\z/m;
574 (use "(?!\n)\Z" in place of "\z" on older perls).
576 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 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 ยท Refusing to accept input unless stdin is a tty.
589 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 If this is your situation, use a pseudo terminal ('<pty<' and
595 '>pty>').
596 ยท Not prompting unless connected to a tty.
598 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 ยท Different output format when not connected to a tty.
607 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
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 CAVEATS
619 Psuedo-terminals are not pipes, though they are similar. Here are some
620 differences to watch out for.
621 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 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 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 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 '>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 start \@cmd, '<pty<', \$in, '>pty>', \$out, '2>', \$err;
648 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 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 Redirection Operators
661 Operator SHNP Description
662 ======== ==== ===========
663 <, N< SHN Redirects input to a child's fd N (0 assumed)
664 >, 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 <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 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 <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 'N' and 'M' are placeholders for integer file descriptor numbers. The
680 terms 'input' and 'output' are from the child process's perspective.
681 The SHNP field indicates what parameters an operator can take:
683 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 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 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 run \@cat, \undef ## Closes child's stdin immediately
697 or die "cat returned $?";
698 run \@cat, \$in;
700 run \@cat, \<<TOHERE;
702 blah
703 TOHERE
704 run \@cat, \&input; ## Calls &input, feeding data returned
706 ## to child's. Closes child's stdin
707 ## when undef is returned.
708 Redirecting from named files requires you to use the input
710 redirection operator:
711 run \@cat, '<.profile';
713 run \@cat, '<', '.profile';
714 open IN, "<foo";
716 run \@cat, \*IN;
717 run \@cat, *IN{IO};
718 The form used second example here is the safest, since filenames
720 like "0" and "&more\n" won't confuse &run:
721 You can't do either of
723 run \@a, *IN; ## INVALID
725 run \@a, '<', *IN; ## BUGGY: Reads file named like "*main::A"
726 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 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 run \@cat, '3<', \$in3;
737 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 The <pipe operator opens the write half of a pipe on the filehandle
744 glob reference it takes as an argument:
745 $h = start \@cat, '<pipe', \*IN;
747 print IN "hello world\n";
748 pump $h;
749 close IN;
750 finish $h;
751 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 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 This is like the behavior of IPC::Open2 and IPC::Open3.
764 Win32: The handle returned is actually a socket handle, so you can
766 use select() on it.
767 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 @ls = ( 'ls' );
776 run \@ls, \undef, \$out
777 or die "ls returned $?";
778 run \@ls, \undef, \&out; ## Calls &out each time some output
780 ## is received from the child's
781 ## when undef is returned.
782 run \@ls, \undef, '2>ls.err';
784 run \@ls, '2>', 'ls.err';
785 The two parameter form guarantees that the filename will not be
787 interpreted as a redirection operator:
788 run \@ls, '>', "&more";
790 run \@ls, '2>', ">foo\n";
791 You can pass file handles you've opened for writing:
793 open( *OUT, ">out.txt" );
795 open( *ERR, ">err.txt" );
796 run \@cat, \*OUT, \*ERR;
797 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 These two do the same things:
803 run( [ 'ls' ], '2>', sub { $err_out .= $_[0] } );
805 does the same basic thing as:
807 run( [ 'ls' ], '2>', \$err_out );
809 The subroutine will be called each time some data is read from the
811 child.
812 The >pipe operator is different in concept than the other '>'
814 operators, although it's syntax is similar:
815 $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 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 Win32: The handle returned is actually a socket handle, so you can
830 use select() on it.
831 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 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 Closing descriptors: <&-, 3<&-
841 This closes descriptor number n (default is 0 if n is omitted).
842 The following commands are equivalent:
843 run \@cmd, \undef;
845 run \@cmd, '<&-';
846 run \@cmd, '<in.txt', '<&-';
847 Doing
849 run \@cmd, \$in, '<&-'; ## SIGPIPE recipe.
851 is dangerous: the parent will get a SIGPIPE if $in is not empty.
853 Redirecting both stdout and stderr: &>, >&, &>pipe, >pipe&
855 The following pairs of commands are equivalent:
856 run \@cmd, '>&', \$out; run \@cmd, '>', \$out, '2>&1';
858 run \@cmd, '>&', 'out.txt'; run \@cmd, '>', 'out.txt', '2>&1';
859 etc.
861 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 The '&>pipe' and '>pipe&' variants behave like the '>pipe'
867 operator, except that both stdout and stderr write to the created
868 pipe.
869 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 run(
879 \@cmd
880 '<', \&in_filter_2, \&in_filter_1, $in,
881 '>', \&out_filter_1, \&in_filter_2, $out,
882 );
883 This capability is not provided for IO handles or named files.
885 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 run(
892 \@cmd
893 '<', new_appender( "\n" ), $in,
894 '>', new_chunker, $out,
895 );
896 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 run io( "filename", '>', \$recv );
903 $h = start io( $io, '>', \$recv );
905 $h = harness \@cmd, '&', io( "file", '<', \$send );
907 Options
909 Options are passed in as name/value pairs:
910 run \@cat, \$in, debug => 1;
912 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 run debug => 1, \@cat, \$in;
917 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
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 $h = harness( ... );
931 $h->start;
932 $h->pump;
933 $h->finish;
934 $h = start( .... );
936 $h->pump;
937 ...
938 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 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 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
952 run Run takes a harness or harness specification and runs it, pumping
953 all input to the child(ren), closing the input pipes when no more
954 input is available, collecting all output that arrives, until the
955 pipes delivering output are closed, then waiting for the children
956 to exit and reaping their result codes.
957 You may think of "run( ... )" as being like
959 start( ... )->finish();
961 , though there is one subtle difference: run() does not set
963 \$input_scalars to '' like finish() does. If an exception is
964 thrown from run(), all children will be killed off "gently", and
965 then "annihilated" if they do not go gently (in to that dark night.
966 sorry).
967 If any exceptions are thrown, this does a "kill_kill" before
969 propogating them.
970 signal
972 ## To send it a specific signal by name ("USR1"):
973 signal $h, "USR1";
974 $h->signal ( "USR1" );
975 If $signal is provided and defined, sends a signal to all child
977 processes. Try not to send numeric signals, use "KILL" instead of
978 9, for instance. Numeric signals aren't portable.
979 Throws an exception if $signal is undef.
981 This will not clean up the harness, "finish" it if you kill it.
983 Normally TERM kills a process gracefully (this is what the command
985 line utility "kill" does by default), INT is sent by one of the
986 keys "^C", "Backspace" or "<Del>", and "QUIT" is used to kill a
987 process and make it coredump.
988 The "HUP" signal is often used to get a process to "restart",
990 rereading config files, and "USR1" and "USR2" for really
991 application-specific things.
992 Often, running "kill -l" (that's a lower case "L") on the command
994 line will list the signals present on your operating system.
995 WARNING: The signal subsystem is not at all portable. We *may*
997 offer to simulate "TERM" and "KILL" on some operating systems,
998 submit code to me if you want this.
999 WARNING 2: Up to and including perl v5.6.1, doing almost anything
1001 in a signal handler could be dangerous. The most safe code avoids
1002 all mallocs and system calls, usually by preallocating a flag
1003 before entering the signal handler, altering the flag's value in
1004 the handler, and responding to the changed value in the main
1005 system:
1006 my $got_usr1 = 0;
1008 sub usr1_handler { ++$got_signal }
1009 $SIG{USR1} = \&usr1_handler;
1011 while () { sleep 1; print "GOT IT" while $got_usr1--; }
1012 Even this approach is perilous if ++ and -- aren't atomic on your
1014 system (I've never heard of this on any modern CPU large enough to
1015 run perl).
1016 kill_kill
1018 ## To kill off a process:
1019 $h->kill_kill;
1020 kill_kill $h;
1021 ## To specify the grace period other than 30 seconds:
1023 kill_kill $h, grace => 5;
1024 ## To send QUIT instead of KILL if a process refuses to die:
1026 kill_kill $h, coup_d_grace => "QUIT";
1027 Sends a "TERM", waits for all children to exit for up to 30
1029 seconds, then sends a "KILL" to any that survived the "TERM".
1030 Will wait for up to 30 more seconds for the OS to sucessfully
1032 "KILL" the processes.
1033 The 30 seconds may be overriden by setting the "grace" option, this
1035 overrides both timers.
1036 The harness is then cleaned up.
1038 The doubled name indicates that this function may kill again and
1040 avoids colliding with the core Perl "kill" function.
1041 Returns a 1 if the "TERM" was sufficient, or a 0 if "KILL" was
1043 required. Throws an exception if "KILL" did not permit the
1044 children to be reaped.
1045 NOTE: The grace period is actually up to 1 second longer than that
1047 given. This is because the granularity of "time" is 1 second. Let
1048 me know if you need finer granularity, we can leverage Time::HiRes
1049 here.
1050 Win32: Win32 does not know how to send real signals, so "TERM" is a
1052 full-force kill on Win32. Thus all talk of grace periods, etc. do
1053 not apply to Win32.
1054 harness
1056 Takes a harness specification and returns a harness. This harness
1057 is blessed in to IPC::Run, allowing you to use method call syntax
1058 for run(), start(), et al if you like.
1059 harness() is provided so that you can pre-build harnesses if you
1061 would like to, but it's not required..
1062 You may proceed to run(), start() or pump() after calling harness()
1064 (pump() calls start() if need be). Alternatively, you may pass
1065 your harness specification to run() or start() and let them
1066 harness() for you. You can't pass harness specifications to
1067 pump(), though.
1068 close_terminal
1070 This is used as (or in) an init sub to cast off the bonds of a
1071 controlling terminal. It must precede all other redirection ops
1072 that affect STDIN, STDOUT, or STDERR to be guaranteed effective.
1073 start
1075 $h = start(
1076 \@cmd, \$in, \$out, ...,
1077 timeout( 30, name => "process timeout" ),
1078 $stall_timeout = timeout( 10, name => "stall timeout" ),
1079 );
1080 $h = start \@cmd, '<', \$in, '|', \@cmd2, ...;
1082 start() accepts a harness or harness specification and returns a
1084 harness after building all of the pipes and launching (via
1085 fork()/exec(), or, maybe someday, spawn()) all the child processes.
1086 It does not send or receive any data on the pipes, see pump() and
1087 finish() for that.
1088 You may call harness() and then pass it's result to start() if you
1090 like, but you only need to if it helps you structure or tune your
1091 application. If you do call harness(), you may skip start() and
1092 proceed directly to pump.
1093 start() also starts all timers in the harness. See IPC::Run::Timer
1095 for more information.
1096 start() flushes STDOUT and STDERR to help you avoid duplicate
1098 output. It has no way of asking Perl to flush all your open
1099 filehandles, so you are going to need to flush any others you have
1100 open. Sorry.
1101 Here's how if you don't want to alter the state of $| for your
1103 filehandle:
1104 $ofh = select HANDLE; $of = $|; $| = 1; $| = $of; select $ofh;
1106 If you don't mind leaving output unbuffered on HANDLE, you can do
1108 the slightly shorter
1109 $ofh = select HANDLE; $| = 1; select $ofh;
1111 Or, you can use IO::Handle's flush() method:
1113 use IO::Handle;
1115 flush HANDLE;
1116 Perl needs the equivalent of C's fflush( (FILE *)NULL ).
1118 pump
1120 pump $h;
1121 $h->pump;
1122 Pump accepts a single parameter harness. It blocks until it
1124 delivers some input or recieves some output. It returns TRUE if
1125 there is still input or output to be done, FALSE otherwise.
1126 pump() will automatically call start() if need be, so you may call
1128 harness() then proceed to pump() if that helps you structure your
1129 application.
1130 If pump() is called after all harnessed activities have completed,
1132 a "process ended prematurely" exception to be thrown. This allows
1133 for simple scripting of external applications without having to add
1134 lots of error handling code at each step of the script:
1135 $h = harness \@smbclient, \$in, \$out, $err;
1137 $in = "cd /foo\n";
1139 $h->pump until $out =~ /^smb.*> \Z/m;
1140 die "error cding to /foo:\n$out" if $out =~ "ERR";
1141 $out = '';
1142 $in = "mget *\n";
1144 $h->pump until $out =~ /^smb.*> \Z/m;
1145 die "error retrieving files:\n$out" if $out =~ "ERR";
1146 $h->finish;
1148 warn $err if $err;
1150 pump_nb
1152 pump_nb $h;
1153 $h->pump_nb;
1154 "pump() non-blocking", pumps if anything's ready to be pumped,
1156 returns immediately otherwise. This is useful if you're doing some
1157 long-running task in the foreground, but don't want to starve any
1158 child processes.
1159 pumpable
1161 Returns TRUE if calling pump() won't throw an immediate "process
1162 ended prematurely" exception. This means that there are open I/O
1163 channels or active processes. May yield the parent processes' time
1164 slice for 0.01 second if all pipes are to the child and all are
1165 paused. In this case we can't tell if the child is dead, so we
1166 yield the processor and then attempt to reap the child in a
1167 nonblocking way.
1168 reap_nb
1170 Attempts to reap child processes, but does not block.
1171 Does not currently take any parameters, one day it will allow
1173 specific children to be reaped.
1174 Only call this from a signal handler if your "perl" is recent
1176 enough to have safe signal handling (5.6.1 did not, IIRC, but it
1177 was beign discussed on perl5-porters). Calling this (or doing any
1178 significant work) in a signal handler on older "perl"s is asking
1179 for seg faults.
1180 finish
1182 This must be called after the last start() or pump() call for a
1183 harness, or your system will accumulate defunct processes and you
1184 may "leak" file descriptors.
1185 finish() returns TRUE if all children returned 0 (and were not
1187 signaled and did not coredump, ie ! $?), and FALSE otherwise (this
1188 is like run(), and the opposite of system()).
1189 Once a harness has been finished, it may be run() or start()ed
1191 again, including by pump()s auto-start.
1192 If this throws an exception rather than a normal exit, the harness
1194 may be left in an unstable state, it's best to kill the harness to
1195 get rid of all the child processes, etc.
1196 Specifically, if a timeout expires in finish(), finish() will not
1198 kill all the children. Call "<$h-"kill_kill>> in this case if you
1199 care. This differs from the behavior of "run".
1200 result
1202 $h->result;
1203 Returns the first non-zero result code (ie $? >> 8). See
1205 "full_result" to get the $? value for a child process.
1206 To get the result of a particular child, do:
1208 $h->result( 0 ); # first child's $? >> 8
1210 $h->result( 1 ); # second child
1211 or
1213 ($h->results)[0]
1215 ($h->results)[1]
1216 Returns undef if no child processes were spawned and no child
1218 number was specified. Throws an exception if an out-of-range child
1219 number is passed.
1220 results
1222 Returns a list of child exit values. See "full_results" if you
1223 want to know if a signal killed the child.
1224 Throws an exception if the harness is not in a finished state.
1226 full_result
1228 $h->full_result;
1229 Returns the first non-zero $?. See "result" to get the first $? >>
1231 8 value for a child process.
1232 To get the result of a particular child, do:
1234 $h->full_result( 0 ); # first child's $? >> 8
1236 $h->full_result( 1 ); # second child
1237 or
1239 ($h->full_results)[0]
1241 ($h->full_results)[1]
1242 Returns undef if no child processes were spawned and no child
1244 number was specified. Throws an exception if an out-of-range child
1245 number is passed.
1246 full_results
1248 Returns a list of child exit values as returned by "wait". See
1249 "results" if you don't care about coredumps or signals.
1250 Throws an exception if the harness is not in a finished state.
1252
1254 These filters are used to modify input our output between a child
1255 process and a scalar or subroutine endpoint.
1256 binary
1258 run \@cmd, ">", binary, \$out;
1259 run \@cmd, ">", binary, \$out; ## Any TRUE value to enable
1260 run \@cmd, ">", binary 0, \$out; ## Any FALSE value to disable
1261 This is a constructor for a "binmode" "filter" that tells IPC::Run
1263 to keep the carriage returns that would ordinarily be edited out
1264 for you (binmode is usually off). This is not a real filter, but
1265 an option masquerading as a filter.
1266 It's not named "binmode" because you're likely to want to call
1268 Perl's binmode in programs that are piping binary data around.
1269 new_chunker
1271 This breaks a stream of data in to chunks, based on an optional
1272 scalar or regular expression parameter. The default is the Perl
1273 input record separator in $/, which is a newline be default.
1274 run \@cmd, '>', new_chunker, \&lines_handler;
1276 run \@cmd, '>', new_chunker( "\r\n" ), \&lines_handler;
1277 Because this uses $/ by default, you should always pass in a
1279 parameter if you are worried about other code (modules, etc)
1280 modifying $/.
1281 If this filter is last in a filter chain that dumps in to a scalar,
1283 the scalar must be set to '' before a new chunk will be written to
1284 it.
1285 As an example of how a filter like this can be written, here's a
1287 chunker that splits on newlines:
1288 sub line_splitter {
1290 my ( $in_ref, $out_ref ) = @_;
1291 return 0 if length $$out_ref;
1293 return input_avail && do {
1295 while (1) {
1296 if ( $$in_ref =~ s/\A(.*?\n)// ) {
1297 $$out_ref .= $1;
1298 return 1;
1299 }
1300 my $hmm = get_more_input;
1301 unless ( defined $hmm ) {
1302 $$out_ref = $$in_ref;
1303 $$in_ref = '';
1304 return length $$out_ref ? 1 : 0;
1305 }
1306 return 0 if $hmm eq 0;
1307 }
1308 }
1309 };
1310 new_appender
1312 This appends a fixed string to each chunk of data read from the
1313 source scalar or sub. This might be useful if you're writing
1314 commands to a child process that always must end in a fixed string,
1315 like "\n":
1316 run( \@cmd,
1318 '<', new_appender( "\n" ), \&commands,
1319 );
1320 Here's a typical filter sub that might be created by
1322 new_appender():
1323 sub newline_appender {
1325 my ( $in_ref, $out_ref ) = @_;
1326 return input_avail && do {
1328 $$out_ref = join( '', $$out_ref, $$in_ref, "\n" );
1329 $$in_ref = '';
1330 1;
1331 }
1332 };
1333 io Takes a filename or filehandle, a redirection operator, optional
1335 filters, and a source or destination (depends on the redirection
1336 operator). Returns an IPC::Run::IO object suitable for
1337 harness()ing (including via start() or run()).
1338 This is shorthand for
1340 require IPC::Run::IO;
1342 ... IPC::Run::IO->new(...) ...
1344 timer
1346 $h = start( \@cmd, \$in, \$out, $t = timer( 5 ) );
1347 pump $h until $out =~ /expected stuff/ || $t->is_expired;
1349 Instantiates a non-fatal timer. pump() returns once each time a
1351 timer expires. Has no direct effect on run(), but you can pass a
1352 subroutine to fire when the timer expires.
1353 See "timeout" for building timers that throw exceptions on
1355 expiration.
1356 See "timer" in IPC::Run::Timer for details.
1358 timeout
1360 $h = start( \@cmd, \$in, \$out, $t = timeout( 5 ) );
1361 pump $h until $out =~ /expected stuff/;
1363 Instantiates a timer that throws an exception when it expires. If
1365 you don't provide an exception, a default exception that matches
1366 /^IPC::Run: .*timed out/ is thrown by default. You can pass in
1367 your own exception scalar or reference:
1368 $h = start(
1370 \@cmd, \$in, \$out,
1371 $t = timeout( 5, exception => 'slowpoke' ),
1372 );
1373 or set the name used in debugging message and in the default
1375 exception string:
1376 $h = start(
1378 \@cmd, \$in, \$out,
1379 timeout( 50, name => 'process timer' ),
1380 $stall_timer = timeout( 5, name => 'stall timer' ),
1381 );
1382 pump $h until $out =~ /started/;
1384 $in = 'command 1';
1386 $stall_timer->start;
1387 pump $h until $out =~ /command 1 finished/;
1388 $in = 'command 2';
1390 $stall_timer->start;
1391 pump $h until $out =~ /command 2 finished/;
1392 $in = 'very slow command 3';
1394 $stall_timer->start( 10 );
1395 pump $h until $out =~ /command 3 finished/;
1396 $stall_timer->start( 5 );
1398 $in = 'command 4';
1399 pump $h until $out =~ /command 4 finished/;
1400 $stall_timer->reset; # Prevent restarting or expirng
1402 finish $h;
1403 See "timer" for building non-fatal timers.
1405 See "timer" in IPC::Run::Timer for details.
1407
1409 These functions are for use from within filters.
1410 input_avail
1412 Returns TRUE if input is available. If none is available, then
1413 &get_more_input is called and its result is returned.
1414 This is usually used in preference to &get_more_input so that the
1416 calling filter removes all data from the $in_ref before more data
1417 gets read in to $in_ref.
1418 "input_avail" is usually used as part of a return expression:
1420 return input_avail && do {
1422 ## process the input just gotten
1423 1;
1424 };
1425 This technique allows input_avail to return the undef or 0 that a
1427 filter normally returns when there's no input to process. If a
1428 filter stores intermediate values, however, it will need to react
1429 to an undef:
1430 my $got = input_avail;
1432 if ( ! defined $got ) {
1433 ## No more input ever, flush internal buffers to $out_ref
1434 }
1435 return $got unless $got;
1436 ## Got some input, move as much as need be
1437 return 1 if $added_to_out_ref;
1438 get_more_input
1440 This is used to fetch more input in to the input variable. It
1441 returns undef if there will never be any more input, 0 if there is
1442 none now, but there might be in the future, and TRUE if more input
1443 was gotten.
1444 "get_more_input" is usually used as part of a return expression,
1446 see "input_avail" for more information.
1447
1449 These will be addressed as needed and as time allows.
1450 Stall timeout.
1452 Expose a list of child process objects. When I do this, each child
1454 process is likely to be blessed into IPC::Run::Proc.
1455 $kid->abort(), $kid->kill(), $kid->signal( $num_or_name ).
1457 Write tests for /(full_)?results?/ subs.
1459 Currently, pump() and run() only work on systems where select() works
1461 on the filehandles returned by pipe(). This does *not* include
1462 ActiveState on Win32, although it does work on cygwin under Win32
1463 (thought the tests whine a bit). I'd like to rectify that, suggestions
1464 and patches welcome.
1465 Likewise start() only fully works on fork()/exec() machines (well, just
1467 fork() if you only ever pass perl subs as subprocesses). There's some
1468 scaffolding for calling Open3::spawn_with_handles(), but that's
1469 untested, and not that useful with limited select().
1470 Support for "\@sub_cmd" as an argument to a command which gets replaced
1472 with /dev/fd or the name of a temporary file containing foo's output.
1473 This is like <(sub_cmd ...) found in bash and csh (IIRC).
1474 Allow multiple harnesses to be combined as independant sets of
1476 processes in to one 'meta-harness'.
1477 Allow a harness to be passed in place of an \@cmd. This would allow
1479 multiple harnesses to be aggregated.
1480 Ability to add external file descriptors w/ filter chains and
1482 endpoints.
1483 Ability to add timeouts and timing generators (i.e. repeating
1485 timeouts).
1486 High resolution timeouts.
1488
1490 Fails on Win9X
1491 If you want Win9X support, you'll have to debug it or fund me
1492 because I don't use that system any more. The Win32 subsysem has
1493 been extended to use temporary files in simple run() invocations
1494 and these may actually work on Win9X too, but I don't have time to
1495 work on it.
1496 May deadlock on Win2K (but not WinNT4 or WinXPPro)
1498 Spawning more than one subprocess on Win2K causes a deadlock I
1499 haven't figured out yet, but simple uses of run() often work.
1500 Passes all tests on WinXPPro and WinNT.
1501 no support yet for <pty< and >pty>
1503 These are likely to be implemented as "<" and ">" with binmode on,
1504 not sure.
1505 no support for file descriptors higher than 2 (stderr)
1507 Win32 only allows passing explicit fds 0, 1, and 2. If you really,
1508 really need to pass file handles, us Win32API:: GetOsFHandle() or
1509 ::FdGetOsFHandle() to get the integer handle and pass it to the
1510 child process using the command line, environment, stdin,
1511 intermediary file, or other IPC mechnism. Then use that handle in
1512 the child (Win32API.pm provides ways to reconstitute Perl file
1513 handles from Win32 file handles).
1514 no support for subroutine subprocesses (CODE refs)
1516 Can't fork(), so the subroutines would have no context, and
1517 closures certainly have no meaning
1518 Perhaps with Win32 fork() emulation, this can be supported in a
1520 limited fashion, but there are other very serious problems with
1521 that: all parent fds get dup()ed in to the thread emulating the
1522 forked process, and that keeps the parent from being able to close
1523 all of the appropriate fds.
1524 no support for init => sub {} routines.
1526 Win32 processes are created from scratch, there is no way to do an
1527 init routine that will affect the running child. Some limited
1528 support might be implemented one day, do chdir() and %ENV changes
1529 can be made.
1530 signals
1532 Win32 does not fully support signals. signal() is likely to cause
1533 errors unless sending a signal that Perl emulates, and
1534 "kill_kill()" is immediately fatal (there is no grace period).
1535 helper processes
1537 IPC::Run uses helper processes, one per redirected file, to adapt
1538 between the anonymous pipe connected to the child and the TCP
1539 socket connected to the parent. This is a waste of resources and
1540 will change in the future to either use threads (instead of helper
1541 processes) or a WaitForMultipleObjects call (instead of select).
1542 Please contact me if you can help with the WaitForMultipleObjects()
1543 approach; I haven't figured out how to get at it without C code.
1544 shutdown pause
1546 There seems to be a pause of up to 1 second between when a child
1547 program exits and the corresponding sockets indicate that they are
1548 closed in the parent. Not sure why.
1549 binmode
1551 binmode is not supported yet. The underpinnings are implemented,
1552 just ask if you need it.
1553 IPC::Run::IO
1555 IPC::Run::IO objects can be used on Unix to read or write arbitrary
1556 files. On Win32, they will need to use the same helper processes
1557 to adapt from non-select()able filehandles to select()able ones (or
1558 perhaps WaitForMultipleObjects() will work with them, not sure).
1559 startup race conditions
1561 There seems to be an occasional race condition between child
1562 process startup and pipe closings. It seems like if the child is
1563 not fully created by the time CreateProcess returns and we close
1564 the TCP socket being handed to it, the parent socket can also get
1565 closed. This is seen with the Win32 pumper applications, not the
1566 "real" child process being spawned.
1567 I assume this is because the kernel hasn't gotten around to
1569 incrementing the reference count on the child's end (since the
1570 child was slow in starting), so the parent's closing of the child
1571 end causes the socket to be closed, thus closing the parent socket.
1572 Being a race condition, it's hard to reproduce, but I encountered
1574 it while testing this code on a drive share to a samba box. In
1575 this case, it takes t/run.t a long time to spawn it's chile
1576 processes (the parent hangs in the first select for several seconds
1577 until the child emits any debugging output).
1578 I have not seen it on local drives, and can't reproduce it at will,
1580 unfortunately. The symptom is a "bad file descriptor in select()"
1581 error, and, by turning on debugging, it's possible to see that
1582 select() is being called on a no longer open file descriptor that
1583 was returned from the _socket() routine in Win32Helper. There's a
1584 new confess() that checks for this ("PARENT_HANDLE no longer
1585 open"), but I haven't been able to reproduce it (typically).
1586
1588 On Unix, requires a system that supports "waitpid( $pid, WNOHANG )" so
1589 it can tell if a child process is still running.
1590 PTYs don't seem to be non-blocking on some versions of Solaris. Here's
1592 a test script contributed by Borislav Deianov <borislav@ensim.com> to
1593 see if you have the problem. If it dies, you have the problem.
1594 #!/usr/bin/perl
1596 use IPC::Run qw(run);
1598 use Fcntl;
1599 use IO::Pty;
1600 sub makecmd {
1602 return ['perl', '-e',
1603 '<STDIN>, print "\n" x '.$_[0].'; while(<STDIN>){last if /end/}'];
1604 }
1605 #pipe R, W;
1607 #fcntl(W, F_SETFL, O_NONBLOCK);
1608 #while (syswrite(W, "\n", 1)) { $pipebuf++ };
1609 #print "pipe buffer size is $pipebuf\n";
1610 my $pipebuf=4096;
1611 my $in = "\n" x ($pipebuf * 2) . "end\n";
1612 my $out;
1613 $SIG{ALRM} = sub { die "Never completed!\n" };
1615 print "reading from scalar via pipe...";
1617 alarm( 2 );
1618 run(makecmd($pipebuf * 2), '<', \$in, '>', \$out);
1619 alarm( 0 );
1620 print "done\n";
1621 print "reading from code via pipe... ";
1623 alarm( 2 );
1624 run(makecmd($pipebuf * 3), '<', sub { $t = $in; undef $in; $t}, '>', \$out);
1625 alarm( 0 );
1626 print "done\n";
1627 $pty = IO::Pty->new();
1629 $pty->blocking(0);
1630 $slave = $pty->slave();
1631 while ($pty->syswrite("\n", 1)) { $ptybuf++ };
1632 print "pty buffer size is $ptybuf\n";
1633 $in = "\n" x ($ptybuf * 3) . "end\n";
1634 print "reading via pty... ";
1636 alarm( 2 );
1637 run(makecmd($ptybuf * 3), '<pty<', \$in, '>', \$out);
1638 alarm(0);
1639 print "done\n";
1640 No support for ';', '&&', '||', '{ ... }', etc: use perl's, since run()
1642 returns TRUE when the command exits with a 0 result code.
1643 Does not provide shell-like string interpolation.
1645 No support for "cd", "setenv", or "export": do these in an init() sub
1647 run(
1649 \cmd,
1650 ...
1651 init => sub {
1652 chdir $dir or die $!;
1653 $ENV{FOO}='BAR'
1654 }
1655 );
1656 Timeout calculation does not allow absolute times, or specification of
1658 days, months, etc.
1659 WARNING: Function coprocesses ("run \&foo, ...") suffer from two
1661 limitations. The first is that it is difficult to close all
1662 filehandles the child inherits from the parent, since there is no way
1663 to scan all open FILEHANDLEs in Perl and it both painful and a bit
1664 dangerous to close all open file descriptors with "POSIX::close()".
1665 Painful because we can't tell which fds are open at the POSIX level,
1666 either, so we'd have to scan all possible fds and close any that we
1667 don't want open (normally "exec()" closes any non-inheritable but we
1668 don't "exec()" for &sub processes.
1669 The second problem is that Perl's DESTROY subs and other on-exit
1671 cleanup gets run in the child process. If objects are instantiated in
1672 the parent before the child is forked, the the DESTROY will get run
1673 once in the parent and once in the child. When coprocess subs exit,
1674 POSIX::exit is called to work around this, but it means that objects
1675 that are still referred to at that time are not cleaned up. So setting
1676 package vars or closure vars to point to objects that rely on DESTROY
1677 to affect things outside the process (files, etc), will lead to bugs.
1678 I goofed on the syntax: "<pipe" vs. "<pty<" and ">filename" are both
1680 oddities.
1681
1683 Allow one harness to "adopt" another:
1684 $new_h = harness \@cmd2;
1685 $h->adopt( $new_h );
1686 Close all filehandles not explicitly marked to stay open.
1688 The problem with this one is that there's no good way to scan all
1689 open FILEHANDLEs in Perl, yet you don't want child processes
1690 inheriting handles willy-nilly.
1691
1693 Well, select() and waitpid() badly needed wrapping, and open3() isn't
1694 open-minded enough for me.
1695 The shell-like API inspired by a message Russ Allbery sent to
1697 perl5-porters, which included:
1698 I've thought for some time that it would be
1700 nice to have a module that could handle full Bourne shell pipe syntax
1701 internally, with fork and exec, without ever invoking a shell. Something
1702 that you could give things like:
1703 pipeopen (PIPE, [ qw/cat file/ ], '|', [ 'analyze', @args ], '>&3');
1705 Message ylln51p2b6.fsf@windlord.stanford.edu, on 2000/02/04.
1707
1709 Bugs should always be submitted via the CPAN bug tracker
1710 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=IPC-Run>
1712 For other issues, contact the maintainer (the first listed author)
1714
1716 Adam Kennedy <adamk@cpan.org>
1717 Barrie Slaymaker <barries@slaysys.com>
1719
1721 Some parts copyright 2008 - 2009 Adam Kennedy.
1722 Copyright 1999 Barrie Slaymaker.
1724 You may distribute under the terms of either the GNU General Public
1726 License or the Artistic License, as specified in the README file.
1727perl v5.10.1 2009-07-13 IPC::Run(3)