"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" throws an exception if the wrapped "system" call returned -1 or anything went wrong with "run3"'s processing of filehandles. Otherwise it returns true. It leaves $? intact for inspection of exit and wait status.

Note that a true return value from "run3" doesn't mean that the command had a successful exit code. Hence you should always check $?.

See "%options" for an option to handle the case of "system" returning -1 yourself.

$cmd

Usually $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 perlfunc for the difference and the pitfalls of using the latter form).

$stdin, $stdout, $stderr

The parameters $stdin, $stdout and $stderr can take one of the following forms:

"undef" (or not specified at all)

The child inherits the corresponding filehandle from the parent.

  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"

The child's filehandle is redirected from or to the local equivalent of "/dev/null" (as returned by "File::Spec->devnull()").

  run3 \@cmd, \undef, $stdout, $stderr; # child reads from /dev/null
    

a simple scalar

The parameter is taken to be the name of a file to read from or write to. In the latter case, the file will be opened via

  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"
    

a filehandle (either a reference to a GLOB or an "IO::Handle")

The filehandle is inherited by the child.

  open my $fh, ">", "out.txt";
  print $fh "prologue\n";
  ...
  run3 \@cmd, \undef, $fh;              # child writes to $fh
  ...
  print $fh "epilogue\n";
  close $fh;
    

a SCALAR reference

The referenced scalar is treated as a string to be read from or written to. In the latter case, the previous content of the string is overwritten.

  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
    

an ARRAY reference

For $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
    

a CODE reference

For $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.

"\%options"

The last parameter, "\%options", must be a hash reference if present.

Currently the following keys are supported:

"binmode_stdin", "binmode_stdout", "binmode_stderr"

The value must a "layer" as described in "binmode" in perlfunc. If specified the corresponding parameter $stdin, $stdout or $stderr, resp., operates with the given layer.

For backward compatibility, a true value that doesn't start with ":" (e.g. a number) is interpreted as ":raw". If the value is false or not specified, the default is ":crlf" on Windows and ":raw" otherwise.

Don't expect that values other than the built-in layers ":raw", ":crlf", and (on newer Perls) ":bytes", ":utf8", ":encoding(...)" will work.

"append_stdout", "append_stderr"

If their value is true then the corresponding parameter $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 "push"ed onto the previous contents of the array).

"return_if_system_error"

If this is true "run3" does not throw an exception if "system" returns -1 (cf. "system" in perlfunc for possible failure scenarios.), but returns true instead. In this case $? has the value -1 and $! contains the errno of the failing "system" call.

compared to "system()", "qx''", "open "...|"", "open "|...""

• better: redirects more than one file descriptor
• better: returns TRUE on success, FALSE on failure
• better: throws an error if problems occur in the parent process (or the pre-exec child)
• better: allows a very perlish interface to Perl data structures and subroutines
• better: allows 1 word invocations to avoid the shell easily:

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

• worse: does not return the exit code, leaves it in $?

compared to "open2()", "open3()"

• better: no lengthy, error prone polling/select loop needed
• better: hides OS dependencies
• better: allows SCALAR, ARRAY, and CODE references to source and sink I/O
• better: I/O parameter order is like "open3()" (not like "open2()").
• worse: does not allow interaction with the subprocess

compared to IPC::Run::run()

• better: smaller, lower overhead, simpler, more portable
• better: no select() loop portability issues
• better: does not fall prey to Perl closure leaks
• worse: does not allow interaction with the subprocess (which IPC::Run::run() allows by redirecting subroutines)
• worse: lacks many features of "IPC::Run::run()" (filters, pipes, redirects, pty support)