NAME

System2 - like system(), but with access to STDOUT and STDERR.

SYNOPSIS

  use System2;

  $System2::debug++;

  my ($out, $err) = system2(@args);

  my ($exit_value, $signal_num, $dumped_core) = &System2::exit_status($?);
  
  print "EXIT: exit_value $exit_value signal_num ".
        "$signal_num dumped_core $dumped_core\n";
  
  print "OUT:\n$out";
  print "ERR:\n$err"

DESCRIPTION

The module presents an interface for executing a command, and gathering the output from STDOUT and STDERR.

Benefits of this interface:

-

the Bourne shell is never implicitly invoked: saves a stray exec(), and bypasses those nasty shell quoting problems.

-

cheaper to run than open3().

-

augmented processing of arguments, to allow for overriding arg[0] (eg. initiating a login shell).

STDOUT and STDERR are returned in scalars. $? is set. (Split on $/ if you want the expected lines back.)

If $debug is set, on-the fly diagnostics will be reported about how much data is being read.

Provides for convenience, a routine exit_status() to break out the exit value into separate scalars, straight from perlvar(1):

-

the exit value of the subprocess

-

which signal, if any, the process died from

-

reports whether there was a core dump.

There are two interfaces available: a regular list, or named parameters:

These are equivalent:

  my @args = ( '/bin/sh', '-x', '-c', 'echo $0' );

  my @args = ( path => '/bin/sh', args => [ '-c', 'echo $0' ] );

To override arg[0], pass in a arrayref for the first argument, or use the arg0 named parameter. Contrast the prior argument lists with these below:

  my @args = ( ['/bin/sh', '-sh'], '-c', 'echo $0' );

  my @args = ( path => '/bin/sh', args => ['-c', 'echo $0'],
               arg0 => '-sh' );

CAVEATS

Obviously, the returned scalars can be quite large, depending on the nature of the program being run. In the future, I intend to introduce options to allow for temporary file handles, but for now, be aware of the potential resource usage.

AUTHOR

Brian Reichert <reichert@numachi.com>

SEE ALSO

perlfunc(1), perlvar(1).