1IPC::Run3(3)          User Contributed Perl Documentation         IPC::Run3(3)
2
3
4

NAME

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

VERSION

9       version 0.045
10

SYNOPSIS

12           use IPC::Run3;    # Exports run3() by default
13
14           run3 \@cmd, \$in, \$out, \$err;
15

DESCRIPTION

17       This module allows you to run a subprocess and redirect stdin, stdout,
18       and/or stderr to files and perl data structures.  It aims to satisfy
19       99% of the need for using "system", "qx", and "open3" with a simple,
20       extremely Perlish API.
21
22       Speed, simplicity, and portability are paramount.  (That's speed of
23       Perl code; which is often much slower than the kind of buffered I/O
24       that this module uses to spool input to and output from the child
25       command.)
26
27   "run3($cmd, $stdin, $stdout, $stderr, \%options)"
28       All parameters after $cmd are optional.
29
30       The parameters $stdin, $stdout and $stderr indicate how the child's
31       corresponding filehandle ("STDIN", "STDOUT" and "STDERR", resp.) will
32       be redirected.  Because the redirects come last, this allows "STDOUT"
33       and "STDERR" to default to the parent's by just not specifying them --
34       a common use case.
35
36       "run3" throws an exception if the wrapped "system" call returned -1 or
37       anything went wrong with "run3"'s processing of filehandles.  Otherwise
38       it returns true.  It leaves $? intact for inspection of exit and wait
39       status.
40
41       Note that a true return value from "run3" doesn't mean that the command
42       had a successful exit code. Hence you should always check $?.
43
44       See "%options" for an option to handle the case of "system" returning
45       -1 yourself.
46
47       $cmd
48
49       Usually $cmd will be an ARRAY reference and the child is invoked via
50
51         system @$cmd;
52
53       But $cmd may also be a string in which case the child is invoked via
54
55         system $cmd;
56
57       (cf. "system" in perlfunc for the difference and the pitfalls of using
58       the latter form).
59
60       $stdin, $stdout, $stderr
61
62       The parameters $stdin, $stdout and $stderr can take one of the
63       following forms:
64
65       "undef" (or not specified at all)
66           The child inherits the corresponding filehandle from the parent.
67
68             run3 \@cmd, $stdin;                   # child writes to same STDOUT and STDERR as parent
69             run3 \@cmd, undef, $stdout, $stderr;  # child reads from same STDIN as parent
70
71       "\undef"
72           The child's filehandle is redirected from or to the local
73           equivalent of "/dev/null" (as returned by "File::Spec->devnull()").
74
75             run3 \@cmd, \undef, $stdout, $stderr; # child reads from /dev/null
76
77       a simple scalar
78           The parameter is taken to be the name of a file to read from or
79           write to. In the latter case, the file will be opened via
80
81             open FH, ">", ...
82
83           i.e. it is created if it doesn't exist and truncated otherwise.
84           Note that the file is opened by the parent which will croak in case
85           of failure.
86
87             run3 \@cmd, \undef, "out.txt";        # child writes to file "out.txt"
88
89       a filehandle (either a reference to a GLOB or an "IO::Handle")
90           The filehandle is inherited by the child.
91
92             open my $fh, ">", "out.txt";
93             print $fh "prologue\n";
94             ...
95             run3 \@cmd, \undef, $fh;              # child writes to $fh
96             ...
97             print $fh "epilogue\n";
98             close $fh;
99
100       a SCALAR reference
101           The referenced scalar is treated as a string to be read from or
102           written to. In the latter case, the previous content of the string
103           is overwritten.
104
105             my $out;
106             run3 \@cmd, \undef, \$out;           # child writes into string
107             run3 \@cmd, \<<EOF;                  # child reads from string (can use "here" notation)
108             Input
109             to
110             child
111             EOF
112
113       an ARRAY reference
114           For $stdin, the elements of @$stdin are simply spooled to the
115           child.
116
117           For $stdout or $stderr, the child's corresponding file descriptor
118           is read line by line (as determined by the current setting of $/)
119           into @$stdout or @$stderr, resp. The previous content of the array
120           is overwritten.
121
122             my @lines;
123             run3 \@cmd, \undef, \@lines;         # child writes into array
124
125       a CODE reference
126           For $stdin, &$stdin will be called repeatedly (with no arguments)
127           and the return values are spooled to the child. &$stdin must signal
128           the end of input by returning "undef".
129
130           For $stdout or $stderr, the child's corresponding file descriptor
131           is read line by line (as determined by the current setting of $/)
132           and &$stdout or &$stderr, resp., is called with the contents of the
133           line.  Note that there's no end-of-file indication.
134
135             my $i = 0;
136             sub producer {
137               return $i < 10 ? "line".$i++."\n" : undef;
138             }
139
140             run3 \@cmd, \&producer;              # child reads 10 lines
141
142           Note that this form of redirecting the child's I/O doesn't imply
143           any form of concurrency between parent and child - run3()'s method
144           of operation is the same no matter which form of redirection you
145           specify.
146
147       If the same value is passed for $stdout and $stderr, then the child
148       will write both "STDOUT" and "STDERR" to the same filehandle.  In
149       general, this means that
150
151           run3 \@cmd, \undef, "foo.txt", "foo.txt";
152           run3 \@cmd, \undef, \$both, \$both;
153
154       will DWIM and pass a single file handle to the child for both "STDOUT"
155       and "STDERR", collecting all into file "foo.txt" or $both.
156
157       "\%options"
158
159       The last parameter, "\%options", must be a hash reference if present.
160
161       Currently the following keys are supported:
162
163       "binmode_stdin", "binmode_stdout", "binmode_stderr"
164           The value must a "layer" as described in "binmode" in perlfunc.  If
165           specified the corresponding parameter $stdin, $stdout or $stderr,
166           resp., operates with the given layer.
167
168           For backward compatibility, a true value that doesn't start with
169           ":" (e.g. a number) is interpreted as ":raw". If the value is false
170           or not specified, the default is ":crlf" on Windows and ":raw"
171           otherwise.
172
173           Don't expect that values other than the built-in layers ":raw",
174           ":crlf", and (on newer Perls) ":bytes", ":utf8", ":encoding(...)"
175           will work.
176
177       "append_stdout", "append_stderr"
178           If their value is true then the corresponding parameter $stdout or
179           $stderr, resp., will append the child's output to the existing
180           "contents" of the redirector. This only makes sense if the
181           redirector is a simple scalar (the corresponding file is opened in
182           append mode), a SCALAR reference (the output is appended to the
183           previous contents of the string) or an ARRAY reference (the output
184           is "push"ed onto the previous contents of the array).
185
186       "return_if_system_error"
187           If this is true "run3" does not throw an exception if "system"
188           returns -1 (cf. "system" in perlfunc for possible failure
189           scenarios.), but returns true instead.  In this case $? has the
190           value -1 and $! contains the errno of the failing "system" call.
191

