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 scalars
239 it appends data to, so we could modify the above so as not to destroy
240 $out by adding a couple of "/gc" modifiers. The "/g" keeps us from
241 tripping over the previous prompt and the "/c" keeps us from resetting
242 the prior match position if the expected prompt doesn't materialize
243 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 redirected
923 in children without having debugging output emitted on 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 argument-passing rules are program-specific
1518 Win32 programs receive all arguments in a single "command line"
1519 string. IPC::Run assembles this string so programs using standard
1520 command line parsing rules <https://docs.microsoft.com/en-
1521 us/cpp/cpp/main-function-command-line-args#parsing-c-command-line-
1522 arguments> will see an "argv" that matches the array reference
1523 specifying the command. Some programs use different rules to parse
1524 their command line. Notable examples include cmd.exe, cscript.exe,
1525 and Cygwin programs called from non-Cygwin programs. Use
1526 IPC::Run::Win32Process to call these and other nonstandard
1527 programs.
1528 batch files
1530 Properly escaping a batch file argument depends on how the script
1531 will use that argument, because some uses experience multiple
1532 levels of caret (escape character) removal. Avoid calling batch
1533 files with arguments, particularly when the argument values
1534 originate outside your program or contain non-alphanumeric
1535 characters. Perl scripts and PowerShell scripts are sound
1536 alternatives. If you do use batch file arguments, IPC::Run escapes
1537 them so the batch file can pass them, unquoted, to a program having
1538 standard command line parsing rules. If the batch file enables
1539 delayed environment variable expansion, it must disable that
1540 feature before expanding its arguments. For example, if foo.cmd
1541 contains "perl %*", "run ['foo.cmd', @list]" will create a Perl
1542 process in which @ARGV matches @list. Prepending a "setlocal
1543 enabledelayedexpansion" line would make the batch file malfunction,
1544 silently. Another silent-malfunction example is "run ['outer.bat',
1545 @list]" for outer.bat containing "foo.cmd %*".
1546 Fails on Win9X
1548 If you want Win9X support, you'll have to debug it or fund me
1549 because I don't use that system any more. The Win32 subsysem has
1550 been extended to use temporary files in simple run() invocations
1551 and these may actually work on Win9X too, but I don't have time to
1552 work on it.
1553 May deadlock on Win2K (but not WinNT4 or WinXPPro)
1555 Spawning more than one subprocess on Win2K causes a deadlock I
1556 haven't figured out yet, but simple uses of run() often work.
1557 Passes all tests on WinXPPro and WinNT.
1558 no support yet for <pty< and >pty>
1560 These are likely to be implemented as "<" and ">" with binmode on,
1561 not sure.
1562 no support for file descriptors higher than 2 (stderr)
1564 Win32 only allows passing explicit fds 0, 1, and 2. If you really,
1565 really need to pass file handles, us Win32API:: GetOsFHandle() or
1566 ::FdGetOsFHandle() to get the integer handle and pass it to the
1567 child process using the command line, environment, stdin,
1568 intermediary file, or other IPC mechanism. Then use that handle in
1569 the child (Win32API.pm provides ways to reconstitute Perl file
1570 handles from Win32 file handles).
1571 no support for subroutine subprocesses (CODE refs)
1573 Can't fork(), so the subroutines would have no context, and
1574 closures certainly have no meaning
1575 Perhaps with Win32 fork() emulation, this can be supported in a
1577 limited fashion, but there are other very serious problems with
1578 that: all parent fds get dup()ed in to the thread emulating the
1579 forked process, and that keeps the parent from being able to close
1580 all of the appropriate fds.
1581 no support for init => sub {} routines.
1583 Win32 processes are created from scratch, there is no way to do an
1584 init routine that will affect the running child. Some limited
1585 support might be implemented one day, do chdir() and %ENV changes
1586 can be made.
1587 signals
1589 Win32 does not fully support signals. signal() is likely to cause
1590 errors unless sending a signal that Perl emulates, and kill_kill()
1591 is immediately fatal (there is no grace period).
1592 helper processes
1594 IPC::Run uses helper processes, one per redirected file, to adapt
1595 between the anonymous pipe connected to the child and the TCP
1596 socket connected to the parent. This is a waste of resources and
1597 will change in the future to either use threads (instead of helper
1598 processes) or a WaitForMultipleObjects call (instead of select).
1599 Please contact me if you can help with the WaitForMultipleObjects()
1600 approach; I haven't figured out how to get at it without C code.
1601 shutdown pause
1603 There seems to be a pause of up to 1 second between when a child
1604 program exits and the corresponding sockets indicate that they are
1605 closed in the parent. Not sure why.
1606 binmode
1608 binmode is not supported yet. The underpinnings are implemented,
1609 just ask if you need it.
1610 IPC::Run::IO
1612 IPC::Run::IO objects can be used on Unix to read or write arbitrary
1613 files. On Win32, they will need to use the same helper processes
1614 to adapt from non-select()able filehandles to select()able ones (or
1615 perhaps WaitForMultipleObjects() will work with them, not sure).
1616 startup race conditions
1618 There seems to be an occasional race condition between child
1619 process startup and pipe closings. It seems like if the child is
1620 not fully created by the time CreateProcess returns and we close
1621 the TCP socket being handed to it, the parent socket can also get
1622 closed. This is seen with the Win32 pumper applications, not the
1623 "real" child process being spawned.
1624 I assume this is because the kernel hasn't gotten around to
1626 incrementing the reference count on the child's end (since the
1627 child was slow in starting), so the parent's closing of the child
1628 end causes the socket to be closed, thus closing the parent socket.
1629 Being a race condition, it's hard to reproduce, but I encountered
1631 it while testing this code on a drive share to a samba box. In
1632 this case, it takes t/run.t a long time to spawn it's child
1633 processes (the parent hangs in the first select for several seconds
1634 until the child emits any debugging output).
1635 I have not seen it on local drives, and can't reproduce it at will,
1637 unfortunately. The symptom is a "bad file descriptor in select()"
1638 error, and, by turning on debugging, it's possible to see that
1639 select() is being called on a no longer open file descriptor that
1640 was returned from the _socket() routine in Win32Helper. There's a
1641 new confess() that checks for this ("PARENT_HANDLE no longer
1642 open"), but I haven't been able to reproduce it (typically).
1643
1645 On Unix, requires a system that supports "waitpid( $pid, WNOHANG )" so
1646 it can tell if a child process is still running.
1647 PTYs don't seem to be non-blocking on some versions of Solaris. Here's
1649 a test script contributed by Borislav Deianov <borislav@ensim.com> to
1650 see if you have the problem. If it dies, you have the problem.
1651 #!/usr/bin/perl
1653 use IPC::Run qw(run);
1655 use Fcntl;
1656 use IO::Pty;
1657 sub makecmd {
1659 return ['perl', '-e',
1660 '<STDIN>, print "\n" x '.$_[0].'; while(<STDIN>){last if /end/}'];
1661 }
1662 #pipe R, W;
1664 #fcntl(W, F_SETFL, O_NONBLOCK);
1665 #while (syswrite(W, "\n", 1)) { $pipebuf++ };
1666 #print "pipe buffer size is $pipebuf\n";
1667 my $pipebuf=4096;
1668 my $in = "\n" x ($pipebuf * 2) . "end\n";
1669 my $out;
1670 $SIG{ALRM} = sub { die "Never completed!\n" };
1672 print "reading from scalar via pipe...";
1674 alarm( 2 );
1675 run(makecmd($pipebuf * 2), '<', \$in, '>', \$out);
1676 alarm( 0 );
1677 print "done\n";
1678 print "reading from code via pipe... ";
1680 alarm( 2 );
1681 run(makecmd($pipebuf * 3), '<', sub { $t = $in; undef $in; $t}, '>', \$out);
1682 alarm( 0 );
1683 print "done\n";
1684 $pty = IO::Pty->new();
1686 $pty->blocking(0);
1687 $slave = $pty->slave();
1688 while ($pty->syswrite("\n", 1)) { $ptybuf++ };
1689 print "pty buffer size is $ptybuf\n";
1690 $in = "\n" x ($ptybuf * 3) . "end\n";
1691 print "reading via pty... ";
1693 alarm( 2 );
1694 run(makecmd($ptybuf * 3), '<pty<', \$in, '>', \$out);
1695 alarm(0);
1696 print "done\n";
1697 No support for ';', '&&', '||', '{ ... }', etc: use perl's, since run()
1699 returns TRUE when the command exits with a 0 result code.
1700 Does not provide shell-like string interpolation.
1702 No support for "cd", "setenv", or "export": do these in an init() sub
1704 run(
1706 \cmd,
1707 ...
1708 init => sub {
1709 chdir $dir or die $!;
1710 $ENV{FOO}='BAR'
1711 }
1712 );
1713 Timeout calculation does not allow absolute times, or specification of
1715 days, months, etc.
1716 WARNING: Function coprocesses ("run \&foo, ...") suffer from two
1718 limitations. The first is that it is difficult to close all
1719 filehandles the child inherits from the parent, since there is no way
1720 to scan all open FILEHANDLEs in Perl and it both painful and a bit
1721 dangerous to close all open file descriptors with POSIX::close().
1722 Painful because we can't tell which fds are open at the POSIX level,
1723 either, so we'd have to scan all possible fds and close any that we
1724 don't want open (normally exec() closes any non-inheritable but we
1725 don't exec() for &sub processes.
1726 The second problem is that Perl's DESTROY subs and other on-exit
1728 cleanup gets run in the child process. If objects are instantiated in
1729 the parent before the child is forked, the DESTROY will get run once in
1730 the parent and once in the child. When coprocess subs exit,
1731 POSIX::_exit is called to work around this, but it means that objects
1732 that are still referred to at that time are not cleaned up. So setting
1733 package vars or closure vars to point to objects that rely on DESTROY
1734 to affect things outside the process (files, etc), will lead to bugs.
1735 I goofed on the syntax: "<pipe" vs. "<pty<" and ">filename" are both
1737 oddities.
1738
1740 Allow one harness to "adopt" another:
1741 $new_h = harness \@cmd2;
1742 $h->adopt( $new_h );
1743 Close all filehandles not explicitly marked to stay open.
1745 The problem with this one is that there's no good way to scan all
1746 open FILEHANDLEs in Perl, yet you don't want child processes
1747 inheriting handles willy-nilly.
1748
1750 Well, select() and waitpid() badly needed wrapping, and open3() isn't
1751 open-minded enough for me.
1752 The shell-like API inspired by a message Russ Allbery sent to
1754 perl5-porters, which included:
1755 I've thought for some time that it would be
1757 nice to have a module that could handle full Bourne shell pipe syntax
1758 internally, with fork and exec, without ever invoking a shell. Something
1759 that you could give things like:
1760 pipeopen (PIPE, [ qw/cat file/ ], '|', [ 'analyze', @args ], '>&3');
1762 Message ylln51p2b6.fsf@windlord.stanford.edu, on 2000/02/04.
1764
1766 Bugs should always be submitted via the GitHub bug tracker
1767 <https://github.com/toddr/IPC-Run/issues>
1769
1771 Adam Kennedy <adamk@cpan.org>
1772 Barrie Slaymaker <barries@slaysys.com>
1774
1776 Some parts copyright 2008 - 2009 Adam Kennedy.
1777 Copyright 1999 Barrie Slaymaker.
1779 You may distribute under the terms of either the GNU General Public
1781 License or the Artistic License, as specified in the README file.
1782perl v5.36.0 2023-01-20 IPC::Run(3)