wait(2) wait(2)
NAME
wait, waitpid - wait for child process to stop or terminate
SYNOPSIS
#include <sys/types.h>
#include <sys/wait.h>
pidt wait(int *statloc);
pidt waitpid(pidt pid, int *statloc, int options);
DESCRIPTION
The wait() and waitpid() functions allow the calling process to obtain
status information pertaining to one of its child processes. Various
options permit status information to be obtained for child processes
that have terminated or stopped. If status information is available
for two or more child processes, the order in which their status is
reported is unspecified.
The wait() function will suspend execution of the calling process
until status information for one of its terminated child processes is
available, or until delivery of a signal whose action is either to
execute a signal-catching function or to terminate the process. If
status information is available prior to the call to wait(), return
will be immediate.
The waitpid() function will behave identically to wait(), if the pid
argument is (pidt)-1 and the options argument is 0. Otherwise, its
behavior will be modified by the values of the pid and options argu-
ments.
The pid argument specifies a set of child processes for which status
is requested. The waitpid() function will only return the status of a
child process from this set:
- If pid is equal to (pidt)-1, status is requested for any child
process. In this respect, waitpid() is then equivalent to wait().
- If pid is greater than 0, it specifies the process ID of a single
child process for which status is requested.
- If pid is 0, status is requested for any child process whose pro-
cess group ID is equal to that of the calling process.
- If pid is less than (pidt)-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> [see wait(5)].
Page 1 Reliant UNIX 5.44 Printed 11/98
wait(2) wait(2)
WCONTINUED The waitpid() function will report the status of any
continued child process specified by pid whose status
has not been reported since it continued from a job
control stop.
WNOHANG The waitpid() function will not suspend execution of
the calling process if status is not immediately
available for one of the child processes specified by
pid.
WUNTRACED The status of any child processes specified by pid
that are stopped, and whose status has not yet been
reported since they stopped, will also be reported to
the requesting process.
If the calling process has SANOCLDWAIT set or has SIGCHLD set to
SIGIGN, and the process has no unwaited for children that were
transformed into zombie processes, it will block until all of its
children terminate, and wait() and waitpid() will fail and set errno
to ECHILD.
If wait() or waitpid() return because the status of a child process is
available, these functions will return a value equal to the process ID
of the child process. In this case, if the value of the argument
statloc is not a null pointer, information will be stored in the
location pointed to by statloc. If and only if the status returned is
from a terminated child process that returned 0 from main() or passed
0 as the status argument to exit() or exit(), the value stored at the
location pointed to by statloc will be 0. 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
statval argument is the integer value pointed to by statloc.
WIFEXITED(statval)
Evaluates to a non-zero value if status was returned for a child
process that terminated normally.
WEXITSTATUS(statval)
If the value of WIFEXITED(statval) 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(statval)
Evaluates to 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(5)].
WTERMSIG(statval)
If the value of WIFSIGNALED(statval) is non-zero, this macro
evaluates to the number of the signal that caused the termination
of the child process.
Page 2 Reliant UNIX 5.44 Printed 11/98
wait(2) wait(2)
WIFSTOPPED(statval)
Evaluates to a non-zero value if status was returned for a child
process that is currently stopped.
WSTOPSIG(statval)
If the value of WIFSTOPPED(statval) is non-zero, this macro
evaluates to the number of the signal that caused the child pro-
cess to stop.
WIFCONTINUED(statval)
Evaluates to a non-zero value if status was returned for a child
process that has continued from a job control stop.
If the information pointed to by statloc was stored by a call to
waitpid() that specified the WUNTRACED flag and did not specify the
WCONTINUED flag, exactly one of the macros WIFEXITED(*statloc),
WIFSIGNALED(*statloc), and WIFSTOPPED(*statloc), will evaluate to a
non-zero value.
If the information pointed to by statloc was stored by a call to
waitpid() that specified the WUNTRACED and WCONTINUED flags, exactly
one of the macros WIFEXITED(*statloc), WIFSIGNALED(*statloc),
WIFSTOPPED(*statloc), and WIFCONTINUED(*statloc), will evaluate to a
non-zero value.
If the information pointed to by statloc was stored by a call to
waitpid() that did not specify the WUNTRACED or WCONTINUED flags, or
by a call to the wait() function, exactly one of the macros
WIFEXITED(*statloc) and WIFSIGNALED(*statloc) will evaluate to a
non-zero value.
If the information pointed to by statloc was stored by a call to
waitpid() that did not specify the WUNTRACED flag and specified the
WCONTINUED flag, or by a call to the wait() function, exactly one of
the macros WIFEXITED(*statloc), WIFSIGNALED(*statloc), and
WIFCONTINUED(*statloc), will evaluate to a non-zero value.
There may be additional implementation-dependent circumstances under
which wait() or waitpid() report status. This will not occur unless
the calling process or one of its child processes explicitly makes use
of a non-standard extension. In these cases the interpretation of the
reported status is implementation-dependent.
If a parent process terminates without waiting for all of its child
processes to terminate, the remaining child processes will be assigned
a new parent process ID corresponding to an implementation-dependent
system process.
Page 3 Reliant UNIX 5.44 Printed 11/98
wait(2) wait(2)
RETURN VALUE
If wait() or waitpid() returns because the status of a child process
is available, these functions will return a value equal to the process
ID of the child process for which status is reported. If wait() or
waitpid() returns due to the delivery of a signal to the calling pro-
cess, -1 will be returned and errno will be set to EINTR. If waitpid()
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, 0 will be returned.
Otherwise, (pidt)-1 will be returned, and errno will be set to indi-
cate the error.
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
The wait() function will fail if:
ECHILD The calling process has no existing unwaited-for child
processes.
EINTR The function was interrupted by a signal. The value of the
location pointed to by statloc is undefined.
The waitpid() function will fail if:
ECHILD The process or process group specified by pid does not exist
or is not a child of the calling process.
EINTR The function was interrupted by a signal. The value of the
location pointed to by statloc is undefined.
EINVAL The options argument is not valid.
SEE ALSO
exec(2), exit(2), fork(2), pause(2), ptrace(2), signal(2), waitid(2),
wait3(3), signal(5), types(5), wait(5), wstat(5).
Page 4 Reliant UNIX 5.44 Printed 11/98