Provided by: libparanoid-perl_2.10-1_all 
NAME
Paranoid::Process - Process Management Functions
VERSION
$Id: lib/Paranoid/Process.pm, 2.10 2022/03/08 00:01:04 acorliss Exp $
SYNOPSIS
use Paranoid::Process qw(:all);
$rv = daemonize();
MAXCHILDREN = 100;
$SIG{CHLD} = \&sigchld;
$count = childrenCount();
installChldHandler(&cleanup);
$rv = pfork();
$rv = pcommFork($rh, $wh);
$uid = ptranslateUser("foo");
$gid = ptranslateGroup("foo");
$rv = switchUser($user, $group);
$rv = pcapture($cmd, $crv, $out);
installSIGH('INT', &sigint1):
installSIGH('INT', &sigint2):
installSIGH('INT', &sigint3):
uninstallSIGH('INT', &sigint2);
installSIGD();
uninstallSIGD();
DESCRIPTION
This module provides a few functions meant to make life easier when managing processes.
IMPORT LISTS
This module exports the following symbols by default:
switchUser daemonize
The following specialized import lists also exist:
List Members
--------------------------------------------------------
misc pcapture
pfork MAXCHILDREN childrenCount installChldHandler
sigchld pfork pcommFork daemonize
signal installSIGH uninstallSIGH installSIGD
uninstallSIGD
user switchUser ptranslateUser ptranslateGroup
all @misc @pfork @signal @user
IMPORT LISTS
This module exports the following symbols by default:
switchUser daemonize
The following specialized import lists also exist:
List Members
--------------------------------------------------------
pfork MAXCHILDREN childrenCount installChldHandler
sigchld pfork pcommFork daemonize
signal installSIGH uninstallSIGH installSIGD
uninstallSIGD
user switchUser ptranslateUser ptranslateGroup
misc pcapture
SUBROUTINES/METHODS
MAXCHILDREN
Setting this lvalue subroutine sets a limit to how many children will be forked at a time by pfork. 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.
NOTE: This limit on children is enforced on a per-process basis. That means that while a process is
limited to the max threshold, its children could also fork their own batch of children as well, up to
whatever max is set in those processes.
childrenCount
$count = childrenCount();
This function returns the current number of children spawned by pfork.
installChldHandler
installChldHandler(&cleanup);
This function takes a reference to a subroutine. If used the subroutine will be called every time a
child exits and triggers sigchild. That subroutine will be called with the child's PID and exit value as
arguments.
sigchld
$SIG{CHLD} = \&sigchld;
# Or, if using the signal dispatcher
installSIGH('CHLD', &sigchld);
installSIGD();
This function decrements the child counter necessary for pfork's operation, as well as calling the user's
signal handler with each child's PID and exit value.
daemonize
$rv = daemonize();
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 /.
pfork
$rv = pfork();
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 MAXCHILDREN limit. Use of this function, however, also assumes the use of sigchld as
the signal handler for SIGCHLD.
pcommFork
$rv = pcommFork($rh, $wh);
This function extends pfork by automatically setting up bidirectional pipes for interprocess
communication. The two scalars passed as arguments will have the appropriate ends of the pipe returned
to both the parent and the child.
In the event that a fork fails, undef will be assigned to both scalars.
The return value will be the result of the fork call.
ptranslateUser
$uid = ptranslateUser("foo");
This function takes a username and returns the corresponding UID as returned by getpwent. If no match is
found it returns undef.
ptranslateGroup
$gid = ptranslateGroup("foo");
This function takes a group name and returns the corresponding GID as returned by getgrent. If no match
is found it returns undef.
switchUser
$rv = switchUser($user);
$rv = switchUser($user, $group);
This function can be fed one or two arguments, both either named user or group, or UID or GID. Both user
and group arguments are optional as long as one of them is defined.
pcapture
$rv = pcapture($cmd, $crv, $out);
This function executes the passed shell command and returns one of the following three values:
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
The actual return value is populated in the passed scalar, while all command output (including STDERR) is
stored in the next scalar. Any errors executing the command will have the error string stored in
Paranoid::ERROR.
If the command exited cleanly it will automatically be bit shifted eight bits.
NOTE: 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.
installSIGH
installSIGH($signal, &subroutine);
This installs another subroutine in the queue for the specified signal. Subroutines are called in the
order that they're added to the queue. Adding a specific subroutine more than once is filtered out so
each subroutine in the queue is unique.
NOTE: Installing handlers for various signals just populates a signal queue with code references. In
order for the queue to actuall act upon a signal, however, one must always install the signal dispatcher
via installSIGD.
uninstallSIGH
uninstallSIGH($signal, &subroutine);
Removes a subroutine from the specified queue.
installSIGD
installSIGD();
Inserts the dispatcher for each signal with subroutines in the queue.
uninstallSIGD
uninstallSIGD();
Removes the dispatcher for each signal that's using the dispatcher. The signal handler installed is what
ever was set when this module's code was loaded and initialized.
DEPENDENCIES
o Carp
o Paranoid
o Paranoid::Debug
o POSIX
EXAMPLES
pfork
This following example caps the number of children processes to three at a time:
$SIG{CHLD} = \&sigchld;
MAXCHILDREN = 3;
for (1 .. 5) {
# Only the children execute the following block
unless ($pid = pfork()) {
# ....
exit 0;
}
}
You can also install a child-exit routine to be called by sigchld. For instance, to track the children's
history in the parent:
sub recordChild ($$) {
my ($cpid, $cexit) = @_;
push(@chistory, [$cpid, $cexit]);
}
installChldHandler(&recordChild);
for (1 .. 5) {
unless ($pid = pfork()) {
# ....
exit $rv;
}
}
# Prints the child process history
foreach (@chistory) { print "PID: $$_[0] EXIT: $$_[1]\n" };
BUGS AND LIMITATIONS
On Solaris pcapture doesn't return a -1 for non-existant commands, but a 0. On Linux this appears to
work as intended.
AUTHOR
Arthur Corliss (corliss@digitalmages.com)
LICENSE AND COPYRIGHT
This software is free software. Similar to Perl, you can redistribute it and/or modify it under the
terms of either:
a) the GNU General Public License
<https://www.gnu.org/licenses/gpl-1.0.html> as published by the
Free Software Foundation <http://www.fsf.org/>; either version 1
<https://www.gnu.org/licenses/gpl-1.0.html>, or any later version
<https://www.gnu.org/licenses/license-list.html#GNUGPL>, or
b) the Artistic License 2.0
<https://opensource.org/licenses/Artistic-2.0>,
subject to the following additional term: No trademark rights to "Paranoid" have been or are conveyed
under any of the above licenses. However, "Paranoid" may be used fairly to describe this unmodified
software, in good faith, but not as a trademark.
(c) 2005 - 2020, Arthur Corliss (corliss@digitalmages.com) (tm) 2008 - 2020, Paranoid Inc.
(www.paranoid.com)