proc::background(3)

NAME

Proc::Background - Generic interface to Unix and Win32
background process management

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
# DETROYed.
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.

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 behav
ior.; 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 al

ways 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 multi

ple
arguments are passed to new, then the first ele

ment 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 giv

en location
or fails otherwise. If the executable's name is

not
absolute, then the executable is searched for us

ing 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 ex

ecutable
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 ab

solute
path, then it is checked to see if it exists and

can be
run, otherwise new fails. If the path is not ab

solute,
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 fin
ished.
alive: Return 1 if the process is still active, 0 otherwise.
die 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. On Unix, the following signals are sent
to the process in one second intervals until the pro
cess dies: HUP, QUIT, INT, KILL.
wait: 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, then return
an empty list in a list context, an undefined value in
a scalar context, or nothing in a void context. This
function may be called multiple times even after the
process has exited and it will return the same exit
status.
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 com plete 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, time
out_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 con
text, an undefined value in a scalar context, or noth
ing in a void context.

IMPLEMENTATION

Proc::Background comes with two modules, Proc::Back_ ground::Unix and Proc::Background::Win32. Currently, on Unix platforms Proc::Background uses the Proc::Back_ ground::Unix class and on Win32 platforms it uses Proc::Background::Win32, which makes use of Win32::Pro_ cess.

The Proc::Background assigns to @ISA either Proc::Back_ ground::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 pro cess 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.

AUTHOR

Blair Zajac <blair@orcaware.com>

docs.sk

komplexný repozitár dokumentácie

Najnavštevovanejšie