1NAME
2 IO::CaptureOutput - (DEPRECATED) capture STDOUT and STDERR from Perl
3 code, subprocesses or XS
4
5VERSION
6 version 1.1105
7
8SYNOPSIS
9 use IO::CaptureOutput qw(capture qxx qxy);
10
11 # STDOUT and STDERR separately
12 capture { noisy_sub(@args) } \$stdout, \$stderr;
13
14 # STDOUT and STDERR together
15 capture { noisy_sub(@args) } \$combined, \$combined;
16
17 # STDOUT and STDERR from external command
18 ($stdout, $stderr, $success) = qxx( @cmd );
19
20 # STDOUT and STDERR together from external command
21 ($combined, $success) = qxy( @cmd );
22
23DESCRIPTION
24 This module is no longer recommended by the maintainer - see
25 Capture::Tiny instead.
26
27 This module provides routines for capturing STDOUT and STDERR from perl
28 subroutines, forked system calls (e.g. "system()", "fork()") and from XS
29 or C modules.
30
31NAME
32FUNCTIONS
33 The following functions will be exported on demand.
34
35 capture()
36 capture \&subroutine, \$stdout, \$stderr;
37
38 Captures everything printed to "STDOUT" and "STDERR" for the duration of
39 &subroutine. $stdout and $stderr are optional scalars that will contain
40 "STDOUT" and "STDERR" respectively.
41
42 "capture()" uses a code prototype so the first argument can be specified
43 directly within brackets if desired.
44
45 # shorthand with prototype
46 capture C< print __PACKAGE__ > \$stdout, \$stderr;
47
48 Returns the return value(s) of &subroutine. The sub is called in the
49 same context as "capture()" was called e.g.:
50
51 @rv = capture C< wantarray > ; # returns true
52 $rv = capture C< wantarray > ; # returns defined, but not true
53 capture C< wantarray >; # void, returns undef
54
55 "capture()" is able to capture output from subprocesses and C code,
56 which traditional "tie()" methods of output capture are unable to do.
57
58 Note: "capture()" will only capture output that has been written or
59 flushed to the filehandle.
60
61 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 the
63 combined output of both.
64
65 capture \&subroutine, \$combined, \$combined;
66
67 Normally, "capture()" uses anonymous, temporary files for capturing
68 output. If desired, specific file names may be provided instead as
69 additional options.
70
71 capture \&subroutine, \$stdout, \$stderr, $out_file, $err_file;
72
73 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
77 By default, when no references are provided to hold STDOUT or STDERR,
78 output is captured and silently discarded.
79
80 # Capture STDOUT, discard STDERR
81 capture \&subroutine, \$stdout;
82
83 # Discard STDOUT, capture STDERR
84 capture \&subroutine, undef, \$stderr;
85
86 However, even when using "undef", output can be captured to specific
87 files.
88
89 # Capture STDOUT to a specific file, discard STDERR
90 capture \&subroutine, \$stdout, undef, $outfile;
91
92 # Discard STDOUT, capture STDERR to a specific file
93 capture \&subroutine, undef, \$stderr, undef, $err_file;
94
95 # Discard both, capture merged output to a specific file
96 capture \&subroutine, undef, undef, $mergedfile;
97
98 It is a fatal error to merge STDOUT and STDERR and request separate,
99 specific files for capture.
100
101 # ERROR:
102 capture \&subroutine, \$stdout, \$stdout, $out_file, $err_file;
103 capture \&subroutine, undef, undef, $out_file, $err_file;
104
105 If either STDOUT or STDERR should be passed through to the terminal
106 instead of captured, provide a reference to undef -- "\undef" -- instead
107 of a capture variable.
108
109 # Capture STDOUT, display STDERR
110 capture \&subroutine, \$stdout, \undef;
111
112 # Display STDOUT, capture STDERR
113 capture \&subroutine, \undef, \$stderr;
114
115 capture_exec()
116 ($stdout, $stderr, $success, $exit_code) = capture_exec(@args);
117
118 Captures and returns the output from "system(@args)". In scalar context,
119 "capture_exec()" will return what was printed to "STDOUT". In list
120 context, it returns what was printed to "STDOUT" and "STDERR" as well as
121 a success flag and the exit value.
122
123 $stdout = capture_exec('perl', '-e', 'print "hello world"');
124
125 ($stdout, $stderr, $success, $exit_code) =
126 capture_exec('perl', '-e', 'warn "Test"');
127
128 "capture_exec" passes its arguments to "system()" and on MSWin32 will
129 protect arguments with shell quotes if necessary. This makes it a handy
130 and slightly more portable alternative to backticks, piped "open()" and
131 "IPC::Open3".
132
133 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
139 ($stdout, $stderr, $success, $exit_code) =
140 capture_exec('perl', '-e', 'warn "Test" and exit 1');
141
142 if ( ! $success ) {
143 print "The exit code was " . ($exit_code >> 8) . "\n";
144 }
145
146 See perlvar for more information on interpreting a child process exit
147 code.
148
149 capture_exec_combined()
150 ($combined, $success, $exit_code) = capture_exec_combined(
151 'perl', '-e', 'print "hello\n"', 'warn "Test\n"
152 );
153
154 This is just like "capture_exec()", except that it merges "STDERR" with
155 "STDOUT" before capturing output.
156
157 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
161 qxx()
162 This is an alias for "capture_exec()".
163
164 qxy()
165 This is an alias for "capture_exec_combined()".
166
167SEE ALSO
168 * Capture::Tiny
169
170 * IPC::Open3
171
172 * IO::Capture
173
174 * IO::Utils
175
176 * IPC::System::Simple
177
178SUPPORT
179 Bugs / Feature Requests
180 Please report any bugs or feature requests through the issue tracker at
181 <https://github.com/dagolden/IO-CaptureOutput/issues>. You will be
182 notified automatically of any progress on your issue.
183
184 Source Code
185 This is open source software. The code repository is available for
186 public review and contribution under the terms of the license.
187
188 <https://github.com/dagolden/IO-CaptureOutput>
189
190 git clone https://github.com/dagolden/IO-CaptureOutput.git
191
192AUTHORS
193 * Simon Flack <simonflk@cpan.org>
194
195 * David Golden <dagolden@cpan.org>
196
197CONTRIBUTORS
198 * David Golden <xdg@xdg.me>
199
200 * José Joaquín Atria <jjatria@gmail.com>
201
202 * Mike Latimer <mlatimer@suse.com>
203
204 * Olivier Mengué <dolmen@cpan.org>
205
206 * Tony Cook <tony@develop-help.com>
207
208COPYRIGHT AND LICENSE
209 This software is copyright (c) 2019 by Simon Flack and David Golden.
210
211 This is free software; you can redistribute it and/or modify it under
212 the same terms as the Perl 5 programming language system itself.
213
214