IO::CaptureOutput(3pm)

1IO::CaptureOutput(3)  User Contributed Perl Documentation IO::CaptureOutput(3)
2
3
4

NAME

6       IO::CaptureOutput - capture STDOUT and STDERR from Perl code,
7       subprocesses or XS
8

VERSION

10       version 1.1104
11

SYNOPSIS

13           use IO::CaptureOutput qw(capture qxx qxy);
14
15           # STDOUT and STDERR separately
16           capture { noisy_sub(@args) } \$stdout, \$stderr;
17
18           # STDOUT and STDERR together
19           capture { noisy_sub(@args) } \$combined, \$combined;
20
21           # STDOUT and STDERR from external command
22           ($stdout, $stderr, $success) = qxx( @cmd );
23
24           # STDOUT and STDERR together from external command
25           ($combined, $success) = qxy( @cmd );
26

DESCRIPTION

28       This module is no longer recommended by the maintainer - see
29       Capture::Tiny instead.
30
31       This module provides routines for capturing STDOUT and STDERR from perl
32       subroutines, forked system calls (e.g. "system()", "fork()") and from
33       XS or C modules.
34

NAME

FUNCTIONS

37       The following functions will be exported on demand.
38
39   capture()
40           capture \&subroutine, \$stdout, \$stderr;
41
42       Captures everything printed to "STDOUT" and "STDERR" for the duration
43       of &subroutine. $stdout and $stderr are optional scalars that will
44       contain "STDOUT" and "STDERR" respectively.
45
46       "capture()" uses a code prototype so the first argument can be
47       specified directly within brackets if desired.
48
49           # shorthand with prototype
50           capture C< print __PACKAGE__ > \$stdout, \$stderr;
51
52       Returns the return value(s) of &subroutine. The sub is called in the
53       same context as "capture()" was called e.g.:
54
55           @rv = capture C< wantarray > ; # returns true
56           $rv = capture C< wantarray > ; # returns defined, but not true
57           capture C< wantarray >;       # void, returns undef
58
59       "capture()" is able to capture output from subprocesses and C code,
60       which traditional "tie()" methods of output capture are unable to do.
61
62       Note: "capture()" will only capture output that has been written or
63       flushed to the filehandle.
64
65       If the two scalar references refer to the same scalar, then "STDERR"
66       will be merged to "STDOUT" before capturing and the scalar will hold
67       the combined output of both.
68
69           capture \&subroutine, \$combined, \$combined;
70
71       Normally, "capture()" uses anonymous, temporary files for capturing
72       output.  If desired, specific file names may be provided instead as
73       additional options.
74
75           capture \&subroutine, \$stdout, \$stderr, $out_file, $err_file;
76
77       Files provided will be clobbered, overwriting any previous data, but
78       will persist after the call to "capture()" for inspection or other
79       manipulation.
80
81       By default, when no references are provided to hold STDOUT or STDERR,
82       output is captured and silently discarded.
83
84           # Capture STDOUT, discard STDERR
85           capture \&subroutine, \$stdout;
86
87           # Discard STDOUT, capture STDERR
88           capture \&subroutine, undef, \$stderr;
89
90       However, even when using "undef", output can be captured to specific
91       files.
92
93           # Capture STDOUT to a specific file, discard STDERR
94           capture \&subroutine, \$stdout, undef, $outfile;
95
96           # Discard STDOUT, capture STDERR to a specific file
97           capture \&subroutine, undef, \$stderr, undef, $err_file;
98
99           # Discard both, capture merged output to a specific file
100           capture \&subroutine, undef, undef, $mergedfile;
101
102       It is a fatal error to merge STDOUT and STDERR and request separate,
103       specific files for capture.
104
105           # ERROR:
106           capture \&subroutine, \$stdout, \$stdout, $out_file, $err_file;
107           capture \&subroutine, undef, undef, $out_file, $err_file;
108
109       If either STDOUT or STDERR should be passed through to the terminal
110       instead of captured, provide a reference to undef -- "\undef" --
111       instead of a capture variable.
112
113           # Capture STDOUT, display STDERR
114           capture \&subroutine, \$stdout, \undef;
115
116           # Display STDOUT, capture STDERR
117           capture \&subroutine, \undef, \$stderr;
118
119   capture_exec()
120           ($stdout, $stderr, $success, $exit_code) = capture_exec(@args);
121
122       Captures and returns the output from "system(@args)". In scalar
123       context, "capture_exec()" will return what was printed to "STDOUT". In
124       list context, it returns what was printed to "STDOUT" and "STDERR" as
125       well as a success flag and the exit value.
126
127           $stdout = capture_exec('perl', '-e', 'print "hello world"');
128
129           ($stdout, $stderr, $success, $exit_code) =
130               capture_exec('perl', '-e', 'warn "Test"');
131
132       "capture_exec" passes its arguments to "system()" and on MSWin32 will
133       protect arguments with shell quotes if necessary.  This makes it a
134       handy and slightly more portable alternative to backticks, piped
135       "open()" and "IPC::Open3".
136
137       The $success flag returned will be true if the command ran successfully
138       and false if it did not (if the command could not be run or if it ran
139       and returned a non-zero exit value).  On failure, the raw exit value of
140       the "system()" call is available both in the $exit_code returned and in
141       the $? variable.
142
143         ($stdout, $stderr, $success, $exit_code) =
144             capture_exec('perl', '-e', 'warn "Test" and exit 1');
145
146         if ( ! $success ) {
147             print "The exit code was " . ($exit_code >> 8) . "\n";
148         }
149
150       See perlvar for more information on interpreting a child process exit
151       code.
152
153   capture_exec_combined()
154           ($combined, $success, $exit_code) = capture_exec_combined(
155               'perl', '-e', 'print "hello\n"', 'warn "Test\n"
156           );
157
158       This is just like "capture_exec()", except that it merges "STDERR" with
159       "STDOUT" before capturing output.
160
161       Note: there is no guarantee that text printed to "STDOUT" and "STDERR"
162       in the subprocess will be appear in order. The actual order will depend
163       on how IO buffering is handled in the subprocess.
164
165   qxx()
166       This is an alias for "capture_exec()".
167
168   qxy()
169       This is an alias for "capture_exec_combined()".
170

SUPPORT

183   Bugs / Feature Requests
184       Please report any bugs or feature requests through the issue tracker at
185       <https://github.com/dagolden/IO-CaptureOutput/issues>.  You will be
186       notified automatically of any progress on your issue.
187
188   Source Code
189       This is open source software.  The code repository is available for
190       public review and contribution under the terms of the license.
191
192       <https://github.com/dagolden/IO-CaptureOutput>
193
194         git clone https://github.com/dagolden/IO-CaptureOutput.git
195

AUTHORS

197       ·   Simon Flack <simonflk@cpan.org>
198
199       ·   David Golden <dagolden@cpan.org>
200

CONTRIBUTORS

202       ·   Mike Latimer <mlatimer@suse.com>
203
204       ·   Olivier Mengué <dolmen@cpan.org>
205
206       ·   Tony Cook <tony@develop-help.com>
207

COPYRIGHT AND LICENSE

209       This software is copyright (c) 2015 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
215
216perl v5.28.0                      2015-01-24              IO::CaptureOutput(3)