IPC::Run3 - run a subprocess in batch mode (a la system) on Unix, Win32, etc.

version 0.030

    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 CWsystem, CWqx, and CWopen3 with a simple, extremely Perlish API and none of the bloat and rarely used features of IPC::Run.

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. Note that passing in a reference to CWundef explicitly redirects the associated file descriptor for CWSTDIN, CWSTDOUT, or CWSTDERR from or to the local equivalent of CW/dev/null (this does not pass a closed filehandle). Passing in CWundef (or not passing a redirection) allows the child to inherit the corresponding CWSTDIN, CWSTDOUT, or CWSTDERR from the parent.

Because the redirects come last, this allows CWSTDOUT and CWSTDERR 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 CW$stdout and CW$stderr, then the child will write both to the same filehandle. In general, this means that

    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 CWSTDOUT and CWSTDERR, collecting all into CW$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:

+ redirects more than one file descriptor

+ returns TRUE on success, FALSE on failure

+ throws an error if problems occur in the parent process (or the pre-exec child)

+ allows a very perlish interface to Perl data structures and subroutines

+ allows 1 word invocations to avoid the shell easily:

 run3 ["foo"];  # does not invoke shell

- does not return the exit code, leaves it in $?

+ No lengthy, error prone polling / select loop needed

+ Hides OS dependancies

+ Allows SCALAR, ARRAY, and CODE references to source and sink I/O

+ I/O parameter order is like open3() (not like open2()).

- Does not allow interaction with the subprocess

+ Smaller, lower overhead, simpler, more portable

+ No select() loop portability issues

+ Does not fall prey to Perl closure leaks

- Does not allow interaction with the subprocess (which IPC::Run::run() allows by redirecting subroutines).

- Lacks many features of IPC::Run::run() (filters, pipes, redirects, pty support).

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 <CWbarries@slaysys.com>

Ricardo SIGNES <CWrjbs@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.