NAME

Proc::Short -- return short system calls with options

SYNOPSIS

   use Proc::Short;

   $myproc = Proc::Short->new();  # create a new process object

   # settings below represent defaults
   $myproc->maxtime(300);         # set final timeout after 5 minutes
   $myproc->num_tries(5);         # try 5 times at most
   $myproc->time_per_try(30);     # time per try 30 sec
   $myproc->time_btw_tries(5);    # time between tries 5 sec

   # additional options
   $myproc->accept_no_error();    # Re-try if any STDERR output
   $myproc->pattern_stdout($pat); # require STDOUT to match regex $pat
   $myproc->pattern_stderr($pat); # require STDERR to match regex $pat
   $myproc->allow_shell(0);       # never use shell for operation
   $myproc->allow_shell(1);       # allowed to use shell for op

   $myproc->run("shell-command-line"); # Launch a shell process
   $myproc->run(sub { ... });          # Launch a perl subroutine
   $myproc->run(\&subroutine);         # Launch a perl subroutine

   Proc::Short::debug($level);         # Turn debug on

DESCRIPTION

The Proc::Short is intended to be an extension of the backticks operator in PERL which incorporates a number of options, including collecting STDOUT and STDERR separately -- plus timeout and automatic retries. A new process object is created by

   $myproc = Proc::Short->new();

The default will timeout after 30 seconds (timeout) for each attempt, will try a process up to 10 times, with 5 seconds between each try. Either shell-like command lines or references to perl subroutines can be specified for launching a process in background. A simple list process, for example, can be started via the shell as

   ($out, $in) = $myproc->run("ls");

or, as a perl subroutine, with

   $myproc->run(sub { return <*>; });

The run Method will try to run the named process. If the process times out (after time_per_try seconds) or has a error defined as unacceptable, it will wait (for time_btw_tries seconds) and try again. This can repeat until maxtime seconds or num_tries tries of the process to be run.

The user can specify what constitutes an unacceptable error of STDOUT or STDERR output -- i.e. demanding a retry. One common shorthand is to have the run method retry if there is any return from STDERR.

   $myproc->accept_no_error();    # Re-try if any STDERR
   $myproc->pattern_stdout($pat); # require STDOUT to match regex $pat
   $myproc->pattern_stderr($pat); # require STDERR to match regex $pat

METHODS

The following methods are available:

new (Constructor)

Create a new instance of this class by writing either

  $proc = new Proc::Short;   or   $proc = Proc::Short->new();

The new method takes no arguments.

findexec

Find where the named executables are in the path, or die if any are not found.

 ($fullpath) = $proc->needexec("ssh");

The needexec method ...

unixhelp

Try various ways to get help on a given executable.

 ($helpmsg) = $proc->unixhelp("ssh");

unixversion

Try various ways to get version number on a given executable.

 ($helpmsg) = $proc->unixhelp("ssh");

run

Run a new process and collect the standard output and standard error via separate pipes. By default, it forks off another process and collects the output when it is done. There is a time limit of

 ($out, $err, $status) = $proc->run("program-name");

There are a number of options. You can start execution of an independent Perl function (like "eval" except with timeout, retries, etc.). Simply provide the function reference like

 ($out, $err, $status) = $proc->run(\&perl_function);

or supply an unnamed subroutine:

 ($out, $err, $status) = $proc->run( sub { sleep(1) } );

The run Method returns after the the function finishes, one way or another.

debug

Switches debug messages on and off -- Proc::Short::debug(1) switches them on, Proc::Short::debug(0) keeps Proc::Short quiet.

accept_no_error

Switches debug messages on and off -- Proc::Short::debug(1) switches them on, Proc::Short::debug(0) keeps Proc::Short quiet.

maxtime Return or set the maximum time in seconds per run method call. Default is 300 seconds (i.e. 5 minutes).

num_tries Return or set the maximum number of tries the run method will attempt an operation if there are unallowed errors. Default is 5.

time_per_try Return or set the maximum time in seconds for each attempt which run makes of an operation. Multiple tries in case of error can go longer than this. Default is 30 seconds.

time_btw_tries Return or set the time in seconds between attempted operations in case of unacceptable error. Default is 5 seconds.

NOTE

This is an attempt to duplicate the ease of use of backticks (``) while allowing additional options like timeout or re-tries in case of error.

Requirements

I'd recommend using at least perl 5.003 -- if you don't have it, this is the time to upgrade! Get 5.005_02 or better.

AUTHORS

John Hanju Kim <jhkim@fnal.gov>