NAME<\/a> IPC::Run3 \u2212 run a subprocess with input\/ouput redirection<\/p>\n version 0.048<\/p>\n use IPC::Run3; # Exports run3() by default 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.<\/small><\/p>\n Speed, simplicity, and portability are paramount. (That\u2019s 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.)<\/p>\n “run3($cmd, $stdin, $stdout, $stderr, %options)”<\/b> The parameters $stdin, $stdout and $stderr indicate how the child\u2019s 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\u2019s by just not specifying them — a common use case.<\/p>\n “run3” throws an exception if the wrapped “system” call returned \u22121 or anything went wrong with “run3″\u2019s processing of filehandles. Otherwise it returns true. It leaves $? intact for inspection of exit and wait status.<\/p>\n Note that a true return value from “run3” doesn\u2019t mean that the command had a successful exit code. Hence you should always check $?.<\/p>\n See “%options” for an option to handle the case of “system” returning \u22121 yourself.<\/p>\n $cmd<\/i><\/p>\n Usually $cmd will be an ARRAY<\/small> reference and the child is invoked via<\/p>\n system @$cmd;<\/p>\n But $cmd may also be a string in which case the child is invoked via<\/p>\n system $cmd;<\/p>\n (cf. “system” in perlfunc for the difference and the pitfalls of using the latter form).<\/p>\n $stdin, $stdout, $stderr<\/i><\/p>\n The parameters $stdin, $stdout and $stderr can take one of the following forms: The child inherits the corresponding filehandle from the parent.<\/p>\n run3 @cmd, $stdin; # child writes to same STDOUT and STDERR as parent “undef”<\/p>\n The child\u2019s filehandle is redirected from or to the local equivalent of “\/dev\/null” (as returned by “File::Spec\u2212>devnull()”).<\/p>\n run3 @cmd, undef, $stdout, $stderr; # child reads from \/dev\/null<\/p>\n a simple scalar<\/p>\n 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<\/p>\n open FH, “>”, …<\/p>\n i.e. it is created if it doesn\u2019t exist and truncated otherwise. Note that the file is opened by the parent which will croak in case of failure.<\/p>\n run3 @cmd, undef, “out.txt”; # child writes to file “out.txt”<\/p>\n a filehandle (either a reference to a GLOB<\/small> or an “IO::Handle”)<\/p>\n The filehandle is inherited by the child.<\/p>\n open my $fh, “>”, “out.txt”; a SCALAR<\/small> reference<\/p>\n 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.<\/p>\n my $out; an ARRAY<\/small> reference<\/p>\n For $stdin, the elements of @$stdin are simply spooled to the child.<\/p>\n For $stdout or $stderr, the child\u2019s 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.<\/p>\n my @lines; a CODE<\/small> reference<\/p>\n 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”.<\/p>\n For $stdout or $stderr, the child\u2019s 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\u2019s no end-of-file indication.<\/p>\n my $i = 0; Note that this form of redirecting the child\u2019s I\/O doesn\u2019t imply any form of concurrency between parent and child \u2212 run3()<\/b>\u2019s method of operation is the same no matter which form of redirection you specify.<\/p>\n 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<\/p>\n run3 @cmd, undef, “foo.txt”, “foo.txt”; will DWIM<\/small> and pass a single file handle to the child for both “STDOUT” and “STDERR”, collecting all into file “foo.txt” or $both.<\/p>\n “%options”<\/i><\/p>\n The last parameter, “%options”, must be a hash reference if present.<\/p>\n Currently the following keys are supported: 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.<\/p>\n For backward compatibility, a true value that doesn\u2019t 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.<\/p>\n Don\u2019t expect that values other than the built-in layers “:raw”, “:crlf”, and (on newer Perls) “:bytes”, “:utf8”, “:encoding(…)” will work.<\/p>\n “append_stdout”, “append_stderr”<\/p>\n If their value is true then the corresponding parameter $stdout or $stderr, resp., will append the child\u2019s 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<\/small> reference (the output is appended to the previous contents of the string) or an ARRAY<\/small> reference (the output is “push”ed onto the previous contents of the array).<\/p>\n “return_if_system_error”<\/p>\n If this is true “run3” does not<\/b> throw an exception if “system” returns \u22121 (cf. “system” in perlfunc for possible failure scenarios.), but returns true instead. In this case $? has the value \u22121 and $! contains the errno of the failing “system” call.<\/p>\n
VERSION<\/a>
SYNOPSIS<\/a>
DESCRIPTION<\/a>
HOW IT WORKS<\/a>
LIMITATIONS<\/a>
DEBUGGING<\/a>
PROFILING<\/a>
COMPARISON<\/a>
COPYRIGHT<\/a>
LICENSE<\/a>
AUTHOR<\/a> <\/p>\n
\nNAME <\/a> <\/h2>\n
VERSION <\/a> <\/h2>\n
SYNOPSIS <\/a> <\/h2>\n
run3 @cmd, $in, $out, $err;<\/p>\nDESCRIPTION <\/a> <\/h2>\n
All parameters after $cmd are optional.<\/p>\n
“undef” (or not specified at all)<\/p>\n
run3 @cmd, undef, $stdout, $stderr; # child reads from same STDIN as parent<\/p>\n
print $fh “prologuen”;
…
run3 @cmd, undef, $fh; # child writes to $fh
…
print $fh “epiloguen”;
close $fh;<\/p>\n
run3 @cmd, undef, $out; # child writes into string
run3 @cmd, <
to
child
EOF<\/p>\n
run3 @cmd, undef, @lines; # child writes into array<\/p>\n
sub producer {
return $i < 10 ? \"line\".$i++.\"n\" : undef;
}
run3 @cmd, &producer; # child reads 10 lines<\/p>\n
run3 @cmd, undef, $both, $both;<\/p>\n
“binmode_stdin”, “binmode_stdout”, “binmode_stderr”<\/p>\nHOW IT WORKS <\/a> <\/h2>\n