| IPC::Run3 - run a subprocess with input/ouput redirection |
system(), qx'', open "...|", open "|..."open2(), open3()
IPC::Run3 - run a subprocess with input/ouput redirection
version 0.040
use IPC::Run3; # Exports run3() by default
run3 \@cmd, \$in, \$out, \$err;
This module allows you to run a subprocess and redirect stdin, stdout,
and/or stderr to files and perl data structures. It aims to satisfy 99% of the
need for using system, qx, and open3
with a simple, extremely Perlish API.
Speed, simplicity, and portability are paramount. (That's speed of Perl code; which is often much slower than the kind of buffered I/O that this module uses to spool input to and output from the child command.)
run3($cmd, $stdin, $stdout, $stderr, \%options)All parameters after $cmd are optional.
The parameters $stdin, $stdout and $stderr indicate
how the child's corresponding filehandle
(STDIN, STDOUT and STDERR, resp.) will be redirected.
Because the redirects come last, this allows STDOUT and STDERR to default
to the parent's by just not specifying them -- a common use case.
run3 returns true if the command executes and throws an exception otherwise.
It leaves $? intact for inspection of exit and wait status.
$cmdUsually $cmd will be an ARRAY reference and the child is invoked via
system @$cmd;
But $cmd may also be a string in which case the child is invoked via
system $cmd;
(cf. system in the perlfunc manpage for the difference and the pitfalls of using the latter form).
$stdin, $stdout, $stderrThe parameters $stdin, $stdout and $stderr
can take one of the following forms:
undef (or not specified at all)run3 \@cmd, $stdin; # child writes to same STDOUT and STDERR as parent run3 \@cmd, undef, $stdout, $stderr; # child reads from same STDIN as parent
\undef/dev/null (as returned by
File::Spec->devnull()).
run3 \@cmd, \undef, $stdout, $stderr; # child reads from /dev/null
open FH, ">", ...
i.e. it is created if it doesn't exist and truncated otherwise. Note that the file is opened by the parent which will croak in case of failure.
run3 \@cmd, \undef, "out.txt"; # child writes to file "out.txt"
IO::Handle)open my $fh, ">", "out.txt"; print $fh "prologue\n"; ... run3 \@cmd, \undef, $fh; # child writes to $fh ... print $fh "epilogue\n"; close $fh;
my $out; run3 \@cmd, \undef, \$out; # child writes into string run3 \@cmd, \<<EOF; # child reads from string (can use "here" notation) Input to child EOF
$stdin, the elements of @$stdin are simply spooled to the child.
For $stdout or $stderr, the child's corresponding file descriptor
is read line by line (as determined by the current setting of $/)
into @$stdout or @$stderr, resp. The previous content of the array
is overwritten.
my @lines; run3 \@cmd, \undef, \@lines; # child writes into array
$stdin, &$stdin will be called repeatedly (with no arguments) and
the return values are spooled to the child. &$stdin must signal the end of
input by returning undef.
For $stdout or $stderr, the child's corresponding file descriptor
is read line by line (as determined by the current setting of $/)
and &$stdout or &$stderr, resp., is called with the contents of the line.
Note that there's no end-of-file indication.
my $i = 0;
sub producer {
return $i < 10 ? "line".$i++."\n" : undef;
}
run3 \@cmd, \&producer; # child reads 10 lines
Note that this form of redirecting the child's I/O doesn't imply any form of concurrency between parent and child - run3()'s method of operation is the same no matter which form of redirection you specify.
If the same value is passed for $stdout and $stderr, then the child
will write both STDOUT and STDERR to the same filehandle.
In general, this means that
run3 \@cmd, \undef, "foo.txt", "foo.txt";
run3 \@cmd, \undef, \$both, \$both;
will DWIM and pass a single file handle to the child for both STDOUT and
STDERR, collecting all into file ``foo.txt'' or $both.
\%optionsThe last parameter, \%options, must be a hash reference if present.
Currently the following keys are supported:
binmode_stdin, binmode_stdout, binmode_stderr$stdin, $stdout or $stderr, resp., operates
in ``binary'' mode (cf. binmode in the perlfunc manpage).
The default is to operate in ``text'' mode.
(This is only relevant for platforms where these modes differ.)
append_stdout, append_stderr$stdout or $stderr, resp., will append the child's output
to the existing ``contents'' of the redirector. This only makes
sense if the redirector is a simple scalar (the corresponding file
is opened in append mode), a SCALAR reference (the output is
appended to the previous contents of the string)
or an ARRAY reference (the output is pushed onto the
previous contents of the array).
$stdin, $stdout, and $stderr,
run3() furnishes a filehandle:
run3() opens the file
in the appropriate mode
in all other cases, run3() opens a temporary file
(using tempfile)
run3() opened a temporary file for $stdin in step (1),
it writes the data using the specified method (either
from a string, an array or returnd by a function) to the temporary file and rewinds it.
run3() saves the parent's STDIN, STDOUT and STDERR by duplicating
them to new filehandles. It duplicates the filehandles from step (1)
to STDIN, STDOUT and STDERR, resp.
run3() runs the child by invoking system
with $cmd as specified above.
run3() restores the parent's STDIN, STDOUT and STDERR saved in step (3).
run3() opened a temporary file for $stdout or $stderr in step (1),
it rewinds it and reads back its contents using the specified method
(either to a string, an array or by calling a function).
run3() closes all filehandles that it opened explicitly in step (1).
Note that when using temporary files, run3() tries to amortize the overhead
by reusing them (i.e. it keeps them open and rewinds and truncates them
before the next operation).
Often uses intermediate files (determined by File::Temp, and thus by the File::Spec defaults and the TMPDIR env. variable) for speed, portability and simplicity.
Use extrem caution when using run3 in a threaded environment if
concurrent calls of run3 are possible. Most likely, I/O from different
invocations will get mixed up. The reason is that in most thread
implementations all threads in a process share the same STDIN/STDOUT/STDERR.
Known failures are Perl ithreads on Linux and Win32. Note that fork
on Win32 is emulated via Win32 threads and hence I/O mix up is possible
between forked children here (run3 is ``fork safe'' on Unix, though).
To enable debugging use the IPCRUN3DEBUG environment variable to a non-zero integer value:
$ IPCRUN3DEBUG=1 myapp
To enable profiling, set IPCRUN3PROFILE to a number to enable emitting profile information to STDERR (1 to get timestamps, 2 to get a summary report at the END of the program, 3 to get mini reports after each run) or to a filename to emit raw data to a file for later analysis.
Here's how it stacks up to existing APIs:
system(), qx'', open "...|", open "|..."run3 ["foo"]; # does not invoke shell
open2(), open3()open3() (not like open2()).
select() loop portability issues
IPC::Run::run() (filters, pipes,
redirects, pty support)
Copyright 2003, R. Barrie Slaymaker, Jr., All Rights Reserved
You may use this module under the terms of the BSD, Artistic, or GPL licenses, any version.
Barrie Slaymaker <barries@slaysys.com>
Ricardo SIGNES <rjbs@cpan.org> performed some routine maintenance in
2005, thanks to help from the following ticket and/or patch submitters: Jody
Belka, Roderich Schupp, David Morel, and anonymous others.
| IPC::Run3 - run a subprocess with input/ouput redirection |