wait(3) (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 w_status 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 w_status are equal to 0177, the
child process has stopped; the 8 bits higher up from the
low-order 8 bits of w_status contain the number of the
signal that caused the process to stop. See ptrace(2) and
sigvec(3).
7/91 Page 1
wait(3) (BSD Compatibility Package) wait(3)
⊕ If the low-order 8 bits of w_status are non-zero and are not
equal to 0177, the child process terminated due to a signal;
the low-order 7 bits of w_status contain the number of the
signal that terminated the process. In addition, if the
low-order seventh bit of w_status (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 w_status
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 w_stopval member has the value WSTOPPED, the child
process has stopped; the value of the w_stopsig member is
the signal that stopped the process.
⊕ If the w_termsig member is non-zero, the child process
terminated due to a signal; the value of the w_termsig
member is the number of the signal that terminated the
process. If the w_coredump member is non-zero, a core dump
was produced.
⊕ Otherwise, the child process terminated due to an exit call;
the value of the w_retcode 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 w_status 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.ru_utime and
rusage.ru_stime, respectively.
Page 2 7/91
wait(3) (BSD Compatibility Package) wait(3)
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.
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 when 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 SV_INTERRUPT 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.
7/91 Page 3
wait(3) (BSD Compatibility Package) wait(3)
wait, and wait3 are automatically restarted when a process receives a
signal while awaiting termination of a child process, unless the
SV_INTERRUPT 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.
Page 4 7/91