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 \@cat, \$in, \$out, \$err, timeout( 10 ) or die "cat: $?";
17 # Can do I/O to sub refs and filenames, too:
19 run \@cat, '<', "in.txt", \&out, \&err or die "cat: $?";
20 run \@cat, '<', "in.txt", '>>', "out.txt", '2>>', "err.txt";
21 # Redirecting using pseudo-terminals instead 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, # may also be a lexical filehandle e.g. \my $infh
76 '>pipe', \*OUT,
77 '2>pipe', \*ERR
78 or die "cat returned $?";
79 print IN "some input\n";
80 close IN;
81 print <OUT>, <ERR>;
82 finish $h;
83 # 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 to run and interact with child processes using
114 files, pipes, and pseudo-ttys. Both system()-style and scripted usages
115 are supported and may be mixed. Likewise, functional and OO API styles
116 are both supported and may be mixed.
117 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 occurred 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 descriptors obtained via POSIX, since it only applies to full-fledged
474 Perl file handles. Such processes will have their stdin closed unless
475 it has been redirected-to.
476 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 Pseudo-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 or lexical filehandle opened by IPC::Run as the parent end of a pipe, but read
689 and written to and closed by the caller (like IPC::Open3).
690 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,
953 pumping all input to the child(ren), closing the input pipes
954 when no more input is available, collecting all output that
955 arrives, until the pipes delivering output are closed, then
956 waiting for the children to exit and reaping their result
957 codes.
958 You may think of "run( ... )" as being like
960 start( ... )->finish();
962 , though there is one subtle difference: run() does not set
964 \$input_scalars to '' like finish() does. If an exception is
965 thrown from run(), all children will be killed off "gently",
966 and then "annihilated" if they do not go gently (in to that
967 dark night. sorry).
968 If any exceptions are thrown, this does a "kill_kill" before
970 propagating them.
971 signal
973 ## To send it a specific signal by name ("USR1"):
974 signal $h, "USR1";
975 $h->signal ( "USR1" );
976 If $signal is provided and defined, sends a signal to all child
978 processes. Try not to send numeric signals, use "KILL" instead
979 of 9, for instance. Numeric signals aren't portable.
980 Throws an exception if $signal is undef.
982 This will not clean up the harness, "finish" it if you kill it.
984 Normally TERM kills a process gracefully (this is what the
986 command line utility "kill" does by default), INT is sent by
987 one of the keys "^C", "Backspace" or "<Del>", and "QUIT" is
988 used to kill a process and make it coredump.
989 The "HUP" signal is often used to get a process to "restart",
991 rereading config files, and "USR1" and "USR2" for really
992 application-specific things.
993 Often, running "kill -l" (that's a lower case "L") on the
995 command line will list the signals present on your operating
996 system.
997 WARNING: The signal subsystem is not at all portable. We *may*
999 offer to simulate "TERM" and "KILL" on some operating systems,
1000 submit code to me if you want this.
1001 WARNING 2: Up to and including perl v5.6.1, doing almost
1003 anything in a signal handler could be dangerous. The most safe
1004 code avoids all mallocs and system calls, usually by
1005 preallocating a flag before entering the signal handler,
1006 altering the flag's value in the handler, and responding to the
1007 changed value in the main system:
1008 my $got_usr1 = 0;
1010 sub usr1_handler { ++$got_signal }
1011 $SIG{USR1} = \&usr1_handler;
1013 while () { sleep 1; print "GOT IT" while $got_usr1--; }
1014 Even this approach is perilous if ++ and -- aren't atomic on
1016 your system (I've never heard of this on any modern CPU large
1017 enough to run perl).
1018 kill_kill
1020 ## To kill off a process:
1021 $h->kill_kill;
1022 kill_kill $h;
1023 ## To specify the grace period other than 30 seconds:
1025 kill_kill $h, grace => 5;
1026 ## To send QUIT instead of KILL if a process refuses to die:
1028 kill_kill $h, coup_d_grace => "QUIT";
1029 Sends a "TERM", waits for all children to exit for up to 30
1031 seconds, then sends a "KILL" to any that survived the "TERM".
1032 Will wait for up to 30 more seconds for the OS to successfully
1034 "KILL" the processes.
1035 The 30 seconds may be overridden by setting the "grace" option,
1037 this overrides both timers.
1038 The harness is then cleaned up.
1040 The doubled name indicates that this function may kill again
1042 and avoids colliding with the core Perl "kill" function.
1043 Returns a 1 if the "TERM" was sufficient, or a 0 if "KILL" was
1045 required. Throws an exception if "KILL" did not permit the
1046 children to be reaped.
1047 NOTE: The grace period is actually up to 1 second longer than
1049 that given. This is because the granularity of "time" is 1
1050 second. Let me know if you need finer granularity, we can
1051 leverage Time::HiRes here.
1052 Win32: Win32 does not know how to send real signals, so "TERM"
1054 is a full-force kill on Win32. Thus all talk of grace periods,
1055 etc. do not apply to Win32.
1056 harness
1058 Takes a harness specification and returns a harness. This
1059 harness is blessed in to IPC::Run, allowing you to use method
1060 call syntax for run(), start(), et al if you like.
1061 harness() is provided so that you can pre-build harnesses if
1063 you would like to, but it's not required..
1064 You may proceed to run(), start() or pump() after calling
1066 harness() (pump() calls start() if need be). Alternatively,
1067 you may pass your harness specification to run() or start() and
1068 let them harness() for you. You can't pass harness
1069 specifications to pump(), though.
1070 close_terminal
1072 This is used as (or in) an init sub to cast off the bonds of a
1073 controlling terminal. It must precede all other redirection
1074 ops that affect STDIN, STDOUT, or STDERR to be guaranteed
1075 effective.
1076 start
1078 $h = start(
1079 \@cmd, \$in, \$out, ...,
1080 timeout( 30, name => "process timeout" ),
1081 $stall_timeout = timeout( 10, name => "stall timeout" ),
1082 );
1083 $h = start \@cmd, '<', \$in, '|', \@cmd2, ...;
1085 start() accepts a harness or harness specification and returns
1087 a harness after building all of the pipes and launching (via
1088 fork()/exec(), or, maybe someday, spawn()) all the child
1089 processes. It does not send or receive any data on the pipes,
1090 see pump() and finish() for that.
1091 You may call harness() and then pass it's result to start() if
1093 you like, but you only need to if it helps you structure or
1094 tune your application. If you do call harness(), you may skip
1095 start() and proceed directly to pump.
1096 start() also starts all timers in the harness. See
1098 IPC::Run::Timer for more information.
1099 start() flushes STDOUT and STDERR to help you avoid duplicate
1101 output. It has no way of asking Perl to flush all your open
1102 filehandles, so you are going to need to flush any others you
1103 have open. Sorry.
1104 Here's how if you don't want to alter the state of $| for your
1106 filehandle:
1107 $ofh = select HANDLE; $of = $|; $| = 1; $| = $of; select $ofh;
1109 If you don't mind leaving output unbuffered on HANDLE, you can
1111 do the slightly shorter
1112 $ofh = select HANDLE; $| = 1; select $ofh;
1114 Or, you can use IO::Handle's flush() method:
1116 use IO::Handle;
1118 flush HANDLE;
1119 Perl needs the equivalent of C's fflush( (FILE *)NULL ).
1121 adopt
1123 Experimental feature. NOT FUNCTIONAL YET, NEED TO CLOSE FDS
1124 BETTER IN CHILDREN. SEE t/adopt.t for a test suite.
1125 pump
1127 pump $h;
1128 $h->pump;
1129 Pump accepts a single parameter harness. It blocks until it
1131 delivers some input or receives some output. It returns TRUE
1132 if there is still input or output to be done, FALSE otherwise.
1133 pump() will automatically call start() if need be, so you may
1135 call harness() then proceed to pump() if that helps you
1136 structure your application.
1137 If pump() is called after all harnessed activities have
1139 completed, a "process ended prematurely" exception to be
1140 thrown. This allows for simple scripting of external
1141 applications without having to add lots of error handling code
1142 at each step of the script:
1143 $h = harness \@smbclient, \$in, \$out, $err;
1145 $in = "cd /foo\n";
1147 $h->pump until $out =~ /^smb.*> \Z/m;
1148 die "error cding to /foo:\n$out" if $out =~ "ERR";
1149 $out = '';
1150 $in = "mget *\n";
1152 $h->pump until $out =~ /^smb.*> \Z/m;
1153 die "error retrieving files:\n$out" if $out =~ "ERR";
1154 $h->finish;
1156 warn $err if $err;
1158 pump_nb
1160 pump_nb $h;
1161 $h->pump_nb;
1162 "pump() non-blocking", pumps if anything's ready to be pumped,
1164 returns immediately otherwise. This is useful if you're doing
1165 some long-running task in the foreground, but don't want to
1166 starve any child processes.
1167 pumpable
1169 Returns TRUE if calling pump() won't throw an immediate
1170 "process ended prematurely" exception. This means that there
1171 are open I/O channels or active processes. May yield the parent
1172 processes' time slice for 0.01 second if all pipes are to the
1173 child and all are paused. In this case we can't tell if the
1174 child is dead, so we yield the processor and then attempt to
1175 reap the child in a nonblocking way.
1176 reap_nb
1178 Attempts to reap child processes, but does not block.
1179 Does not currently take any parameters, one day it will allow
1181 specific children to be reaped.
1182 Only call this from a signal handler if your "perl" is recent
1184 enough to have safe signal handling (5.6.1 did not, IIRC, but
1185 it was being discussed on perl5-porters). Calling this (or
1186 doing any significant work) in a signal handler on older
1187 "perl"s is asking for seg faults.
1188 finish
1190 This must be called after the last start() or pump() call for a
1191 harness, or your system will accumulate defunct processes and
1192 you may "leak" file descriptors.
1193 finish() returns TRUE if all children returned 0 (and were not
1195 signaled and did not coredump, ie ! $?), and FALSE otherwise
1196 (this is like run(), and the opposite of system()).
1197 Once a harness has been finished, it may be run() or start()ed
1199 again, including by pump()s auto-start.
1200 If this throws an exception rather than a normal exit, the
1202 harness may be left in an unstable state, it's best to kill the
1203 harness to get rid of all the child processes, etc.
1204 Specifically, if a timeout expires in finish(), finish() will
1206 not kill all the children. Call "<$h-"kill_kill>> in this case
1207 if you care. This differs from the behavior of "run".
1208 result
1210 $h->result;
1211 Returns the first non-zero result code (ie $? >> 8). See
1213 "full_result" to get the $? value for a child process.
1214 To get the result of a particular child, do:
1216 $h->result( 0 ); # first child's $? >> 8
1218 $h->result( 1 ); # second child
1219 or
1221 ($h->results)[0]
1223 ($h->results)[1]
1224 Returns undef if no child processes were spawned and no child
1226 number was specified. Throws an exception if an out-of-range
1227 child number is passed.
1228 results
1230 Returns a list of child exit values. See "full_results" if you
1231 want to know if a signal killed the child.
1232 Throws an exception if the harness is not in a finished state.
1234 full_result
1236 $h->full_result;
1237 Returns the first non-zero $?. See "result" to get the first
1239 $? >> 8 value for a child process.
1240 To get the result of a particular child, do:
1242 $h->full_result( 0 ); # first child's $?
1244 $h->full_result( 1 ); # second child
1245 or
1247 ($h->full_results)[0]
1249 ($h->full_results)[1]
1250 Returns undef if no child processes were spawned and no child
1252 number was specified. Throws an exception if an out-of-range
1253 child number is passed.
1254 full_results
1256 Returns a list of child exit values as returned by "wait". See
1257 "results" if you don't care about coredumps or signals.
1258 Throws an exception if the harness is not in a finished state.
1260
1262 These filters are used to modify input our output between a child
1263 process and a scalar or subroutine endpoint.
1264 binary
1266 run \@cmd, ">", binary, \$out;
1267 run \@cmd, ">", binary, \$out; ## Any TRUE value to enable
1268 run \@cmd, ">", binary 0, \$out; ## Any FALSE value to disable
1269 This is a constructor for a "binmode" "filter" that tells IPC::Run
1271 to keep the carriage returns that would ordinarily be edited out
1272 for you (binmode is usually off). This is not a real filter, but
1273 an option masquerading as a filter.
1274 It's not named "binmode" because you're likely to want to call
1276 Perl's binmode in programs that are piping binary data around.
1277 new_chunker
1279 This breaks a stream of data in to chunks, based on an optional
1280 scalar or regular expression parameter. The default is the Perl
1281 input record separator in $/, which is a newline be default.
1282 run \@cmd, '>', new_chunker, \&lines_handler;
1284 run \@cmd, '>', new_chunker( "\r\n" ), \&lines_handler;
1285 Because this uses $/ by default, you should always pass in a
1287 parameter if you are worried about other code (modules, etc)
1288 modifying $/.
1289 If this filter is last in a filter chain that dumps in to a scalar,
1291 the scalar must be set to '' before a new chunk will be written to
1292 it.
1293 As an example of how a filter like this can be written, here's a
1295 chunker that splits on newlines:
1296 sub line_splitter {
1298 my ( $in_ref, $out_ref ) = @_;
1299 return 0 if length $$out_ref;
1301 return input_avail && do {
1303 while (1) {
1304 if ( $$in_ref =~ s/\A(.*?\n)// ) {
1305 $$out_ref .= $1;
1306 return 1;
1307 }
1308 my $hmm = get_more_input;
1309 unless ( defined $hmm ) {
1310 $$out_ref = $$in_ref;
1311 $$in_ref = '';
1312 return length $$out_ref ? 1 : 0;
1313 }
1314 return 0 if $hmm eq 0;
1315 }
1316 }
1317 };
1318 new_appender
1320 This appends a fixed string to each chunk of data read from the
1321 source scalar or sub. This might be useful if you're writing
1322 commands to a child process that always must end in a fixed string,
1323 like "\n":
1324 run( \@cmd,
1326 '<', new_appender( "\n" ), \&commands,
1327 );
1328 Here's a typical filter sub that might be created by
1330 new_appender():
1331 sub newline_appender {
1333 my ( $in_ref, $out_ref ) = @_;
1334 return input_avail && do {
1336 $$out_ref = join( '', $$out_ref, $$in_ref, "\n" );
1337 $$in_ref = '';
1338 1;
1339 }
1340 };
1341 new_string_source
1343 TODO: Needs confirmation. Was previously undocumented. in this
1344 module.
1345 This is a filter which is exportable. Returns a sub which appends
1347 the data passed in to the output buffer and returns 1 if data was
1348 appended. 0 if it was an empty string and undef if no data was
1349 passed.
1350 NOTE: Any additional variables passed to new_string_source will be
1352 passed to the sub every time it's called and appended to the
1353 output.
1354 new_string_sink
1356 TODO: Needs confirmation. Was previously undocumented.
1357 This is a filter which is exportable. Returns a sub which pops the
1359 data out of the input stream and pushes it onto the string.
1360 io Takes a filename or filehandle, a redirection operator, optional
1362 filters, and a source or destination (depends on the redirection
1363 operator). Returns an IPC::Run::IO object suitable for
1364 harness()ing (including via start() or run()).
1365 This is shorthand for
1367 require IPC::Run::IO;
1369 ... IPC::Run::IO->new(...) ...
1371 timer
1373 $h = start( \@cmd, \$in, \$out, $t = timer( 5 ) );
1374 pump $h until $out =~ /expected stuff/ || $t->is_expired;
1376 Instantiates a non-fatal timer. pump() returns once each time a
1378 timer expires. Has no direct effect on run(), but you can pass a
1379 subroutine to fire when the timer expires.
1380 See "timeout" for building timers that throw exceptions on
1382 expiration.
1383 See "timer" in IPC::Run::Timer for details.
1385 timeout
1387 $h = start( \@cmd, \$in, \$out, $t = timeout( 5 ) );
1388 pump $h until $out =~ /expected stuff/;
1390 Instantiates a timer that throws an exception when it expires. If
1392 you don't provide an exception, a default exception that matches
1393 /^IPC::Run: .*timed out/ is thrown by default. You can pass in
1394 your own exception scalar or reference:
1395 $h = start(
1397 \@cmd, \$in, \$out,
1398 $t = timeout( 5, exception => 'slowpoke' ),
1399 );
1400 or set the name used in debugging message and in the default
1402 exception string:
1403 $h = start(
1405 \@cmd, \$in, \$out,
1406 timeout( 50, name => 'process timer' ),
1407 $stall_timer = timeout( 5, name => 'stall timer' ),
1408 );
1409 pump $h until $out =~ /started/;
1411 $in = 'command 1';
1413 $stall_timer->start;
1414 pump $h until $out =~ /command 1 finished/;
1415 $in = 'command 2';
1417 $stall_timer->start;
1418 pump $h until $out =~ /command 2 finished/;
1419 $in = 'very slow command 3';
1421 $stall_timer->start( 10 );
1422 pump $h until $out =~ /command 3 finished/;
1423 $stall_timer->start( 5 );
1425 $in = 'command 4';
1426 pump $h until $out =~ /command 4 finished/;
1427 $stall_timer->reset; # Prevent restarting or expirng
1429 finish $h;
1430 See "timer" for building non-fatal timers.
1432 See "timer" in IPC::Run::Timer for details.
1434
1436 These functions are for use from within filters.
1437 input_avail
1439 Returns TRUE if input is available. If none is available, then
1440 &get_more_input is called and its result is returned.
1441 This is usually used in preference to &get_more_input so that the
1443 calling filter removes all data from the $in_ref before more data
1444 gets read in to $in_ref.
1445 "input_avail" is usually used as part of a return expression:
1447 return input_avail && do {
1449 ## process the input just gotten
1450 1;
1451 };
1452 This technique allows input_avail to return the undef or 0 that a
1454 filter normally returns when there's no input to process. If a
1455 filter stores intermediate values, however, it will need to react
1456 to an undef:
1457 my $got = input_avail;
1459 if ( ! defined $got ) {
1460 ## No more input ever, flush internal buffers to $out_ref
1461 }
1462 return $got unless $got;
1463 ## Got some input, move as much as need be
1464 return 1 if $added_to_out_ref;
1465 get_more_input
1467 This is used to fetch more input in to the input variable. It
1468 returns undef if there will never be any more input, 0 if there is
1469 none now, but there might be in the future, and TRUE if more input
1470 was gotten.
1471 "get_more_input" is usually used as part of a return expression,
1473 see "input_avail" for more information.
1474
1476 These will be addressed as needed and as time allows.
1477 Stall timeout.
1479 Expose a list of child process objects. When I do this, each child
1481 process is likely to be blessed into IPC::Run::Proc.
1482 $kid->abort(), $kid->kill(), $kid->signal( $num_or_name ).
1484 Write tests for /(full_)?results?/ subs.
1486 Currently, pump() and run() only work on systems where select() works
1488 on the filehandles returned by pipe(). This does *not* include
1489 ActiveState on Win32, although it does work on cygwin under Win32
1490 (thought the tests whine a bit). I'd like to rectify that, suggestions
1491 and patches welcome.
1492 Likewise start() only fully works on fork()/exec() machines (well, just
1494 fork() if you only ever pass perl subs as subprocesses). There's some
1495 scaffolding for calling Open3::spawn_with_handles(), but that's
1496 untested, and not that useful with limited select().
1497 Support for "\@sub_cmd" as an argument to a command which gets replaced
1499 with /dev/fd or the name of a temporary file containing foo's output.
1500 This is like <(sub_cmd ...) found in bash and csh (IIRC).
1501 Allow multiple harnesses to be combined as independent sets of
1503 processes in to one 'meta-harness'.
1504 Allow a harness to be passed in place of an \@cmd. This would allow
1506 multiple harnesses to be aggregated.
1507 Ability to add external file descriptors w/ filter chains and
1509 endpoints.
1510 Ability to add timeouts and timing generators (i.e. repeating
1512 timeouts).
1513 High resolution timeouts.
1515
1517 Fails on Win9X
1518 If you want Win9X support, you'll have to debug it or fund me
1519 because I don't use that system any more. The Win32 subsysem has
1520 been extended to use temporary files in simple run() invocations
1521 and these may actually work on Win9X too, but I don't have time to
1522 work on it.
1523 May deadlock on Win2K (but not WinNT4 or WinXPPro)
1525 Spawning more than one subprocess on Win2K causes a deadlock I
1526 haven't figured out yet, but simple uses of run() often work.
1527 Passes all tests on WinXPPro and WinNT.
1528 no support yet for <pty< and >pty>
1530 These are likely to be implemented as "<" and ">" with binmode on,
1531 not sure.
1532 no support for file descriptors higher than 2 (stderr)
1534 Win32 only allows passing explicit fds 0, 1, and 2. If you really,
1535 really need to pass file handles, us Win32API:: GetOsFHandle() or
1536 ::FdGetOsFHandle() to get the integer handle and pass it to the
1537 child process using the command line, environment, stdin,
1538 intermediary file, or other IPC mechanism. Then use that handle in
1539 the child (Win32API.pm provides ways to reconstitute Perl file
1540 handles from Win32 file handles).
1541 no support for subroutine subprocesses (CODE refs)
1543 Can't fork(), so the subroutines would have no context, and
1544 closures certainly have no meaning
1545 Perhaps with Win32 fork() emulation, this can be supported in a
1547 limited fashion, but there are other very serious problems with
1548 that: all parent fds get dup()ed in to the thread emulating the
1549 forked process, and that keeps the parent from being able to close
1550 all of the appropriate fds.
1551 no support for init => sub {} routines.
1553 Win32 processes are created from scratch, there is no way to do an
1554 init routine that will affect the running child. Some limited
1555 support might be implemented one day, do chdir() and %ENV changes
1556 can be made.
1557 signals
1559 Win32 does not fully support signals. signal() is likely to cause
1560 errors unless sending a signal that Perl emulates, and
1561 "kill_kill()" is immediately fatal (there is no grace period).
1562 helper processes
1564 IPC::Run uses helper processes, one per redirected file, to adapt
1565 between the anonymous pipe connected to the child and the TCP
1566 socket connected to the parent. This is a waste of resources and
1567 will change in the future to either use threads (instead of helper
1568 processes) or a WaitForMultipleObjects call (instead of select).
1569 Please contact me if you can help with the WaitForMultipleObjects()
1570 approach; I haven't figured out how to get at it without C code.
1571 shutdown pause
1573 There seems to be a pause of up to 1 second between when a child
1574 program exits and the corresponding sockets indicate that they are
1575 closed in the parent. Not sure why.
1576 binmode
1578 binmode is not supported yet. The underpinnings are implemented,
1579 just ask if you need it.
1580 IPC::Run::IO
1582 IPC::Run::IO objects can be used on Unix to read or write arbitrary
1583 files. On Win32, they will need to use the same helper processes
1584 to adapt from non-select()able filehandles to select()able ones (or
1585 perhaps WaitForMultipleObjects() will work with them, not sure).
1586 startup race conditions
1588 There seems to be an occasional race condition between child
1589 process startup and pipe closings. It seems like if the child is
1590 not fully created by the time CreateProcess returns and we close
1591 the TCP socket being handed to it, the parent socket can also get
1592 closed. This is seen with the Win32 pumper applications, not the
1593 "real" child process being spawned.
1594 I assume this is because the kernel hasn't gotten around to
1596 incrementing the reference count on the child's end (since the
1597 child was slow in starting), so the parent's closing of the child
1598 end causes the socket to be closed, thus closing the parent socket.
1599 Being a race condition, it's hard to reproduce, but I encountered
1601 it while testing this code on a drive share to a samba box. In
1602 this case, it takes t/run.t a long time to spawn it's child
1603 processes (the parent hangs in the first select for several seconds
1604 until the child emits any debugging output).
1605 I have not seen it on local drives, and can't reproduce it at will,
1607 unfortunately. The symptom is a "bad file descriptor in select()"
1608 error, and, by turning on debugging, it's possible to see that
1609 select() is being called on a no longer open file descriptor that
1610 was returned from the _socket() routine in Win32Helper. There's a
1611 new confess() that checks for this ("PARENT_HANDLE no longer
1612 open"), but I haven't been able to reproduce it (typically).
1613
1615 On Unix, requires a system that supports "waitpid( $pid, WNOHANG )" so
1616 it can tell if a child process is still running.
1617 PTYs don't seem to be non-blocking on some versions of Solaris. Here's
1619 a test script contributed by Borislav Deianov <borislav@ensim.com> to
1620 see if you have the problem. If it dies, you have the problem.
1621 #!/usr/bin/perl
1623 use IPC::Run qw(run);
1625 use Fcntl;
1626 use IO::Pty;
1627 sub makecmd {
1629 return ['perl', '-e',
1630 '<STDIN>, print "\n" x '.$_[0].'; while(<STDIN>){last if /end/}'];
1631 }
1632 #pipe R, W;
1634 #fcntl(W, F_SETFL, O_NONBLOCK);
1635 #while (syswrite(W, "\n", 1)) { $pipebuf++ };
1636 #print "pipe buffer size is $pipebuf\n";
1637 my $pipebuf=4096;
1638 my $in = "\n" x ($pipebuf * 2) . "end\n";
1639 my $out;
1640 $SIG{ALRM} = sub { die "Never completed!\n" };
1642 print "reading from scalar via pipe...";
1644 alarm( 2 );
1645 run(makecmd($pipebuf * 2), '<', \$in, '>', \$out);
1646 alarm( 0 );
1647 print "done\n";
1648 print "reading from code via pipe... ";
1650 alarm( 2 );
1651 run(makecmd($pipebuf * 3), '<', sub { $t = $in; undef $in; $t}, '>', \$out);
1652 alarm( 0 );
1653 print "done\n";
1654 $pty = IO::Pty->new();
1656 $pty->blocking(0);
1657 $slave = $pty->slave();
1658 while ($pty->syswrite("\n", 1)) { $ptybuf++ };
1659 print "pty buffer size is $ptybuf\n";
1660 $in = "\n" x ($ptybuf * 3) . "end\n";
1661 print "reading via pty... ";
1663 alarm( 2 );
1664 run(makecmd($ptybuf * 3), '<pty<', \$in, '>', \$out);
1665 alarm(0);
1666 print "done\n";
1667 No support for ';', '&&', '||', '{ ... }', etc: use perl's, since run()
1669 returns TRUE when the command exits with a 0 result code.
1670 Does not provide shell-like string interpolation.
1672 No support for "cd", "setenv", or "export": do these in an init() sub
1674 run(
1676 \cmd,
1677 ...
1678 init => sub {
1679 chdir $dir or die $!;
1680 $ENV{FOO}='BAR'
1681 }
1682 );
1683 Timeout calculation does not allow absolute times, or specification of
1685 days, months, etc.
1686 WARNING: Function coprocesses ("run \&foo, ...") suffer from two
1688 limitations. The first is that it is difficult to close all
1689 filehandles the child inherits from the parent, since there is no way
1690 to scan all open FILEHANDLEs in Perl and it both painful and a bit
1691 dangerous to close all open file descriptors with "POSIX::close()".
1692 Painful because we can't tell which fds are open at the POSIX level,
1693 either, so we'd have to scan all possible fds and close any that we
1694 don't want open (normally "exec()" closes any non-inheritable but we
1695 don't "exec()" for &sub processes.
1696 The second problem is that Perl's DESTROY subs and other on-exit
1698 cleanup gets run in the child process. If objects are instantiated in
1699 the parent before the child is forked, the DESTROY will get run once in
1700 the parent and once in the child. When coprocess subs exit,
1701 POSIX::_exit is called to work around this, but it means that objects
1702 that are still referred to at that time are not cleaned up. So setting
1703 package vars or closure vars to point to objects that rely on DESTROY
1704 to affect things outside the process (files, etc), will lead to bugs.
1705 I goofed on the syntax: "<pipe" vs. "<pty<" and ">filename" are both
1707 oddities.
1708
1710 Allow one harness to "adopt" another:
1711 $new_h = harness \@cmd2;
1712 $h->adopt( $new_h );
1713 Close all filehandles not explicitly marked to stay open.
1715 The problem with this one is that there's no good way to scan all
1716 open FILEHANDLEs in Perl, yet you don't want child processes
1717 inheriting handles willy-nilly.
1718
1720 Well, select() and waitpid() badly needed wrapping, and open3() isn't
1721 open-minded enough for me.
1722 The shell-like API inspired by a message Russ Allbery sent to
1724 perl5-porters, which included:
1725 I've thought for some time that it would be
1727 nice to have a module that could handle full Bourne shell pipe syntax
1728 internally, with fork and exec, without ever invoking a shell. Something
1729 that you could give things like:
1730 pipeopen (PIPE, [ qw/cat file/ ], '|', [ 'analyze', @args ], '>&3');
1732 Message ylln51p2b6.fsf@windlord.stanford.edu, on 2000/02/04.
1734
1736 Bugs should always be submitted via the GitHub bug tracker
1737 <https://github.com/toddr/IPC-Run/issues>
1739
1741 Adam Kennedy <adamk@cpan.org>
1742 Barrie Slaymaker <barries@slaysys.com>
1744
1746 Some parts copyright 2008 - 2009 Adam Kennedy.
1747 Copyright 1999 Barrie Slaymaker.
1749 You may distribute under the terms of either the GNU General Public
1751 License or the Artistic License, as specified in the README file.
1752perl v5.32.0 2020-07-28 IPC::Run(3)