.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.07) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Proc::Background 3pm" .TH Proc::Background 3pm "2009-07-06" "perl v5.10.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Proc::Background \- Generic interface to Unix and Win32 background process management .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& 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 = {\*(Aqdie_upon_destroy\*(Aq => 1}; \& my $proc3 = Proc::Background\->new($opts, $command, $arg1, $arg2); \& $proc3 = undef; .Ve .SH "DESCRIPTION" .IX Header "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. .SH "METHODS" .IX Header "METHODS" .IP "\fBnew\fR [options] \fIcommand\fR, [\fIarg\fR, [\fIarg\fR, ...]]" 4 .IX Item "new [options] command, [arg, [arg, ...]]" .PD 0 .IP "\fBnew\fR [options] '\fIcommand\fR [\fIarg\fR [\fIarg\fR ...]]'" 4 .IX Item "new [options] 'command [arg [arg ...]]'" .PD This creates a new background process. As \fIexec()\fR or \fIsystem()\fR 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, \fBnew\fR has the same behavior. .Sp In certain cases \fBnew\fR will attempt to find \fIcommand\fR on the system and fail if it cannot be found. .Sp For Win32 operating systems: .Sp .Vb 10 \& 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\*(Aqs 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\*(Aqs name. If multiple \& arguments are passed to new, then the first element is used \& as the executable\*(Aqs name. \& \& If the executable\*(Aqs name is an absolute path, then new \& checks to see if the executable exists in the given location \& or fails otherwise. If the executable\*(Aqs 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\*(Aq to the name in case the name was passed \& without the \`.exe\*(Aq suffix. \& \& Finally, the argument array is placed back into a single \& string and passed to Win32::Process::Create. .Ve .Sp For non\-Win32 operating systems, such as Unix: .Sp .Vb 11 \& 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\*(Aqs 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. .Ve .Sp The first argument to \fBnew\fR \fIoptions\fR may be a reference to a hash which contains key/value pairs to modify Proc::Background's behavior. Currently the only key understood by \fBnew\fR is \fIdie_upon_destroy\fR. When this value is set to true, then when the Proc::Background object is being \s-1DESTROY\s0'ed for any reason (i.e. the variable goes out of scope) the process is killed via the \fIdie()\fR method. .Sp 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. .IP "\fBpid\fR" 4 .IX Item "pid" Returns the process \s-1ID\s0 of the created process. This value is saved even if the process has already finished. .IP "\fBalive\fR" 4 .IX Item "alive" Return 1 if the process is still active, 0 otherwise. .IP "\fBdie\fR" 4 .IX Item "die" Reliably try to kill the process. Returns 1 if the process no longer exists once \fBdie\fR 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: \&\s-1HUP\s0, \s-1QUIT\s0, \s-1INT\s0, \s-1KILL\s0. .IP "\fBwait\fR" 4 .IX Item "wait" Wait for the process to exit. Return the exit status of the command as returned by \fIwait()\fR 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. .IP "\fBstart_time\fR" 4 .IX Item "start_time" Return the value that the Perl function \fItime()\fR returned when the process was started. .IP "\fBend_time\fR" 4 .IX Item "end_time" Return the value that the Perl function \fItime()\fR returned when the exit status was obtained from the process. .SH "FUNCTIONS" .IX Header "FUNCTIONS" .IP "\fBtimeout_system\fR \fItimeout\fR, \fIcommand\fR, [\fIarg\fR, [\fIarg\fR...]]" 4 .IX Item "timeout_system timeout, command, [arg, [arg...]]" .PD 0 .IP "\fBtimeout_system\fR '\fItimeout\fR \fIcommand\fR [\fIarg\fR [\fIarg\fR...]]'" 4 .IX Item "timeout_system 'timeout command [arg [arg...]]'" .PD Run a command for \fItimeout\fR seconds and if the process did not exit, then kill it. While the timeout is implemented using \fIsleep()\fR, this function makes sure that the full \fItimeout\fR is reached before killing the process. \fBtimeout_system\fR does not wait for the complete \&\fItimeout\fR 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. .Sp In a scalar context, \fBtimeout_system\fR returns the exit status from the process. In an array context, \fBtimeout_system\fR 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 \&\fBtimeout_system\fR or 0 if the process exited by itself. .Sp The exit status is the value returned from the \fIwait()\fR 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. .Sp 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. .SH "IMPLEMENTATION" .IX Header "IMPLEMENTATION" \&\fIProc::Background\fR comes with two modules, \fIProc::Background::Unix\fR and \fIProc::Background::Win32\fR. Currently, on Unix platforms \&\fIProc::Background\fR uses the \fIProc::Background::Unix\fR class and on Win32 platforms it uses \fIProc::Background::Win32\fR, which makes use of \&\fIWin32::Process\fR. .PP The \fIProc::Background\fR assigns to \f(CW@ISA\fR either \&\fIProc::Background::Unix\fR or \fIProc::Background::Win32\fR, which does the \s-1OS\s0 dependent work. The \s-1OS\s0 independent work is done in \&\fIProc::Background\fR. .PP Proc::Background uses two variables to keep track of the process. \&\f(CW$self\fR\->{_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 \fIWin32::Process\fR class. When \&\f(CW$self\fR\->{_os_obj} exists, then the process is running. When the process dies, this is recorded by deleting \f(CW$self\fR\->{_os_obj} and saving the exit value \f(CW$self\fR\->{_exit_value}. .PP Anytime \fIalive\fR is called, a \fIwaitpid()\fR is called on the process and the return status, if any, is gathered and saved for a call to \&\fIwait\fR. This module does not install a signal handler for \s-1SIGCHLD\s0. If for some reason, the user has installed a signal handler for \&\s-1SIGCHLD\s0, then, then when this module calls \fIwaitpid()\fR, 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. .SH "SEE ALSO" .IX Header "SEE ALSO" See also Proc::Background::Unix and Proc::Background::Win32. .SH "AUTHOR" .IX Header "AUTHOR" Blair Zajac .SH "COPYRIGHT" .IX Header "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.