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 released.
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 or
402 IPC::Run::Win32Process objects. On systems supporting fork(), Perl
403 code may be passed in as subs:
404 run \@cmd;
406 run \@cmd1, '|', \@cmd2;
407 run \@cmd1, '&', \@cmd2;
408 run \&sub1;
409 run \&sub1, '|', \&sub2;
410 run \&sub1, '&', \&sub2;
411 '|' pipes the stdout of \@cmd1 the stdin of \@cmd2, just like a shell
413 pipe. '&' does not. Child processes to the right of a '&' will have
414 their stdin closed unless it's redirected-to.
415 IPC::Run::IO objects may be passed in as well, whether or not child
417 processes are also specified:
418 run io( "infile", ">", \$in ), io( "outfile", "<", \$in );
420 as can IPC::Run::Timer objects:
422 run \@cmd, io( "outfile", "<", \$in ), timeout( 10 );
424 Commands may be followed by scalar, sub, or i/o handle references for
426 redirecting child process input & output:
427 run \@cmd, \undef, \$out;
429 run \@cmd, \$in, \$out;
430 run \@cmd1, \&in, '|', \@cmd2, \*OUT;
431 run \@cmd1, \*IN, '|', \@cmd2, \&out;
432 This is known as succinct redirection syntax, since run(), start() and
434 harness(), figure out which file descriptor to redirect and how. File
435 descriptor 0 is presumed to be an input for the child process, all
436 others are outputs. The assumed file descriptor always starts at 0,
437 unless the command is being piped to, in which case it starts at 1.
438 To be explicit about your redirects, or if you need to do more complex
440 things, there's also a redirection operator syntax:
441 run \@cmd, '<', \undef, '>', \$out;
443 run \@cmd, '<', \undef, '>&', \$out_and_err;
444 run(
445 \@cmd1,
446 '<', \$in,
447 '|', \@cmd2,
448 \$out
449 );
450 Operator syntax is required if you need to do something other than
452 simple redirection to/from scalars or subs, like duping or closing file
453 descriptors or redirecting to/from a named file. The operators are
454 covered in detail below.
455 After each \@cmd (or \&foo), parsing begins in succinct mode and
457 toggles to operator syntax mode when an operator (ie plain scalar, not
458 a ref) is seen. Once in operator syntax mode, parsing only reverts to
459 succinct mode when a '|' or '&' is seen.
460 In succinct mode, each parameter after the \@cmd specifies what to do
462 with the next highest file descriptor. These File descriptor start with
463 0 (stdin) unless stdin is being piped to ("'|', \@cmd"), in which case
464 they start with 1 (stdout). Currently, being on the left of a pipe
465 ("\@cmd, \$out, \$err, '|'") does not cause stdout to be skipped,
466 though this may change since it's not as DWIMerly as it could be. Only
467 stdin is assumed to be an input in succinct mode, all others are
468 assumed to be outputs.
469 If no piping or redirection is specified for a child, it will inherit
471 the parent's open file handles as dictated by your system's close-on-
472 exec behavior and the $^F flag, except that processes after a '&' will
473 not inherit the parent's stdin. Also note that $^F does not affect file
474 descriptors obtained via POSIX, since it only applies to full-fledged
475 Perl file handles. Such processes will have their stdin closed unless
476 it has been redirected-to.
477 If you want to close a child processes stdin, you may do any of:
479 run \@cmd, \undef;
481 run \@cmd, \"";
482 run \@cmd, '<&-';
483 run \@cmd, '0<&-';
484 Redirection is done by placing redirection specifications immediately
486 after a command or child subroutine:
487 run \@cmd1, \$in, '|', \@cmd2, \$out;
489 run \@cmd1, '<', \$in, '|', \@cmd2, '>', \$out;
490 If you omit the redirection operators, descriptors are counted starting
492 at 0. Descriptor 0 is assumed to be input, all others are outputs. A
493 leading '|' consumes descriptor 0, so this works as expected.
494 run \@cmd1, \$in, '|', \@cmd2, \$out;
496 The parameter following a redirection operator can be a scalar ref, a
498 subroutine ref, a file name, an open filehandle, or a closed
499 filehandle.
500 If it's a scalar ref, the child reads input from or sends output to
502 that variable:
503 $in = "Hello World.\n";
505 run \@cat, \$in, \$out;
506 print $out;
507 Scalars used in incremental (start()/pump()/finish()) applications are
509 treated as queues: input is removed from input scalers, resulting in
510 them dwindling to '', and output is appended to output scalars. This
511 is not true of harnesses run() in batch mode.
512 It's usually wise to append new input to be sent to the child to the
514 input queue, and you'll often want to zap output queues to '' before
515 pumping.
516 $h = start \@cat, \$in;
518 $in = "line 1\n";
519 pump $h;
520 $in .= "line 2\n";
521 pump $h;
522 $in .= "line 3\n";
523 finish $h;
524 The final call to finish() must be there: it allows the child
526 process(es) to run to completion and waits for their exit values.
527
529 Interactive applications are usually optimized for human use. This can
530 help or hinder trying to interact with them through modules like
531 IPC::Run. Frequently, programs alter their behavior when they detect
532 that stdin, stdout, or stderr are not connected to a tty, assuming that
533 they are being run in batch mode. Whether this helps or hurts depends
534 on which optimizations change. And there's often no way of telling
535 what a program does in these areas other than trial and error and
536 occasionally, reading the source. This includes different versions and
537 implementations of the same program.
538 All hope is not lost, however. Most programs behave in reasonably
540 tractable manners, once you figure out what it's trying to do.
541 Here are some of the issues you might need to be aware of.
543 • fflush()ing stdout and stderr
545 This lets the user see stdout and stderr immediately. Many
547 programs undo this optimization if stdout is not a tty, making them
548 harder to manage by things like IPC::Run.
549 Many programs decline to fflush stdout or stderr if they do not
551 detect a tty there. Some ftp commands do this, for instance.
552 If this happens to you, look for a way to force interactive
554 behavior, like a command line switch or command. If you can't, you
555 will need to use a pseudo terminal ('<pty<' and '>pty>').
556 • false prompts
558 Interactive programs generally do not guarantee that output from
560 user commands won't contain a prompt string. For example, your
561 shell prompt might be a '$', and a file named '$' might be the only
562 file in a directory listing.
563 This can make it hard to guarantee that your output parser won't be
565 fooled into early termination of results.
566 To help work around this, you can see if the program can alter it's
568 prompt, and use something you feel is never going to occur in
569 actual practice.
570 You should also look for your prompt to be the only thing on a
572 line:
573 pump $h until $out =~ /^<SILLYPROMPT>\s?\z/m;
575 (use "(?!\n)\Z" in place of "\z" on older perls).
577 You can also take the approach that IPC::ChildSafe takes and emit a
579 command with known output after each 'real' command you issue, then
580 look for this known output. See new_appender() and new_chunker()
581 for filters that can help with this task.
582 If it's not convenient or possibly to alter a prompt or use a known
584 command/response pair, you might need to autodetect the prompt in
585 case the local version of the child program is different then the
586 one you tested with, or if the user has control over the look &
587 feel of the prompt.
588 • Refusing to accept input unless stdin is a tty.
590 Some programs, for security reasons, will only accept certain types
592 of input from a tty. su, notable, will not prompt for a password
593 unless it's connected to a tty.
594 If this is your situation, use a pseudo terminal ('<pty<' and
596 '>pty>').
597 • Not prompting unless connected to a tty.
599 Some programs don't prompt unless stdin or stdout is a tty. See if
601 you can turn prompting back on. If not, see if you can come up
602 with a command that you can issue after every real command and look
603 for it's output, as IPC::ChildSafe does. There are two filters
604 included with IPC::Run that can help with doing this: appender and
605 chunker (see new_appender() and new_chunker()).
606 • Different output format when not connected to a tty.
608 Some commands alter their formats to ease machine parsability when
610 they aren't connected to a pipe. This is actually good, but can be
611 surprising.
612
614 On systems providing pseudo terminals under /dev, IPC::Run can use
615 IO::Pty (available on CPAN) to provide a terminal environment to
616 subprocesses. This is necessary when the subprocess really wants to
617 think it's connected to a real terminal.
618 CAVEATS
620 Pseudo-terminals are not pipes, though they are similar. Here are some
621 differences to watch out for.
622 Echoing
624 Sending to stdin will cause an echo on stdout, which occurs before
625 each line is passed to the child program. There is currently no
626 way to disable this, although the child process can and should
627 disable it for things like passwords.
628 Shutdown
630 IPC::Run cannot close a pty until all output has been collected.
631 This means that it is not possible to send an EOF to stdin by half-
632 closing the pty, as we can when using a pipe to stdin.
633 This means that you need to send the child process an exit command
635 or signal, or run() / finish() will time out. Be careful not to
636 expect a prompt after sending the exit command.
637 Command line editing
639 Some subprocesses, notable shells that depend on the user's prompt
640 settings, will reissue the prompt plus the command line input so
641 far once for each character.
642 '>pty>' means '&>pty>', not '1>pty>'
644 The pseudo terminal redirects both stdout and stderr unless you
645 specify a file descriptor. If you want to grab stderr separately,
646 do this:
647 start \@cmd, '<pty<', \$in, '>pty>', \$out, '2>', \$err;
649 stdin, stdout, and stderr not inherited
651 Child processes harnessed to a pseudo terminal have their stdin,
652 stdout, and stderr completely closed before any redirection
653 operators take effect. This casts of the bonds of the controlling
654 terminal. This is not done when using pipes.
655 Right now, this affects all children in a harness that has a pty in
657 use, even if that pty would not affect a particular child. That's
658 a bug and will be fixed. Until it is, it's best not to mix-and-
659 match children.
660 Redirection Operators
662 Operator SHNP Description
663 ======== ==== ===========
664 <, N< SHN Redirects input to a child's fd N (0 assumed)
665 >, N> SHN Redirects output from a child's fd N (1 assumed)
667 >>, N>> SHN Like '>', but appends to scalars or named files
668 >&, &> SHN Redirects stdout & stderr from a child process
669 <pty, N<pty S Like '<', but uses a pseudo-tty instead of a pipe
671 >pty, N>pty S Like '>', but uses a pseudo-tty instead of a pipe
672 N<&M Dups input fd N to input fd M
674 M>&N Dups output fd N to input fd M
675 N<&- Closes fd N
676 <pipe, N<pipe P Pipe opens H for caller to read, write, close.
678 >pipe, N>pipe P Pipe opens H for caller to read, write, close.
679 'N' and 'M' are placeholders for integer file descriptor numbers. The
681 terms 'input' and 'output' are from the child process's perspective.
682 The SHNP field indicates what parameters an operator can take:
684 S: \$scalar or \&function references. Filters may be used with
686 these operators (and only these).
687 H: \*HANDLE or IO::Handle for caller to open, and close
688 N: "file name".
689 P: \*HANDLE or lexical filehandle opened by IPC::Run as the parent end of a pipe, but read
690 and written to and closed by the caller (like IPC::Open3).
691 Redirecting input: [n]<, [n]<pipe
693 You can input the child reads on file descriptor number n to come
694 from a scalar variable, subroutine, file handle, or a named file.
695 If stdin is not redirected, the parent's stdin is inherited.
696 run \@cat, \undef ## Closes child's stdin immediately
698 or die "cat returned $?";
699 run \@cat, \$in;
701 run \@cat, \<<TOHERE;
703 blah
704 TOHERE
705 run \@cat, \&input; ## Calls &input, feeding data returned
707 ## to child's. Closes child's stdin
708 ## when undef is returned.
709 Redirecting from named files requires you to use the input
711 redirection operator:
712 run \@cat, '<.profile';
714 run \@cat, '<', '.profile';
715 open IN, "<foo";
717 run \@cat, \*IN;
718 run \@cat, *IN{IO};
719 The form used second example here is the safest, since filenames
721 like "0" and "&more\n" won't confuse &run:
722 You can't do either of
724 run \@a, *IN; ## INVALID
726 run \@a, '<', *IN; ## BUGGY: Reads file named like "*main::A"
727 because perl passes a scalar containing a string that looks like
729 "*main::A" to &run, and &run can't tell the difference between that
730 and a redirection operator or a file name. &run guarantees that
731 any scalar you pass after a redirection operator is a file name.
732 If your child process will take input from file descriptors other
734 than 0 (stdin), you can use a redirection operator with any of the
735 valid input forms (scalar ref, sub ref, etc.):
736 run \@cat, '3<', \$in3;
738 When redirecting input from a scalar ref, the scalar ref is used as
740 a queue. This allows you to use &harness and pump() to feed
741 incremental bits of input to a coprocess. See "Coprocesses" below
742 for more information.
743 The <pipe operator opens the write half of a pipe on the filehandle
745 glob reference it takes as an argument:
746 $h = start \@cat, '<pipe', \*IN;
748 print IN "hello world\n";
749 pump $h;
750 close IN;
751 finish $h;
752 Unlike the other '<' operators, IPC::Run does nothing further with
754 it: you are responsible for it. The previous example is
755 functionally equivalent to:
756 pipe( \*R, \*IN ) or die $!;
758 $h = start \@cat, '<', \*IN;
759 print IN "hello world\n";
760 pump $h;
761 close IN;
762 finish $h;
763 This is like the behavior of IPC::Open2 and IPC::Open3.
765 Win32: The handle returned is actually a socket handle, so you can
767 use select() on it.
768 Redirecting output: [n]>, [n]>>, [n]>&[m], [n]>pipe
770 You can redirect any output the child emits to a scalar variable,
771 subroutine, file handle, or file name. You can have &run truncate
772 or append to named files or scalars. If you are redirecting stdin
773 as well, or if the command is on the receiving end of a pipeline
774 ('|'), you can omit the redirection operator:
775 @ls = ( 'ls' );
777 run \@ls, \undef, \$out
778 or die "ls returned $?";
779 run \@ls, \undef, \&out; ## Calls &out each time some output
781 ## is received from the child's
782 ## when undef is returned.
783 run \@ls, \undef, '2>ls.err';
785 run \@ls, '2>', 'ls.err';
786 The two parameter form guarantees that the filename will not be
788 interpreted as a redirection operator:
789 run \@ls, '>', "&more";
791 run \@ls, '2>', ">foo\n";
792 You can pass file handles you've opened for writing:
794 open( *OUT, ">out.txt" );
796 open( *ERR, ">err.txt" );
797 run \@cat, \*OUT, \*ERR;
798 Passing a scalar reference and a code reference requires a little
800 more work, but allows you to capture all of the output in a scalar
801 or each piece of output by a callback:
802 These two do the same things:
804 run( [ 'ls' ], '2>', sub { $err_out .= $_[0] } );
806 does the same basic thing as:
808 run( [ 'ls' ], '2>', \$err_out );
810 The subroutine will be called each time some data is read from the
812 child.
813 The >pipe operator is different in concept than the other '>'
815 operators, although it's syntax is similar:
816 $h = start \@cat, $in, '>pipe', \*OUT, '2>pipe', \*ERR;
818 $in = "hello world\n";
819 finish $h;
820 print <OUT>;
821 print <ERR>;
822 close OUT;
823 close ERR;
824 causes two pipe to be created, with one end attached to cat's
826 stdout and stderr, respectively, and the other left open on OUT and
827 ERR, so that the script can manually read(), select(), etc. on
828 them. This is like the behavior of IPC::Open2 and IPC::Open3.
829 Win32: The handle returned is actually a socket handle, so you can
831 use select() on it.
832 Duplicating output descriptors: >&m, n>&m
834 This duplicates output descriptor number n (default is 1 if n is
835 omitted) from descriptor number m.
836 Duplicating input descriptors: <&m, n<&m
838 This duplicates input descriptor number n (default is 0 if n is
839 omitted) from descriptor number m
840 Closing descriptors: <&-, 3<&-
842 This closes descriptor number n (default is 0 if n is omitted).
843 The following commands are equivalent:
844 run \@cmd, \undef;
846 run \@cmd, '<&-';
847 run \@cmd, '<in.txt', '<&-';
848 Doing
850 run \@cmd, \$in, '<&-'; ## SIGPIPE recipe.
852 is dangerous: the parent will get a SIGPIPE if $in is not empty.
854 Redirecting both stdout and stderr: &>, >&, &>pipe, >pipe&
856 The following pairs of commands are equivalent:
857 run \@cmd, '>&', \$out; run \@cmd, '>', \$out, '2>&1';
859 run \@cmd, '>&', 'out.txt'; run \@cmd, '>', 'out.txt', '2>&1';
860 etc.
862 File descriptor numbers are not permitted to the left or the right
864 of these operators, and the '&' may occur on either end of the
865 operator.
866 The '&>pipe' and '>pipe&' variants behave like the '>pipe'
868 operator, except that both stdout and stderr write to the created
869 pipe.
870 Redirection Filters
872 Both input redirections and output redirections that use scalars or
873 subs as endpoints may have an arbitrary number of filter subs
874 placed between them and the child process. This is useful if you
875 want to receive output in chunks, or if you want to massage each
876 chunk of data sent to the child. To use this feature, you must use
877 operator syntax:
878 run(
880 \@cmd
881 '<', \&in_filter_2, \&in_filter_1, $in,
882 '>', \&out_filter_1, \&in_filter_2, $out,
883 );
884 This capability is not provided for IO handles or named files.
886 Two filters are provided by IPC::Run: appender and chunker.
888 Because these may take an argument, you need to use the constructor
889 functions new_appender() and new_chunker() rather than using \&
890 syntax:
891 run(
893 \@cmd
894 '<', new_appender( "\n" ), $in,
895 '>', new_chunker, $out,
896 );
897 Just doing I/O
899 If you just want to do I/O to a handle or file you open yourself, you
900 may specify a filehandle or filename instead of a command in the
901 harness specification:
902 run io( "filename", '>', \$recv );
904 $h = start io( $io, '>', \$recv );
906 $h = harness \@cmd, '&', io( "file", '<', \$send );
908 Options
910 Options are passed in as name/value pairs:
911 run \@cat, \$in, debug => 1;
913 If you pass the debug option, you may want to pass it in first, so you
915 can see what parsing is going on:
916 run debug => 1, \@cat, \$in;
918 debug
920 Enables debugging output in parent and child. Debugging info is
921 emitted to the STDERR that was present when IPC::Run was first
922 "use()"ed (it's "dup()"ed out of the way so that it can be
923 redirected in children without having debugging output emitted on
924 it).
925
927 harness() and start() return a reference to an IPC::Run harness. This
928 is blessed in to the IPC::Run package, so you may make later calls to
929 functions as members if you like:
930 $h = harness( ... );
932 $h->start;
933 $h->pump;
934 $h->finish;
935 $h = start( .... );
937 $h->pump;
938 ...
939 Of course, using method call syntax lets you deal with any IPC::Run
941 subclasses that might crop up, but don't hold your breath waiting for
942 any.
943 run() and finish() return TRUE when all subcommands exit with a 0
945 result code. This is the opposite of perl's system() command.
946 All routines raise exceptions (via die()) when error conditions are
948 recognized. A non-zero command result is not treated as an error
949 condition, since some commands are tests whose results are reported in
950 their exit codes.
951
953 run Run takes a harness or harness specification and runs it,
954 pumping all input to the child(ren), closing the input pipes
955 when no more input is available, collecting all output that
956 arrives, until the pipes delivering output are closed, then
957 waiting for the children to exit and reaping their result
958 codes.
959 You may think of "run( ... )" as being like
961 start( ... )->finish();
963 , though there is one subtle difference: run() does not set
965 \$input_scalars to '' like finish() does. If an exception is
966 thrown from run(), all children will be killed off "gently",
967 and then "annihilated" if they do not go gently (in to that
968 dark night. sorry).
969 If any exceptions are thrown, this does a "kill_kill" before
971 propagating them.
972 signal
974 ## To send it a specific signal by name ("USR1"):
975 signal $h, "USR1";
976 $h->signal ( "USR1" );
977 If $signal is provided and defined, sends a signal to all child
979 processes. Try not to send numeric signals, use "KILL" instead
980 of 9, for instance. Numeric signals aren't portable.
981 Throws an exception if $signal is undef.
983 This will not clean up the harness, "finish" it if you kill it.
985 Normally TERM kills a process gracefully (this is what the
987 command line utility "kill" does by default), INT is sent by
988 one of the keys "^C", "Backspace" or "<Del>", and "QUIT" is
989 used to kill a process and make it coredump.
990 The "HUP" signal is often used to get a process to "restart",
992 rereading config files, and "USR1" and "USR2" for really
993 application-specific things.
994 Often, running "kill -l" (that's a lower case "L") on the
996 command line will list the signals present on your operating
997 system.
998 WARNING: The signal subsystem is not at all portable. We *may*
1000 offer to simulate "TERM" and "KILL" on some operating systems,
1001 submit code to me if you want this.
1002 WARNING 2: Up to and including perl v5.6.1, doing almost
1004 anything in a signal handler could be dangerous. The most safe
1005 code avoids all mallocs and system calls, usually by
1006 preallocating a flag before entering the signal handler,
1007 altering the flag's value in the handler, and responding to the
1008 changed value in the main system:
1009 my $got_usr1 = 0;
1011 sub usr1_handler { ++$got_signal }
1012 $SIG{USR1} = \&usr1_handler;
1014 while () { sleep 1; print "GOT IT" while $got_usr1--; }
1015 Even this approach is perilous if ++ and -- aren't atomic on
1017 your system (I've never heard of this on any modern CPU large
1018 enough to run perl).
1019 kill_kill
1021 ## To kill off a process:
1022 $h->kill_kill;
1023 kill_kill $h;
1024 ## To specify the grace period other than 30 seconds:
1026 kill_kill $h, grace => 5;
1027 ## To send QUIT instead of KILL if a process refuses to die:
1029 kill_kill $h, coup_d_grace => "QUIT";
1030 Sends a "TERM", waits for all children to exit for up to 30
1032 seconds, then sends a "KILL" to any that survived the "TERM".
1033 Will wait for up to 30 more seconds for the OS to successfully
1035 "KILL" the processes.
1036 The 30 seconds may be overridden by setting the "grace" option,
1038 this overrides both timers.
1039 The harness is then cleaned up.
1041 The doubled name indicates that this function may kill again
1043 and avoids colliding with the core Perl "kill" function.
1044 Returns a 1 if the "TERM" was sufficient, or a 0 if "KILL" was
1046 required. Throws an exception if "KILL" did not permit the
1047 children to be reaped.
1048 NOTE: The grace period is actually up to 1 second longer than
1050 that given. This is because the granularity of "time" is 1
1051 second. Let me know if you need finer granularity, we can
1052 leverage Time::HiRes here.
1053 Win32: Win32 does not know how to send real signals, so "TERM"
1055 is a full-force kill on Win32. Thus all talk of grace periods,
1056 etc. do not apply to Win32.
1057 harness
1059 Takes a harness specification and returns a harness. This
1060 harness is blessed in to IPC::Run, allowing you to use method
1061 call syntax for run(), start(), et al if you like.
1062 harness() is provided so that you can pre-build harnesses if
1064 you would like to, but it's not required..
1065 You may proceed to run(), start() or pump() after calling
1067 harness() (pump() calls start() if need be). Alternatively,
1068 you may pass your harness specification to run() or start() and
1069 let them harness() for you. You can't pass harness
1070 specifications to pump(), though.
1071 close_terminal
1073 This is used as (or in) an init sub to cast off the bonds of a
1074 controlling terminal. It must precede all other redirection
1075 ops that affect STDIN, STDOUT, or STDERR to be guaranteed
1076 effective.
1077 start
1079 $h = start(
1080 \@cmd, \$in, \$out, ...,
1081 timeout( 30, name => "process timeout" ),
1082 $stall_timeout = timeout( 10, name => "stall timeout" ),
1083 );
1084 $h = start \@cmd, '<', \$in, '|', \@cmd2, ...;
1086 start() accepts a harness or harness specification and returns
1088 a harness after building all of the pipes and launching (via
1089 fork()/exec(), or, maybe someday, spawn()) all the child
1090 processes. It does not send or receive any data on the pipes,
1091 see pump() and finish() for that.
1092 You may call harness() and then pass it's result to start() if
1094 you like, but you only need to if it helps you structure or
1095 tune your application. If you do call harness(), you may skip
1096 start() and proceed directly to pump.
1097 start() also starts all timers in the harness. See
1099 IPC::Run::Timer for more information.
1100 start() flushes STDOUT and STDERR to help you avoid duplicate
1102 output. It has no way of asking Perl to flush all your open
1103 filehandles, so you are going to need to flush any others you
1104 have open. Sorry.
1105 Here's how if you don't want to alter the state of $| for your
1107 filehandle:
1108 $ofh = select HANDLE; $of = $|; $| = 1; $| = $of; select $ofh;
1110 If you don't mind leaving output unbuffered on HANDLE, you can
1112 do the slightly shorter
1113 $ofh = select HANDLE; $| = 1; select $ofh;
1115 Or, you can use IO::Handle's flush() method:
1117 use IO::Handle;
1119 flush HANDLE;
1120 Perl needs the equivalent of C's fflush( (FILE *)NULL ).
1122 adopt
1124 Experimental feature. NOT FUNCTIONAL YET, NEED TO CLOSE FDS
1125 BETTER IN CHILDREN. SEE t/adopt.t for a test suite.
1126 pump
1128 pump $h;
1129 $h->pump;
1130 Pump accepts a single parameter harness. It blocks until it
1132 delivers some input or receives some output. It returns TRUE
1133 if there is still input or output to be done, FALSE otherwise.
1134 pump() will automatically call start() if need be, so you may
1136 call harness() then proceed to pump() if that helps you
1137 structure your application.
1138 If pump() is called after all harnessed activities have
1140 completed, a "process ended prematurely" exception to be
1141 thrown. This allows for simple scripting of external
1142 applications without having to add lots of error handling code
1143 at each step of the script:
1144 $h = harness \@smbclient, \$in, \$out, $err;
1146 $in = "cd /foo\n";
1148 $h->pump until $out =~ /^smb.*> \Z/m;
1149 die "error cding to /foo:\n$out" if $out =~ "ERR";
1150 $out = '';
1151 $in = "mget *\n";
1153 $h->pump until $out =~ /^smb.*> \Z/m;
1154 die "error retrieving files:\n$out" if $out =~ "ERR";
1155 $h->finish;
1157 warn $err if $err;
1159 pump_nb
1161 pump_nb $h;
1162 $h->pump_nb;
1163 "pump() non-blocking", pumps if anything's ready to be pumped,
1165 returns immediately otherwise. This is useful if you're doing
1166 some long-running task in the foreground, but don't want to
1167 starve any child processes.
1168 pumpable
1170 Returns TRUE if calling pump() won't throw an immediate
1171 "process ended prematurely" exception. This means that there
1172 are open I/O channels or active processes. May yield the parent
1173 processes' time slice for 0.01 second if all pipes are to the
1174 child and all are paused. In this case we can't tell if the
1175 child is dead, so we yield the processor and then attempt to
1176 reap the child in a nonblocking way.
1177 reap_nb
1179 Attempts to reap child processes, but does not block.
1180 Does not currently take any parameters, one day it will allow
1182 specific children to be reaped.
1183 Only call this from a signal handler if your "perl" is recent
1185 enough to have safe signal handling (5.6.1 did not, IIRC, but
1186 it was being discussed on perl5-porters). Calling this (or
1187 doing any significant work) in a signal handler on older
1188 "perl"s is asking for seg faults.
1189 finish
1191 This must be called after the last start() or pump() call for a
1192 harness, or your system will accumulate defunct processes and
1193 you may "leak" file descriptors.
1194 finish() returns TRUE if all children returned 0 (and were not
1196 signaled and did not coredump, ie ! $?), and FALSE otherwise
1197 (this is like run(), and the opposite of system()).
1198 Once a harness has been finished, it may be run() or start()ed
1200 again, including by pump()s auto-start.
1201 If this throws an exception rather than a normal exit, the
1203 harness may be left in an unstable state, it's best to kill the
1204 harness to get rid of all the child processes, etc.
1205 Specifically, if a timeout expires in finish(), finish() will
1207 not kill all the children. Call "<$h-"kill_kill>> in this case
1208 if you care. This differs from the behavior of "run".
1209 result
1211 $h->result;
1212 Returns the first non-zero result code (ie $? >> 8). See
1214 "full_result" to get the $? value for a child process.
1215 To get the result of a particular child, do:
1217 $h->result( 0 ); # first child's $? >> 8
1219 $h->result( 1 ); # second child
1220 or
1222 ($h->results)[0]
1224 ($h->results)[1]
1225 Returns undef if no child processes were spawned and no child
1227 number was specified. Throws an exception if an out-of-range
1228 child number is passed.
1229 results
1231 Returns a list of child exit values. See "full_results" if you
1232 want to know if a signal killed the child.
1233 Throws an exception if the harness is not in a finished state.
1235 full_result
1237 $h->full_result;
1238 Returns the first non-zero $?. See "result" to get the first
1240 $? >> 8 value for a child process.
1241 To get the result of a particular child, do:
1243 $h->full_result( 0 ); # first child's $?
1245 $h->full_result( 1 ); # second child
1246 or
1248 ($h->full_results)[0]
1250 ($h->full_results)[1]
1251 Returns undef if no child processes were spawned and no child
1253 number was specified. Throws an exception if an out-of-range
1254 child number is passed.
1255 full_results
1257 Returns a list of child exit values as returned by "wait". See
1258 "results" if you don't care about coredumps or signals.
1259 Throws an exception if the harness is not in a finished state.
1261
1263 These filters are used to modify input our output between a child
1264 process and a scalar or subroutine endpoint.
1265 binary
1267 run \@cmd, ">", binary, \$out;
1268 run \@cmd, ">", binary, \$out; ## Any TRUE value to enable
1269 run \@cmd, ">", binary 0, \$out; ## Any FALSE value to disable
1270 This is a constructor for a "binmode" "filter" that tells IPC::Run
1272 to keep the carriage returns that would ordinarily be edited out
1273 for you (binmode is usually off). This is not a real filter, but
1274 an option masquerading as a filter.
1275 It's not named "binmode" because you're likely to want to call
1277 Perl's binmode in programs that are piping binary data around.
1278 new_chunker
1280 This breaks a stream of data in to chunks, based on an optional
1281 scalar or regular expression parameter. The default is the Perl
1282 input record separator in $/, which is a newline be default.
1283 run \@cmd, '>', new_chunker, \&lines_handler;
1285 run \@cmd, '>', new_chunker( "\r\n" ), \&lines_handler;
1286 Because this uses $/ by default, you should always pass in a
1288 parameter if you are worried about other code (modules, etc)
1289 modifying $/.
1290 If this filter is last in a filter chain that dumps in to a scalar,
1292 the scalar must be set to '' before a new chunk will be written to
1293 it.
1294 As an example of how a filter like this can be written, here's a
1296 chunker that splits on newlines:
1297 sub line_splitter {
1299 my ( $in_ref, $out_ref ) = @_;
1300 return 0 if length $$out_ref;
1302 return input_avail && do {
1304 while (1) {
1305 if ( $$in_ref =~ s/\A(.*?\n)// ) {
1306 $$out_ref .= $1;
1307 return 1;
1308 }
1309 my $hmm = get_more_input;
1310 unless ( defined $hmm ) {
1311 $$out_ref = $$in_ref;
1312 $$in_ref = '';
1313 return length $$out_ref ? 1 : 0;
1314 }
1315 return 0 if $hmm eq 0;
1316 }
1317 }
1318 };
1319 new_appender
1321 This appends a fixed string to each chunk of data read from the
1322 source scalar or sub. This might be useful if you're writing
1323 commands to a child process that always must end in a fixed string,
1324 like "\n":
1325 run( \@cmd,
1327 '<', new_appender( "\n" ), \&commands,
1328 );
1329 Here's a typical filter sub that might be created by
1331 new_appender():
1332 sub newline_appender {
1334 my ( $in_ref, $out_ref ) = @_;
1335 return input_avail && do {
1337 $$out_ref = join( '', $$out_ref, $$in_ref, "\n" );
1338 $$in_ref = '';
1339 1;
1340 }
1341 };
1342 new_string_source
1344 TODO: Needs confirmation. Was previously undocumented. in this
1345 module.
1346 This is a filter which is exportable. Returns a sub which appends
1348 the data passed in to the output buffer and returns 1 if data was
1349 appended. 0 if it was an empty string and undef if no data was
1350 passed.
1351 NOTE: Any additional variables passed to new_string_source will be
1353 passed to the sub every time it's called and appended to the
1354 output.
1355 new_string_sink
1357 TODO: Needs confirmation. Was previously undocumented.
1358 This is a filter which is exportable. Returns a sub which pops the
1360 data out of the input stream and pushes it onto the string.
1361 io Takes a filename or filehandle, a redirection operator, optional
1363 filters, and a source or destination (depends on the redirection
1364 operator). Returns an IPC::Run::IO object suitable for
1365 harness()ing (including via start() or run()).
1366 This is shorthand for
1368 require IPC::Run::IO;
1370 ... IPC::Run::IO->new(...) ...
1372 timer
1374 $h = start( \@cmd, \$in, \$out, $t = timer( 5 ) );
1375 pump $h until $out =~ /expected stuff/ || $t->is_expired;
1377 Instantiates a non-fatal timer. pump() returns once each time a
1379 timer expires. Has no direct effect on run(), but you can pass a
1380 subroutine to fire when the timer expires.
1381 See "timeout" for building timers that throw exceptions on
1383 expiration.
1384 See "timer" in IPC::Run::Timer for details.
1386 timeout
1388 $h = start( \@cmd, \$in, \$out, $t = timeout( 5 ) );
1389 pump $h until $out =~ /expected stuff/;
1391 Instantiates a timer that throws an exception when it expires. If
1393 you don't provide an exception, a default exception that matches
1394 /^IPC::Run: .*timed out/ is thrown by default. You can pass in
1395 your own exception scalar or reference:
1396 $h = start(
1398 \@cmd, \$in, \$out,
1399 $t = timeout( 5, exception => 'slowpoke' ),
1400 );
1401 or set the name used in debugging message and in the default
1403 exception string:
1404 $h = start(
1406 \@cmd, \$in, \$out,
1407 timeout( 50, name => 'process timer' ),
1408 $stall_timer = timeout( 5, name => 'stall timer' ),
1409 );
1410 pump $h until $out =~ /started/;
1412 $in = 'command 1';
1414 $stall_timer->start;
1415 pump $h until $out =~ /command 1 finished/;
1416 $in = 'command 2';
1418 $stall_timer->start;
1419 pump $h until $out =~ /command 2 finished/;
1420 $in = 'very slow command 3';
1422 $stall_timer->start( 10 );
1423 pump $h until $out =~ /command 3 finished/;
1424 $stall_timer->start( 5 );
1426 $in = 'command 4';
1427 pump $h until $out =~ /command 4 finished/;
1428 $stall_timer->reset; # Prevent restarting or expirng
1430 finish $h;
1431 See "timer" for building non-fatal timers.
1433 See "timer" in IPC::Run::Timer for details.
1435
1437 These functions are for use from within filters.
1438 input_avail
1440 Returns TRUE if input is available. If none is available, then
1441 &get_more_input is called and its result is returned.
1442 This is usually used in preference to &get_more_input so that the
1444 calling filter removes all data from the $in_ref before more data
1445 gets read in to $in_ref.
1446 "input_avail" is usually used as part of a return expression:
1448 return input_avail && do {
1450 ## process the input just gotten
1451 1;
1452 };
1453 This technique allows input_avail to return the undef or 0 that a
1455 filter normally returns when there's no input to process. If a
1456 filter stores intermediate values, however, it will need to react
1457 to an undef:
1458 my $got = input_avail;
1460 if ( ! defined $got ) {
1461 ## No more input ever, flush internal buffers to $out_ref
1462 }
1463 return $got unless $got;
1464 ## Got some input, move as much as need be
1465 return 1 if $added_to_out_ref;
1466 get_more_input
1468 This is used to fetch more input in to the input variable. It
1469 returns undef if there will never be any more input, 0 if there is
1470 none now, but there might be in the future, and TRUE if more input
1471 was gotten.
1472 "get_more_input" is usually used as part of a return expression,
1474 see "input_avail" for more information.
1475
1477 These will be addressed as needed and as time allows.
1478 Stall timeout.
1480 Expose a list of child process objects. When I do this, each child
1482 process is likely to be blessed into IPC::Run::Proc.
1483 $kid->abort(), $kid->kill(), $kid->signal( $num_or_name ).
1485 Write tests for /(full_)?results?/ subs.
1487 Currently, pump() and run() only work on systems where select() works
1489 on the filehandles returned by pipe(). This does *not* include
1490 ActiveState on Win32, although it does work on cygwin under Win32
1491 (thought the tests whine a bit). I'd like to rectify that, suggestions
1492 and patches welcome.
1493 Likewise start() only fully works on fork()/exec() machines (well, just
1495 fork() if you only ever pass perl subs as subprocesses). There's some
1496 scaffolding for calling Open3::spawn_with_handles(), but that's
1497 untested, and not that useful with limited select().
1498 Support for "\@sub_cmd" as an argument to a command which gets replaced
1500 with /dev/fd or the name of a temporary file containing foo's output.
1501 This is like <(sub_cmd ...) found in bash and csh (IIRC).
1502 Allow multiple harnesses to be combined as independent sets of
1504 processes in to one 'meta-harness'.
1505 Allow a harness to be passed in place of an \@cmd. This would allow
1507 multiple harnesses to be aggregated.
1508 Ability to add external file descriptors w/ filter chains and
1510 endpoints.
1511 Ability to add timeouts and timing generators (i.e. repeating
1513 timeouts).
1514 High resolution timeouts.
1516
1518 argument-passing rules are program-specific
1519 Win32 programs receive all arguments in a single "command line"
1520 string. IPC::Run assembles this string so programs using standard
1521 command line parsing rules <https://docs.microsoft.com/en-
1522 us/cpp/cpp/main-function-command-line-args#parsing-c-command-line-
1523 arguments> will see an "argv" that matches the array reference
1524 specifying the command. Some programs use different rules to parse
1525 their command line. Notable examples include cmd.exe, cscript.exe,
1526 and Cygwin programs called from non-Cygwin programs. Use
1527 IPC::Run::Win32Process to call these and other nonstandard
1528 programs.
1529 batch files
1531 Properly escaping a batch file argument depends on how the script
1532 will use that argument, because some uses experience multiple
1533 levels of caret (escape character) removal. Avoid calling batch
1534 files with arguments, particularly when the argument values
1535 originate outside your program or contain non-alphanumeric
1536 characters. Perl scripts and PowerShell scripts are sound
1537 alternatives. If you do use batch file arguments, IPC::Run escapes
1538 them so the batch file can pass them, unquoted, to a program having
1539 standard command line parsing rules. If the batch file enables
1540 delayed environment variable expansion, it must disable that
1541 feature before expanding its arguments. For example, if foo.cmd
1542 contains "perl %*", "run ['foo.cmd', @list]" will create a Perl
1543 process in which @ARGV matches @list. Prepending a "setlocal
1544 enabledelayedexpansion" line would make the batch file malfunction,
1545 silently. Another silent-malfunction example is "run ['outer.bat',
1546 @list]" for outer.bat containing "foo.cmd %*".
1547 Fails on Win9X
1549 If you want Win9X support, you'll have to debug it or fund me
1550 because I don't use that system any more. The Win32 subsysem has
1551 been extended to use temporary files in simple run() invocations
1552 and these may actually work on Win9X too, but I don't have time to
1553 work on it.
1554 May deadlock on Win2K (but not WinNT4 or WinXPPro)
1556 Spawning more than one subprocess on Win2K causes a deadlock I
1557 haven't figured out yet, but simple uses of run() often work.
1558 Passes all tests on WinXPPro and WinNT.
1559 no support yet for <pty< and >pty>
1561 These are likely to be implemented as "<" and ">" with binmode on,
1562 not sure.
1563 no support for file descriptors higher than 2 (stderr)
1565 Win32 only allows passing explicit fds 0, 1, and 2. If you really,
1566 really need to pass file handles, us Win32API:: GetOsFHandle() or
1567 ::FdGetOsFHandle() to get the integer handle and pass it to the
1568 child process using the command line, environment, stdin,
1569 intermediary file, or other IPC mechanism. Then use that handle in
1570 the child (Win32API.pm provides ways to reconstitute Perl file
1571 handles from Win32 file handles).
1572 no support for subroutine subprocesses (CODE refs)
1574 Can't fork(), so the subroutines would have no context, and
1575 closures certainly have no meaning
1576 Perhaps with Win32 fork() emulation, this can be supported in a
1578 limited fashion, but there are other very serious problems with
1579 that: all parent fds get dup()ed in to the thread emulating the
1580 forked process, and that keeps the parent from being able to close
1581 all of the appropriate fds.
1582 no support for init => sub {} routines.
1584 Win32 processes are created from scratch, there is no way to do an
1585 init routine that will affect the running child. Some limited
1586 support might be implemented one day, do chdir() and %ENV changes
1587 can be made.
1588 signals
1590 Win32 does not fully support signals. signal() is likely to cause
1591 errors unless sending a signal that Perl emulates, and
1592 "kill_kill()" is immediately fatal (there is no grace period).
1593 helper processes
1595 IPC::Run uses helper processes, one per redirected file, to adapt
1596 between the anonymous pipe connected to the child and the TCP
1597 socket connected to the parent. This is a waste of resources and
1598 will change in the future to either use threads (instead of helper
1599 processes) or a WaitForMultipleObjects call (instead of select).
1600 Please contact me if you can help with the WaitForMultipleObjects()
1601 approach; I haven't figured out how to get at it without C code.
1602 shutdown pause
1604 There seems to be a pause of up to 1 second between when a child
1605 program exits and the corresponding sockets indicate that they are
1606 closed in the parent. Not sure why.
1607 binmode
1609 binmode is not supported yet. The underpinnings are implemented,
1610 just ask if you need it.
1611 IPC::Run::IO
1613 IPC::Run::IO objects can be used on Unix to read or write arbitrary
1614 files. On Win32, they will need to use the same helper processes
1615 to adapt from non-select()able filehandles to select()able ones (or
1616 perhaps WaitForMultipleObjects() will work with them, not sure).
1617 startup race conditions
1619 There seems to be an occasional race condition between child
1620 process startup and pipe closings. It seems like if the child is
1621 not fully created by the time CreateProcess returns and we close
1622 the TCP socket being handed to it, the parent socket can also get
1623 closed. This is seen with the Win32 pumper applications, not the
1624 "real" child process being spawned.
1625 I assume this is because the kernel hasn't gotten around to
1627 incrementing the reference count on the child's end (since the
1628 child was slow in starting), so the parent's closing of the child
1629 end causes the socket to be closed, thus closing the parent socket.
1630 Being a race condition, it's hard to reproduce, but I encountered
1632 it while testing this code on a drive share to a samba box. In
1633 this case, it takes t/run.t a long time to spawn it's child
1634 processes (the parent hangs in the first select for several seconds
1635 until the child emits any debugging output).
1636 I have not seen it on local drives, and can't reproduce it at will,
1638 unfortunately. The symptom is a "bad file descriptor in select()"
1639 error, and, by turning on debugging, it's possible to see that
1640 select() is being called on a no longer open file descriptor that
1641 was returned from the _socket() routine in Win32Helper. There's a
1642 new confess() that checks for this ("PARENT_HANDLE no longer
1643 open"), but I haven't been able to reproduce it (typically).
1644
1646 On Unix, requires a system that supports "waitpid( $pid, WNOHANG )" so
1647 it can tell if a child process is still running.
1648 PTYs don't seem to be non-blocking on some versions of Solaris. Here's
1650 a test script contributed by Borislav Deianov <borislav@ensim.com> to
1651 see if you have the problem. If it dies, you have the problem.
1652 #!/usr/bin/perl
1654 use IPC::Run qw(run);
1656 use Fcntl;
1657 use IO::Pty;
1658 sub makecmd {
1660 return ['perl', '-e',
1661 '<STDIN>, print "\n" x '.$_[0].'; while(<STDIN>){last if /end/}'];
1662 }
1663 #pipe R, W;
1665 #fcntl(W, F_SETFL, O_NONBLOCK);
1666 #while (syswrite(W, "\n", 1)) { $pipebuf++ };
1667 #print "pipe buffer size is $pipebuf\n";
1668 my $pipebuf=4096;
1669 my $in = "\n" x ($pipebuf * 2) . "end\n";
1670 my $out;
1671 $SIG{ALRM} = sub { die "Never completed!\n" };
1673 print "reading from scalar via pipe...";
1675 alarm( 2 );
1676 run(makecmd($pipebuf * 2), '<', \$in, '>', \$out);
1677 alarm( 0 );
1678 print "done\n";
1679 print "reading from code via pipe... ";
1681 alarm( 2 );
1682 run(makecmd($pipebuf * 3), '<', sub { $t = $in; undef $in; $t}, '>', \$out);
1683 alarm( 0 );
1684 print "done\n";
1685 $pty = IO::Pty->new();
1687 $pty->blocking(0);
1688 $slave = $pty->slave();
1689 while ($pty->syswrite("\n", 1)) { $ptybuf++ };
1690 print "pty buffer size is $ptybuf\n";
1691 $in = "\n" x ($ptybuf * 3) . "end\n";
1692 print "reading via pty... ";
1694 alarm( 2 );
1695 run(makecmd($ptybuf * 3), '<pty<', \$in, '>', \$out);
1696 alarm(0);
1697 print "done\n";
1698 No support for ';', '&&', '||', '{ ... }', etc: use perl's, since run()
1700 returns TRUE when the command exits with a 0 result code.
1701 Does not provide shell-like string interpolation.
1703 No support for "cd", "setenv", or "export": do these in an init() sub
1705 run(
1707 \cmd,
1708 ...
1709 init => sub {
1710 chdir $dir or die $!;
1711 $ENV{FOO}='BAR'
1712 }
1713 );
1714 Timeout calculation does not allow absolute times, or specification of
1716 days, months, etc.
1717 WARNING: Function coprocesses ("run \&foo, ...") suffer from two
1719 limitations. The first is that it is difficult to close all
1720 filehandles the child inherits from the parent, since there is no way
1721 to scan all open FILEHANDLEs in Perl and it both painful and a bit
1722 dangerous to close all open file descriptors with "POSIX::close()".
1723 Painful because we can't tell which fds are open at the POSIX level,
1724 either, so we'd have to scan all possible fds and close any that we
1725 don't want open (normally "exec()" closes any non-inheritable but we
1726 don't "exec()" for &sub processes.
1727 The second problem is that Perl's DESTROY subs and other on-exit
1729 cleanup gets run in the child process. If objects are instantiated in
1730 the parent before the child is forked, the DESTROY will get run once in
1731 the parent and once in the child. When coprocess subs exit,
1732 POSIX::_exit is called to work around this, but it means that objects
1733 that are still referred to at that time are not cleaned up. So setting
1734 package vars or closure vars to point to objects that rely on DESTROY
1735 to affect things outside the process (files, etc), will lead to bugs.
1736 I goofed on the syntax: "<pipe" vs. "<pty<" and ">filename" are both
1738 oddities.
1739
1741 Allow one harness to "adopt" another:
1742 $new_h = harness \@cmd2;
1743 $h->adopt( $new_h );
1744 Close all filehandles not explicitly marked to stay open.
1746 The problem with this one is that there's no good way to scan all
1747 open FILEHANDLEs in Perl, yet you don't want child processes
1748 inheriting handles willy-nilly.
1749
1751 Well, select() and waitpid() badly needed wrapping, and open3() isn't
1752 open-minded enough for me.
1753 The shell-like API inspired by a message Russ Allbery sent to
1755 perl5-porters, which included:
1756 I've thought for some time that it would be
1758 nice to have a module that could handle full Bourne shell pipe syntax
1759 internally, with fork and exec, without ever invoking a shell. Something
1760 that you could give things like:
1761 pipeopen (PIPE, [ qw/cat file/ ], '|', [ 'analyze', @args ], '>&3');
1763 Message ylln51p2b6.fsf@windlord.stanford.edu, on 2000/02/04.
1765
1767 Bugs should always be submitted via the GitHub bug tracker
1768 <https://github.com/toddr/IPC-Run/issues>
1770
1772 Adam Kennedy <adamk@cpan.org>
1773 Barrie Slaymaker <barries@slaysys.com>
1775
1777 Some parts copyright 2008 - 2009 Adam Kennedy.
1778 Copyright 1999 Barrie Slaymaker.
1780 You may distribute under the terms of either the GNU General Public
1782 License or the Artistic License, as specified in the README file.
1783perl v5.36.0 2022-08-07 IPC::Run(3)