wait(2) DG/UX 4.30 wait(2)
NAME
wait, waitpid - wait for process termination
SYNOPSIS
#include <sys/types.h>
#include <sys/wait.h>
pid_t wait(stat_loc)
int *stat_loc;
pid_t waitpid (pid, stat_loc, options)
pid_t pid;
int *stat_loc;
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 shall 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 shall be
immediate.
The waitpid() function shall behave 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 shall be 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() function shall
only return the status of a child process from this set.
(1) If pid is equal to -1, status is requested for any
child process. In this respect, waitpid() is then
equivalent to wait().
(2) If pid is greater than zero, it specifies the process
ID of a single child process for which status is
requested.
(3) If pid is equal to zero, status is requested for any
child process whose process group ID is equal to that
Licensed material--property of copyright holder(s) Page 1
wait(2) DG/UX 4.30 wait(2)
of the calling process.
(4) 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 shall not suspend execution
of the calling process if status is not
immediately 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, shall also be
reported to the requesting process.
If wait() or waitpid() return because the status of a child
process is available, these functions shall 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 shall be 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 shall be 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.
WIFEXITED(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.h>).
Licensed material--property of copyright holder(s) Page 2
wait(2) DG/UX 4.30 wait(2)
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) shall evaluate 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) shall
evaluate to a non-zero value.
An implementation may define additional circumstances under
which wait() or waitpid() reports status. This shall not
occur unless the calling process or one of its child
processes explicitly makes use of a nonstandard extension.
In these cases the interpretation of the reported status is
implementation-defined.
If a parent process terminates without waiting for all of
its child processes to terminate, the remaining child
processes shall be assigned a new parent process ID
corresponding to an implementation-defined system process.
RETURNS
If the wait() or waitpid() functions return because the
status of a child process is available, these functions
shall 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 shall be returned and
errno shall be 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 shall be returned.
Otherwise, a value of -1 shall be returned, and errno shall
be set to indicate the error.
Licensed material--property of copyright holder(s) Page 3
wait(2) DG/UX 4.30 wait(2)
ERRORS
If any of the following conditions occur, the wait()
function shall return -1 and set errno to the corresponding
value:
[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 stat_loc is
undefined.
If any of the following conditions occur, the waitpid()
function shall return -1 and set errno to the corresponding
value:
[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 stat_loc is
undefined.
[EINVAL] The value of the options argument is not valid.
SEE ALSO
_exit(2), fork(2), pause(2), times(2), /usr/include/signal.h
COPYRIGHT
Portions of this text are reprinted from IEEE Std 1003.1-
1988, Portable Operating System Interface for Computer
Environment, copyright © 1988 by the Institute of Electrical
and Electronics Engineers, Inc., with the permission of the
IEEE Standards Department. To purchase IEEE Standards, call
800/678-IEEE.
In the event of a discrepancy between the electronic and the
original printed version, the original version takes
precedence.
STANDARDS
Wait and waitpid report status if a child process that is
being traced [by ptrace(2) or dgxtrace(2)] stops. In this
case, the 8 low order bits of the wait status will contain
the octal value 0177 and the 8 high order bits will contain
the value of the signal that stopped the child process.
If the parent process terminates without waiting for all of
its child processes to terminate, the remaining child
processes are assigned a new parent process ID of 1, which
is the PID of the special system initialization process.
Licensed material--property of copyright holder(s) Page 4