HOW IT WORKS

193       (1) For each redirector $stdin, $stdout, and $stderr, "run3()"
194           furnishes a filehandle:
195
196           ·   if the redirector already specifies a filehandle it just uses
197               that
198
199           ·   if the redirector specifies a filename, "run3()" opens the file
200               in the appropriate mode
201
202           ·   in all other cases, "run3()" opens a temporary file (using
203               tempfile)
204
205       (2) If "run3()" opened a temporary file for $stdin in step (1), it
206           writes the data using the specified method (either from a string,
207           an array or returnd by a function) to the temporary file and
208           rewinds it.
209
210       (3) "run3()" saves the parent's "STDIN", "STDOUT" and "STDERR" by
211           duplicating them to new filehandles. It duplicates the filehandles
212           from step (1) to "STDIN", "STDOUT" and "STDERR", resp.
213
214       (4) "run3()" runs the child by invoking system with $cmd as specified
215           above.
216
217       (5) "run3()" restores the parent's "STDIN", "STDOUT" and "STDERR" saved
218           in step (3).
219
220       (6) If "run3()" opened a temporary file for $stdout or $stderr in step
221           (1), it rewinds it and reads back its contents using the specified
222           method (either to a string, an array or by calling a function).
223
224       (7) "run3()" closes all filehandles that it opened explicitly in step
225           (1).
226
227       Note that when using temporary files, "run3()" tries to amortize the
228       overhead by reusing them (i.e. it keeps them open and rewinds and
229       truncates them before the next operation).
230

