Add built local::lib

[catagits/Gitalist.git] / local-lib5 / man / man3 / IPC::Run3.3pm

.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "IPC::Run3 3"
.TH IPC::Run3 3 "2009-05-30" "perl v5.8.7" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
IPC::Run3 \- run a subprocess with input/ouput redirection
.SH "VERSION"
.IX Header "VERSION"
version 0.043
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use IPC::Run3;    # Exports run3() by default
\&
\&    run3 \e@cmd, \e$in, \e$out, \e$err;
.Ve
.SH "DESCRIPTION"
.IX Header "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 \f(CW\*(C`system\*(C'\fR, \f(CW\*(C`qx\*(C'\fR, and \f(CW\*(C`open3\*(C'\fR 
with a simple, extremely Perlish \s-1API\s0.
.PP
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.)
.ie n .SS """run3($cmd, $stdin, $stdout, $stderr, \e%options)"""
.el .SS "\f(CWrun3($cmd, $stdin, $stdout, $stderr, \e%options)\fP"
.IX Subsection "run3($cmd, $stdin, $stdout, $stderr, %options)"
All parameters after \f(CW$cmd\fR are optional.
.PP
The parameters \f(CW$stdin\fR, \f(CW$stdout\fR and \f(CW$stderr\fR indicate
how the child's corresponding filehandle 
(\f(CW\*(C`STDIN\*(C'\fR, \f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR, resp.) will be redirected.
Because the redirects come last, this allows \f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR to default
to the parent's by just not specifying them \*(-- a common use case.
.PP
\&\f(CW\*(C`run3\*(C'\fR throws an exception if the wrapped \f(CW\*(C`system\*(C'\fR call returned \-1
or anything went wrong with \f(CW\*(C`run3\*(C'\fR's processing of filehandles.
Otherwise it returns true. 
It leaves \f(CW$?\fR intact for inspection of exit and wait status.
.PP
Note that a true return value from \f(CW\*(C`run3\*(C'\fR doesn't mean that the command
had a successful exit code. Hence you should always check \f(CW$?\fR.
.PP
See \*(L"%options\*(R" for an option to handle the case of \f(CW\*(C`system\*(C'\fR
returning \-1 yourself.
.PP
\fI\f(CI$cmd\fI\fR
.IX Subsection "$cmd"
.PP
Usually \f(CW$cmd\fR will be an \s-1ARRAY\s0 reference and the child is invoked via
.PP
.Vb 1
\&  system @$cmd;
.Ve
.PP
But \f(CW$cmd\fR may also be a string in which case the child is invoked via
.PP
.Vb 1
\&  system $cmd;
.Ve
.PP
(cf. \*(L"system\*(R" in perlfunc for the difference and the pitfalls of using
the latter form).
.PP
\fI\f(CI$stdin\fI, \f(CI$stdout\fI, \f(CI$stderr\fI\fR
.IX Subsection "$stdin, $stdout, $stderr"
.PP
The parameters \f(CW$stdin\fR, \f(CW$stdout\fR and \f(CW$stderr\fR 
can take one of the following forms:
.ie n .IP """undef"" (or not specified at all)" 4
.el .IP "\f(CWundef\fR (or not specified at all)" 4
.IX Item "undef (or not specified at all)"
The child inherits the corresponding filehandle from the parent.
.Sp
.Vb 2
\&  run3 \e@cmd, $stdin;                   # child writes to same STDOUT and STDERR as parent
\&  run3 \e@cmd, undef, $stdout, $stderr;  # child reads from same STDIN as parent
.Ve
.ie n .IP """\eundef""" 4
.el .IP "\f(CW\eundef\fR" 4
.IX Item "undef"
The child's filehandle is redirected from or to the
local equivalent of \f(CW\*(C`/dev/null\*(C'\fR (as returned by 
\&\f(CW\*(C`File::Spec\->devnull()\*(C'\fR).
.Sp
.Vb 1
\&  run3 \e@cmd, \eundef, $stdout, $stderr; # child reads from /dev/null
.Ve
.IP "a simple scalar" 4
.IX Item "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
.Sp
.Vb 1
\&  open FH, ">", ...
.Ve
.Sp
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.
.Sp
.Vb 1
\&  run3 \e@cmd, \eundef, "out.txt";        # child writes to file "out.txt"
.Ve
.ie n .IP "a filehandle (either a reference to a \s-1GLOB\s0 or an ""IO::Handle"")" 4
.el .IP "a filehandle (either a reference to a \s-1GLOB\s0 or an \f(CWIO::Handle\fR)" 4
.IX Item "a filehandle (either a reference to a GLOB or an IO::Handle)"
The filehandle is inherited by the child.
.Sp
.Vb 7
\&  open my $fh, ">", "out.txt";
\&  print $fh "prologue\en";
\&  ...
\&  run3 \e@cmd, \eundef, $fh;              # child writes to $fh
\&  ...
\&  print $fh "epilogue\en";
\&  close $fh;
.Ve
.IP "a \s-1SCALAR\s0 reference" 4
.IX Item "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.
.Sp
.Vb 7
\&  my $out;
\&  run3 \e@cmd, \eundef, \e$out;           # child writes into string 
\&  run3 \e@cmd, \e<<EOF;                  # child reads from string (can use "here" notation)
\&  Input
\&  to 
\&  child
\&  EOF
.Ve
.IP "an \s-1ARRAY\s0 reference" 4
.IX Item "an ARRAY reference"
For \f(CW$stdin\fR, the elements of \f(CW@$stdin\fR are simply spooled to the child.
.Sp
For \f(CW$stdout\fR or \f(CW$stderr\fR, the child's corresponding file descriptor 
is read line by line (as determined by the current setting of \f(CW$/\fR)
into \f(CW@$stdout\fR or \f(CW@$stderr\fR, resp. The previous content of the array
is overwritten.
.Sp
.Vb 2
\&  my @lines;
\&  run3 \e@cmd, \eundef, \e@lines;         # child writes into array
.Ve
.IP "a \s-1CODE\s0 reference" 4
.IX Item "a CODE reference"
For \f(CW$stdin\fR, \f(CW&$stdin\fR will be called repeatedly (with no arguments) and 
the return values are spooled to the child. \f(CW&$stdin\fR must signal the end of
input by returning \f(CW\*(C`undef\*(C'\fR.
.Sp
For \f(CW$stdout\fR or \f(CW$stderr\fR, the child's corresponding file descriptor 
is read line by line (as determined by the current setting of \f(CW$/\fR)
and \f(CW&$stdout\fR or \f(CW&$stderr\fR, resp., is called with the contents of the line.
Note that there's no end-of-file indication.
.Sp
.Vb 4
\&  my $i = 0;
\&  sub producer {
\&    return $i < 10 ? "line".$i++."\en" : undef;
\&  }
\&    
\&  run3 \e@cmd, \e&producer;              # child reads 10 lines
.Ve
.Sp
Note that this form of redirecting the child's I/O doesn't imply
any form of concurrency between parent and child \- \fIrun3()\fR's method of
operation is the same no matter which form of redirection you specify.
.PP
If the same value is passed for \f(CW$stdout\fR and \f(CW$stderr\fR, then the child
will write both \f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR to the same filehandle.
In general, this means that
.PP
.Vb 2
\&    run3 \e@cmd, \eundef, "foo.txt", "foo.txt";
\&    run3 \e@cmd, \eundef, \e$both, \e$both;
.Ve
.PP
will \s-1DWIM\s0 and pass a single file handle to the child for both \f(CW\*(C`STDOUT\*(C'\fR and
\&\f(CW\*(C`STDERR\*(C'\fR, collecting all into file \*(L"foo.txt\*(R" or \f(CW$both\fR.
.PP
\fI\f(CI\*(C`\e%options\*(C'\fI\fR
.IX Subsection "%options"
.PP
The last parameter, \f(CW\*(C`\e%options\*(C'\fR, must be a hash reference if present.
.PP
Currently the following
keys are supported:
.ie n .IP """binmode_stdin"", ""binmode_stdout"", ""binmode_stderr""" 4
.el .IP "\f(CWbinmode_stdin\fR, \f(CWbinmode_stdout\fR, \f(CWbinmode_stderr\fR" 4
.IX Item "binmode_stdin, binmode_stdout, binmode_stderr"
The value must a \*(L"layer\*(R" as described in \*(L"binmode\*(R" in perlfunc.
If specified the corresponding
parameter \f(CW$stdin\fR, \f(CW$stdout\fR or \f(CW$stderr\fR, resp., operates
with the given layer.
.Sp
For backward compatibility, a true value that doesn't start with \*(L":\*(R"
(e.g. a number) is interpreted as \*(L":raw\*(R". If the value is false
or not specified, the default is \*(L":crlf\*(R" on Windows and \*(L":raw\*(R" otherwise.
.Sp
Don't expect that values other than the built-in layers \*(L":raw\*(R", \*(L":crlf\*(R",
and (on newer Perls) \*(L":bytes\*(R", \*(L":utf8\*(R", \*(L":encoding(...)\*(R" will work.
.ie n .IP """append_stdout"", ""append_stderr""" 4
.el .IP "\f(CWappend_stdout\fR, \f(CWappend_stderr\fR" 4
.IX Item "append_stdout, append_stderr"
If their value is true then the corresponding
parameter \f(CW$stdout\fR or \f(CW$stderr\fR, resp., will append the child's output
to the existing \*(L"contents\*(R" of the redirector. This only makes
sense if the redirector is a simple scalar (the corresponding file
is opened in append mode), a \s-1SCALAR\s0 reference (the output is 
appended to the previous contents of the string) 
or an \s-1ARRAY\s0 reference (the output is \f(CW\*(C`push\*(C'\fRed onto the 
previous contents of the array).
.ie n .IP """return_if_system_error""" 4
.el .IP "\f(CWreturn_if_system_error\fR" 4
.IX Item "return_if_system_error"
If this is true \f(CW\*(C`run3\*(C'\fR does \fBnot\fR throw an exception if \f(CW\*(C`system\*(C'\fR
returns \-1 (cf. \*(L"system\*(R" in perlfunc for possible
failure scenarios.), but returns true instead.
In this case \f(CW$?\fR has the value \-1 and \f(CW$!\fR 
contains the errno of the failing \f(CW\*(C`system\*(C'\fR call.
.SH "HOW IT WORKS"
.IX Header "HOW IT WORKS"
.IP "(1)" 4
.IX Item "(1)"
For each redirector \f(CW$stdin\fR, \f(CW$stdout\fR, and \f(CW$stderr\fR, 
\&\f(CW\*(C`run3()\*(C'\fR furnishes a filehandle:
.RS 4
.IP "\(bu" 4
if the redirector already specifies a filehandle it just uses that
.IP "\(bu" 4
if the redirector specifies a filename, \f(CW\*(C`run3()\*(C'\fR opens the file
in the appropriate mode
.IP "\(bu" 4
in all other cases, \f(CW\*(C`run3()\*(C'\fR opens a temporary file 
(using tempfile)
.RE
.RS 4
.RE
.IP "(2)" 4
.IX Item "(2)"
If \f(CW\*(C`run3()\*(C'\fR opened a temporary file for \f(CW$stdin\fR 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.
.IP "(3)" 4
.IX Item "(3)"
\&\f(CW\*(C`run3()\*(C'\fR saves the parent's \f(CW\*(C`STDIN\*(C'\fR, \f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR by duplicating
them to new filehandles. It duplicates the filehandles from step (1)
to \f(CW\*(C`STDIN\*(C'\fR, \f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR, resp.
.IP "(4)" 4
.IX Item "(4)"
\&\f(CW\*(C`run3()\*(C'\fR runs the child by invoking system 
with \f(CW$cmd\fR as specified above.
.IP "(5)" 4
.IX Item "(5)"
\&\f(CW\*(C`run3()\*(C'\fR restores the parent's \f(CW\*(C`STDIN\*(C'\fR, \f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR saved in step (3).
.IP "(6)" 4
.IX Item "(6)"
If \f(CW\*(C`run3()\*(C'\fR opened a temporary file for \f(CW$stdout\fR or \f(CW$stderr\fR 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).
.IP "(7)" 4
.IX Item "(7)"
\&\f(CW\*(C`run3()\*(C'\fR closes all filehandles that it opened explicitly in step (1).
.PP
Note that when using temporary files, \f(CW\*(C`run3()\*(C'\fR tries to amortize the overhead
by reusing them (i.e. it keeps them open and rewinds and truncates them
before the next operation).
.SH "LIMITATIONS"
.IX Header "LIMITATIONS"
Often uses intermediate files (determined by File::Temp, and thus by the
File::Spec defaults and the \s-1TMPDIR\s0 env. variable) for speed, portability and
simplicity.
.PP
Use extrem caution when using \f(CW\*(C`run3\*(C'\fR in a threaded environment if
concurrent calls of \f(CW\*(C`run3\*(C'\fR 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 \s-1STDIN/STDOUT/STDERR\s0.
Known failures are Perl ithreads on Linux and Win32. Note that \f(CW\*(C`fork\*(C'\fR
on Win32 is emulated via Win32 threads and hence I/O mix up is possible
between forked children here (\f(CW\*(C`run3\*(C'\fR is \*(L"fork safe\*(R" on Unix, though).
.SH "DEBUGGING"
.IX Header "DEBUGGING"
To enable debugging use the \s-1IPCRUN3DEBUG\s0 environment variable to
a non-zero integer value:
.PP
.Vb 1
\&  $ IPCRUN3DEBUG=1 myapp
.Ve
.SH "PROFILING"
.IX Header "PROFILING"
To enable profiling, set \s-1IPCRUN3PROFILE\s0 to a number to enable emitting profile
information to \s-1STDERR\s0 (1 to get timestamps, 2 to get a summary report at the
\&\s-1END\s0 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.
.SH "COMPARISON"
.IX Header "COMPARISON"
Here's how it stacks up to existing APIs:
.ie n .SS "compared to ""system()"", ""qx\*(Aq\*(Aq"", ""open ""...|"""", ""open ""|..."""""
.el .SS "compared to \f(CWsystem()\fP, \f(CWqx\*(Aq\*(Aq\fP, \f(CWopen ``...|''\fP, \f(CWopen ``|...''\fP"
.IX Subsection "compared to system(), qx, open ""...|"", open ""|..."""
.IP "+" 4
redirects more than one file descriptor
.IP "+" 4
returns \s-1TRUE\s0 on success, \s-1FALSE\s0 on failure
.IP "+" 4
throws an error if problems occur in the parent process (or the pre-exec child)
.IP "+" 4
allows a very perlish interface to Perl data structures and subroutines
.IP "+" 4
allows 1 word invocations to avoid the shell easily:
.Sp
.Vb 1
\& run3 ["foo"];  # does not invoke shell
.Ve
.IP "\-" 4
does not return the exit code, leaves it in $?
.ie n .SS "compared to ""open2()"", ""open3()"""
.el .SS "compared to \f(CWopen2()\fP, \f(CWopen3()\fP"
.IX Subsection "compared to open2(), open3()"
.IP "+" 4
no lengthy, error prone polling/select loop needed
.IP "+" 4
hides \s-1OS\s0 dependancies
.IP "+" 4
allows \s-1SCALAR\s0, \s-1ARRAY\s0, and \s-1CODE\s0 references to source and sink I/O
.IP "+" 4
I/O parameter order is like \f(CW\*(C`open3()\*(C'\fR  (not like \f(CW\*(C`open2()\*(C'\fR).
.IP "\-" 4
does not allow interaction with the subprocess
.SS "compared to \fIIPC::Run::run()\fP"
.IX Subsection "compared to IPC::Run::run()"
.IP "+" 4
smaller, lower overhead, simpler, more portable
.IP "+" 4
no \fIselect()\fR loop portability issues
.IP "+" 4
does not fall prey to Perl closure leaks
.IP "\-" 4
does not allow interaction with the subprocess (which
\&\fIIPC::Run::run()\fR allows by redirecting subroutines)
.IP "\-" 4
lacks many features of \f(CW\*(C`IPC::Run::run()\*(C'\fR (filters, pipes,
redirects, pty support)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2003, R. Barrie Slaymaker, Jr., All Rights Reserved
.SH "LICENSE"
.IX Header "LICENSE"
You may use this module under the terms of the \s-1BSD\s0, Artistic, or \s-1GPL\s0 licenses,
any version.
.SH "AUTHOR"
.IX Header "AUTHOR"
Barrie Slaymaker <\f(CW\*(C`barries@slaysys.com\*(C'\fR>
.PP
Ricardo \s-1SIGNES\s0 <\f(CW\*(C`rjbs@cpan.org\*(C'\fR> 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.