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.
23 run \@cat, '<pty<', \$in, '>pty>', \$out_and_err ;
24 ## Scripting subprocesses (like Expect):
26 use IPC::Run qw( start pump finish timeout ) ;
28 # Incrementally read from / write to scalars.
30 # $in is drained as it is fed to cat's stdin,
31 # $out accumulates cat's stdout
32 # $err accumulates cat's stderr
33 # $h is for "harness".
34 my $h = start \@cat, \$in, \$out, \$err, timeout( 10 ) ;
35 $in .= "some input\n" ;
37 pump $h until $out =~ /input\n/g ;
38 $in .= "some more input\n" ;
40 pump $h until $out =~ /\G.*more input\n/ ;
41 $in .= "some final input\n" ;
43 finish $h or die "cat returned $?" ;
44 warn $err if $err ;
46 print $out ; ## All of cat's output
47 # Piping between children
49 run \@cat, '⎪', \@gzip ;
50 # Multiple children simultaneously (run() blocks until all
52 # children exit, use start() for background execution):
53 run \@foo1, '&', \@foo2 ;
54 # Calling \&set_up_child in the child before it executes the
56 # command (only works on systems with true fork() & exec())
57 # exceptions thrown in set_up_child() will be propagated back
58 # to the parent and thrown from run().
59 run \@cat, \$in, \$out,
60 init => \&set_up_child ;
61 # Read from / write to file handles you open and close
63 open IN, '<in.txt' or die $! ;
64 open OUT, '>out.txt' or die $! ;
65 print OUT "preamble\n" ;
66 run \@cat, \*IN, \*OUT or die "cat returned $?" ;
67 print OUT "postamble\n" ;
68 close IN ;
69 close OUT ;
70 # Create pipes for you to read / write (like IPC::Open2 & 3).
72 $h = start
73 \@cat,
74 '<pipe', \*IN,
75 '>pipe', \*OUT,
76 '2>pipe', \*ERR
77 or die "cat returned $?" ;
78 print IN "some input\n" ;
79 close IN ;
80 print <OUT>, <ERR> ;
81 finish $h ;
82 # Mixing input and output modes
84 run \@cat, 'in.txt', \&catch_some_out, \*ERR_LOG ) ;
85 # Other redirection constructs
87 run \@cat, '>&', \$out_and_err ;
88 run \@cat, '2>&1' ;
89 run \@cat, '0<&3' ;
90 run \@cat, '<&-' ;
91 run \@cat, '3<', \$in3 ;
92 run \@cat, '4>', \$out4 ;
93 # etc.
94 # Passing options:
96 run \@cat, 'in.txt', debug => 1 ;
97 # Call this system's shell, returns TRUE on 0 exit code
99 # THIS IS THE OPPOSITE SENSE OF system()'s RETURN VALUE
100 run "cat a b c" or die "cat returned $?" ;
101 # Launch a sub process directly, no shell. Can't do redirection
103 # with this form, it's here to behave like system() with an
104 # inverted result.
105 $r = run "cat a b c" ;
106 # Read from a file in to a scalar
108 run io( "filename", 'r', \$recv ) ;
109 run io( \*HANDLE, 'r', \$recv ) ;
110
112 IPC::Run allows you run and interact with child processes using files,
113 pipes, and pseudo-ttys. Both system()-style and scripted usages are
114 supported and may be mixed. Likewise, functional and OO API styles are
115 both supported and may be mixed.
116 Various redirection operators reminiscent of those seen on common Unix
118 and DOS command lines are provided.
119 Before digging in to the details a few LIMITATIONS are important enough
121 to be mentioned right up front:
122 Win32 Support
124 Win32 support is working but EXPERIMENTAL, but does pass all rele‐
125 vant tests on NT 4.0. See "Win32 LIMITATIONS".
126 pty Support
128 If you need pty support, IPC::Run should work well enough most of
129 the time, but IO::Pty is being improved, and IPC::Run will be
130 improved to use IO::Pty's new features when it is release.
131 The basic problem is that the pty needs to initialize itself before
133 the parent writes to the master pty, or the data written gets lost.
134 So IPC::Run does a sleep(1) in the parent after forking to (hope‐
135 fully) give the child a chance to run. This is a kludge that works
136 well on non heavily loaded systems :(.
137 ptys are not supported yet under Win32, but will be emulated...
139 Debugging Tip
141 You may use the environment variable "IPCRUNDEBUG" to see what's
142 going on under the hood:
143 $ IPCRUNDEBUG=basic myscript # prints minimal debugging
145 $ IPCRUNDEBUG=data myscript # prints all data reads/writes
146 $ IPCRUNDEBUG=details myscript # prints lots of low-level details
147 $ IPCRUNDEBUG=gory myscript # (Win32 only) prints data moving through
148 # the helper processes.
149 We now return you to your regularly scheduled documentation.
151 Harnesses
153 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
160 enhanced system(), and start()/pump()/finish() allow for background
161 processes and scripted interactions with them.
162 When using run(), all data to be sent to the harness is set up in
164 advance (though one can feed subprocesses input from subroutine refs to
165 get around this limitation). The harness is run and all output is col‐
166 lected from it, then any child processes are waited for:
167 run \@cmd, \<<IN, \$out ;
169 blah
170 IN
171 ## To precompile harnesses and run them later:
173 my $h = harness \@cmd, \<<IN, \$out ;
174 blah
175 IN
176 run $h ;
178 The background and scripting API is provided by start(), pump(), and
180 finish(): start() creates a harness if need be (by calling harness())
181 and launches any subprocesses, pump() allows you to poll them for
182 activity, and finish() then monitors the harnessed activities until
183 they complete.
184 ## Build the harness, open all pipes, and launch the subprocesses
186 my $h = start \@cat, \$in, \$out ;
187 $in = "first input\n" ;
188 ## Now do I/O. start() does no I/O.
190 pump $h while length $in ; ## Wait for all input to go
191 ## Now do some more I/O.
193 $in = "second input\n" ;
194 pump $h until $out =~ /second input/ ;
195 ## Clean up
197 finish $h or die "cat returned $?" ;
198 You can optionally compile the harness with harness() prior to
200 start()ing or run()ing, and you may omit start() between harness() and
201 pump(). You might want to do these things if you compile your har‐
202 nesses ahead of time.
203 Using regexps to match output
205 As shown in most of the scripting examples, the read-to-scalar facility
207 for gathering subcommand's output is often used with regular expres‐
208 sions to detect stopping points. This is because subcommand output
209 often arrives in dribbles and drabs, often only a character or line at
210 a time. This output is input for the main program and piles up in
211 variables like the $out and $err in our examples.
212 Regular expressions can be used to wait for appropriate output in sev‐
214 eral ways. The "cat" example in the previous section demonstrates how
215 to pump() until some string appears in the output. Here's an example
216 that uses "smb" to fetch files from a remote server:
217 $h = harness \@smbclient, \$in, \$out ;
219 $in = "cd /src\n" ;
221 $h->pump until $out =~ /^smb.*> \Z/m ;
222 die "error cding to /src:\n$out" if $out =~ "ERR" ;
223 $out = '' ;
224 $in = "mget *\n" ;
226 $h->pump until $out =~ /^smb.*> \Z/m ;
227 die "error retrieving files:\n$out" if $out =~ "ERR" ;
228 $in = "quit\n" ;
230 $h->finish ;
231 Notice that we carefully clear $out after the first command/response
233 cycle? That's because IPC::Run does not delete $out when we continue,
234 and we don't want to trip over the old output in the second com‐
235 mand/response cycle.
236 Say you want to accumulate all the output in $out and analyze it after‐
238 wards. Perl offers incremental regular expression matching using the
239 "m//gc" and pattern matching idiom and the "\G" assertion. IPC::Run is
240 careful not to disturb the current "pos()" value for scalars it appends
241 data to, so we could modify the above so as not to destroy $out by
242 adding a couple of "/gc" modifiers. The "/g" keeps us from tripping
243 over the previous prompt and the "/c" keeps us from resetting the prior
244 match position if the expected prompt doesn't materialize immediately:
245 $h = harness \@smbclient, \$in, \$out ;
247 $in = "cd /src\n" ;
249 $h->pump until $out =~ /^smb.*> \Z/mgc ;
250 die "error cding to /src:\n$out" if $out =~ "ERR" ;
251 $in = "mget *\n" ;
253 $h->pump until $out =~ /^smb.*> \Z/mgc ;
254 die "error retrieving files:\n$out" if $out =~ "ERR" ;
255 $in = "quit\n" ;
257 $h->finish ;
258 analyze( $out ) ;
260 When using this technique, you may want to preallocate $out to have
262 plenty of memory or you may find that the act of growing $out each time
263 new input arrives causes an "O(length($out)^2)" slowdown as $out grows.
264 Say we expect no more than 10,000 characters of input at the most. To
265 preallocate memory to $out, do something like:
266 my $out = "x" x 10_000 ;
268 $out = "" ;
269 "perl" will allocate at least 10,000 characters' worth of space, then
271 mark the $out as having 0 length without freeing all that yummy RAM.
272 Timeouts and Timers
274 More than likely, you don't want your subprocesses to run forever, and
276 sometimes it's nice to know that they're going a little slowly. Time‐
277 outs throw exceptions after a some time has elapsed, timers merely
278 cause pump() to return after some time has elapsed. Neither is
279 reset/restarted automatically.
280 Timeout objects are created by calling timeout( $interval ) and passing
282 the result to run(), start() or harness(). The timeout period starts
283 ticking just after all the child processes have been fork()ed or
284 spawn()ed, and are polled for expiration in run(), pump() and finish().
285 If/when they expire, an exception is thrown. This is typically useful
286 to keep a subprocess from taking too long.
287 If a timeout occurs in run(), all child processes will be terminated
289 and all file/pipe/ptty descriptors opened by run() will be closed.
290 File descriptors opened by the parent process and passed in to run()
291 are not closed in this event.
292 If a timeout occurs in pump(), pump_nb(), or finish(), it's up to you
294 to decide whether to kill_kill() all the children or to implement some
295 more graceful fallback. No I/O will be closed in pump(), pump_nb() or
296 finish() by such an exception (though I/O is often closed down in those
297 routines during the natural course of events).
298 Often an exception is too harsh. timer( $interval ) creates timer
300 objects that merely prevent pump() from blocking forever. This can be
301 useful for detecting stalled I/O or printing a soothing message or "."
302 to pacify an anxious user.
303 Timeouts and timers can both be restarted at any time using the timer's
305 start() method (this is not the start() that launches subprocesses).
306 To restart a timer, you need to keep a reference to the timer:
307 ## Start with a nice long timeout to let smbclient connect. If
309 ## pump or finish take too long, an exception will be thrown.
310 my $h ;
312 eval {
313 $h = harness \@smbclient, \$in, \$out, \$err, ( my $t = timeout 30 ) ;
314 sleep 11 ; # No effect: timer not running yet
315 start $h ;
317 $in = "cd /src\n" ;
318 pump $h until ! length $in ;
319 $in = "ls\n" ;
321 ## Now use a short timeout, since this should be faster
322 $t->start( 5 ) ;
323 pump $h until ! length $in ;
324 $t->start( 10 ) ; ## Give smbclient a little while to shut down.
326 $h->finish ;
327 } ;
328 if ( $@ ) {
329 my $x = $@ ; ## Preserve $@ in case another exception occurs
330 $h->kill_kill ; ## kill it gently, then brutally if need be, or just
331 ## brutally on Win32.
332 die $x ;
333 }
334 Timeouts and timers are not checked once the subprocesses are shut
336 down; they will not expire in the interval between the last valid
337 process and when IPC::Run scoops up the processes' result codes, for
338 instance.
339 Spawning synchronization, child exception propagation
341 start() pauses the parent until the child executes the command or CODE
343 reference and propagates any exceptions thrown (including exec() fail‐
344 ure) back to the parent. This has several pleasant effects: any excep‐
345 tions thrown in the child, including exec() failure, come flying out of
346 start() or run() as though they had ocurred in the parent.
347 This includes exceptions your code thrown from init subs. In this
349 example:
350 eval {
352 run \@cmd, init => sub { die "blast it! foiled again!" } ;
353 } ;
354 print $@ ;
355 the exception "blast it! foiled again" will be thrown from the child
357 process (preventing the exec()) and printed by the parent.
358 In situations like
360 run \@cmd1, "⎪", \@cmd2, "⎪", \@cmd3 ;
362 @cmd1 will be initted and exec()ed before @cmd2, and @cmd2 before
364 @cmd3. This can save time and prevent oddball errors emitted by later
365 commands when earlier commands fail to execute. Note that IPC::Run
366 doesn't start any commands unless it can find the executables refer‐
367 enced by all commands. These executables must pass both the "-f" and
368 "-x" tests described in perlfunc.
369 Another nice effect is that init() subs can take their time doing
371 things and there will be no problems caused by a parent continuing to
372 execute before a child's init() routine is complete. Say the init()
373 routine needs to open a socket or a temp file that the parent wants to
374 connect to; without this synchronization, the parent will need to
375 implement a retry loop to wait for the child to run, since often, the
376 parent gets a lot of things done before the child's first timeslice is
377 allocated.
378 This is also quite necessary for pseudo-tty initialization, which needs
380 to take place before the parent writes to the child via pty. Writes
381 that occur before the pty is set up can get lost.
382 A final, minor, nicety is that debugging output from the child will be
384 emitted before the parent continues on, making for much clearer debug‐
385 ging output in complex situations.
386 The only drawback I can conceive of is that the parent can't continue
388 to operate while the child is being initted. If this ever becomes a
389 problem in the field, we can implement an option to avoid this behav‐
390 ior, but I don't expect it to.
391 Win32: executing CODE references isn't supported on Win32, see "Win32
393 LIMITATIONS" for details.
394 Syntax
396 run(), start(), and harness() can all take a harness specification as
398 input. A harness specification is either a single string to be passed
399 to the systems' shell:
400 run "echo 'hi there'" ;
402 or a list of commands, io operations, and/or timers/timeouts to exe‐
404 cute. Consecutive commands must be separated by a pipe operator '⎪' or
405 an '&'. External commands are passed in as array references, and, on
406 systems supporting fork(), Perl code may be passed in as subs:
407 run \@cmd ;
409 run \@cmd1, '⎪', \@cmd2 ;
410 run \@cmd1, '&', \@cmd2 ;
411 run \&sub1 ;
412 run \&sub1, '⎪', \&sub2 ;
413 run \&sub1, '&', \&sub2 ;
414 '⎪' pipes the stdout of \@cmd1 the stdin of \@cmd2, just like a shell
416 pipe. '&' does not. Child processes to the right of a '&' will have
417 their stdin closed unless it's redirected-to.
418 IPC::Run::IO objects may be passed in as well, whether or not child
420 processes are also specified:
421 run io( "infile", ">", \$in ), io( "outfile", "<", \$in ) ;
423 as can IPC::Run::Timer objects:
425 run \@cmd, io( "outfile", "<", \$in ), timeout( 10 ) ;
427 Commands may be followed by scalar, sub, or i/o handle references for
429 redirecting child process input & output:
430 run \@cmd, \undef, \$out ;
432 run \@cmd, \$in, \$out ;
433 run \@cmd1, \&in, '⎪', \@cmd2, \*OUT ;
434 run \@cmd1, \*IN, '⎪', \@cmd2, \&out ;
435 This is known as succinct redirection syntax, since run(), start() and
437 harness(), figure out which file descriptor to redirect and how. File
438 descriptor 0 is presumed to be an input for the child process, all oth‐
439 ers are outputs. The assumed file descriptor always starts at 0,
440 unless the command is being piped to, in which case it starts at 1.
441 To be explicit about your redirects, or if you need to do more complex
443 things, there's also a redirection operator syntax:
444 run \@cmd, '<', \undef, '>', \$out ;
446 run \@cmd, '<', \undef, '>&', \$out_and_err ;
447 run(
448 \@cmd1,
449 '<', \$in,
450 '⎪', \@cmd2,
451 \$out
452 ) ;
453 Operator syntax is required if you need to do something other than sim‐
455 ple redirection to/from scalars or subs, like duping or closing file
456 descriptors or redirecting to/from a named file. The operators are
457 covered in detail below.
458 After each \@cmd (or \&foo), parsing begins in succinct mode and tog‐
460 gles to operator syntax mode when an operator (ie plain scalar, not a
461 ref) is seen. Once in operator syntax mode, parsing only reverts to
462 succinct mode when a '⎪' or '&' is seen.
463 In succinct mode, each parameter after the \@cmd specifies what to do
465 with the next highest file descriptor. These File descriptor start with
466 0 (stdin) unless stdin is being piped to ("'⎪', \@cmd"), in which case
467 they start with 1 (stdout). Currently, being on the left of a pipe
468 ("\@cmd, \$out, \$err, '⎪'") does not cause stdout to be skipped,
469 though this may change since it's not as DWIMerly as it could be. Only
470 stdin is assumed to be an input in succinct mode, all others are
471 assumed to be outputs.
472 If no piping or redirection is specified for a child, it will inherit
474 the parent's open file handles as dictated by your system's close-on-
475 exec behavior and the $^F flag, except that processes after a '&' will
476 not inherit the parent's stdin. Also note that $^F does not affect file
477 desciptors obtained via POSIX, since it only applies to full-fledged
478 Perl file handles. Such processes will have their stdin closed unless
479 it has been redirected-to.
480 If you want to close a child processes stdin, you may do any of:
482 run \@cmd, \undef ;
484 run \@cmd, \"" ;
485 run \@cmd, '<&-' ;
486 run \@cmd, '0<&-' ;
487 Redirection is done by placing redirection specifications immediately
489 after a command or child subroutine:
490 run \@cmd1, \$in, '⎪', \@cmd2, \$out ;
492 run \@cmd1, '<', \$in, '⎪', \@cmd2, '>', \$out ;
493 If you omit the redirection operators, descriptors are counted starting
495 at 0. Descriptor 0 is assumed to be input, all others are outputs. A
496 leading '⎪' consumes descriptor 0, so this works as expected.
497 run \@cmd1, \$in, '⎪', \@cmd2, \$out ;
499 The parameter following a redirection operator can be a scalar ref, a
501 subroutine ref, a file name, an open filehandle, or a closed filehan‐
502 dle.
503 If it's a scalar ref, the child reads input from or sends output to
505 that variable:
506 $in = "Hello World.\n" ;
508 run \@cat, \$in, \$out ;
509 print $out ;
510 Scalars used in incremental (start()/pump()/finish()) applications are
512 treated as queues: input is removed from input scalers, resulting in
513 them dwindling to '', and output is appended to output scalars. This
514 is not true of harnesses run() in batch mode.
515 It's usually wise to append new input to be sent to the child to the
517 input queue, and you'll often want to zap output queues to '' before
518 pumping.
519 $h = start \@cat, \$in ;
521 $in = "line 1\n" ;
522 pump $h ;
523 $in .= "line 2\n" ;
524 pump $h ;
525 $in .= "line 3\n" ;
526 finish $h ;
527 The final call to finish() must be there: it allows the child
529 process(es) to run to completion and waits for their exit values.
530
532 Interactive applications are usually optimized for human use. This can
533 help or hinder trying to interact with them through modules like
534 IPC::Run. Frequently, programs alter their behavior when they detect
535 that stdin, stdout, or stderr are not connected to a tty, assuming that
536 they are being run in batch mode. Whether this helps or hurts depends
537 on which optimizations change. And there's often no way of telling
538 what a program does in these areas other than trial and error and,
539 occasionally, reading the source. This includes different versions and
540 implementations of the same program.
541 All hope is not lost, however. Most programs behave in reasonably
543 tractable manners, once you figure out what it's trying to do.
544 Here are some of the issues you might need to be aware of.
546 · fflush()ing stdout and stderr
548 This lets the user see stdout and stderr immediately. Many pro‐
550 grams undo this optimization if stdout is not a tty, making them
551 harder to manage by things like IPC::Run.
552 Many programs decline to fflush stdout or stderr if they do not
554 detect a tty there. Some ftp commands do this, for instance.
555 If this happens to you, look for a way to force interactive behav‐
557 ior, like a command line switch or command. If you can't, you will
558 need to use a pseudo terminal ('<pty<' and '>pty>').
559 · false prompts
561 Interactive programs generally do not guarantee that output from
563 user commands won't contain a prompt string. For example, your
564 shell prompt might be a '$', and a file named '$' might be the only
565 file in a directory listing.
566 This can make it hard to guarantee that your output parser won't be
568 fooled into early termination of results.
569 To help work around this, you can see if the program can alter it's
571 prompt, and use something you feel is never going to occur in
572 actual practice.
573 You should also look for your prompt to be the only thing on a
575 line:
576 pump $h until $out =~ /^<SILLYPROMPT>\s?\z/m ;
578 (use "(?!\n)\Z" in place of "\z" on older perls).
580 You can also take the approach that IPC::ChildSafe takes and emit a
582 command with known output after each 'real' command you issue, then
583 look for this known output. See new_appender() and new_chunker()
584 for filters that can help with this task.
585 If it's not convenient or possibly to alter a prompt or use a known
587 command/response pair, you might need to autodetect the prompt in
588 case the local version of the child program is different then the
589 one you tested with, or if the user has control over the look &
590 feel of the prompt.
591 · Refusing to accept input unless stdin is a tty.
593 Some programs, for security reasons, will only accept certain types
595 of input from a tty. su, notable, will not prompt for a password
596 unless it's connected to a tty.
597 If this is your situation, use a pseudo terminal ('<pty<' and
599 '>pty>').
600 · Not prompting unless connected to a tty.
602 Some programs don't prompt unless stdin or stdout is a tty. See if
604 you can turn prompting back on. If not, see if you can come up
605 with a command that you can issue after every real command and look
606 for it's output, as IPC::ChildSafe does. There are two filters
607 included with IPC::Run that can help with doing this: appender and
608 chunker (see new_appender() and new_chunker()).
609 · Different output format when not connected to a tty.
611 Some commands alter their formats to ease machine parsability when
613 they aren't connected to a pipe. This is actually good, but can be
614 surprising.
615
617 On systems providing pseudo terminals under /dev, IPC::Run can use
618 IO::Pty (available on CPAN) to provide a terminal environment to sub‐
619 processes. This is necessary when the subprocess really wants to think
620 it's connected to a real terminal.
621 CAVEATS
623 Psuedo-terminals are not pipes, though they are similar. Here are some
625 differences to watch out for.
626 Echoing
628 Sending to stdin will cause an echo on stdout, which occurs before
629 each line is passed to the child program. There is currently no
630 way to disable this, although the child process can and should dis‐
631 able it for things like passwords.
632 Shutdown
634 IPC::Run cannot close a pty until all output has been collected.
635 This means that it is not possible to send an EOF to stdin by half-
636 closing the pty, as we can when using a pipe to stdin.
637 This means that you need to send the child process an exit command
639 or signal, or run() / finish() will time out. Be careful not to
640 expect a prompt after sending the exit command.
641 Command line editing
643 Some subprocesses, notable shells that depend on the user's prompt
644 settings, will reissue the prompt plus the command line input so
645 far once for each character.
646 '>pty>' means '&>pty>', not '1>pty>'
648 The pseudo terminal redirects both stdout and stderr unless you
649 specify a file descriptor. If you want to grab stderr separately,
650 do this:
651 start \@cmd, '<pty<', \$in, '>pty>', \$out, '2>', \$err ;
653 stdin, stdout, and stderr not inherited
655 Child processes harnessed to a pseudo terminal have their stdin,
656 stdout, and stderr completely closed before any redirection opera‐
657 tors take effect. This casts of the bonds of the controlling ter‐
658 minal. This is not done when using pipes.
659 Right now, this affects all children in a harness that has a pty in
661 use, even if that pty would not affect a particular child. That's
662 a bug and will be fixed. Until it is, it's best not to mix-and-
663 match children.
664 Redirection Operators
666 Operator SHNP Description
668 ======== ==== ===========
669 <, N< SHN Redirects input to a child's fd N (0 assumed)
670 >, N> SHN Redirects output from a child's fd N (1 assumed)
672 >>, N>> SHN Like '>', but appends to scalars or named files
673 >&, &> SHN Redirects stdout & stderr from a child process
674 <pty, N<pty S Like '<', but uses a pseudo-tty instead of a pipe
676 >pty, N>pty S Like '>', but uses a pseudo-tty instead of a pipe
677 N<&M Dups input fd N to input fd M
679 M>&N Dups output fd N to input fd M
680 N<&- Closes fd N
681 <pipe, N<pipe P Pipe opens H for caller to read, write, close.
683 >pipe, N>pipe P Pipe opens H for caller to read, write, close.
684 'N' and 'M' are placeholders for integer file descriptor numbers. The
686 terms 'input' and 'output' are from the child process's perspective.
687 The SHNP field indicates what parameters an operator can take:
689 S: \$scalar or \&function references. Filters may be used with
691 these operators (and only these).
692 H: \*HANDLE or IO::Handle for caller to open, and close
693 N: "file name".
694 P: \*HANDLE opened by IPC::Run as the parent end of a pipe, but read
695 and written to and closed by the caller (like IPC::Open3).
696 Redirecting input: [n]<, [n]<pipe
698 You can input the child reads on file descriptor number n to come
699 from a scalar variable, subroutine, file handle, or a named file.
700 If stdin is not redirected, the parent's stdin is inherited.
701 run \@cat, \undef ## Closes child's stdin immediately
703 or die "cat returned $?" ;
704 run \@cat, \$in ;
706 run \@cat, \<<TOHERE ;
708 blah
709 TOHERE
710 run \@cat, \&input ; ## Calls &input, feeding data returned
712 ## to child's. Closes child's stdin
713 ## when undef is returned.
714 Redirecting from named files requires you to use the input redi‐
716 rection operator:
717 run \@cat, '<.profile' ;
719 run \@cat, '<', '.profile' ;
720 open IN, "<foo" ;
722 run \@cat, \*IN ;
723 run \@cat, *IN{IO} ;
724 The form used second example here is the safest, since filenames
726 like "0" and "&more\n" won't confuse &run:
727 You can't do either of
729 run \@a, *IN ; ## INVALID
731 run \@a, '<', *IN ; ## BUGGY: Reads file named like "*main::A"
732 because perl passes a scalar containing a string that looks like
734 "*main::A" to &run, and &run can't tell the difference between that
735 and a redirection operator or a file name. &run guarantees that
736 any scalar you pass after a redirection operator is a file name.
737 If your child process will take input from file descriptors other
739 than 0 (stdin), you can use a redirection operator with any of the
740 valid input forms (scalar ref, sub ref, etc.):
741 run \@cat, '3<', \$in3 ;
743 When redirecting input from a scalar ref, the scalar ref is used as
745 a queue. This allows you to use &harness and pump() to feed incre‐
746 mental bits of input to a coprocess. See "Coprocesses" below for
747 more information.
748 The <pipe operator opens the write half of a pipe on the filehandle
750 glob reference it takes as an argument:
751 $h = start \@cat, '<pipe', \*IN ;
753 print IN "hello world\n" ;
754 pump $h ;
755 close IN ;
756 finish $h ;
757 Unlike the other '<' operators, IPC::Run does nothing further with
759 it: you are responsible for it. The previous example is function‐
760 ally equivalent to:
761 pipe( \*R, \*IN ) or die $! ;
763 $h = start \@cat, '<', \*IN ;
764 print IN "hello world\n" ;
765 pump $h ;
766 close IN ;
767 finish $h ;
768 This is like the behavior of IPC::Open2 and IPC::Open3.
770 Win32: The handle returned is actually a socket handle, so you can
772 use select() on it.
773 Redirecting output: [n]>, [n]>>, [n]>&[m], [n]>pipe
775 You can redirect any output the child emits to a scalar variable,
776 subroutine, file handle, or file name. You can have &run truncate
777 or append to named files or scalars. If you are redirecting stdin
778 as well, or if the command is on the receiving end of a pipeline
779 ('⎪'), you can omit the redirection operator:
780 @ls = ( 'ls' ) ;
782 run \@ls, \undef, \$out
783 or die "ls returned $?" ;
784 run \@ls, \undef, \&out ; ## Calls &out each time some output
786 ## is received from the child's
787 ## when undef is returned.
788 run \@ls, \undef, '2>ls.err' ;
790 run \@ls, '2>', 'ls.err' ;
791 The two parameter form guarantees that the filename will not be
793 interpreted as a redirection operator:
794 run \@ls, '>', "&more" ;
796 run \@ls, '2>', ">foo\n" ;
797 You can pass file handles you've opened for writing:
799 open( *OUT, ">out.txt" ) ;
801 open( *ERR, ">err.txt" ) ;
802 run \@cat, \*OUT, \*ERR ;
803 Passing a scalar reference and a code reference requires a little
805 more work, but allows you to capture all of the output in a scalar
806 or each piece of output by a callback:
807 These two do the same things:
809 run( [ 'ls' ], '2>', sub { $err_out .= $_[0] } ) ;
811 does the same basic thing as:
813 run( [ 'ls' ], '2>', \$err_out ) ;
815 The subroutine will be called each time some data is read from the
817 child.
818 The >pipe operator is different in concept than the other '>' oper‐
820 ators, although it's syntax is similar:
821 $h = start \@cat, $in, '>pipe', \*OUT, '2>pipe', \*ERR ;
823 $in = "hello world\n" ;
824 finish $h ;
825 print <OUT> ;
826 print <ERR> ;
827 close OUT ;
828 close ERR ;
829 causes two pipe to be created, with one end attached to cat's std‐
831 out and stderr, respectively, and the other left open on OUT and
832 ERR, so that the script can manually read(), select(), etc. on
833 them. This is like the behavior of IPC::Open2 and IPC::Open3.
834 Win32: The handle returned is actually a socket handle, so you can
836 use select() on it.
837 Duplicating output descriptors: >&m, n>&m
839 This duplicates output descriptor number n (default is 1 if n is
840 omitted) from descriptor number m.
841 Duplicating input descriptors: <&m, n<&m
843 This duplicates input descriptor number n (default is 0 if n is
844 omitted) from descriptor number m
845 Closing descriptors: <&-, 3<&-
847 This closes descriptor number n (default is 0 if n is omitted).
848 The following commands are equivalent:
849 run \@cmd, \undef ;
851 run \@cmd, '<&-' ;
852 run \@cmd, '<in.txt', '<&-' ;
853 Doing
855 run \@cmd, \$in, '<&-' ; ## SIGPIPE recipe.
857 is dangerous: the parent will get a SIGPIPE if $in is not empty.
859 Redirecting both stdout and stderr: &>, >&, &>pipe, >pipe&
861 The following pairs of commands are equivalent:
862 run \@cmd, '>&', \$out ; run \@cmd, '>', \$out, '2>&1' ;
864 run \@cmd, '>&', 'out.txt' ; run \@cmd, '>', 'out.txt', '2>&1' ;
865 etc.
867 File descriptor numbers are not permitted to the left or the right
869 of these operators, and the '&' may occur on either end of the
870 operator.
871 The '&>pipe' and '>pipe&' variants behave like the '>pipe' opera‐
873 tor, except that both stdout and stderr write to the created pipe.
874 Redirection Filters
876 Both input redirections and output redirections that use scalars or
877 subs as endpoints may have an arbitrary number of filter subs
878 placed between them and the child process. This is useful if you
879 want to receive output in chunks, or if you want to massage each
880 chunk of data sent to the child. To use this feature, you must use
881 operator syntax:
882 run(
884 \@cmd
885 '<', \&in_filter_2, \&in_filter_1, $in,
886 '>', \&out_filter_1, \&in_filter_2, $out,
887 ) ;
888 This capability is not provided for IO handles or named files.
890 Two filters are provided by IPC::Run: appender and chunker.
892 Because these may take an argument, you need to use the constructor
893 functions new_appender() and new_chunker() rather than using \&
894 syntax:
895 run(
897 \@cmd
898 '<', new_appender( "\n" ), $in,
899 '>', new_chunker, $out,
900 ) ;
901 Just doing I/O
903 If you just want to do I/O to a handle or file you open yourself, you
905 may specify a filehandle or filename instead of a command in the har‐
906 ness specification:
907 run io( "filename", '>', \$recv ) ;
909 $h = start io( $io, '>', \$recv ) ;
911 $h = harness \@cmd, '&', io( "file", '<', \$send ) ;
913 Options
915 Options are passed in as name/value pairs:
917 run \@cat, \$in, debug => 1 ;
919 If you pass the debug option, you may want to pass it in first, so you
921 can see what parsing is going on:
922 run debug => 1, \@cat, \$in ;
924 debug
926 Enables debugging output in parent and child. Debugging info is
927 emitted to the STDERR that was present when IPC::Run was first
928 "use()"ed (it's "dup()"ed out of the way so that it can be redi‐
929 rected in children without having debugging output emitted on it).
930
932 harness() and start() return a reference to an IPC::Run harness. This
933 is blessed in to the IPC::Run package, so you may make later calls to
934 functions as members if you like:
935 $h = harness( ... ) ;
937 $h->start ;
938 $h->pump ;
939 $h->finish ;
940 $h = start( .... ) ;
942 $h->pump ;
943 ...
944 Of course, using method call syntax lets you deal with any IPC::Run
946 subclasses that might crop up, but don't hold your breath waiting for
947 any.
948 run() and finish() return TRUE when all subcommands exit with a 0
950 result code. This is the opposite of perl's system() command.
951 All routines raise exceptions (via die()) when error conditions are
953 recognized. A non-zero command result is not treated as an error con‐
954 dition, since some commands are tests whose results are reported in
955 their exit codes.
956
958 run Run takes a harness or harness specification and runs it, pumping
959 all input to the child(ren), closing the input pipes when no more
960 input is available, collecting all output that arrives, until the
961 pipes delivering output are closed, then waiting for the children
962 to exit and reaping their result codes.
963 You may think of "run( ... )" as being like
965 start( ... )->finish() ;
967 , though there is one subtle difference: run() does not set
969 \$input_scalars to '' like finish() does. If an exception is
970 thrown from run(), all children will be killed off "gently", and
971 then "annihilated" if they do not go gently (in to that dark night.
972 sorry).
973 If any exceptions are thrown, this does a "kill_kill" before pro‐
975 pogating them.
976 signal
978 ## To send it a specific signal by name ("USR1"):
979 signal $h, "USR1" ;
980 $h->signal ( "USR1" ) ;
981 If $signal is provided and defined, sends a signal to all child
983 processes. Try not to send numeric signals, use "KILL" instead of
984 9, for instance. Numeric signals aren't portable.
985 Throws an exception if $signal is undef.
987 This will not clean up the harness, "finish" it if you kill it.
989 Normally TERM kills a process gracefully (this is what the command
991 line utility "kill" does by default), INT is sent by one of the
992 keys "^C", "Backspace" or "<Del>", and "QUIT" is used to kill a
993 process and make it coredump.
994 The "HUP" signal is often used to get a process to "restart",
996 rereading config files, and "USR1" and "USR2" for really applica‐
997 tion-specific things.
998 Often, running "kill -l" (that's a lower case "L") on the command
1000 line will list the signals present on your operating system.
1001 WARNING: The signal subsystem is not at all portable. We *may*
1003 offer to simulate "TERM" and "KILL" on some operating systems, sub‐
1004 mit code to me if you want this.
1005 WARNING 2: Up to and including perl v5.6.1, doing almost anything
1007 in a signal handler could be dangerous. The most safe code avoids
1008 all mallocs and system calls, usually by preallocating a flag
1009 before entering the signal handler, altering the flag's value in
1010 the handler, and responding to the changed value in the main sys‐
1011 tem:
1012 my $got_usr1 = 0 ;
1014 sub usr1_handler { ++$got_signal }
1015 $SIG{USR1} = \&usr1_handler ;
1017 while () { sleep 1 ; print "GOT IT" while $got_usr1-- ; }
1018 Even this approach is perilous if ++ and -- aren't atomic on your
1020 system (I've never heard of this on any modern CPU large enough to
1021 run perl).
1022 kill_kill
1024 ## To kill off a process:
1025 $h->kill_kill ;
1026 kill_kill $h ;
1027 ## To specify the grace period other than 30 seconds:
1029 kill_kill $h, grace => 5 ;
1030 ## To send QUIT instead of KILL if a process refuses to die:
1032 kill_kill $h, coup_d_grace => "QUIT" ;
1033 Sends a "TERM", waits for all children to exit for up to 30 sec‐
1035 onds, then sends a "KILL" to any that survived the "TERM".
1036 Will wait for up to 30 more seconds for the OS to sucessfully
1038 "KILL" the processes.
1039 The 30 seconds may be overriden by setting the "grace" option, this
1041 overrides both timers.
1042 The harness is then cleaned up.
1044 The doubled name indicates that this function may kill again and
1046 avoids colliding with the core Perl "kill" function.
1047 Returns a 1 if the "TERM" was sufficient, or a 0 if "KILL" was
1049 required. Throws an exception if "KILL" did not permit the chil‐
1050 dren to be reaped.
1051 NOTE: The grace period is actually up to 1 second longer than that
1053 given. This is because the granularity of "time" is 1 second. Let
1054 me know if you need finer granularity, we can leverage Time::HiRes
1055 here.
1056 Win32: Win32 does not know how to send real signals, so "TERM" is a
1058 full-force kill on Win32. Thus all talk of grace periods, etc. do
1059 not apply to Win32.
1060 harness
1062 Takes a harness specification and returns a harness. This harness
1063 is blessed in to IPC::Run, allowing you to use method call syntax
1064 for run(), start(), et al if you like.
1065 harness() is provided so that you can pre-build harnesses if you
1067 would like to, but it's not required..
1068 You may proceed to run(), start() or pump() after calling harness()
1070 (pump() calls start() if need be). Alternatively, you may pass
1071 your harness specification to run() or start() and let them har‐
1072 ness() for you. You can't pass harness specifications to pump(),
1073 though.
1074 close_terminal
1076 This is used as (or in) an init sub to cast off the bonds of a con‐
1077 trolling terminal. It must precede all other redirection ops that
1078 affect STDIN, STDOUT, or STDERR to be guaranteed effective.
1079 start
1081 $h = start(
1082 \@cmd, \$in, \$out, ...,
1083 timeout( 30, name => "process timeout" ),
1084 $stall_timeout = timeout( 10, name => "stall timeout" ),
1085 ) ;
1086 $h = start \@cmd, '<', \$in, '⎪', \@cmd2, ... ;
1088 start() accepts a harness or harness specification and returns a
1090 harness after building all of the pipes and launching (via
1091 fork()/exec(), or, maybe someday, spawn()) all the child processes.
1092 It does not send or receive any data on the pipes, see pump() and
1093 finish() for that.
1094 You may call harness() and then pass it's result to start() if you
1096 like, but you only need to if it helps you structure or tune your
1097 application. If you do call harness(), you may skip start() and
1098 proceed directly to pump.
1099 start() also starts all timers in the harness. See IPC::Run::Timer
1101 for more information.
1102 start() flushes STDOUT and STDERR to help you avoid duplicate out‐
1104 put. It has no way of asking Perl to flush all your open filehan‐
1105 dles, so you are going to need to flush any others you have open.
1106 Sorry.
1107 Here's how if you don't want to alter the state of $⎪ for your
1109 filehandle:
1110 $ofh = select HANDLE ; $of = $⎪ ; $⎪ = 1 ; $⎪ = $of ; select $ofh;
1112 If you don't mind leaving output unbuffered on HANDLE, you can do
1114 the slightly shorter
1115 $ofh = select HANDLE ; $⎪ = 1 ; select $ofh;
1117 Or, you can use IO::Handle's flush() method:
1119 use IO::Handle ;
1121 flush HANDLE ;
1122 Perl needs the equivalent of C's fflush( (FILE *)NULL ).
1124 pump
1126 pump $h ;
1127 $h->pump ;
1128 Pump accepts a single parameter harness. It blocks until it deliv‐
1130 ers some input or recieves some output. It returns TRUE if there
1131 is still input or output to be done, FALSE otherwise.
1132 pump() will automatically call start() if need be, so you may call
1134 harness() then proceed to pump() if that helps you structure your
1135 application.
1136 If pump() is called after all harnessed activities have completed,
1138 a "process ended prematurely" exception to be thrown. This allows
1139 for simple scripting of external applications without having to add
1140 lots of error handling code at each step of the script:
1141 $h = harness \@smbclient, \$in, \$out, $err ;
1143 $in = "cd /foo\n" ;
1145 $h->pump until $out =~ /^smb.*> \Z/m ;
1146 die "error cding to /foo:\n$out" if $out =~ "ERR" ;
1147 $out = '' ;
1148 $in = "mget *\n" ;
1150 $h->pump until $out =~ /^smb.*> \Z/m ;
1151 die "error retrieving files:\n$out" if $out =~ "ERR" ;
1152 $h->finish ;
1154 warn $err if $err ;
1156 pump_nb
1158 pump_nb $h ;
1159 $h->pump_nb ;
1160 "pump() non-blocking", pumps if anything's ready to be pumped,
1162 returns immediately otherwise. This is useful if you're doing some
1163 long-running task in the foreground, but don't want to starve any
1164 child processes.
1165 pumpable
1167 Returns TRUE if calling pump() won't throw an immediate "process
1168 ended prematurely" exception. This means that there are open I/O
1169 channels or active processes. May yield the parent processes' time
1170 slice for 0.01 second if all pipes are to the child and all are
1171 paused. In this case we can't tell if the child is dead, so we
1172 yield the processor and then attempt to reap the child in a non‐
1173 blocking way.
1174 reap_nb
1176 Attempts to reap child processes, but does not block.
1177 Does not currently take any parameters, one day it will allow spe‐
1179 cific children to be reaped.
1180 Only call this from a signal handler if your "perl" is recent
1182 enough to have safe signal handling (5.6.1 did not, IIRC, but it
1183 was beign discussed on perl5-porters). Calling this (or doing any
1184 significant work) in a signal handler on older "perl"s is asking
1185 for seg faults.
1186 finish
1188 This must be called after the last start() or pump() call for a
1189 harness, or your system will accumulate defunct processes and you
1190 may "leak" file descriptors.
1191 finish() returns TRUE if all children returned 0 (and were not sig‐
1193 naled and did not coredump, ie ! $?), and FALSE otherwise (this is
1194 like run(), and the opposite of system()).
1195 Once a harness has been finished, it may be run() or start()ed
1197 again, including by pump()s auto-start.
1198 If this throws an exception rather than a normal exit, the harness
1200 may be left in an unstable state, it's best to kill the harness to
1201 get rid of all the child processes, etc.
1202 Specifically, if a timeout expires in finish(), finish() will not
1204 kill all the children. Call "<$h-"kill_kill>> in this case if you
1205 care. This differs from the behavior of "run".
1206 result
1208 $h->result ;
1209 Returns the first non-zero result code (ie $? >> 8). See
1211 "full_result" to get the $? value for a child process.
1212 To get the result of a particular child, do:
1214 $h->result( 0 ) ; # first child's $? >> 8
1216 $h->result( 1 ) ; # second child
1217 or
1219 ($h->results)[0]
1221 ($h->results)[1]
1222 Returns undef if no child processes were spawned and no child num‐
1224 ber was specified. Throws an exception if an out-of-range child
1225 number is passed.
1226 results
1228 Returns a list of child exit values. See "full_results" if you
1229 want to know if a signal killed the child.
1230 Throws an exception if the harness is not in a finished state.
1232 full_result
1234 $h->full_result ;
1235 Returns the first non-zero $?. See "result" to get the first $? >>
1237 8 value for a child process.
1238 To get the result of a particular child, do:
1240 $h->full_result( 0 ) ; # first child's $? >> 8
1242 $h->full_result( 1 ) ; # second child
1243 or
1245 ($h->full_results)[0]
1247 ($h->full_results)[1]
1248 Returns undef if no child processes were spawned and no child num‐
1250 ber was specified. Throws an exception if an out-of-range child
1251 number is passed.
1252 full_results
1254 Returns a list of child exit values as returned by "wait". See
1255 "results" if you don't care about coredumps or signals.
1256 Throws an exception if the harness is not in a finished state.
1258
1260 These filters are used to modify input our output between a child
1261 process and a scalar or subroutine endpoint.
1262 binary
1264 run \@cmd, ">", binary, \$out ;
1265 run \@cmd, ">", binary, \$out ; ## Any TRUE value to enable
1266 run \@cmd, ">", binary 0, \$out ; ## Any FALSE value to disable
1267 This is a constructor for a "binmode" "filter" that tells IPC::Run
1269 to keep the carriage returns that would ordinarily be edited out
1270 for you (binmode is usually off). This is not a real filter, but
1271 an option masquerading as a filter.
1272 It's not named "binmode" because you're likely to want to call
1274 Perl's binmode in programs that are piping binary data around.
1275 new_chunker
1277 This breaks a stream of data in to chunks, based on an optional
1278 scalar or regular expression parameter. The default is the Perl
1279 input record separator in $/, which is a newline be default.
1280 run \@cmd, '>', new_chunker, \&lines_handler ;
1282 run \@cmd, '>', new_chunker( "\r\n" ), \&lines_handler ;
1283 Because this uses $/ by default, you should always pass in a param‐
1285 eter if you are worried about other code (modules, etc) modifying
1286 $/.
1287 If this filter is last in a filter chain that dumps in to a scalar,
1289 the scalar must be set to '' before a new chunk will be written to
1290 it.
1291 As an example of how a filter like this can be written, here's a
1293 chunker that splits on newlines:
1294 sub line_splitter {
1296 my ( $in_ref, $out_ref ) = @_ ;
1297 return 0 if length $$out_ref ;
1299 return input_avail && do {
1301 while (1) {
1302 if ( $$in_ref =~ s/\A(.*?\n)// ) {
1303 $$out_ref .= $1 ;
1304 return 1 ;
1305 }
1306 my $hmm = get_more_input ;
1307 unless ( defined $hmm ) {
1308 $$out_ref = $$in_ref ;
1309 $$in_ref = '' ;
1310 return length $$out_ref ? 1 : 0 ;
1311 }
1312 return 0 if $hmm eq 0 ;
1313 }
1314 }
1315 } ;
1316 new_appender
1318 This appends a fixed string to each chunk of data read from the
1319 source scalar or sub. This might be useful if you're writing com‐
1320 mands to a child process that always must end in a fixed string,
1321 like "\n":
1322 run( \@cmd,
1324 '<', new_appender( "\n" ), \&commands,
1325 ) ;
1326 Here's a typical filter sub that might be created by new_appen‐
1328 der():
1329 sub newline_appender {
1331 my ( $in_ref, $out_ref ) = @_ ;
1332 return input_avail && do {
1334 $$out_ref = join( '', $$out_ref, $$in_ref, "\n" ) ;
1335 $$in_ref = '' ;
1336 1 ;
1337 }
1338 } ;
1339 io Takes a filename or filehandle, a redirection operator, optional
1341 filters, and a source or destination (depends on the redirection
1342 operator). Returns an IPC::Run::IO object suitable for har‐
1343 ness()ing (including via start() or run()).
1344 This is shorthand for
1346 require IPC::Run::IO ;
1348 ... IPC::Run::IO->new(...) ...
1350 timer
1352 $h = start( \@cmd, \$in, \$out, $t = timer( 5 ) ) ;
1353 pump $h until $out =~ /expected stuff/ ⎪⎪ $t->is_expired ;
1355 Instantiates a non-fatal timer. pump() returns once each time a
1357 timer expires. Has no direct effect on run(), but you can pass a
1358 subroutine to fire when the timer expires.
1359 See "timeout" for building timers that throw exceptions on expira‐
1361 tion.
1362 See "timer" in IPC::Run::Timer for details.
1364 timeout
1366 $h = start( \@cmd, \$in, \$out, $t = timeout( 5 ) ) ;
1367 pump $h until $out =~ /expected stuff/ ;
1369 Instantiates a timer that throws an exception when it expires. If
1371 you don't provide an exception, a default exception that matches
1372 /^IPC::Run: .*timed out/ is thrown by default. You can pass in
1373 your own exception scalar or reference:
1374 $h = start(
1376 \@cmd, \$in, \$out,
1377 $t = timeout( 5, exception => 'slowpoke' ),
1378 ) ;
1379 or set the name used in debugging message and in the default excep‐
1381 tion string:
1382 $h = start(
1384 \@cmd, \$in, \$out,
1385 timeout( 50, name => 'process timer' ),
1386 $stall_timer = timeout( 5, name => 'stall timer' ),
1387 ) ;
1388 pump $h until $out =~ /started/ ;
1390 $in = 'command 1' ;
1392 $stall_timer->start ;
1393 pump $h until $out =~ /command 1 finished/ ;
1394 $in = 'command 2' ;
1396 $stall_timer->start ;
1397 pump $h until $out =~ /command 2 finished/ ;
1398 $in = 'very slow command 3' ;
1400 $stall_timer->start( 10 ) ;
1401 pump $h until $out =~ /command 3 finished/ ;
1402 $stall_timer->start( 5 ) ;
1404 $in = 'command 4' ;
1405 pump $h until $out =~ /command 4 finished/ ;
1406 $stall_timer->reset; # Prevent restarting or expirng
1408 finish $h ;
1409 See "timer" for building non-fatal timers.
1411 See "timer" in IPC::Run::Timer for details.
1413
1415 These functions are for use from within filters.
1416 input_avail
1418 Returns TRUE if input is available. If none is available, then
1419 &get_more_input is called and its result is returned.
1420 This is usually used in preference to &get_more_input so that the
1422 calling filter removes all data from the $in_ref before more data
1423 gets read in to $in_ref.
1424 "input_avail" is usually used as part of a return expression:
1426 return input_avail && do {
1428 ## process the input just gotten
1429 1 ;
1430 } ;
1431 This technique allows input_avail to return the undef or 0 that a
1433 filter normally returns when there's no input to process. If a
1434 filter stores intermediate values, however, it will need to react
1435 to an undef:
1436 my $got = input_avail ;
1438 if ( ! defined $got ) {
1439 ## No more input ever, flush internal buffers to $out_ref
1440 }
1441 return $got unless $got ;
1442 ## Got some input, move as much as need be
1443 return 1 if $added_to_out_ref ;
1444 get_more_input
1446 This is used to fetch more input in to the input variable. It
1447 returns undef if there will never be any more input, 0 if there is
1448 none now, but there might be in the future, and TRUE if more input
1449 was gotten.
1450 "get_more_input" is usually used as part of a return expression,
1452 see "input_avail" for more information.
1453
1455 These will be addressed as needed and as time allows.
1456 Stall timeout.
1458 Expose a list of child process objects. When I do this, each child
1460 process is likely to be blessed into IPC::Run::Proc.
1461 $kid->abort(), $kid->kill(), $kid->signal( $num_or_name ).
1463 Write tests for /(full_)?results?/ subs.
1465 Currently, pump() and run() only work on systems where select() works
1467 on the filehandles returned by pipe(). This does *not* include
1468 ActiveState on Win32, although it does work on cygwin under Win32
1469 (thought the tests whine a bit). I'd like to rectify that, suggestions
1470 and patches welcome.
1471 Likewise start() only fully works on fork()/exec() machines (well, just
1473 fork() if you only ever pass perl subs as subprocesses). There's some
1474 scaffolding for calling Open3::spawn_with_handles(), but that's
1475 untested, and not that useful with limited select().
1476 Support for "\@sub_cmd" as an argument to a command which gets replaced
1478 with /dev/fd or the name of a temporary file containing foo's output.
1479 This is like <(sub_cmd ...) found in bash and csh (IIRC).
1480 Allow multiple harnesses to be combined as independant sets of pro‐
1482 cesses in to one 'meta-harness'.
1483 Allow a harness to be passed in place of an \@cmd. This would allow
1485 multiple harnesses to be aggregated.
1486 Ability to add external file descriptors w/ filter chains and end‐
1488 points.
1489 Ability to add timeouts and timing generators (i.e. repeating time‐
1491 outs).
1492 High resolution timeouts.
1494
1496 Fails on Win9X
1497 If you want Win9X support, you'll have to debug it or fund me
1498 because I don't use that system any more. The Win32 subsysem has
1499 been extended to use temporary files in simple run() invocations
1500 and these may actually work on Win9X too, but I don't have time to
1501 work on it.
1502 May deadlock on Win2K (but not WinNT4 or WinXPPro)
1504 Spawning more than one subprocess on Win2K causes a deadlock I
1505 haven't figured out yet, but simple uses of run() often work.
1506 Passes all tests on WinXPPro and WinNT.
1507 no support yet for <pty< and >pty>
1509 These are likely to be implemented as "<" and ">" with binmode on,
1510 not sure.
1511 no support for file descriptors higher than 2 (stderr)
1513 Win32 only allows passing explicit fds 0, 1, and 2. If you really,
1514 really need to pass file handles, us Win32API:: GetOsFHandle() or
1515 ::FdGetOsFHandle() to get the integer handle and pass it to the
1516 child process using the command line, environment, stdin, interme‐
1517 diary file, or other IPC mechnism. Then use that handle in the
1518 child (Win32API.pm provides ways to reconstitute Perl file handles
1519 from Win32 file handles).
1520 no support for subroutine subprocesses (CODE refs)
1522 Can't fork(), so the subroutines would have no context, and clo‐
1523 sures certainly have no meaning
1524 Perhaps with Win32 fork() emulation, this can be supported in a
1526 limited fashion, but there are other very serious problems with
1527 that: all parent fds get dup()ed in to the thread emulating the
1528 forked process, and that keeps the parent from being able to close
1529 all of the appropriate fds.
1530 no support for init => sub {} routines.
1532 Win32 processes are created from scratch, there is no way to do an
1533 init routine that will affect the running child. Some limited sup‐
1534 port might be implemented one day, do chdir() and %ENV changes can
1535 be made.
1536 signals
1538 Win32 does not fully support signals. signal() is likely to cause
1539 errors unless sending a signal that Perl emulates, and
1540 "kill_kill()" is immediately fatal (there is no grace period).
1541 helper processes
1543 IPC::Run uses helper processes, one per redirected file, to adapt
1544 between the anonymous pipe connected to the child and the TCP
1545 socket connected to the parent. This is a waste of resources and
1546 will change in the future to either use threads (instead of helper
1547 processes) or a WaitForMultipleObjects call (instead of select).
1548 Please contact me if you can help with the WaitForMultipleObjects()
1549 approach; I haven't figured out how to get at it without C code.
1550 shutdown pause
1552 There seems to be a pause of up to 1 second between when a child
1553 program exits and the corresponding sockets indicate that they are
1554 closed in the parent. Not sure why.
1555 binmode
1557 binmode is not supported yet. The underpinnings are implemented,
1558 just ask if you need it.
1559 IPC::Run::IO
1561 IPC::Run::IO objects can be used on Unix to read or write arbitrary
1562 files. On Win32, they will need to use the same helper processes
1563 to adapt from non-select()able filehandles to select()able ones (or
1564 perhaps WaitForMultipleObjects() will work with them, not sure).
1565 startup race conditions
1567 There seems to be an occasional race condition between child
1568 process startup and pipe closings. It seems like if the child is
1569 not fully created by the time CreateProcess returns and we close
1570 the TCP socket being handed to it, the parent socket can also get
1571 closed. This is seen with the Win32 pumper applications, not the
1572 "real" child process being spawned.
1573 I assume this is because the kernel hasn't gotten around to incre‐
1575 menting the reference count on the child's end (since the child was
1576 slow in starting), so the parent's closing of the child end causes
1577 the socket to be closed, thus closing the parent socket.
1578 Being a race condition, it's hard to reproduce, but I encountered
1580 it while testing this code on a drive share to a samba box. In
1581 this case, it takes t/run.t a long time to spawn it's chile pro‐
1582 cesses (the parent hangs in the first select for several seconds
1583 until the child emits any debugging output).
1584 I have not seen it on local drives, and can't reproduce it at will,
1586 unfortunately. The symptom is a "bad file descriptor in select()"
1587 error, and, by turning on debugging, it's possible to see that
1588 select() is being called on a no longer open file descriptor that
1589 was returned from the _socket() routine in Win32Helper. There's a
1590 new confess() that checks for this ("PARENT_HANDLE no longer
1591 open"), but I haven't been able to reproduce it (typically).
1592
1594 On Unix, requires a system that supports "waitpid( $pid, WNOHANG )" so
1595 it can tell if a child process is still running.
1596 PTYs don't seem to be non-blocking on some versions of Solaris. Here's
1598 a test script contributed by Borislav Deianov <borislav@ensim.com> to
1599 see if you have the problem. If it dies, you have the problem.
1600 #!/usr/bin/perl
1602 use IPC::Run qw(run);
1604 use Fcntl;
1605 use IO::Pty;
1606 sub makecmd {
1608 return ['perl', '-e',
1609 '<STDIN>, print "\n" x '.$_[0].'; while(<STDIN>){last if /end/}'];
1610 }
1611 #pipe R, W;
1613 #fcntl(W, F_SETFL, O_NONBLOCK);
1614 #while (syswrite(W, "\n", 1)) { $pipebuf++ };
1615 #print "pipe buffer size is $pipebuf\n";
1616 my $pipebuf=4096;
1617 my $in = "\n" x ($pipebuf * 2) . "end\n";
1618 my $out;
1619 $SIG{ALRM} = sub { die "Never completed!\n" } ;
1621 print "reading from scalar via pipe...";
1623 alarm( 2 ) ;
1624 run(makecmd($pipebuf * 2), '<', \$in, '>', \$out);
1625 alarm( 0 );
1626 print "done\n";
1627 print "reading from code via pipe... ";
1629 alarm( 2 ) ;
1630 run(makecmd($pipebuf * 3), '<', sub { $t = $in; undef $in; $t}, '>', \$out);
1631 alarm( 0 ) ;
1632 print "done\n";
1633 $pty = IO::Pty->new();
1635 $pty->blocking(0);
1636 $slave = $pty->slave();
1637 while ($pty->syswrite("\n", 1)) { $ptybuf++ };
1638 print "pty buffer size is $ptybuf\n";
1639 $in = "\n" x ($ptybuf * 3) . "end\n";
1640 print "reading via pty... ";
1642 alarm( 2 ) ;
1643 run(makecmd($ptybuf * 3), '<pty<', \$in, '>', \$out);
1644 alarm(0);
1645 print "done\n";
1646 No support for ';', '&&', '⎪⎪', '{ ... }', etc: use perl's, since run()
1648 returns TRUE when the command exits with a 0 result code.
1649 Does not provide shell-like string interpolation.
1651 No support for "cd", "setenv", or "export": do these in an init() sub
1653 run(
1655 \cmd,
1656 ...
1657 init => sub {
1658 chdir $dir or die $! ;
1659 $ENV{FOO}='BAR'
1660 }
1661 ) ;
1662 Timeout calculation does not allow absolute times, or specification of
1664 days, months, etc.
1665 WARNING: Function coprocesses ("run \&foo, ...") suffer from two limi‐
1667 tations. The first is that it is difficult to close all filehandles
1668 the child inherits from the parent, since there is no way to scan all
1669 open FILEHANDLEs in Perl and it both painful and a bit dangerous to
1670 close all open file descriptors with "POSIX::close()". Painful because
1671 we can't tell which fds are open at the POSIX level, either, so we'd
1672 have to scan all possible fds and close any that we don't want open
1673 (normally "exec()" closes any non-inheritable but we don't "exec()" for
1674 &sub processes.
1675 The second problem is that Perl's DESTROY subs and other on-exit
1677 cleanup gets run in the child process. If objects are instantiated in
1678 the parent before the child is forked, the the DESTROY will get run
1679 once in the parent and once in the child. When coprocess subs exit,
1680 POSIX::exit is called to work around this, but it means that objects
1681 that are still referred to at that time are not cleaned up. So setting
1682 package vars or closure vars to point to objects that rely on DESTROY
1683 to affect things outside the process (files, etc), will lead to bugs.
1684 I goofed on the syntax: "<pipe" vs. "<pty<" and ">filename" are both
1686 oddities.
1687
1689 Allow one harness to "adopt" another:
1690 $new_h = harness \@cmd2 ;
1691 $h->adopt( $new_h ) ;
1692 Close all filehandles not explicitly marked to stay open.
1694 The problem with this one is that there's no good way to scan all
1695 open FILEHANDLEs in Perl, yet you don't want child processes inher‐
1696 iting handles willy-nilly.
1697
1699 Well, select() and waitpid() badly needed wrapping, and open3() isn't
1700 open-minded enough for me.
1701 The shell-like API inspired by a message Russ Allbery sent to
1703 perl5-porters, which included:
1704 I've thought for some time that it would be
1706 nice to have a module that could handle full Bourne shell pipe syntax
1707 internally, with fork and exec, without ever invoking a shell. Something
1708 that you could give things like:
1709 pipeopen (PIPE, [ qw/cat file/ ], '⎪', [ 'analyze', @args ], '>&3');
1711 Message ylln51p2b6.fsf@windlord.stanford.edu, on 2000/02/04.
1713
1715 Barrie Slaymaker <barries@slaysys.com>, with numerous suggestions by
1716 p5p.
1717perl v5.8.8 2006-05-10 IPC::Run(3)