NAME
Capture::SystemIO - system() capture stderr, stdout, and signals.
SYNOPSIS
use strict;
use warnings;
use Capture::SystemIO qw(cs_system);
# Run a command; chuck the output.
cs_system("dd if=/dev/zero of=/dev/sda");
# Run a command and capture STDIN and STDOUT; do something with it.
my ($stdin, $stdout) = cs_system("ls -l /bin");
print "ls said: $$stdout \n\n ls also mentioned: $$stderr";
# Run a command and check for errors.
eval {
cs_system("sudo rm -rf /");
};
if (my $e = Exception::Class->Caught("Capture::SystemIO::Interrupt")) {
print "Keyboard interrupt. Signal: " $e->signal();
exit();
} elsif (my $e = Exception::Class->Caught("Capture::SystemIO::Error")) {
print "Stderr: ". $e->stderr()
."Stdout: ". $e->stdout()
."Return code: ". $return_code
."Command: ". $command
} elsif (my $e = Exception::Class->Caught()) {
print "Some other error". $e->stderr();
$e->rethrow();
}DESCRIPTION
Runs a system command from within Perl and captures both STDOUT and STDERR;
provides exception based interface to SIGINT and SIGQUIT;
provides exceptions for non-zero return values.
EXPORTS
Default
none
Optional
cs_system
CLASS METHODS
Capture::SystemIO::cs_system()
This is a wrapper for system() that uses Capture::Tiny::Capture() along with bits and pieces of IO::CaptureOutput, to capture both STDOUT and STDERR. It also checks the return value of system() and throws an exception if the command terminated unexpectedly because of a signal or the command exited with a non-zero result to indicate failure. In which case, the captured STDOUT and STDERR are contained within the exception object.
When used in list context, references to the captured STDOUT and STDERR are returned. In scalar context, however, only numeric exit code for the command is returned.
Example
my ($$stdout,$stderr) = cs_system("true");
my ($return) = cs_system("true");Arguments
See perfunc system for details
Return
The return value depends on the context in which cs_system was called
- Scalar
-
The return code from the call to system
- List
-
References to the captured stderr and stdout
Exceptions
- Capture::SystemIO::Interrupt
-
Thrown if the subprocess terminated as a result of either SIGINT or SIGQUIT
- Capture::SystemIO::Signal
-
Thrown if the subprocess terminated as a result of another signal
- Capture::SystemIO::Error
-
Thrown if the return value of the subprocess is non-zero
EXCEPTIONS
Capture::SystemIO::Error
- $e->stderr()
-
my $stderr = $e->stderr(); - $e->stdout()
-
my $stdout = $e->stdout(); - $e->return_code()
-
my $return_code = $e->return_code(); - $e->command()
-
my $command = $e->command();
Capture::SystemIO::Interrupt
- $e->signal()
-
my $signal = $e->signal();The name signal that caused the subprocess to terminate
- $e->signal_no()
-
my $signal_number = $e->signal_no();The numerical signal that caused the subprocess to terminate
- $e->stdout()
-
Standard output captured before termination
- $e->stdoerr()
-
Returns the Standard error output captured before termination of the subprocess
Capture::SystemIO::Signal
- $e->signal()
-
The name of the signal that caused the subprocess to terminate, if known.
- $e->signal_no()
-
my $signal_number = $e->signal_no();The numerical signal that caused the subprocess to terminate
- $e->stdout()
-
Standard output captured before termination
- $e->stdoerr()
-
Returns the Standard error output captured before termination of the subprocess
TODO
planned
move pre-condition checks from test suite to Makefile.PL
write more tests
test on more systems/platforms
possible
SEE ALSO
Capture::Tiny, Exception::Class, IO::CaptureOutput, "system" in perlfunc, signal(7), "SIGNAL" in Posix
AUTHOR
Rudolf Lippan <rlippan@kolkhoz.org>
LICENSE
You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.
COPYRIGHT
Copyright (c) 2008 - 2010, Remote Linux, Inc. All rights reserved.
Portions Copyright (c) 2009-2010, Public Karma, Inc.
Portions lifted from IO::CaptureOutput; copyright belongs to the respective authors.