wait(2) DG/UX 5.4.2 wait(2)
NAME
wait, waitpid - wait for process termination
SYNOPSIS
#include <sys/types.h>
#include <sys/wait.h>
pidt wait(statloc)
int *statloc;
pidt waitpid (pid, statloc, options)
pidt pid;
int *statloc;
int options;
where:
pid A process identifier
statloc A location for returning a process status
options 0 or a positive integer (see "Option Flags" below)
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 of the calling
process.
Licensed material--property of copyright holder(s) 1
wait(2) DG/UX 5.4.2 wait(2)
(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.
Option Flags
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>:
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.
WCONTINUED
Also report the status of any continued child process
specified by pid whose status has not been reported since
it continued.
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.
WNOWAIT Keep the process whose status is returned in statloc in a
waitable state. The process may be waited for again with
identical results.
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 statloc is not NULL, information shall be stored in the
location pointed to by statloc. 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 statloc 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 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 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) 2
wait(2) DG/UX 5.4.2 wait(2)
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.
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
process to stop.
WIFCONTINUED(statval)
Evaluates to a non-zero value if status was returned for a
child process that has continued.
If the information stored at the location pointed to by statloc was
stored there by a call to the waitpid() function that specified the
WUNTRACED flag, exactly one of the macros WIFEXITED(*statloc),
WIFSIGNALED(*statloc), and WIFSTOPPED(*statloc) shall evaluate to a
non-zero value. If the information stored at the location pointed to
by statloc 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(*statloc) and
WIFSIGNALED(*statloc) 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.
RETURN VALUE
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.
DIAGNOSTICS
If any of the following conditions occur, the wait() function shall
Licensed material--property of copyright holder(s) 3
wait(2) DG/UX 5.4.2 wait(2)
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 statloc 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 statloc 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) 4