Current File : //data/old/usr/share/perl5/vendor_perl/No/Worries/Proc.pm
#+##############################################################################
# #
# File: No/Worries/Proc.pm #
# #
# Description: process handling without worries #
# #
#-##############################################################################
#
# module definition
#
package No::Worries::Proc;
use strict;
use warnings;
use 5.005; # need the four-argument form of substr()
our $VERSION = "1.7";
our $REVISION = sprintf("%d.%02d", q$Revision: 1.26 $ =~ /(\d+)\.(\d+)/);
#
# used modules
#
use Config qw(%Config);
use IO::Select qw();
use No::Worries qw($_IntegerRegexp $_NumberRegexp);
use No::Worries::Die qw(dief);
use No::Worries::Dir qw(dir_change);
use No::Worries::Export qw(export_control);
use Params::Validate qw(validate validate_with :types);
use POSIX qw(:sys_wait_h :errno_h setsid);
use Time::HiRes qw();
#
# global variables
#
our(@SigName, $Transient);
#
# check a command to be executed
#
sub _chk_cmd (@) {
my(@cmd) = @_;
my($path);
if ($cmd[0] =~ /\//) {
dief("invalid command: %s", $cmd[0]) unless -f $cmd[0] and -x _;
} else {
$path = $ENV{PATH} || "/usr/bin:/usr/sbin:/bin:/sbin";
foreach my $dir (split(/:/, $path)) {
next unless length($dir) and -d $dir;
next unless -f "$dir/$cmd[0]" and -x _;
$cmd[0] = "$dir/$cmd[0]";
last;
}
dief("command not found: %s", $cmd[0]) unless $cmd[0] =~ /\//;
}
return(\@cmd);
}
#
# definition of the process structure
#
my $nbre = "(\\d+\\.)?\\d+"; # fractional number pattern
my $ksre = "([A-Z]+\\/${nbre}\\s+)*[A-Z]+\\/${nbre}"; # kill spec. pattern
my %proc_structure = (
# public
command => { optional => 0, type => ARRAYREF },
pid => { optional => 0, type => SCALAR, regex => $_IntegerRegexp },
start => { optional => 0, type => SCALAR, regex => $_NumberRegexp },
stop => { optional => 1, type => SCALAR, regex => $_NumberRegexp },
status => { optional => 1, type => SCALAR, regex => qr/^-?\d+$/ },
timeout => { optional => 1, type => SCALAR, regex => $_NumberRegexp },
# private
kill => { optional => 1, type => SCALAR, regex => qr/^${ksre}$/ },
maxtime => { optional => 1, type => SCALAR, regex => $_NumberRegexp },
fhin => { optional => 1, type => GLOBREF },
fhout => { optional => 1, type => GLOBREF },
fherr => { optional => 1, type => GLOBREF },
bufin => { optional => 1, type => SCALAR },
cbout => { optional => 1, type => CODEREF },
cberr => { optional => 1, type => CODEREF },
);
sub _chk_proc ($) {
my($proc) = @_;
validate_with(
params => $proc,
spec => \%proc_structure,
on_fail => sub { dief("invalid process structure: %s", $_[0]) },
);
return(); # so that validate_with() is called in void context
}
#
# close a file handle used for IPC
#
sub _close ($$$$) {
my($proc, $fh, $what, $ios) = @_;
$ios->remove($fh) if $ios;
close($fh) or dief("cannot close(): %s", $!);
delete($proc->{"fh$what"});
delete($proc->{"cb$what"});
}
#
# try to read from a dead process in case we called _is_alive() on it
# before all its output pipes got emptied...
#
sub _read_zombie ($$$) {
my($proc, $iosr, $iosw) = @_;
my($fh, $buf, $done);
foreach my $what (qw(in)) {
next unless $proc->{"fh$what"} and $proc->{"cb$what"};
$fh = $proc->{"fh$what"};
# no write, simply close
_close($proc, $fh, $what, $iosw);
}
foreach my $what (qw(out err)) {
next unless $proc->{"fh$what"} and $proc->{"cb$what"};
$fh = $proc->{"fh$what"};
# read until EOF then close
$done = 1;
while ($done) {
last if $iosr and not grep($fh eq $_, $iosr->can_read(1));
$buf = "";
$done = sysread($fh, $buf, 8192);
dief("cannot sysread(): %s", $!) unless defined($done);
$proc->{"cb$what"}($proc, $buf);
}
_close($proc, $fh, $what, $iosr);
}
}
#
# check if a process is alive, record its status if not
#
sub _is_alive ($$$) {
my($proc, $iosr, $iosw) = @_;
# check if it recently died
if (waitpid($proc->{pid}, WNOHANG) == $proc->{pid}) {
$proc->{status} = $?;
$proc->{stop} = Time::HiRes::time();
delete($proc->{maxtime});
delete($proc->{kill});
_read_zombie($proc, $iosr, $iosw);
return(0); # no
}
# check if we can kill it
if (kill(0, $proc->{pid}) or $! == EPERM) {
return(1); # yes
}
# ooops
return(); # don't know
}
#
# prepare I/O before creating a process
#
sub _prepare_stdin ($$) {
my($proc, $stdin) = @_;
my($ref, $rdrin, $wrtin);
return() unless defined($stdin);
$ref = ref($stdin);
if ($ref eq "") {
if ($stdin eq "") {
dief("unexpected stdin: empty string");
} else {
## no critic 'InputOutput::RequireBriefOpen'
open($rdrin, "<", $stdin)
or dief("cannot open(<, %s): %s", $stdin, $!);
}
} elsif ($ref eq "SCALAR") {
pipe($rdrin, $wrtin)
or dief("cannot pipe(): %s", $!);
$proc->{fhin} = $wrtin;
$proc->{bufin} = ${ $stdin };
} else {
dief("unexpected stdin: ref(%s)", $ref);
}
return($rdrin, $wrtin);
}
sub _prepare_stdout ($$) {
my($proc, $stdout) = @_;
my($ref, $rdrout, $wrtout);
return() unless defined($stdout);
$ref = ref($stdout);
if ($ref eq "") {
if ($stdout eq "") {
dief("unexpected stdout: empty string");
} else {
## no critic 'InputOutput::RequireBriefOpen'
open($wrtout, ">", $stdout)
or dief("cannot open(>, %s): %s", $stdout, $!);
}
} elsif ($ref eq "CODE" or $ref eq "SCALAR") {
pipe($rdrout, $wrtout)
or dief("cannot pipe(): %s", $!);
$proc->{fhout} = $rdrout;
if ($ref eq "CODE") {
$proc->{cbout} = $stdout;
} else {
${ $stdout } = "";
$proc->{cbout} = sub {
my($_proc, $_buf) = @_;
${ $stdout } .= $_buf;
};
}
} else {
dief("unexpected stdout: ref(%s)", $ref);
}
return($rdrout, $wrtout);
}
sub _prepare_stderr ($$) {
my($proc, $stderr) = @_;
my($ref, $rdrerr, $wrterr, $merge);
return() unless defined($stderr);
$ref = ref($stderr);
if ($ref eq "") {
if ($stderr eq "") {
# special case: stderr will be merged with stdout
$merge = 1;
} else {
## no critic 'InputOutput::RequireBriefOpen'
open($wrterr, ">", $stderr)
or dief("cannot open(>, %s): %s", $stderr, $!);
}
} elsif ($ref eq "CODE" or $ref eq "SCALAR") {
pipe($rdrerr, $wrterr)
or dief("cannot pipe(): %s", $!);
$proc->{fherr} = $rdrerr;
if ($ref eq "CODE") {
$proc->{cberr} = $stderr;
} else {
${ $stderr } = "";
$proc->{cberr} = sub {
my($_proc, $_buf) = @_;
${ $stderr } .= $_buf;
};
}
} else {
dief("unexpected stderr: ref(%s)", $ref);
}
return($rdrerr, $wrterr, $merge);
}
#
# redirect I/O after creating a process
#
sub _redirect_io ($$$$) {
my($rdrin, $wrtout, $wrterr, $merge) = @_;
my($fd);
# handle stdin
if ($rdrin) {
$fd = fileno($rdrin);
if (fileno(*STDIN) != $fd) {
open(*STDIN, "<&=$fd")
or dief("cannot redirect stdin: %s", $!);
}
}
# handle stdout
if ($wrtout) {
$fd = fileno($wrtout);
if (fileno(*STDOUT) != $fd) {
open(*STDOUT, ">&=$fd")
or dief("cannot redirect stdout: %s", $!);
}
}
# handle stderr
if ($wrterr or $merge) {
$fd = $merge ? fileno(*STDOUT) : fileno($wrterr);
if (fileno(*STDERR) != $fd) {
open(*STDERR, ">&=$fd")
or dief("cannot redirect stderr: %s", $!);
}
}
}
#
# fork a new process, setup its environment and exec() the command
#
my %proc_create_options = (
command => { optional => 0, type => ARRAYREF },
cwd => { optional => 1, type => SCALAR },
timeout => { optional => 1, type => SCALAR, regex => $_NumberRegexp },
kill => { optional => 1, type => SCALAR, regex => qr/^${ksre}$/ },
stdin => { optional => 1, type => SCALAR | SCALARREF },
stdout => { optional => 1, type => SCALAR | SCALARREF | CODEREF },
stderr => { optional => 1, type => SCALAR | SCALARREF | CODEREF },
);
sub proc_create (@) {
my(%option, %proc, $merge);
my($rdrin, $wrtin, $rdrout, $wrtout, $rdrerr, $wrterr);
#
# preparation
#
%option = validate(@_, \%proc_create_options);
$proc{command} = _chk_cmd(@{ $option{command} });
# check the "current working directory" option
if (defined($option{cwd})) {
dief("invalid directory: %s", $option{cwd}) unless -d $option{cwd};
}
# prepare I/O
($rdrin, $wrtin) = _prepare_stdin(\%proc, $option{stdin});
($rdrout, $wrtout) = _prepare_stdout(\%proc, $option{stdout});
($rdrerr, $wrterr, $merge) = _prepare_stderr(\%proc, $option{stderr});
# fork
$proc{pid} = fork();
dief("cannot fork(): %s", $!) unless defined($proc{pid});
#
# handle the child
#
unless ($proc{pid}) {
# we are about to exec() or die()
$Transient = 1;
# handle the "current working directory"
dir_change($option{cwd}) if defined($option{cwd});
# make sure the STD* file handles are "normal"
foreach my $glob (*STDIN, *STDOUT, *STDERR) {
next unless tied($glob);
no warnings qw(untie); ## no critic 'ProhibitNoWarnings'
untie($glob);
}
# handle the pipe ends to close
foreach my $fh ($wrtin, $rdrout, $rdrerr) {
next unless $fh;
close($fh) or dief("cannot close pipe: %s", $!);
}
# redirect I/O
_redirect_io($rdrin, $wrtout, $wrterr, $merge);
# execute the command
exec({ $proc{command}[0] } @{ $proc{command} })
or dief("cannot execute %s: %s", $proc{command}[0], $!);
exit(-1);
}
#
# handle the father
#
# record the "start" time
$proc{start} = Time::HiRes::time();
# record the maximum running time
if (defined($option{timeout})) {
$proc{maxtime} = $proc{start} + $option{timeout};
}
# record the kill specification
$proc{kill} = $option{kill} if $option{kill};
# handle the pipe ends to close
foreach my $fh ($rdrin, $wrtout, $wrterr) {
next unless $fh;
close($fh) or dief("cannot close pipe: %s", $!);
}
# so far so good
return(\%proc);
}
#
# terminate a process
#
my %proc_terminate_options = (
kill => { optional => 1, type => SCALAR, regex => qr/^${ksre}$/ },
_iosr => { optional => 1, type => UNDEF|OBJECT },
_iosw => { optional => 1, type => UNDEF|OBJECT },
);
sub proc_terminate ($@) {
my($proc, %option, $pid, $sig, $grace, $maxtime);
# setup
$proc = shift(@_);
if (ref($proc) eq "") {
dief("unexpected pid: %s", $proc) unless $proc =~ /^\d+$/;
$proc = { pid => $proc };
} elsif (ref($proc) eq "HASH") {
_chk_proc($proc);
} else {
dief("unexpected process: %s", $proc);
}
%option = validate(@_, \%proc_terminate_options) if @_;
$option{kill} ||= $proc->{kill} || "TERM/1 INT/1 QUIT/1";
$pid = $proc->{pid};
# gentle kill
foreach my $spec (split(/\s+/, $option{kill})) {
if ($spec =~ /^([A-Z]+)\/(${nbre})$/) {
($sig, $grace) = ($1, $2);
} else {
dief("unexpected kill specification: %s", $spec);
}
unless (kill($sig, $pid)) {
dief("cannot kill(%s, %d): %s", $sig, $pid, $!) unless $! == ESRCH;
}
$maxtime = Time::HiRes::time() + $grace;
while (Time::HiRes::time() < $maxtime) {
return unless _is_alive($proc, $option{_iosr}, $option{_iosw});
Time::HiRes::sleep(0.01);
}
return unless _is_alive($proc, $option{_iosr}, $option{_iosw});
}
# hard kill
$sig = "KILL";
unless (kill($sig, $pid)) {
dief("cannot kill(%s, %d): %s", $sig, $pid, $!) unless $! == ESRCH;
}
}
#
# setup monitoring
#
sub _monitor_setup ($) {
my($procs) = @_;
my(%process, %map, $iosr, $iosw, $fh);
# store the processes to monitor in a hash
foreach my $proc (@{ $procs }) {
_chk_proc($proc);
$process{$proc->{pid}} = $proc;
}
# record the file handles to monitor
$iosr = IO::Select->new();
$iosw = IO::Select->new();
foreach my $proc (values(%process)) {
foreach my $what (qw(in out err)) {
$fh = $proc->{"fh$what"};
next unless $fh;
if ($what eq "in") {
$iosw->add($fh);
} else {
$iosr->add($fh);
}
$map{"$fh"} = [ $proc->{pid}, $what ];
}
}
$iosr = undef unless $iosr->count();
$iosw = undef unless $iosw->count();
return(\%process, \%map, $iosr, $iosw);
}
#
# monitor I/O
#
sub _monitor_reading ($$$$$) {
my($process, $map, $iosr, $bufsize, $timeout) = @_;
my($buf, $done, $proc, $what);
foreach my $fh ($iosr->can_read($timeout)) {
$timeout = 0;
$buf = "";
$done = sysread($fh, $buf, $bufsize);
dief("cannot sysread(): %s", $!) unless defined($done);
$proc = $process->{$map->{"$fh"}[0]};
$what = $map->{"$fh"}[1];
$proc->{"cb$what"}($proc, $buf);
unless ($done) {
_close($proc, $fh, $what, $iosr);
}
}
return($timeout);
}
sub _monitor_writing ($$$$$) {
my($process, $map, $iosw, $bufsize, $timeout) = @_;
my($buf, $done, $proc, $what);
foreach my $fh ($iosw->can_write($timeout)) {
$timeout = 0;
$proc = $process->{$map->{"$fh"}[0]};
$what = $map->{"$fh"}[1];
$buf = $proc->{"buf$what"};
if (length($buf)) {
$done = syswrite($fh, $buf, length($buf));
dief("cannot syswrite(): %s", $!) unless defined($done);
substr($proc->{"buf$what"}, 0, $done, "");
} else {
_close($proc, $fh, $what, $iosw);
}
}
return($timeout);
}
#
# monitor termination (death and timeout)
#
sub _monitor_termination ($$$$) {
my($process, $iosr, $iosw, $timeout) = @_;
my($now);
# check if some processes finished
foreach my $proc (grep(!defined($_->{status}), values(%{ $process }))) {
next if _is_alive($proc, $iosr, $iosw);
$timeout = 0;
}
# check if some processes timed out
$now = Time::HiRes::time();
foreach my $proc (grep($_->{maxtime}, values(%{ $process }))) {
next unless $now > $proc->{maxtime};
$timeout = 0;
delete($proc->{maxtime});
$proc->{timeout} = $now;
proc_terminate($proc, _iosr => $iosr, _iosw => $iosw);
}
return($timeout);
}
#
# monitor one or more processes
#
my %proc_monitor_options = (
timeout => { optional => 1, type => SCALAR, regex => $_NumberRegexp },
bufsize => { optional => 1, type => SCALAR, regex => $_IntegerRegexp },
deaths => { optional => 1, type => SCALAR, regex => $_IntegerRegexp },
);
sub proc_monitor ($@) {
my($procs, %option, $process, $map, $iosr, $iosw);
my($maxtime, $timeout, $zombies);
#
# preparation
#
$procs = shift(@_);
if (ref($procs) eq "HASH") {
$procs = [ $procs ];
} elsif (ref($procs) ne "ARRAY") {
dief("unexpected processes: %s", $procs);
}
%option = validate(@_, \%proc_monitor_options) if @_;
$option{bufsize} ||= 8192;
($process, $map, $iosr, $iosw) = _monitor_setup($procs);
# count the number of processes which are already dead
$zombies = grep(defined($_->{status}), values(%{ $process }));
#
# work
#
$maxtime = Time::HiRes::time() + $option{timeout}
if defined($option{timeout});
while ($iosr or $iosw
or grep(!defined($_->{status}), values(%{ $process }))) {
$timeout = 0.01;
# read what can be read
$timeout = _monitor_reading($process, $map, $iosr, $option{bufsize},
$timeout) if $iosr;
# write what can be written
$timeout = _monitor_writing($process, $map, $iosw, $option{bufsize},
$timeout) if $iosw;
# check if some processes finished or timed out
$timeout = _monitor_termination($process, $iosr, $iosw, $timeout);
# or if we timed out
last if $maxtime and Time::HiRes::time() > $maxtime;
# or if enough processes died
last if $option{deaths}
and grep(defined($_->{status}), values(%{ $process }))
>= $zombies + $option{deaths};
# sleep a bit if needed (= if we have not worked before in the loop)
Time::HiRes::sleep($timeout) if $timeout;
# update the IO::Select objects
$iosr = undef unless $iosr and $iosr->count();
$iosw = undef unless $iosw and $iosw->count();
}
}
#
# run the given command
#
sub proc_run (@) {
my(@args) = @_;
my($proc);
# create the process
$proc = proc_create(@args);
# monitor it until it ends
proc_monitor($proc);
# return what is expected
return(%{ $proc }) if wantarray();
return($proc->{status});
}
#
# execute the given command, check its status and return its output
#
sub proc_output (@) {
my(@command) = @_;
my($output, $status);
$output = "";
$status = proc_run(command => \@command, stdout => \$output);
dief("%s failed: %d", $command[0], $status) if $status;
return($output);
}
#
# detach ourself and go in the background
#
my %proc_detach_options = (
callback => { optional => 1, type => CODEREF },
);
sub proc_detach (@) {
my(%option, $pid, $sid);
%option = validate(@_, \%proc_detach_options) if @_;
# change directory to a known place
dir_change("/");
# fork and let dad die
$pid = fork();
dief("cannot fork(): %s", $!) unless defined($pid);
if ($pid) {
# we are about to exit()
$Transient = 1;
$option{callback}->($pid) if $option{callback};
exit(0);
}
# create a new session
$sid = setsid();
dief("cannot setsid(): %s", $!) if $sid == -1;
# detach std* from anything but plain files (i.e. allow: cmd --detach > log)
unless (-f STDIN) {
open(STDIN, "<", "/dev/null")
or dief("cannot re-open stdin: %s", $!);
}
unless (-f STDOUT) {
open(STDOUT, ">", "/dev/null")
or dief("cannot re-open stdout: %s", $!);
}
unless (-f STDERR) {
open(STDERR, ">", "/dev/null")
or dief("cannot re-open stderr: %s", $!);
}
}
#
# return a string representation of the process status
#
sub proc_status ($) {
my($status) = @_;
my($signum, @list);
return("ok") unless $status;
$signum = $status & 127;
push(@list, sprintf("code=%d", $status >> 8));
push(@list, sprintf("signal=%s", $SigName[$signum] || $signum))
if $signum;
push(@list, "(core dumped)")
if $status & 128;
return(join(" ", @list));
}
#
# module initialization
#
@SigName[split(/\s+/, $Config{sig_num})] = split(/\s+/, $Config{sig_name});
#
# export control
#
sub import : method {
my($pkg, %exported);
$pkg = shift(@_);
grep($exported{$_}++,
map("proc_$_", qw(create detach monitor output run status terminate)));
export_control(scalar(caller()), $pkg, \%exported, @_);
}
1;
__DATA__
=head1 NAME
No::Worries::Proc - process handling without worries
=head1 SYNOPSIS
use No::Worries::Proc qw(proc_run proc_create proc_monitor proc_detach);
# simple interface to execute a command
$status = proc_run(command => [ "foo", "-x", 7 ]);
printf("foo exited with %d\n", $status);
# idem but with output redirection and more information
%proc = proc_run(command => [ qw(uname -a) ], stdout => \$output);
printf("process %d output is %s\n", $proc->{pid}, $output);
# start two process and wait for them to finish
$p1 = proc_create(
command => \@cmd1,
timeout => 5, # to be killed if still running after 5s
stderr => "/dev/null", # discard stderr
);
$p2 = proc_create(
command => \@cmd2,
stdout => \$output, # get stdout+stderr in $output
stderr => "", # merge stderr with stdout
);
proc_monitor([ $p1, $p2 ], timeout => 10);
printf("%d finished\n", $p1->{pid}) if $p1->{stop};
printf("%d finished\n", $p2->{pid}) if $p2->{stop};
# detach ourself to run as a daemon
proc_detach(callback => sub { print("started with pid $_[0]\n")});
=head1 DESCRIPTION
This module eases process handling by providing high level functions to start,
monitor and stop processes. All the functions die() on error.
It also provides the $No::Worries::Proc::Transient variable that indicates,
after a fork(), which process is transient and is about to exec() or exit().
This is useful for instance in an END block:
END {
# remove our pid file unless we are transient
pf_unset($pidfile) unless $No::Worries::Proc::Transient;
}
=head1 FUNCTIONS
This module provides the following functions (none of them being exported by
default):
=over
=item proc_output(COMMAND...)
execute the given command, capture its output (stdout only), check its exit
code (report an error if it is not zero) and return the captured output; this
is similar to Perl's qx() operator but bypassing the shell and always checking
the exit code
=item proc_create(OPTIONS)
create a new process that will execute the given command and return a hash
reference representing this process (see the L</"PROCESS STRUCTURE"> sections
for more information), to be given to proc_monitor() or proc_terminate()
afterwards; supported options:
=over
=item * C<command>: the command to execute, it must be an array reference
=item * C<cwd>: the current working directory of the new process
=item * C<timeout>: the maximum number of seconds that the process is allowed
to take to run (can be fractional); after this, it may be killed by
proc_monitor()
=item * C<kill>: how to "gently" kill the process, see below
=item * C<stdin>: what to do with stdin, see below
=item * C<stdout>: what to do with stdout, see below
=item * C<stderr>: what to do with stderr, see below
=back
=item proc_terminate(PROC[, OPTIONS])
terminate the given process (PROC can be either a process structure or simply
a process id) by sending signals and waiting for the process to finish;
supported options:
=over
=item * C<kill>: how to "gently" kill the process, see below
=back
=item proc_monitor(PROCS[, OPTIONS])
monitor the given process(es) (as created by proc_create()); PROCS can be
either a single process or a reference to a list of processes; supported
options:
=over
=item * C<timeout>: the maximum number of seconds that proc_monitor() should
take, can be fractional
=item * C<bufsize>: the buffer size to use for I/O operations (default: 8192)
=item * C<deaths>: the minimum number of process deaths that proc_monitor()
will wait for before returning
=back
=item proc_run(OPTIONS)
execute the given process (i.e. create and monitor it until termination) and
return its status (i.e. $?) in scalar context or the whole process structure
in list context; supported options: the ones of proc_create()
=item proc_detach([OPTIONS])
detach the current process so that it becomes a daemon running in the
background (this implies forking and re-opening std*); supported options:
=item proc_status(STATUS)
return a string representation of the given process status (i.e. $?)
=over
=item * C<callback>: code reference that will be executed by the parent
process just before exiting and will be given the child pid
=back
=back
=head1 PROCESS STRUCTURE
The process structure (hash) used in this module has the following fields:
=over
=item * C<command>: the command being executed, as an array reference
=item * C<pid>: the process id
=item * C<start>: the start time, in fractional seconds
=item * C<stop>: the stop time, in fractional seconds
=item * C<status>: the status (i.e. $?)
=item * C<timeout>: true if the process has been killed because of timeout
=back
=head1 FILE DESCRIPTOR REDIRECTION
When using the C<stdin> option of proc_create(), the value can be:
=over
=item * a string: input will be read from the given file name
=item * a scalar reference: input will be the scalar itself
=back
When using the C<stdout> and C<stderr> options of proc_create(), the value can
be:
=over
=item * a string: output will be written to the given file name
=item * a scalar reference: output will be stored in the scalar
=item * a code reference: each time new output is available, the code will be
called with two parameters: the process structure and the new output
=back
In addition, C<stderr> can also be given an empty string that means that
stderr should be merged with stdout.
=head1 KILL SPECIFICATION
Both proc_create() and proc_terminate() can be given a C<kill> option that
specifies how the process should be killed.
The specification is a string containing a space separated list of
I<signal>/I<grace> couples, meaning: send the given signal and wait a bit for
the process to finish.
If not specified, the default is C<TERM/1 INT/1 QUIT/1>, meaning:
=over
=item * send SIGTERM and wait up to 1 second for the process to finish
=item * if the process is still alive, send SIGINT and wait up to 1 second
=item * if the process is still alive, send SIGQUIT and wait up to 1 second
=item * if the process is still alive, send SIGKILL (implicit)
=back
=head1 GLOBAL VARIABLES
This module uses the following global variables (none of them being exported):
=over
=item $Transient
true if the process is about to exec() or exit(), there is usually no need to
perform any cleanup (e.g. in an END block) for this kind of process
=back
=head1 SEE ALSO
L<No::Worries>.
=head1 AUTHOR
Lionel Cons L<http://cern.ch/lionel.cons>
Copyright (C) CERN 2012-2019
Mini Shell