1IO::CaptureOutput(3) User Contributed Perl Documentation IO::CaptureOutput(3)
2
6 IO::CaptureOutput - capture STDOUT and STDERR from Perl code,
7 subprocesses or XS
8
10 This documentation describes version 1.1102.
11
13 use IO::CaptureOutput qw(capture qxx qxy);
14 # STDOUT and STDERR separately
16 capture { noisy_sub(@args) } \$stdout, \$stderr;
17 # STDOUT and STDERR together
19 capture { noisy_sub(@args) } \$combined, \$combined;
20 # STDOUT and STDERR from external command
22 ($stdout, $stderr, $success) = qxx( @cmd );
23 # STDOUT and STDERR together from external command
25 ($combined, $success) = qxy( @cmd );
26
28 This module provides routines for capturing STDOUT and STDERR from perl
29 subroutines, forked system calls (e.g. "system()", "fork()") and from
30 XS or C modules.
31
33 The following functions will be exported on demand.
34 capture()
36 capture \&subroutine, \$stdout, \$stderr;
37 Captures everything printed to "STDOUT" and "STDERR" for the duration
39 of &subroutine. $stdout and $stderr are optional scalars that will
40 contain "STDOUT" and "STDERR" respectively.
41 "capture()" uses a code prototype so the first argument can be
43 specified directly within brackets if desired.
44 # shorthand with prototype
46 capture { print __PACKAGE__ } \$stdout, \$stderr;
47 Returns the return value(s) of &subroutine. The sub is called in the
49 same context as "capture()" was called e.g.:
50 @rv = capture { wantarray } ; # returns true
52 $rv = capture { wantarray } ; # returns defined, but not true
53 capture { wantarray }; # void, returns undef
54 "capture()" is able to capture output from subprocesses and C code,
56 which traditional "tie()" methods of output capture are unable to do.
57 Note: "capture()" will only capture output that has been written or
59 flushed to the filehandle.
60 If the two scalar references refer to the same scalar, then "STDERR"
62 will be merged to "STDOUT" before capturing and the scalar will hold
63 the combined output of both.
64 capture \&subroutine, \$combined, \$combined;
66 Normally, "capture()" uses anonymous, temporary files for capturing
68 output. If desired, specific file names may be provided instead as
69 additional options.
70 capture \&subroutine, \$stdout, \$stderr, $out_file, $err_file;
72 Files provided will be clobbered, overwriting any previous data, but
74 will persist after the call to "capture()" for inspection or other
75 manipulation.
76 By default, when no references are provided to hold STDOUT or STDERR,
78 output is captured and silently discarded.
79 # Capture STDOUT, discard STDERR
81 capture \&subroutine, \$stdout;
82 # Discard STDOUT, capture STDERR
84 capture \&subroutine, undef, \$stderr;
85 However, even when using "undef", output can be captured to specific
87 files.
88 # Capture STDOUT to a specific file, discard STDERR
90 capture \&subroutine, \$stdout, undef, $outfile;
91 # Discard STDOUT, capture STDERR to a specific file
93 capture \&subroutine, undef, \$stderr, undef, $err_file;
94 # Discard both, capture merged output to a specific file
96 capture \&subroutine, undef, undef, $mergedfile;
97 It is a fatal error to merge STDOUT and STDERR and request separate,
99 specific files for capture.
100 # ERROR:
102 capture \&subroutine, \$stdout, \$stdout, $out_file, $err_file;
103 capture \&subroutine, undef, undef, $out_file, $err_file;
104 If either STDOUT or STDERR should be passed through to the terminal
106 instead of captured, provide a reference to undef -- "\undef" --
107 instead of a capture variable.
108 # Capture STDOUT, display STDERR
110 capture \&subroutine, \$stdout, \undef;
111 # Display STDOUT, capture STDERR
113 capture \&subroutine, \undef, \$stderr;
114 capture_exec()
116 ($stdout, $stderr, $success, $exit_code) = capture_exec(@args);
117 Captures and returns the output from "system(@args)". In scalar
119 context, "capture_exec()" will return what was printed to "STDOUT". In
120 list context, it returns what was printed to "STDOUT" and "STDERR" as
121 well as a success flag and the exit value.
122 $stdout = capture_exec('perl', '-e', 'print "hello world"');
124 ($stdout, $stderr, $success, $exit_code) =
126 capture_exec('perl', '-e', 'warn "Test"');
127 "capture_exec" passes its arguments to "system()" and on MSWin32 will
129 protect arguments with shell quotes if necessary. This makes it a
130 handy and slightly more portable alternative to backticks, piped
131 "open()" and "IPC::Open3".
132 The $success flag returned will be true if the command ran successfully
134 and false if it did not (if the command could not be run or if it ran
135 and returned a non-zero exit value). On failure, the raw exit value of
136 the "system()" call is available both in the $exit_code returned and in
137 the $? variable.
138 ($stdout, $stderr, $success, $exit_code) =
140 capture_exec('perl', '-e', 'warn "Test" and exit 1');
141 if ( ! $success ) {
143 print "The exit code was " . ($exit_code >> 8) . "\n";
144 }
145 See perlvar for more information on interpreting a child process exit
147 code.
148 capture_exec_combined()
150 ($combined, $success, $exit_code) = capture_exec_combined(
151 'perl', '-e', 'print "hello\n"', 'warn "Test\n"
152 );
153 This is just like "capture_exec()", except that it merges "STDERR" with
155 "STDOUT" before capturing output.
156 Note: there is no guarantee that text printed to "STDOUT" and "STDERR"
158 in the subprocess will be appear in order. The actual order will depend
159 on how IO buffering is handled in the subprocess.
160 qxx()
162 This is an alias for "capture_exec()".
163 qxy()
165 This is an alias for "capture_exec_combined()".
166
168 · IPC::Open3
169 · IO::Capture
171 · IO::Utils
173 · IPC::System::Simple
175
177 · Simon Flack <simonflk _AT_ cpan.org> (original author)
178 · David Golden <dagolden _AT_ cpan.org> (co-maintainer since version
180 1.04)
181
183 Portions copyright 2004, 2005 Simon Flack. Portions copyright 2007,
184 2008 David Golden. All rights reserved.
185 You may distribute under the terms of either the GNU General Public
187 License or the Artistic License, as specified in the Perl README file.
188perl v5.16.3 2010-02-15 IO::CaptureOutput(3)