proc::waitstat(3pm) [debian man page]

WaitStat(3pm)						User Contributed Perl Documentation					     WaitStat(3pm)

NAME

       Proc::WaitStat - Interpret and act on wait() status values

SYNOPSIS

	   $description = waitstat $?;
	   exit waitstat_reuse $?;
	   waitstat_die $?, 'program-name';
	   close_die COMMAND, 'program-name';

DESCRIPTION

       This module contains functions for interpreting and acting on wait status values.

       Nothing is exported by default.

       waitstat wait-status
	   Returns a string representation of wait() status value wait-status.	Values returned are like "0" and "64" and "killed (SIGHUP)".

	   This function is prototyped to take a single scalar argument.

       waitstat_reuse wait-status
	   Turn wait-status into a value which can be passed to exit, converted in the same manner the shell uses.  If wait-status indicates a
	   normal exit, return the exit value.	If wait-status instead indicates death by signal, return 128 plus the signal number.

	   This function is prototyped to take a single scalar argument.

       waitstat_die wait-status program-name
	   die() if wait-status is non-zero (mentioning program-name as the source of the error).

	   This function is prototyped to take two scalar arguments.

       close_die filehandle name
	   Close filehandle, if that fails die() with an appropriate message which refers to name.  This handles failed closings of both programs
	   and files properly.

	   This function is prototyped to take a filehandle (actually, a glob ref) and a scalar.

EXAMPLES

	   close SENDMAIL;
	   exit if $? == 0;
	   log "sendmail failure: ", waitstat $?;
	   exit EX_TEMPFAIL;

	   $pid == waitpid $pid, 0 or croak "Failed to reap $pid: $!";
	   exit waitstat_reuse $?;

	   $output = `some-program -with args`;
	   waitstat_die $?, 'some-program';
	   print "Output from some-process:
", $output;

	   open PROGRAM, '| post-processor' or die "Can't fork: $!";
	   while (<IN>) {
	       print PROGRAM pre_process $_
		   or die "Error writing to post-processor: $!";
	   }
	   # This handles both flush failures at close time and a non-zero exit
	   # from the subprocess.
	   close_die PROGRAM, 'post-processor';

AUTHOR

       Roderick Schertler <roderick@argon.org>

SEE ALSO

       perl(1), IPC::Signal(3pm).

perl v5.8.8							    1999-10-27							     WaitStat(3pm)

WAIT(2) 							System Calls Manual							   WAIT(2)

NAME

       wait, waitpid - wait for process to terminate

SYNOPSIS

       #include <sys/types.h>
       #include <sys/wait.h>

       pid_t wait(int *status)
       pid_t waitpid(pid_t pid, int *status, int options)

DESCRIPTION

       Wait  causes its caller to delay until a signal is received or one of its child processes terminates.  If any child has died since the last
       wait, return is immediate, returning the process id and exit status of one of the terminated children.  If there are no children, return is
       immediate with the value -1 returned.

       On  return  from  a successful wait call, status is nonzero, and the high byte of status contains the low byte of the argument to exit sup-
       plied by the child process; the low byte of status contains the termination status of the process.  A more precise definition of the status
       word is given in <sys/wait.h>.  If wait can called with a null pointer argument to indicate that no status need be returned.

       Waitpid	provides  an  alternate  interface for programs that must not block when collecting the status of child processes, or that wish to
       wait for one particular child.  The pid parameter is the process ID of the child to wait for, -1 for any child.	The  status  parameter	is
       defined as above.  The options parameter is used to indicate the call should not block if there are no processes that wish to report status
       (WNOHANG), and/or that children of the current process that are stopped due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal  should  also
       have their status reported (WUNTRACED).	(Job control is not implemented for Minix, but these symbold and signals are.)

       When  the WNOHANG option is specified and no processes wish to report status, waitpid returns -1 with errno set to EAGAIN.  The WNOHANG and
       WUNTRACED options may be combined by or'ing the two values.

NOTES

       The call wait(&status) is equivalent to waitpid(-1, &status, 0).

       See sigaction(2) for a list of termination statuses (signals); 0 status indicates normal termination.  A special status (0177) is  returned
       for  a  stopped	process  that has not terminated and can be restarted; see ptrace(2).  If the 0200 bit of the termination status is set, a
       core image of the process was produced by the system.

       If the parent process terminates without waiting on its children, the initialization process (process ID = 1) inherits the children.

       <sys/wait.h> defines a number of macros that operate on a status word:

       WIFEXITED(status)
	    True if normal exit.

       WEXITSTATUS(status)
	    Exit status if the process returned by a normal exit, zero otherwise.

       WTERMSIG(status)
	    Signal number if the process died by a signal, zero otherwise.

       WIFSIGNALED(status)
	    True if the process died by a signal.

       WIFSTOPPED(status)
	    True if the process is stopped.  (Never true under Minix.)

       WSTOPSIG(status)
	    Signal number of the signal that stopped the process.

RETURN VALUE

       If wait returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process.  Otherwise, a
       value of -1 is returned and errno is set to indicate the error.

       Waitpid	returns  -1 if there are no children not previously waited for, if the process that it wants to wait for doesn't exist, or if WNO-
       HANG is specified and there are no stopped or exited children.

ERRORS

       Wait will fail and return immediately if one or more of the following are true:

       [ECHILD]       The calling process has no existing unwaited-for child processes.

       [EFAULT]       The status argument points to an illegal address.

       [EAGAIN]       Waitpid is called with the WNOHANG option and no child has exited yet.

SEE ALSO

       execve(2), exit(2), sigaction(2).

4th Berkeley Distribution					   June 30, 1985							   WAIT(2)