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

Add OO interface for returned output and setting options.

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.

cpanm Capture::SystemIO

perl -MCPAN -e shell
install Capture::SystemIO