1IPC::Run3(3) User Contributed Perl Documentation IPC::Run3(3)
2
6 IPC::Run3 - run a subprocess with input/ouput redirection
7
9 version 0.048
10
12 use IPC::Run3; # Exports run3() by default
13 run3 \@cmd, \$in, \$out, \$err;
15
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 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 "run3($cmd, $stdin, $stdout, $stderr, \%options)"
28 All parameters after $cmd are optional.
29 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 "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 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 See "%options" for an option to handle the case of "system" returning
45 -1 yourself.
46 $cmd
48 Usually $cmd will be an ARRAY reference and the child is invoked via
50 system @$cmd;
52 But $cmd may also be a string in which case the child is invoked via
54 system $cmd;
56 (cf. "system" in perlfunc for the difference and the pitfalls of using
58 the latter form).
59 $stdin, $stdout, $stderr
61 The parameters $stdin, $stdout and $stderr can take one of the
63 following forms:
64 "undef" (or not specified at all)
66 The child inherits the corresponding filehandle from the parent.
67 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 "\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 run3 \@cmd, \undef, $stdout, $stderr; # child reads from /dev/null
76 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 open FH, ">", ...
82 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 run3 \@cmd, \undef, "out.txt"; # child writes to file "out.txt"
88 a filehandle (either a reference to a GLOB or an "IO::Handle")
90 The filehandle is inherited by the child.
91 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 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 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 an ARRAY reference
114 For $stdin, the elements of @$stdin are simply spooled to the
115 child.
116 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 my @lines;
123 run3 \@cmd, \undef, \@lines; # child writes into array
124 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 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 my $i = 0;
136 sub producer {
137 return $i < 10 ? "line".$i++."\n" : undef;
138 }
139 run3 \@cmd, \&producer; # child reads 10 lines
141 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 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 run3 \@cmd, \undef, "foo.txt", "foo.txt";
152 run3 \@cmd, \undef, \$both, \$both;
153 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 "\%options"
158 The last parameter, "\%options", must be a hash reference if present.
160 Currently the following keys are supported:
162 "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 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 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 "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 "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
193 (1) For each redirector $stdin, $stdout, and $stderr, "run3()"
194 furnishes a filehandle:
195 • if the redirector already specifies a filehandle it just uses
197 that
198 • if the redirector specifies a filename, "run3()" opens the file
200 in the appropriate mode
201 • in all other cases, "run3()" opens a temporary file (using
203 tempfile)
204 (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 returned by a function) to the temporary file and
208 rewinds it.
209 (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 (4) "run3()" runs the child by invoking system with $cmd as specified
215 above.
216 (5) "run3()" restores the parent's "STDIN", "STDOUT" and "STDERR" saved
218 in step (3).
219 (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 (7) "run3()" closes all filehandles that it opened explicitly in step
225 (1).
226 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
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 Use extreme 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
246 To enable debugging use the IPCRUN3DEBUG environment variable to a non-
247 zero integer value:
248 $ IPCRUN3DEBUG=1 myapp
250
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
258 Here's how it stacks up to existing APIs:
259 compared to "system()", "qx''", "open "...|"", "open "|...""
261 • better: redirects more than one file descriptor
262 • better: returns TRUE on success, FALSE on failure
264 • better: throws an error if problems occur in the parent process (or
266 the pre-exec child)
267 • better: allows a very perlish interface to Perl data structures and
269 subroutines
270 • better: allows 1 word invocations to avoid the shell easily:
272 run3 ["foo"]; # does not invoke shell
274 • worse: does not return the exit code, leaves it in $?
276 compared to "open2()", "open3()"
278 • better: no lengthy, error prone polling/select loop needed
279 • better: hides OS dependencies
281 • better: allows SCALAR, ARRAY, and CODE references to source and
283 sink I/O
284 • better: I/O parameter order is like "open3()" (not like
286 "open2()").
287 • worse: does not allow interaction with the subprocess
289 compared to IPC::Run::run()
291 • better: smaller, lower overhead, simpler, more portable
292 • better: no select() loop portability issues
294 • better: does not fall prey to Perl closure leaks
296 • worse: does not allow interaction with the subprocess (which
298 IPC::Run::run() allows by redirecting subroutines)
299 • 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
307 You may use this module under the terms of the BSD, Artistic, or GPL
308 licenses, any version.
309
311 Barrie Slaymaker <"barries@slaysys.com">
312 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.
317perl v5.32.1 2021-01-27 IPC::Run3(3)