except that [perlsub] is really a perl child process with access to main program variables in scope.

DESCRIPTION

This module was written to provide a secure and highly flexible way to execute external programs with an intuitive syntax. In addition, more info is returned with each string of executions, such as the list of PIDs and $? of the last external pipe process (see "RETURN VALUES"). Execution uses exec command, and the shell is never invoked.

The two exported subroutines perform all the heavy lifting of forking and executing processes. In particular, exe( ) implements the KID_TO_READ version of

LIST is exec( ) in the child process after the parent is forked, where the child's stdout is redirected to &READER's stdin. It is optional if &PREEXEC is provided.

&PREEXEC is called right before exec( ) in the child process, so we may reopen filehandles or do some child-only operations beforehand. It is optional if LIST is provided.

&PREEXEC could return a LIST of @REDIRECTS to perform common filehandle redirections and/or modify binmode settings. The @REDIRECTS may be optionally specified (as references) after LIST. Returning these strings (or references to them) will do the following preset actions:

It is important to note that the actions & return of &PREEXEC matters, as it may be used to redirect filehandles before &PREEXEC becomes the exec process. If @REDIRECTS are provided along with &PREEXEC, the filehandle operations returned by &PREEXEC are done first prior to @REDIRECTS, in return-order.

&PREEXEC is called with arguments passed to the CODE reference returned by exe( ).

&READER is called with ($child_pid, LIST) as its arguments. LIST corresponds to the positional arguments passed in-between &PREEXEC and @REDIRECTS.

If exe( )'s are chained, &READER calls itself as the next exe( ) in line, which in turn, calls the next &PREEXEC, LIST, etc.

&READER is always called in the parent process.

&PREEXEC is always called in the child process.

waitpid( $_[0], 0 ) in &READER to set exit status $? of previous process executing on the pipe. close( $IPC::Exe::PIPE ) can also be used to close the input filehandle and set $? at the same time (for Unix platforms only).

bg( )

\%BG_OPTIONS is an optional hash reference to instruct bg( ) to wait a certain amount of time for PREEXEC to complete (for non-Unix platforms only). See "SETTING OPTIONS".

&BACKGROUND is called after it is sent to the init process.

If &BACKGROUND is not a CODE reference, return an empty list upon execution.

bg( ) with no arguments returns an empty list.

This experimental feature is not enabled by default:

Upon failure of background to init process, bg( ) can fallback by calling &BACKGROUND in parent or child process if $IPC::Exe::bg_fallback is true. To enable fallback feature, set

$IPC::Exe::bg_fallback = 1;

SETTING OPTIONS

exe( )

\%EXE_OPTIONS is a hash reference that can be provided as the first argument to exe( ) to control returned values. It may be used to return or assign STDIN / STDERR / STDOUT filehandle(s) of the child process to emulate IPC::Open2 and IPC::Open3 behavior.

Set $pid to the child process PID, given a SCALAR reference. The PID will not be returned as part of the return values of exe( ).

stdin => 1 or stdin => \$TO_STDIN

Return a WRITEHANDLE to STDIN of the child process. The filehandle will be set to autoflush on write if $EXE_OPTIONS{autoflush} is true.

If given a SCALAR reference, set $TO_STDIN to the WRITEHANDLE described above. The WRITEHANDLE then will not be returned as part of the return values of exe( ).

stdout => 1 or stdout => \$FROM_STDOUT

Return a READHANDLE from STDOUT of the child process, so output to stdout may be captured. When this option is set and &READER is not provided, the default &READER subroutine will NOT be called.

If given a SCALAR reference, set $FROM_STDOUT to the READHANDLE described above. The READHANDLE then will not be returned as part of the return values of exe( ).

stderr => 1 or stdout => \$FROM_STDERR

Return a READHANDLE from STDERR of the child process, so output to stderr may be captured.

If given a SCALAR reference, set $FROM_STDERR to the READHANDLE described above. The READHANDLE then will not be returned as part of the return values of exe( ).

autoflush => 0

Disable autoflush on the WRITEHANDLE to STDIN of the child process. This option only has effect when $EXE_OPTIONS{stdin} is true.

binmode_io => ":raw", ":crlf", ":bytes", ":encoding(utf8)", etc.

Set binmode of STDIN and STDOUT of the child process for layer $EXE_OPTIONS{binmode_io}. This is automatically done for subsequently chained exe( )cutions. To stop this, set to an empty string "" or another layer to bring a different mode into effect.

bg( )

NOTE: This only applies to non-Unix platforms.

\%BG_OPTIONS is a hash reference that can be provided as the first argument to bg( ) to set wait time (in seconds) before relinquishing control back to the parent thread. See "CAVEAT" for reasons why this is necessary.

The default value is:

%BG_OPTIONS = (
wait => 2, # Win32 option
);

RETURN VALUES

By chaining exe( ) and bg( ) statements, calling the single returned CODE reference sets off the chain of executions. This returns a LIST in which each element corresponds to each exe( ) or bg( ) call.

