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).

• 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 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
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 alter-
nate interface that allows both non-blocking status  collec-
tion 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,  respec-
tively.   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 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 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. 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.