wait(3) UNIX System V(BSD Compatibility Package) wait(3)
NAME
wait, wait3, WIFSTOPPED, WIFSIGNALED, WIFEXITED - wait for process to
terminate or stop
SYNOPSIS
cc [ flag. . . ] file . . . -lucb
#include <sys/wait.h>
int wait(statusp)
union wait *statusp;
#include <sys/time.h>
#include <sys/resource.h>
int wait3(statusp, options, rusage)
union wait *statusp;
int options;
struct rusage *rusage;
WIFSTOPPED(status)
union wait status;
WIFSIGNALED(status)
union wait status;
WIFEXITED(status)
union wait status;
DESCRIPTION
wait delays its caller until a signal is received or one of its child
processes terminates or stops due to tracing. If any child has died or
stopped due to tracing and this has not been reported using wait, return
is immediate, returning the process ID and exit status of one of those
children. If that child had died, it is discarded. If there are no
children, return is immediate with the value -1 returned. If there are
only running or stopped but reported children, the calling process is
blocked.
If status is not a NULL pointer, then on return from a successful wait
call the status of the child process whose process ID is the return value
of wait is stored in the wait union pointed to by status. The wstatus
member of that union is an int; it indicates the cause of termination and
other information about the terminated process in the following manner:
⊕ If the low-order 8 bits of wstatus are equal to 0177, the child
process has stopped; the 8 bits higher up from the low-order 8
bits of wstatus contain the number of the signal that caused
the process to stop. See ptrace(2) and sigvec(3).
10/89 Page 1
wait(3) UNIX System V(BSD Compatibility Package) wait(3)
⊕ If the low-order 8 bits of wstatus are non-zero and are not
equal to 0177, the child process terminated due to a signal; the
low-order 7 bits of wstatus contain the number of the signal
that terminated the process. In addition, if the low-order
seventh bit of wstatus (that is, bit 0200) is set, a ``core
image'' of the process was produced; see sigvec(3).
⊕ Otherwise, the child process terminated due to an exit call; the
8 bits higher up from the low-order 8 bits of wstatus contain
the low-order 8 bits of the argument that the child process
passed to exit; see exit(2).
Other members of the wait union can be used to extract this information
more conveniently:
⊕ If the wstopval member has the value WSTOPPED, the child
process has stopped; the value of the wstopsig member is the
signal that stopped the process.
⊕ If the wtermsig member is non-zero, the child process
terminated due to a signal; the value of the wtermsig member is
the number of the signal that terminated the process. If the
wcoredump member is non-zero, a core dump was produced.
⊕ Otherwise, the child process terminated due to an exit call; the
value of the wretcode member is the low-order 8 bits of the
argument that the child process passed to exit.
The other members of the wait union merely provide an alternate way of
analyzing the status. The value stored in the wstatus field is
compatible with the values stored by other versions of the UNIX system,
and an argument of type int * may be provided instead of an argument of
type union wait * for compatibility with those versions.
wait3 is an alternate interface that allows both non-blocking status
collection and the collection of the status of children stopped by any
means. 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 have status to report (WNOHANG), and/or that children of the current
process that are stopped due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP
signal are eligible to have their status reported as well (WUNTRACED). A
terminated child is discarded after it reports status, and a stopped
process will not report its status more than once. If rusage is not a
NULL pointer, a summary of the resources used by the terminated process
and all its children is returned. Only the user time used and the system
time used are currently available. They are returned in rusage.ruutime
and rusage.rustime, respectively.
When the WNOHANG option is specified and no processes have status to
report, wait3 returns 0. The WNOHANG and WUNTRACED options may be
combined by ORing the two values.
Page 2 10/89
wait(3) UNIX System V(BSD Compatibility Package) wait(3)
WIFSTOPPED, WIFSIGNALED, WIFEXITED, are macros that take an argument
status, of type `union wait', as returned by wait, or wait3. WIFSTOPPED
evaluates to true (1) when the process for which the wait call was made
is stopped, or to false (0) otherwise. WIFSIGNALED evaluates to true
when the process was terminated with a signal. WIFEXITED evaluates to
true whe the process exited by using an exit(2) call.
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.
wait3 returns 0 if WNOHANG is specified and there are no stopped or
exited children, and returns the process ID of the child process if it
returns due to a stopped or terminated child process. Otherwise, wait3
returns a value of -1 and sets errno to indicate the error.
ERRORS
wait, or wait3 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 or rusage arguments point to an illegal
address.
wait, and wait3 will terminate prematurely, return -1, and set errno to
EINTR upon the arrival of a signal whose SVINTERRUPT bit in its flags
field is set [see sigvec(3) and siginterrupt(3)]. signal(3), in the
System V compatibility library, sets this bit for any signal it catches.
SEE ALSO
sigvec(3), getrusage(3), siginterrupt(3), signal(3)
exit(2), ptrace(2), signal(2) wait(2), waitpid(2) in the Programmer's
Reference Manual
NOTES
If a parent process terminates without waiting on its children, the
initialization process (process ID = 1) inherits the children.
wait, and wait3 are automatically restarted when a process receives a
signal while awaiting termination of a child process, unless the
SVINTERRUPT bit is set in the flags for that signal.
Calls to wait with an argument of 0 should be cast to type `union wait
*', as in:
wait((union wait *)0)
10/89 Page 3
wait(3) UNIX System V(BSD Compatibility Package) wait(3)
Otherwise lint will complain.
Page 4 10/89