Provided by: libproc-background-perl_1.21-1_all 
NAME
Proc::Background - Generic interface to background process management
VERSION
version 1.21
SYNOPSIS
use Proc::Background;
timeout_system($seconds, $command, $arg1);
timeout_system($seconds, "$command $arg1");
my $proc1 = Proc::Background->new($command, $arg1, $arg2);
my $proc2 = Proc::Background->new("$command $arg1 1>&2");
$proc1->alive;
$proc1->die;
$proc1->wait;
my $time1 = $proc1->start_time;
my $time2 = $proc1->end_time;
# Add an option to kill the process with die when the variable is
# DESTROYed.
my $opts = {'die_upon_destroy' => 1};
my $proc3 = Proc::Background->new($opts, $command, $arg1, $arg2);
$proc3 = undef;
DESCRIPTION
This is a generic interface for placing processes in the background on both Unix and Win32
platforms. This module lets you start, kill, wait on, retrieve exit values, and see if
background processes still exist.
NAME
Proc::Background - Generic interface to Unix and Win32 background process management
METHODS
new [options] command, [arg, [arg, ...]]
new [options] 'command [arg [arg ...]]'
This creates a new background process. As exec() or system() may be passed an array
with a single single string element containing a command to be passed to the shell or
an array with more than one element to be run without calling the shell, new has the
same behavior.
In certain cases new will attempt to find command on the system and fail if it cannot
be found.
For Win32 operating systems:
The Win32::Process module is always used to spawn background
processes on the Win32 platform. This module always takes a
single string argument containing the executable's name and
any option arguments. In addition, it requires that the
absolute path to the executable is also passed to it. If
only a single argument is passed to new, then it is split on
whitespace into an array and the first element of the split
array is used at the executable's name. If multiple
arguments are passed to new, then the first element is used
as the executable's name.
If the executable's name is an absolute path, then new
checks to see if the executable exists in the given location
or fails otherwise. If the executable's name is not
absolute, then the executable is searched for using the PATH
environmental variable. The input executable name is always
replaced with the absolute path determined by this process.
In addition, when searching for the executable, the
executable is searched for using the unchanged executable
name and if that is not found, then it is checked by
appending `.exe' to the name in case the name was passed
without the `.exe' suffix.
Finally, the argument array is placed back into a single
string and passed to Win32::Process::Create.
For non-Win32 operating systems, such as Unix:
If more than one argument is passed to new, then new
assumes that the command will not be passed through the
shell and the first argument is the executable's relative
or absolute path. If the first argument is an absolute
path, then it is checked to see if it exists and can be
run, otherwise new fails. If the path is not absolute,
then the PATH environmental variable is checked to see if
the executable can be found. If the executable cannot be
found, then new fails. These steps are taking to prevent
exec() from failing after an fork() without the caller of
new knowing that something failed.
The first argument to new options may be a reference to a hash which contains
key/value pairs to modify Proc::Background's behavior. Currently the only key
understood by new is die_upon_destroy. When this value is set to true, then when the
Proc::Background object is being DESTROY'ed for any reason (i.e. the variable goes out
of scope) the process is killed via the die() method.
If anything fails, then new returns an empty list in a list context, an undefined
value in a scalar context, or nothing in a void context.
pid Returns the process ID of the created process. This value is saved even if the
process has already finished.
alive
Return 1 if the process is still active, 0 otherwise.
die, die(@kill_sequence)
Reliably try to kill the process. Returns 1 if the process no longer exists once die
has completed, 0 otherwise. This will also return 1 if the process has already died.
@kill_sequence is a list of actions and seconds-to-wait for that action to end the
process. The default is " TERM 2 TERM 8 KILL 3 KILL 7 ". On Unix this sends SIGTERM
and SIGKILL; on Windows it just calls TerminateProcess (graceful termination is still
a TODO).
Note that "die()" on Proc::Background 1.10 and earlier on Unix called a sequence of:
->die( ( HUP => 1 )x5, ( QUIT => 1 )x5, ( INT => 1 )x5, ( KILL => 1 )x5 );
which didn't particularly make a lot of sense, since SIGHUP is open to interpretation,
and QUIT is almost always immediately fatal and generates an unneeded coredump. The
new default should accomodate programs that acknowledge a second SIGTERM, and give
enough time for it to exit on a laggy system while still not holding up the main
script too much.
wait
$exit= $proc->wait; # blocks forever
$exit= $proc->wait($timeout_seconds); # since version 1.20
Wait for the process to exit. Return the exit status of the command as returned by
wait() on the system. To get the actual exit value, divide by 256 or right bit shift
by 8, regardless of the operating system being used. If the process never existed,
this returns undef. This function may be called multiple times even after the process
has exited and it will return the same exit status.
Since version 1.20, you may pass an optional argument of the number of seconds to wait
for the process to exit. This may be fractional, and if it is zero then the wait will
be non-blocking. Note that on Unix this is implemented with "alarm" in Time::HiRes
before a call to wait(), so it may not be compatible with scripts that use alarm() for
other purposes, or systems/perls that resume system calls after a signal. In the
event of a timeout, the return will be undef.
exit_code
Returns the exit code of the process, assuming it exited cleanly. Returns "undef" if
the process has not exited yet, and 0 if the process exited with a signal (or
TerminateProcess). Since 0 is ambiguous, check for "exit_signal" first.
exit_signal
Returns the value of the signal the process exited with, assuming it died on a signal.
Returns "undef" if it has not exited yet, and 0 if it did not die to a signal.
start_time
Return the value that the Perl function time() returned when the process was started.
end_time
Return the value that the Perl function time() returned when the exit status was
obtained from the process.
FUNCTIONS
timeout_system timeout, command, [arg, [arg...]]
timeout_system 'timeout command [arg [arg...]]'
Run a command for timeout seconds and if the process did not exit, then kill it.
While the timeout is implemented using sleep(), this function makes sure that the full
timeout is reached before killing the process. timeout_system does not wait for the
complete timeout number of seconds before checking if the process has exited. Rather,
it sleeps repeatidly for 1 second and checks to see if the process still exists.
In a scalar context, timeout_system returns the exit status from the process. In an
array context, timeout_system returns a two element array, where the first element is
the exist status from the process and the second is set to 1 if the process was killed
by timeout_system or 0 if the process exited by itself.
The exit status is the value returned from the wait() call. If the process was
killed, then the return value will include the killing of it. To get the actual exit
value, divide by 256.
If something failed in the creation of the process, the subroutine returns an empty
list in a list context, an undefined value in a scalar context, or nothing in a void
context.
IMPLEMENTATION
Proc::Background comes with two modules, Proc::Background::Unix and
Proc::Background::Win32. Currently, on Unix platforms Proc::Background uses the
Proc::Background::Unix class and on Win32 platforms it uses Proc::Background::Win32, which
makes use of Win32::Process.
The Proc::Background assigns to @ISA either Proc::Background::Unix or
Proc::Background::Win32, which does the OS dependent work. The OS independent work is
done in Proc::Background.
Proc::Background uses two variables to keep track of the process. $self->{_os_obj}
contains the operating system object to reference the process. On a Unix systems this is
the process id (pid). On Win32, it is an object returned from the Win32::Process class.
When $self->{_os_obj} exists, then the process is running. When the process dies, this is
recorded by deleting $self->{_os_obj} and saving the exit value $self->{_exit_value}.
Anytime alive is called, a waitpid() is called on the process and the return status, if
any, is gathered and saved for a call to wait. This module does not install a signal
handler for SIGCHLD. If for some reason, the user has installed a signal handler for
SIGCHLD, then, then when this module calls waitpid(), the failure will be noticed and
taken as the exited child, but it won't be able to gather the exit status. In this case,
the exit status will be set to 0.
SEE ALSO
IPC::Run
IPC::Run is a much more complete solution for running child processes. It handles
dozens of forms of redirection and pipe pumping, and should probably be your first
stop for any complex needs.
However, also note the very large and slightly alarming list of limitations it lists
for Win32. Proc::Background is a much simpler design and should be more reliable for
simple needs.
Win32::ShellQuote
If you are running on Win32, this article by helps describe the problem you are up
against for passing argument lists:
Everyone quotes command line arguments the wrong way
<https://blogs.msdn.microsoft.com/twistylittlepassagesallalike/2011/04/23/everyone-
quotes-command-line-arguments-the-wrong-way/> by Daniel Colascione.
This module gives you parsing / quoting per the standard CommandLineToArgvW behavior.
But, if you need to pass arguments to be processed by "cmd.exe" then you need to do
additional work.
AUTHORS
• Blair Zajac <blair@orcaware.com>
• Michael Conrad <mike@nrdvana.net>
CONTRIBUTORS
• Florian Schlichting <fsfs@debian.org>
• Kevin Ryde <user42@zip.com.au>
• Salvador Fandiño <sfandino@yahoo.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2019 by Michael Conrad, (C) 1998-2009 by Blair Zajac.
This is free software; you can redistribute it and/or modify it under the same terms as
the Perl 5 programming language system itself.