wait(3-BSD) MISC. REFERENCE MANUAL PAGES wait(3-BSD)
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 chil-
dren, 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 suc-
cessful wait call the status of the child process whose pro-
cess 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 fol-
lowing 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 con-
tain the number of the signal that caused the
1
wait(3-BSD) MISC. REFERENCE MANUAL PAGES wait(3-BSD)
process to stop. See ptrace(2) and sigvec(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 pro-
cess.
⊕ If the wtermsig member is non-zero, the child pro-
cess 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 pro-
cess passed to exit.
The other members of the wait union merely provide an alter-
nate 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 dis-
carded after it reports status, and a stopped process will
2
wait(3-BSD) MISC. REFERENCE MANUAL PAGES wait(3-BSD)
not report its status more than once. If rusage is not a
NULL pointer, a summary of the resources used by the ter-
minated process and all its children is returned. Only the
user time used and the system time used are currently avail-
able. 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 WUN-
TRACED options may be combined by ORing the two values.
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 pro-
cess, 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 ter-
minated 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 compati-
bility 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.
3
wait(3-BSD) MISC. REFERENCE MANUAL PAGES wait(3-BSD)
NOTES
If a parent process terminates without waiting on its chil-
dren, 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 pro-
cess, unless the SVINTERRUPT bit is set in the flags for
that signal.
WARNINGS
Calls to wait with an argument of 0 should be cast to type
`union wait *', as in:
wait((union wait *)0)
Otherwise lint will complain.
4