Proc::Background(3pm)					User Contributed Perl Documentation				     Proc::Background(3pm)

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
	   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 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
	   process 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 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

       See also Proc::Background::Unix and Proc::Background::Win32.

AUTHOR

       Blair Zajac <blair@orcaware.com>

COPYRIGHT

       Copyright (C) 1998-2005 Blair Zajac.  All rights reserved.  This package is free software; you can redistribute it and/or modify it under
       the same terms as Perl itself.

perl v5.10.0							    2009-07-06						     Proc::Background(3pm)