|undef (or not specified at all)||The child inherits the corresponding filehandle from the parent.|
The childs filehandle is redirected from or to the local equivalent of
/dev/null (as returned by File::Spec->devnull()).
|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
|a filehandle (either a reference to a GLOB or an IO::Handle)||
The filehandle is inherited by the child.
|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
|an ARRAY reference||
For $stdin, the elements of @$stdin are simply spooled to the child.
For $stdout or $stderr, the childs 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.
|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 childs 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 theres no end-of-file indication.
Note that this form of redirecting the childs I/O doesnt 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.
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.
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 doesnt 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.
|append_stdout, append_stderr||If their value is true then the corresponding parameter $stdout or $stderr, resp., will append the childs 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).|
|return_if_system_error||If this is true run3 does <B>notB> 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.|
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).
(1) For each redirector $stdin, $stdout, and $stderr, run3() furnishes a filehandle:
o if the redirector already specifies a filehandle it just uses that o if the redirector specifies a filename, run3() opens the file in the appropriate mode o in all other cases, run3() opens a temporary file (using tempfile) (2) If 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 returned by a function) to the temporary file and rewinds it. (3) run3() saves the parents STDIN, STDOUT and STDERR by duplicating them to new filehandles. It duplicates the filehandles from step (1) to STDIN, STDOUT and STDERR, resp. (4) run3() runs the child by invoking system with $cmd as specified above. (5) run3() restores the parents STDIN, STDOUT and STDERR saved in step (3). (6) If 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). (7) run3() closes all filehandles that it opened explicitly in step (1).
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 extreme 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.
Heres how it stacks up to existing APIs:
compared to CWsystem(), CWqx, CWopen ...|, CWopen |...
o better: redirects more than one file descriptor o better: returns TRUE on success, FALSE on failure o better: throws an error if problems occur in the parent process (or the pre-exec child) o better: allows a very perlish interface to Perl data structures and subroutines o better: allows 1 word invocations to avoid the shell easily:
run3 ["foo"]; # does not invoke shell
o worse: does not return the exit code, leaves it in $?
compared to CWopen2(), CWopen3()
o better: no lengthy, error prone polling/select loop needed o better: hides OS dependencies o better: allows SCALAR, ARRAY, and CODE references to source and sink I/O o better: I/O parameter order is like open3() (not like open2()). o worse: does not allow interaction with the subprocess
compared to IPC::Run::run()
o better: smaller, lower overhead, simpler, more portable o better: no select() loop portability issues o better: does not fall prey to Perl closure leaks o worse: does not allow interaction with the subprocess (which IPC::Run::run() allows by redirecting subroutines) o worse: lacks many features of 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 <firstname.lastname@example.org>
Ricardo SIGNES <email@example.com> performed routine maintenance since 2010, thanks to help from the following ticket and/or patch submitters: Jody Belka, Roderich Schupp, David Morel, Jeff Lavallee, and anonymous others.
|perl v5.20.3||IPC::RUN3 (3)||2014-03-29|