John Eaglesham > Spawn-Safe-2.006 > Spawn::Safe

Download:
Spawn-Safe-2.006.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 2.006   Source  

NAME ^

Spawn::Safe - Fork and exec a process "safely".

EXAMPLE ^

A basic example:

 use Spawn::Safe;
 use Data::Dumper;
 my $results = spawn_safe({ argv => [ 'ls', '-al', '/var/' ], timeout => 2 });
 die Dumper $results;

As a replacement for backticks:

 use Spawn::Safe;
 # $output = `ls -al /var/`;
 $output = spawn_safe(qw{ ls -al /var/ })->{stdout};

SYNOPSIS ^

Spawn::Safe is a module designed to make "safe" calls to outside binaries easier and more reliable. Spawn::Safe never invokes a shell (unless the shell is explicitly requested), so escaping for the shell is not a concern. An optional timeout is made available, so scripts will not hang forever, and the caller is able to retrieve both stdout and stderr. An optional string can be passed to the executed program's standard input stream.

FUNCTIONS ^

spawn_safe

Spawn (via fork and exec) the specified binary and capture its output.

Parameters

If passed a single scalar, spawn_safe will assume that to be the the target binary, and execute it without a limit on runtime.

If passed an array, spawn_safe will execute the first element of the array as the target binary, with the remaining elements passed as parameters to the target binary, without a limit on runtime.

The preferred mode is to pass in a single hash reference. When called this way, the following keys are available:

Return value

A hash reference will be returned containing one of the following sets of values:

The key "exit_zero" will always be present, which is true if the binary is executed successfully and exited with a code of zero.

Notes

The current PATH will be searched for the binary, if available. Open filehandles are subject to Perl's standard close-on-exec behavior. A shell will not be invoked unless explicitly defined as the target binary, as such output redirection and other shell features are unavailable.

If passed invalid parameters, spawn_safe will croak.

Please note that when specifying a timeout, alarm() is no longer used. If the clock is stepped significantly backwards during a timeout, a possibly false timeout error may be thrown. Timeout accuracy should be within one second.

If a timeout does occur, the spawned program will be sent a SIGKILL before spawn_safe returns.

COMPATIBILITY ^

This module attempts to work on MSWin32 but I've been unable to get it working due to strange issues with IO::Select. I haven't been able to track down the exact cause, so for now I don't believe this module functions on MSWin32.

Linux and BSD are tested and supported platforms.

LICENSE ^

This module is licensed under the same terms as Perl itself.

CHANGES ^

Version 2.006 - 2013-11-12, jeagle

Modify PIPE_BUF_SIZE to be more conservative to ensure non-blocking writes on all OSs.

Version 2.005 - 2013-11-11, jeagle

Add stdin option, clarify docs, add exit_zero return flag.

Version 2.004 - 2012-08-13, jeagle

Include license. Oops.

Version 2.003 - 2012-04-01, jeagle

Untie any tied filehandles before we re-open them to ourselves to work around any weird tie behavior (should fix issues running under FCGI). Thanks Charly.

Version 2.002 - 2012-01-04, jeagle

Correct documentation (RT#72831, thanks Stas)

Update unit tests to specify number of tests instead of using no_plan, otherwse CPAN Testers reports tests fail.

Version 2.001 - 2011-06-13, jeagle

Give the spawned program its own STDIN.

Version 2.000 - 2011-05-12, jeagle

Correct timeout handling. Attempt to correct unit tests for MSWin32, but there seems to be an issue with IO::Select preventing it from working properly. Update docs for MSWin32.

Version 1.9 - 2011-05-10, jeagle

Don't use clock_gettime(), use time() and return a timeout if time steps backwards.

Version 1.8 - 2011-05-09, jeagle

Clean up docs, stop using SIGALARM for timeouts.

Version 1.7 - 2010-07-09, jeagle

Clean up for release to CPAN.

Version 0.4 - 2009-05-13, jeagle

Correct a warning issued when using spawn_safe without a timeout.

Fix compatibility with perl < 5.8.

Version 0.3 - 2009-04-21, jeagle

Clarify documentation regarding use of SIGALRM and for passing of a new environment.

Correct a warning thrown by exec().

Correct an issue with incorrectly handled timeouts.

Version 0.2 - 2009-04-20, jeagle

Modify API, breaking compatibility, for clarity and expandability.

Add the ability to specify the target program's environment.

Return the (partial) stdout and stderr on a timeout.

Update and clarify documentation.

Version 0.1 - 2009-04-11, jeagle

Inital release.

syntax highlighting: