.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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 "Paranoid::Process 3pm"
.TH Paranoid::Process 3pm "2010-05-10" "perl v5.14.2" "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"
Paranoid::Process \- Process Management Functions
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Id:\fR Process.pm,v 1.01 2010/05/10 04:55:07 acorliss Exp $
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Paranoid::Process;
\&
\&  $rv = daemonize();
\&
\&  MAXCHILDREN = 100;
\&
\&  $SIG{CHLD} = \e&sigchld;
\&  $count = childrenCount();
\&  installChldHandler($sub);
\&  $rv = pfork();
\&
\&  $uid = ptranslateUser("foo");
\&  $gid = ptranslateGroup("foo");
\&  $rv = switchUser($user, $group);
\&
\&  $rv = pcapture($cmd, \e$crv, \e$out);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a few functions meant to make life easier when managing
processes.  The following export targets are provided:
.PP
.Vb 2
\&  all               All functions within this module
\&  pfork             All child management functions
.Ve
.PP
Only the functions \fBswitchUser\fR and \fBdaemonize\fR are currently exported by 
default.
.SH "SUBROUTINES/METHODS"
.IX Header "SUBROUTINES/METHODS"
.SS "\s-1MAXCHILDREN\s0"
.IX Subsection "MAXCHILDREN"
Setting this lvalue subroutine sets a limit to how many children will be 
forked at a time by \fBpfork\fR.  The default is zero, which allows unlimited 
children.  Once the limit is met pfork becomes a blocking call until a child 
exits so the new one can be spawned.
.SS "childrenCount"
.IX Subsection "childrenCount"
.Vb 1
\&  $count = childrenCount();
.Ve
.PP
This function returns the current number of children spawned by \fBpfork\fR.
.SS "installChldHandler"
.IX Subsection "installChldHandler"
.Vb 1
\&  installChldHandler($sub);
.Ve
.PP
This function takes a reference to a subroutine.  If used the subroutine will
be called every time a child exits.  That subroutine will be called with the
child's \s-1PID\s0 and exit value as arguments.
.SS "sigchld"
.IX Subsection "sigchld"
.Vb 1
\&  $SIG{CHLD} = \e&sigchld;
.Ve
.PP
This function decrements the child counter necessary for pfork's operation, as
well as calling the user's signal handler with each child's \s-1PID\s0 and exit
value.
.SS "daemonize"
.IX Subsection "daemonize"
.Vb 1
\&    $rv = daemonize();
.Ve
.PP
This function forks a child who reopens all STD* filehandles on /dev/null and 
starts a new process group.  The parent exits cleanly.  If the fork fails for
any reason it returns a false value.  The child will also change its directory
to \fB/\fR.
.SS "pfork"
.IX Subsection "pfork"
.Vb 1
\&  $rv = pfork();
.Ve
.PP
This function should be used in lieu of Perl's fork if you want to take
advantage of a blocking fork call that respects the \s-1MAXCHILDREN\s0 limit.  Use of
this function, however, also assumes the use of \fBsigchld\fR as the signal
handler for \s-1SIGCHLD\s0.
.SS "ptranslateUser"
.IX Subsection "ptranslateUser"
.Vb 1
\&  $uid = ptranslateUser("foo");
.Ve
.PP
This function takes a username and returns the corresponding \s-1UID\s0 as returned
by \fBgetpwent\fR.  If no match is found it returns undef.
.SS "ptranslateGroup"
.IX Subsection "ptranslateGroup"
.Vb 1
\&  $gid = ptranslateGroup("foo");
.Ve
.PP
This function takes a group name and returns the corresponding \s-1GID\s0 as returned
by \fBgetgrent\fR.  If no match is found it returns undef.
.SS "switchUser"
.IX Subsection "switchUser"
.Vb 1
\&  $rv = switchUser($user, $group);
.Ve
.PP
This function can be fed one or two arguments, both either named user or
group, or \s-1UID\s0 or \s-1GID\s0.  Both user and group arguments are optional as long as
the other is called.  In other words, you can pass undef for one of the
arguments, but not for both.  If you're only switching the user you can pass
only the user argument.
.SS "pcapture"
.IX Subsection "pcapture"
.Vb 1
\&  $rv = pcapture($cmd, \e$crv, \e$out);
.Ve
.PP
This function executes the passed shell command and returns one of the following
three values:
.PP
.Vb 5
\&  RV    Description
\&  =======================================================
\&  \-1    Command failed to execute or died with signal
\&   0    Command executed but exited with a non\-0 RV
\&   1    Command executed and exited with a 0 RV
.Ve
.PP
The actual return value is populated in the passed scalar reference, while all
\&\s-1STDERR/STDOUT\s0 output is stored in the last scalar reference.  Any errors
executing the command will have the error string stored in \fBParanoid::ERROR\fR.
.PP
If the command exited cleanly it will automatically be bit shifted eight
bits.
.PP
\&\fB\s-1NOTE:\s0\fR Unlike many other functions in this suite it is up to you to detaint
the command passed to this function yourself.  There's simply no way for me to
know ahead of time what kind of convoluted arguments you might be handing this
call before system is called.  Failing to detaint that argument will cause
your script to exit under taint mode.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
.IP "o" 4
.IX Item "o"
Paranoid
.IP "o" 4
.IX Item "o"
Paranoid::Debug
.IP "o" 4
.IX Item "o"
\&\s-1POSIX\s0
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "pfork"
.IX Subsection "pfork"
This following example caps the number of children processes to three at a
time:
.PP
.Vb 3
\&  $SIG{CHLD}  = \e&sigchld;
\&  MAXCHILDREN = 3;
\&  for (1 .. 5) {
\&
\&    # Only the children execute the following block
\&    unless ($pid = pfork()) {
\&      # ....
\&      exit 0;
\&    }
\&  }
.Ve
.PP
You can also install a child-exit routine to be called by sigchld.
For instance, to track the children's history in the parent:
.PP
.Vb 2
\&  sub recordChild ($$) {
\&    my ($cpid, $cexit) = @_;
\&
\&    push(@chistory, [$cpid, $cexit]);
\&  }
\&
\&  installChldHandler(\e&recordChild);
\&  for (1 .. 5) {
\&    unless ($pid = pfork()) {
\&      # ....
\&      exit $rv;
\&    }
\&  }
\&
\&  # Prints the child process history
\&  foreach (@chistory) { print "PID: $$_[0] EXIT: $$_[1]\en" };
.Ve
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
There's a bug in an current versions of Perl where \fBptranslateGroup\fR can 
return negative numbers instead the actual \s-1GID\s0.  This is due to the platform
supporting unsigned integers for the \s-1GID\s0, but Perl was casting it as a signed
integer.  A patch has been submitted to blead-perl.
.PP
On Solaris \fBpcapture\fR doesn't return a \-1 for non-existant commands, but a 0.
On Linux this appears to work as intended.
.SH "AUTHOR"
.IX Header "AUTHOR"
Arthur Corliss (corliss@digitalmages.com)
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
This software is licensed under the same terms as Perl, itself. 
Please see http://dev.perl.org/licenses/ for more information.
.PP
(c) 2005, Arthur Corliss (corliss@digitalmages.com)