WAIT(S) UNIX System V WAIT(S)
Name
wait, waitpid - wait for child process to stop or terminate
Syntax
#include <sys/types.h>
#include <sys/wait.h>
int wait (stat_loc)
int *stat_loc;
int wait ((int *) 0)
pid_t waitpid (pid, stat_loc, options)
pid_t pid;
int *stat_loc;
int options;
Description
The wait and waitpid system calls suspends the calling
process until one of the immediate children terminates or
until a child that is being traced stops, because it has hit
a break point. The wait system call returns prematurely if
a signal is received. If a child process stops or
terminates prior to the call on wait; return is immediate.
The waitpid() function behaves identically to the wait()
function, if the pid argument has a value of -1 and the
options argument has a value of zero. Otherwise, its
behavior is modified by the values of the pid and options
arguments.
The pid argument specifies a set of child processes for
which status is requested. The waitpid() only returns the
status of a child process from this set.
If pid is equal to -1, status is requested for any child
process. In this respect, waitpid() is then equivalent to
wait().
If pid is greater than zero, it specifies the process ID of
a single child process for which status is requested.
If pid is equal to zero, status is requested for any child
process whose process group ID is equal to that of the
calling process.
If pid is less than -1, status is requested for any child
process whose process group ID is equal to the absolute
value of pid.
The options argument is constructed from the bitwise
inclusive or of zero or more of the following flags, defined
in the header <sys/wait.h>:
WNOHANG The waitpid() function does not suspend
execution of the calling process if
status is not immmediately available for
one of the child processes specified by
pid.
WUNTRACED If the implementation supports job
control, the status of any child
processes specified by pid that are
stopped, and whose status has not yet
been reported since they stopped, are
also reported to the requesting process.
If wait() or waitpid() return because the status of a child
process is available, these functions return a value equal
to the process ID of the child process.
In this case, if the value of the argument stat_loc is not
NULL, information is stored in the location pointed to by
stat_loc. If and only if the status returned is from a
terminated child process that returned a value of zero from
main() or passed a value of zero as the status argument to
_exit() or exit(), the value stored at the location pointed
to by stat_loc is zero. Regardless of its value, this
information may be interpreted using the following macros,
which are defined in <sys/wait.h> and evaluate to integral
expressions; the stat_val argument is the integer value
pointed to by stat_loc.
WIFEEXITED(stat_val)
Evaluates to a non-zero value if status
was returned for a child process that
terminated normally.
WEXITSTATUS(stat_val)
If the value of WIFEXITED(stat_val) is
non-zero, this macro evaluates to the
low-order 8 bits of the status argument
that the child process passed to _exit()
or exit(), or the value the child
process returned from main().
WIFSIGNALED(stat_val)
Evaluates to a non-zero value if status
was returned for a child process that
terminated due to the receipt of a
signal that was not caught (see
signal(S)).
WTERMSIG(stat_val)
If the value of WIFSIGNALED(stat_val) is
non-zero, this macro evaluates to the
number of the signal that caused the
termination of the child process.
WIFSTOPPED(stat_val)
Evaluates to a non-zero value if status
was returned for a child process that is
currently stopped.
WSTOPSIG(stat_val)
If the value of WIFSTOPPED(stat_val) is
non-zero, this macro evaluates to the
number of the signal that caused the
child process to stop.
If the information stored at the location pointed to by
stat_loc was stored there by a call to the waitpid()
function that specified the WUNTRACED flag, exactly one of
the macros WIFEXITED(stat_loc), WIFSIGNALED(stat_loc), and
WIFSTOPPED(stat_loc) evaluates to a non-zero value. If the
information stored at the location pointed to by stat_loc
was stored there by a call to the waitpid() function that
did not specify the WUNTRACED flag or by a call to the
wait() function, exactly one of the macros
WIFEXITED(*stat_loc) and WIFSIGNALED(*stat_loc) evaluates to
a non-zero number.
If stat_loc is non-zero, 16 bits of information called
status are stored in the low order 16 bits of the location
pointed to by stat_loc. status can be used to differentiate
between stopped and terminated child processes and if the
child process terminated, status identifies the cause of
termination and passes useful information to the parent.
This is accomplished in the following manner:
If the child process stopped, the high order 8 bits of
status will contain the number of the signal that
caused the process to stop, and the low order 8 bits
will be set equal to 0177.
If the child process terminated due to an exit call,
the low order 8 bits of status will be zero, and the
high order 8 bits will contain the low order 8 bits of
the argument that the child process passed to exit (see
exit(S)).
If the child process terminated due to a signal, the
high order 8 bits of status will be zero, and the low
order 8 bits will contain the number of the signal that
caused the termination. In addition, if the low order
seventh bit (that is, bit 200) is set, a ``core image''
will have been produced (see signal(S)).
If a parent process terminates without waiting for its child
processes to terminate, the parent process ID of each child
process is set to 1. This means the initialization process
inherits the child processes (see intro(S)).
Return Value
If the wait() or waitpid() functions return because the
status of a child process is available, these functions
return a value equal to the process ID of the child process
for which status is reported. If the wait() or waitpid()
functions return due to the delivery of a signal to the
calling process, a value of -1 is returned and errno is set
to [EINTR]. If the waitpid() function was invoked with
WNOHANG 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, a
value of zero is returned. Otherwise, a value of -1 is
returned, and errno is set to indicate the error.
The wait() function fails and returns -1 if one or more of
the following is true:
[ECHILD] The calling process has no existing
unwaited-for child processes.
[EINTR] The function was interrrupted by a
signal. The value of the location
pointed to by stat_loc is undefined.
If any of the following conditions occur, the waitpid()
function returns -1 and sets errno to the corresponding
value:
[ECHILD] The process or process group defined by
pid does not exist or is not a child of
the calling process.
[EINTR] The function was interrrupted by a
signal. The value of the location
pointed to by stat_loc is undefined.
[EINVAL] The value of the options argument is not
valid.
See Also
exec(S), exit(S), fork(S), intro(S), pause(S), ptrace(S),
signal(S), times(S)
Warning
The wait system call fails and its actions are undefined if
stat_loc points to an invalid address.
Standards Conformance
wait is conformant with:
AT&T SVID Issue 2, Select Code 307-127;
The X/Open Portability Guide II of January 1987;
IEEE POSIX Std 1003.1-1988 with C Standard Language-
Dependent System Support;
and NIST FIPS 151-1.
waitpid is conformant with:
IEEE POSIX Std 1003.1-1988 with C Standard Language-
Dependent System Support;
and NIST FIPS 151-1.
(printed 6/20/89)