exe( )

When exe( ) executes an external process, the PID for that process is returned, or an EMPTY LIST if exe( ) failed in any operation prior to forking. If an EMPTY LIST is returned, the chain of execution stops there and the next &READER is not called, guaranteeing the final return LIST to be truncated at that point. Failure after forking causes die( ) to be called.

When exe( ) executes a &READER subroutine, the subroutine's return value is returned. If there is no explicit &READER, the implicit default &READER subroutine is called instead:

When non-default \%EXE_OPTIONS are specified, each exe( ) returns additional filehandles in the following LIST:

(
$PID, # undef if exec failed
$STDIN_WRITEHANDLE, # only if $EXE_OPTIONS{stdin} is true
$STDOUT_READHANDLE, # only if $EXE_OPTIONS{stdout} is true
$STDERR_READHANDLE, # only if $EXE_OPTIONS{stderr} is true
)

Note: It is necessary to disambiguate \%EXE_OPTIONS (also \%BG_OPTIONS) as a hash reference by including a unary + before the opening curly bracket:

+{ stdin => 1, autoflush => 0 }
+{ wait => 2.5 }

bg( )

Calling the CODE reference returned by bg( )returns the PID of the background process, or an EMPTY LIST if bg( ) failed in any operation prior to forking. Failure after forking causes die( ) to be called.

ERROR CHECKING

To determine if either exe( ) or bg( ) was successful until the point of forking, check whether the returned $PID is defined.

WARNING: This may get a slightly complicated for chained exe( )'s when non-default \%EXE_OPTIONS cause the positions of $PID in the overall returned LIST to be non-uniform (caveat emptor). Remember, the chain of executions is doing a lot for just a single CODE call, so due diligence is required for error checking.

A minimum count of items (PIDs and/or filehandles) can be expected in the returned LIST to determine whether forks were initiated for the entire exe( ) / bg( ) chain.

Failures after forking are responded with die( ). To handle these errors, use eval.

TAINT CHECKING

In taint mode, exe( ) will die if it is called with tainted arguments or environment variables. By default, the following environment variables are checked:

CAVEAT

END { } blocks

Code declared in END blocks will be called upon exit, whether it be after &PREEXEC sub without a LIST command, from a die failure, or even a failed exec call.

The user should make provisions to handle this situation. This is desirable when END blocks must only be called in the main process (or thread).

$IPC::Exe::is_forked is set to true after the code forks in &PREEXEC and &BACKGROUND. It can be used to tell the main process/thread apart from child processes/threads:

END {
# only run in main process/thread
return if $IPC::Exe::is_forked;
### REST OF THE CODE GOES HERE ###
...
}

PLATFORMS

This module is targeted for Unix environments, using techniques described in perlipc and perlfaq8. Development is done on FreeBSD, Linux, and Win32 platforms. It may not work well on other non-Unix systems, let alone Win32.

MSWin32

Some care was taken to rely on Perl's Win32 threaded implementation of fork( ). To get things to work almost like Unix, redirections of filehandles have to be performed in a certain order. More specifically: let's say STDOUT of a child process (read: thread) needs to be redirected elsewhere (anywhere, it doesn't matter). It is important that the parent process (read: thread) does not use STDOUT until after the child is exec'ed. At the point after exec, the parent must restore STDOUT to a previously dup'ed original and may then proceed along as usual. If this order is violated, deadlocks may occur, often manifesting as an apparent stall in execution when the parent tries to use STDOUT.

exe( )

Since fork( ) is emulated with threads, &PREEXEC and &READER really do begin their lives in the same process, but in separate threads. This imposes limitations on how they can be used. One limitation is that, as separate threads, either one MUST NOT block, or else the other thread will not be able to continue.

Writing to, or reading from a pipe will block when the pipe buffer is full or empty, respectively.

Putting the facts together, it means that a pipe writer and reader should not function (as separate threads or otherwise) in the same process for fear that one may block and not let the other continue (a deadlock).

The execution stalls, and the program just hangs there. &PREEXEC is writing out more data than the pipe buffer can fit. Once the buffer is full, print will block to wait for the buffer to be emptied. However, &READER is not able to continue and read off some data from the pipe buffer because it is in the same blocked process. If it were in a separate process (as in a real fork), than a blocking &PREEXEC cannot affect the &READER.

The way to ensure exe( ) works smoothly on Win32 is to exec processes on the pipeline chain. This code will work instead:

Now, &PREEXEC is no longer running in the same process, and cannot affect &READER. If the new perl process blocks, &READER in the original process can still continue to read the pipe.

Writing and reading small amounts of data (to not cause blocking) between &PREEXEC and &READER is possible, but not recommended.

bg( )

On Win32, bg( ) unfortunately has to substantially rely on timer code to wait for &PREEXEC to complete in order to work properly with exe( ). The example shown below illustrates that bg( ) has to wait at least until $program is exec'ed. Hence, $wait_time > $work_time must hold true and this requires a priori knowledge of how long &PREEXEC will take.