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.040
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 com‐
25 mand.)
26 "run3($cmd, $stdin, $stdout, $stderr, \%options)"
28 All parameters after $cmd are optional.
30 The parameters $stdin, $stdout and $stderr indicate how the child's
32 corresponding filehandle ("STDIN", "STDOUT" and "STDERR", resp.) will
33 be redirected. Because the redirects come last, this allows "STDOUT"
34 and "STDERR" to default to the parent's by just not specifying them --
35 a common use case.
36 "run3" returns true if the command executes and throws an exception
38 otherwise. It leaves $? intact for inspection of exit and wait status.
39 $cmd
41 Usually $cmd will be an ARRAY reference and the child is invoked via
43 system @$cmd;
45 But $cmd may also be a string in which case the child is invoked via
47 system $cmd;
49 (cf. "system" in perlfunc for the difference and the pitfalls of using
51 the latter form).
52 $stdin, $stdout, $stderr
54 The parameters $stdin, $stdout and $stderr can take one of the follow‐
56 ing forms:
57 "undef" (or not specified at all)
59 The child inherits the corresponding filehandle from the parent.
60 run3 \@cmd, $stdin; # child writes to same STDOUT and STDERR as parent
62 run3 \@cmd, undef, $stdout, $stderr; # child reads from same STDIN as parent
63 "\undef"
65 The child's filehandle is redirected from or to the local equiva‐
66 lent of "/dev/null" (as returned by "File::Spec->devnull()").
67 run3 \@cmd, \undef, $stdout, $stderr; # child reads from /dev/null
69 a simple scalar
71 The parameter is taken to be the name of a file to read from or
72 write to. In the latter case, the file will be opened via
73 open FH, ">", ...
75 i.e. it is created if it doesn't exist and truncated otherwise.
77 Note that the file is opened by the parent which will croak in case
78 of failure.
79 run3 \@cmd, \undef, "out.txt"; # child writes to file "out.txt"
81 a filehandle (either a reference to a GLOB or an "IO::Handle")
83 The filehandle is inherited by the child.
84 open my $fh, ">", "out.txt";
86 print $fh "prologue\n";
87 ...
88 run3 \@cmd, \undef, $fh; # child writes to $fh
89 ...
90 print $fh "epilogue\n";
91 close $fh;
92 a SCALAR reference
94 The referenced scalar is treated as a string to be read from or
95 written to. In the latter case, the previous content of the string
96 is overwritten.
97 my $out;
99 run3 \@cmd, \undef, \$out; # child writes into string
100 run3 \@cmd, \<<EOF; # child reads from string (can use "here" notation)
101 Input
102 to
103 child
104 EOF
105 an ARRAY reference
107 For $stdin, the elements of @$stdin are simply spooled to the
108 child.
109 For $stdout or $stderr, the child's corresponding file descriptor
111 is read line by line (as determined by the current setting of $/)
112 into @$stdout or @$stderr, resp. The previous content of the array
113 is overwritten.
114 my @lines;
116 run3 \@cmd, \undef, \@lines; # child writes into array
117 a CODE reference
119 For $stdin, &$stdin will be called repeatedly (with no arguments)
120 and the return values are spooled to the child. &$stdin must signal
121 the end of input by returning "undef".
122 For $stdout or $stderr, the child's corresponding file descriptor
124 is read line by line (as determined by the current setting of $/)
125 and &$stdout or &$stderr, resp., is called with the contents of the
126 line. Note that there's no end-of-file indication.
127 my $i = 0;
129 sub producer {
130 return $i < 10 ? "line".$i++."\n" : undef;
131 }
132 run3 \@cmd, \&producer; # child reads 10 lines
134 Note that this form of redirecting the child's I/O doesn't imply
136 any form of concurrency between parent and child - run3()'s method
137 of operation is the same no matter which form of redirection you
138 specify.
139 If the same value is passed for $stdout and $stderr, then the child
141 will write both "STDOUT" and "STDERR" to the same filehandle. In gen‐
142 eral, this means that
143 run3 \@cmd, \undef, "foo.txt", "foo.txt";
145 run3 \@cmd, \undef, \$both, \$both;
146 will DWIM and pass a single file handle to the child for both "STDOUT"
148 and "STDERR", collecting all into file "foo.txt" or $both.
149 "\%options"
151 The last parameter, "\%options", must be a hash reference if present.
153 Currently the following keys are supported:
155 "binmode_stdin", "binmode_stdout", "binmode_stderr"
157 If their value is true then the corresponding parameter $stdin,
158 $stdout or $stderr, resp., operates in "binary" mode (cf. "binmode"
159 in perlfunc). The default is to operate in "text" mode. (This is
160 only relevant for platforms where these modes differ.)
161 "append_stdout", "append_stderr"
163 If their value is true then the corresponding parameter $stdout or
164 $stderr, resp., will append the child's output to the existing
165 "contents" of the redirector. This only makes sense if the redirec‐
166 tor is a simple scalar (the corresponding file is opened in append
167 mode), a SCALAR reference (the output is appended to the previous
168 contents of the string) or an ARRAY reference (the output is
169 "push"ed onto the previous contents of the array).
170
172 (1) For each redirector $stdin, $stdout, and $stderr, "run3()" fur‐
173 nishes a filehandle:
174 * if the redirector already specifies a filehandle it just uses
176 that
177 * if the redirector specifies a filename, "run3()" opens the file
179 in the appropriate mode
180 * in all other cases, "run3()" opens a temporary file (using
182 tempfile)
183 (2) If "run3()" opened a temporary file for $stdin in step (1), it
185 writes the data using the specified method (either from a string,
186 an array or returnd by a function) to the temporary file and
187 rewinds it.
188 (3) "run3()" saves the parent's "STDIN", "STDOUT" and "STDERR" by
190 duplicating them to new filehandles. It duplicates the filehandles
191 from step (1) to "STDIN", "STDOUT" and "STDERR", resp.
192 (4) "run3()" runs the child by invoking system with $cmd as specified
194 above.
195 (5) "run3()" restores the parent's "STDIN", "STDOUT" and "STDERR" saved
197 in step (3).
198 (6) If "run3()" opened a temporary file for $stdout or $stderr in step
200 (1), it rewinds it and reads back its contents using the specified
201 method (either to a string, an array or by calling a function).
202 (7) "run3()" closes all filehandles that it opened explicitly in step
204 (1).
205 Note that when using temporary files, "run3()" tries to amortize the
207 overhead by reusing them (i.e. it keeps them open and rewinds and trun‐
208 cates them before the next operation).
209
211 Often uses intermediate files (determined by File::Temp, and thus by
212 the File::Spec defaults and the TMPDIR env. variable) for speed, porta‐
213 bility and simplicity.
214 Use extrem caution when using "run3" in a threaded environment if con‐
216 current calls of "run3" are possible. Most likely, I/O from different
217 invocations will get mixed up. The reason is that in most thread imple‐
218 mentations all threads in a process share the same STDIN/STDOUT/STDERR.
219 Known failures are Perl ithreads on Linux and Win32. Note that "fork"
220 on Win32 is emulated via Win32 threads and hence I/O mix up is possible
221 between forked children here ("run3" is "fork safe" on Unix, though).
222
224 To enable debugging use the IPCRUN3DEBUG environment variable to a non-
225 zero integer value:
226 $ IPCRUN3DEBUG=1 myapp
228
230 To enable profiling, set IPCRUN3PROFILE to a number to enable emitting
231 profile information to STDERR (1 to get timestamps, 2 to get a summary
232 report at the END of the program, 3 to get mini reports after each run)
233 or to a filename to emit raw data to a file for later analysis.
234
236 Here's how it stacks up to existing APIs:
237 compared to "system()", "qx''", "open "...⎪"", "open "⎪...""
239 + redirects more than one file descriptor
241 + returns TRUE on success, FALSE on failure
243 + throws an error if problems occur in the parent process (or the
245 pre-exec child)
246 + allows a very perlish interface to Perl data structures and subrou‐
248 tines
249 + allows 1 word invocations to avoid the shell easily:
251 run3 ["foo"]; # does not invoke shell
253 - does not return the exit code, leaves it in $?
255 compared to "open2()", "open3()"
257 + no lengthy, error prone polling/select loop needed
259 + hides OS dependancies
261 + allows SCALAR, ARRAY, and CODE references to source and sink I/O
263 + I/O parameter order is like "open3()" (not like "open2()").
265 - does not allow interaction with the subprocess
267 compared to IPC::Run::run()
269 + smaller, lower overhead, simpler, more portable
271 + no select() loop portability issues
273 + does not fall prey to Perl closure leaks
275 - does not allow interaction with the subprocess (which
277 IPC::Run::run() allows by redirecting subroutines)
278 - lacks many features of "IPC::Run::run()" (filters, pipes, redi‐
280 rects, pty support)
281
283 Copyright 2003, R. Barrie Slaymaker, Jr., All Rights Reserved
284
286 You may use this module under the terms of the BSD, Artistic, or GPL
287 licenses, any version.
288
290 Barrie Slaymaker <"barries@slaysys.com">
291 Ricardo SIGNES <"rjbs@cpan.org"> performed some routine maintenance in
293 2005, thanks to help from the following ticket and/or patch submitters:
294 Jody Belka, Roderich Schupp, David Morel, and anonymous others.
295perl v5.8.8 2007-10-08 IPC::Run3(3)