IPC::Run3 - run a subprocess in batch mode (a la system) on Unix, Win32, etc.
version 0.032
use IPC::Run3; # Exports run3() by default run3 \@cmd, \$in, \$out, \$err; 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 and none of the bloat and rarely used features of IPC::Run.
system
qx
open3
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.) Disk space is not.
run3(\@cmd, INPUT, OUTPUT, \$err)
Note that passing in a reference to undef explicitly redirects the associated file descriptor for STDIN, STDOUT, or STDERR from or to the local equivalent of /dev/null (this does not pass a closed filehandle). Passing in undef (or not passing a redirection) allows the child to inherit the corresponding STDIN, STDOUT, or STDERR from the parent.
undef
STDIN
STDOUT
STDERR
/dev/null
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.
Note: This means that:
run3 \@cmd, undef, \$out; # Pass on parent's STDIN
does not close the child's STDIN, it passes on the parent's. Use
run3 \@cmd, \undef, \$out; # Close child's STDIN
for that. It's not ideal, but it does work.
If the exact same value is passed for $stdout and $stderr, then the child will write both to the same filehandle. In general, this means that
$stdout
$stderr
run3 \@cmd, \undef, "foo.txt", "foo.txt"; run3 \@cmd, \undef, \$both, \$both;
will DWYM and pass a single file handle to the child for both STDOUT and STDERR, collecting all into $both.
$both
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()
IPC::Run::run()
pty support
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.
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>
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.
rjbs@cpan.org
To install IPC::Run3, copy and paste the appropriate command in to your terminal.
cpanm
cpanm IPC::Run3
CPAN shell
perl -MCPAN -e shell install IPC::Run3
For more information on module installation, please visit the detailed CPAN module installation guide.