LIMITATIONS

232       Often uses intermediate files (determined by File::Temp, and thus by
233       the File::Spec defaults and the TMPDIR env. variable) for speed,
234       portability and simplicity.
235
236       Use extrem caution when using "run3" in a threaded environment if
237       concurrent calls of "run3" are possible. Most likely, I/O from
238       different invocations will get mixed up. The reason is that in most
239       thread implementations all threads in a process share the same
240       STDIN/STDOUT/STDERR.  Known failures are Perl ithreads on Linux and
241       Win32. Note that "fork" on Win32 is emulated via Win32 threads and
242       hence I/O mix up is possible between forked children here ("run3" is
243       "fork safe" on Unix, though).
244

DEBUGGING

246       To enable debugging use the IPCRUN3DEBUG environment variable to a non-
247       zero integer value:
248
249         $ IPCRUN3DEBUG=1 myapp
250

PROFILING

252       To enable profiling, set IPCRUN3PROFILE to a number to enable emitting
253       profile information to STDERR (1 to get timestamps, 2 to get a summary
254       report at the END of the program, 3 to get mini reports after each run)
255       or to a filename to emit raw data to a file for later analysis.
256

COMPARISON

258       Here's how it stacks up to existing APIs:
259
260   compared to "system()", "qx''", "open "...|"", "open "|...""
261       ·   better: redirects more than one file descriptor
262
263       ·   better: returns TRUE on success, FALSE on failure
264
265       ·   better: throws an error if problems occur in the parent process (or
266           the pre-exec child)
267
268       ·   better: allows a very perlish interface to Perl data structures and
269           subroutines
270
271       ·   better: allows 1 word invocations to avoid the shell easily:
272
273            run3 ["foo"];  # does not invoke shell
274
275       ·   worse: does not return the exit code, leaves it in $?
276
277   compared to "open2()", "open3()"
278       ·   better: no lengthy, error prone polling/select loop needed
279
280       ·   better: hides OS dependencies
281
282       ·   better: allows SCALAR, ARRAY, and CODE references to source and
283           sink I/O
284
285       ·   better: I/O parameter order is like "open3()"  (not like
286           "open2()").
287
288       ·   worse: does not allow interaction with the subprocess
289
290   compared to IPC::Run::run()
291       ·   better: smaller, lower overhead, simpler, more portable
292
293       ·   better: no select() loop portability issues
294
295       ·   better: does not fall prey to Perl closure leaks
296
297       ·   worse: does not allow interaction with the subprocess (which
298           IPC::Run::run() allows by redirecting subroutines)
299
300       ·   worse: lacks many features of "IPC::Run::run()" (filters, pipes,
301           redirects, pty support)
302
304       Copyright 2003, R. Barrie Slaymaker, Jr., All Rights Reserved
305

LICENSE

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

AUTHOR

311       Barrie Slaymaker <"barries@slaysys.com">
312
313       Ricardo SIGNES <"rjbs@cpan.org"> performed routine maintenance since
314       2010, thanks to help from the following ticket and/or patch submitters:
315       Jody Belka, Roderich Schupp, David Morel, Jeff Lavallee, and anonymous
316       others.
317
318
319
320perl v5.16.3                      2011-12-23                      IPC::Run3(3)
Impressum