WAIT3(3C) Standard C Library Functions WAIT3(3C)
NAME
wait3, wait4 - wait for process to terminate or stop
SYNOPSIS
#include <sys/wait.h>
#include <sys/time.h>
#include <sys/resource.h>
pid_t wait3(
int *statusp,
int options,
struct rusage *rusage);
pid_t wait4(
pid_t pid,
int *statusp,
int options,
struct rusage *rusage);
DESCRIPTION
The
wait3() function delays its caller until a signal is received or one
of its child processes terminates or stops due to tracing. If any child
process has died or stopped due to tracing and this has not already been
reported, return is immediate, returning the process
ID and status of one
of those children. If that child process has died, it is discarded. If
there are no children, -1 is returned immediately. If there are only
running or stopped but reported children, the calling process is blocked.
If
statusp is not a null pointer, then on return from a successful
wait3() call, the status of the child process is stored in the integer
pointed to by
statusp.
*statusp indicates the cause of termination and
other information about the terminated process in the following manner:
o If the low-order 8 bits of
*statusp are equal to 0177, the
child process has stopped; the 8 bits higher up from the low-
order 8 bits of
*statusp contain the number of the signal that
caused the process to stop. See
signal.h(3HEAD).
o If the low-order 8 bits of
*statusp are non-zero and are not
equal to 0177, the child process terminated due to a signal;
the low-order 7 bits of
*statusp contain the number of the
signal that terminated the process. In addition, if the low-
order seventh bit of
*statusp (that is, bit 0200) is set, a
``core image'' of the process was produced; see
signal.h(3HEAD).
o Otherwise, the child process terminated due to an
exit() call;
the 8 bits higher up from the low-order 8 bits of
*statusp contain the low-order 8 bits of the argument that the child
process passed to
exit(); see
exit(2).
The
options argument is constructed from the bitwise inclusive
OR of zero
or more of the following flags, defined in <
sys/wait.h>:
WNOHANG Execution of the calling process is not suspended if status
is not immediately available for any child process.
WUNTRACED The status of any child processes that are stopped, and
whose status has not yet been reported since they stopped,
are also reported to the requesting process.
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 the
ru_utime and
ru_stime, members of the rusage structure,
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 the bitwise
OR operation of the two values.
The
wait4() function is an extended interface. If
pid is 0,
wait4() is
equivalent to
wait3(). If
pid has a nonzero value,
wait4() returns status
only for the indicated process
ID, but not for any other child processes.
If
pid has a negative value,
wait4() return status only for child
processes whose process group ID is equal to the absolute value of
pid.
The status can be evaluated using the macros defined by
wait.h(3HEAD).
RETURN VALUES
If
wait3() or
wait4() returns due to a stopped or terminated child
process, the process
ID of the child is returned to the calling process.
Otherwise,
-1 is returned and
errno is set to indicate the error.
If
wait3() or
wait4() return due to the delivery of a signal to the
calling process,
-1 is returned and
errno is set to
EINTR. If
WNOHANG was set in
options, it has at least one child process specified by
pid for which status is not available, and status is not available for any
process specified by
pid,
0 is returned. Otherwise,
-1 is returned and
errno is set to indicate the error.
The
wait3() and
wait4() functions return
0 if
WNOHANG is specified and
there are no stopped or exited children, and return the process
ID of the
child process if they return due to a stopped or terminated child
process. Otherwise, they return
-1 and set
errno to indicate the error.
ERRORS
The
wait3() and
wait4() functions will fail and return immediately if:
ECHILD The calling process has no existing unwaited-for child
processes.
EFAULT The
statusp or
rusage arguments point to an illegal address.
EINTR The function was interrupted by a signal. The value of the
location pointed to by
statusp is undefined.
EINVAL The value of
options is not valid.
The
wait4() function may fail if:
ECHILD The process specified by
pid does not exist or is not a child
of the calling process.
The
wait3()and
wait4() functions will terminate prematurely, return
-1,
and set
errno to
EINTR upon the arrival of a signal whose
SA_RESTART bit
in its flags field is not set (see
sigaction(2)).
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+---------------+-------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-------------------+
|MT-Level | Async-Signal-Safe |
+---------------+-------------------+
SEE ALSO
kill(1),
exit(2),
waitid(2),
getrusage(3C),
signal(3C),
wait(3C),
waitpid(3C),
signal.h(3HEAD),
wait.h(3HEAD),
proc(5),
attributes(7)NOTES
If a parent process terminates without waiting on its children, the
initialization process (process
ID = 1) inherits the children.
The
wait3() and
wait4() functions are automatically restarted when a
process receives a signal while awaiting termination of a child process,
unless the
SA_RESTART bit is not set in the flags for that signal.
November 4, 2005
WAIT3(3C)