Unix/Linux Go Back    


CentOS 7.0 - man page for ipc::run3 (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


IPC::Run3(3)		       User Contributed Perl Documentation		     IPC::Run3(3)

NAME
       IPC::Run3 - run a subprocess with input/ouput redirection

VERSION
       version 0.045

SYNOPSIS
	   use IPC::Run3;    # Exports run3() by default

	   run3 \@cmd, \$in, \$out, \$err;

DESCRIPTION
       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.

       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.)

   "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.

HOW IT WORKS
       (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 returnd by a function) to the
	   temporary file and rewinds it.

       (3) "run3()" saves the parent's "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 parent's "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).

       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).

LIMITATIONS
       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 extrem 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).

DEBUGGING
       To enable debugging use the IPCRUN3DEBUG environment variable to a non-zero integer value:

	 $ IPCRUN3DEBUG=1 myapp

PROFILING
       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.

COMPARISON
       Here's how it stacks up to existing APIs:

   compared to "system()", "qx''", "open "...|"", "open "|...""
       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 "open2()", "open3()"
       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
       Copyright 2003, R. Barrie Slaymaker, Jr., All Rights Reserved

LICENSE
       You may use this module under the terms of the BSD, Artistic, or GPL licenses, any
       version.

AUTHOR
       Barrie Slaymaker <"barries@slaysys.com">

       Ricardo SIGNES <"rjbs@cpan.org"> 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.16.3				    2011-12-23				     IPC::Run3(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 09:25 AM.