WAIT(2,L) AIX Technical Reference WAIT(2,L)
-------------------------------------------------------------------------------
wait, waitpid
PURPOSE
Obtains status information pertaining to a child process.
SYNTAX
#include <sys/types.h>
#include <sys/wait.h>
#include <unistd.h>
pid_t wait(NULL);
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 system calls allow the calling process to obtain status
information pertaining to one of its child processes. Various options permit
the waitpid system call to be used to obtain status information for child
processes that have terminated or stopped. If status information is available
for more than one child process, the order in which this status is reported is
not reliable.
The wait system call suspends execution of the calling process until status
information for one of its terminated child processes is available, or until a
signal is delivered (to the calling process) 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 the wait system call, the wait system call
immediately returns with status information. This is not to say that the wait
system call will be executed atomically; other processes may execute between
the time the call to the wait system call is made and the time that the wait
system call returns.
If the waitpid system call is given a pid argument with a value of -1 and an
options argument with a value of 0, then the waitpid system call behaves
identically to the wait system call. Otherwise, the behavior of the waitpid
system call is similar to the behavior of the wait system call, but differs as
indicated by the values of its pid and options arguments.
The pid argument specifies the set of child processes for which status may be
reported by the waitpid system call. The waitpid system call does not return
Processed November 7, 1990 WAIT(2,L) 1
WAIT(2,L) AIX Technical Reference WAIT(2,L)
the status of a child process that is not in the set specified by the pid
argument.
A pid argument with a value that is less than -1 specifies the set which
includes all child processes with a process group ID that is equal to the
absolute value of the pid argument. A pid argument with a value of -1
specifies the set which includes all child processes. This is the same set
that is implicitly specified in a wait system call. A pid argument with a
value of 0 specifies the set which includes all child processes that are in the
same process group as the process which called the waitpid system call. A pid
argument with a value that is greater than 0 specifies the set which includes
only the child process with a process ID that is equal to the value of the pid
argument.
The options argument is constructed from the bitwise inclusive OR of 0 or more
of the WNOHANG and WUNTRACED flags. These flags are defined in the header
<sys/wait.h>.
If the WNOHANG flag is inclusive ORed into the options argument of a waitpid
system call, the lack of immediately available status information (for one of
the processes that is in the set specified by pid) will not cause the
suspension of the execution of the calling process.
If the WUNTRACED flag is inclusive ORed into the options argument of a waitpid
system call, the status of any child processes in a set of child processes
specified by the pid argument (of the same call to the waitpid system call)
that are stopped, and whose status has not yet been reported since they stopped
will be included in the set of processes from which one member has its status
reported to the calling process.
If the wait or waitpid system call returns to report the status of a child
process, the call returns the value of the process ID of the child process
whose status is being reported. In the case in which the wait or waitpid
system call returns to report the status of a child process, if the value of
the argument stat_loc is not NULL, wait and waitpid store information in
*stat_loc (that is, the location pointed to by stat_loc). The wait and waitpid
calls store a value of 0 at *stat_loc only if the status that the wait or
waitpid system call reports is from a terminated child process that returned a
value of 0 from its main or gave a status argument with a value of 0 to a call
to _exit or exit. Any value that wait or waitpid stores in *stat_loc may be
interpreted using the macros WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG,
WIFSTOPPED, and WSTOPSIG. These macros are defined in <sys/wait.h> and
evaluate to values of type int. Note that these macros do not accept a
constant as an argument.
The macro WIFEXITED(*stat_loc) evaluates to a nonzero value if status was
reported for a child process that terminated normally.
If the macro WIFEXITED(*stat_loc) evaluates to a nonzero value, the macro
WEXITSTATUS(*stat_loc) evaluates to the value of the low-order 8 bits of the
status argument that the child process (for which status was reported) returned
from its main or gave as the status argument of a call to _exit or exit.
Processed November 7, 1990 WAIT(2,L) 2
WAIT(2,L) AIX Technical Reference WAIT(2,L)
The macro WIFSIGNALED(*stat_loc) evaluates to a nonzero value if status was
reported for a child process that terminated due to the receipt of a signal
that was not caught.
If the macro WIFSIGNALED(*stat_loc) evaluates to a nonzero value, the macro
WTERMSIG(*stat_loc) evaluates to the number of the signal that caused the
termination of the child process for which status was reported.
The macro WIFSTOPPED(*stat_loc) evaluates to a nonzero value if status was
reported for a child process because that child process was stopped.
If the macro WIFSTOPPED(*stat_loc) evaluates to a nonzero value, then the macro
WSTOPSIG(*stat_loc) evaluates to the number of the signal that caused the child
process (for which status was reported) to stop.
If the information stored in *stat_loc was stored there by a call to the
waitpid system call that was passed an options argument that had WUNTRACED
bitwise inclusive ORed into it, exactly one of the macros WIFEXITED(*stat_loc),
WIFSIGNALED(*stat_loc), and WIFSTOPPED(*stat_loc) evaluates to a nonzero value.
If the information stored in *stat_loc was stored there by a call to the
waitpid system call that was passed an options argument that did not have
WUNTRACED bitwise inclusive ORed into it or by a call to the wait system call,
exactly one of the macros WIFEXITED(*stat_loc) and WIFSIGNALED(*stat_loc)
evaluates to a nonzero value.
The following information may also be used to interpret *stat_loc:
o If the child process stopped in a trace mode, then bits 8-15 (starting with
the least significant bit) of *stat_loc contain the number of the signal
that caused the process to stop and the low-order 8 bits are set to one of
the following:
- 0177 (0x7F), which indicates the process was stopped while being
traced. If multi-process debugging mode was not set by the ptrace
system call, the low-order bits are set to this value. (For more
information on multi-process debugging, see "ptrace.")
- 0176 (0x7E), which means the process was stopped after a fork system
call. Both the traced process and its newly forked child process are
stopped. This value only occurs when multi-process debugging mode is
set with the ptrace system call.
- 0175 (0x7D), which indicates that the process was stopped after an exec
system call. This value only occurs when multi-process debugging mode
is set with the ptrace system call.
o If the child process stopped in a trace mode, then bits 8-15 (starting with
the least significant bit) of *stat_loc contain the number of the signal
that caused the process to stop and the low-order 8 bits are set equal to
0177.
Processed November 7, 1990 WAIT(2,L) 3
WAIT(2,L) AIX Technical Reference WAIT(2,L)
o If the child process terminated due to an exit system call, the low-order 8
bits of *stat_loc are 0 and the high-order 8 bits contain the low-order 8
bits of the parameter that the child passed to exit or _exit.
o If the child process terminated due to a signal, bits 8-15 (starting with
the least significant bit) of *stat_loc are 0 and the low-order 8 bits
contain the number of the signal that caused the termination. In addition,
if the low-order seventh bit (bit 0200 or 0x80) is set, then a memory image
file is produced before wait returns.
o If the Transparent Computing Facility is installed and the child process
was running on a different site, and that site left the cluster, a
*stat_loc argument looks as though the child terminated due to a SIGPWR
signal.
If a parent process terminates without waiting for all of its child processes
to terminate, the remaining child processes become "orphans" and the parent
process ID of each of the remaining child processes are set to -1. This is
done to avoid confusion between processes which are the real child processes of
the init process and processes which are orphaned; this is useful in a
Transparent Computing Facility cluster. Note that if an orphan calls the
getppid system call, the orphan is informed that its parent process ID is 1,
not -1.
Note: The effect of the wait system call is modified by the signal action of
the SIGCHLD signal. See "sigaction, sigvec, signal" for details.
Warning: The actions of the wait and waitpid system calls are undefined if the
stat_loc parameter points to a location outside of the process's allocated
address space.
RETURN VALUE
If the wait or waitpid system calls return to report the status of a suitable
child process, these system calls return the value of the process ID of the
child process for which the status is reported. For the wait system call any
child process is "suitable". A "suitable" a child process for the waitpid
system call is a member of the set of child processes that is specified by that
waitpid system call's pid argument. If the wait or waitpid system calls return
due to the delivery of a signal to the calling process, a value of -1 is
returned and errno is set to the value EINTR. If a waitpid system call was
passed an options argument that had WNOHANG inclusive ORed into it, and there
is at least one suitable child process (of the process which called the waitpid
system call), and status is not available for any of these suitable child
processes, then that waitpid system call returns a value of 0. Otherwise, the
wait and waitpid system calls return a value of -1, and set errno to indicate
the error.
ERROR CONDITIONS
Processed November 7, 1990 WAIT(2,L) 4
WAIT(2,L) AIX Technical Reference WAIT(2,L)
If any of the following conditions occur, then the wait system call returns
without waiting and returns a value of -1 and sets errno to the corresponding
value.
ECHILD The calling process has no existing child processes not yet waited
for.
EINTR The wait system call was interrupted by a signal. When a call to the
wait system call indicates this error, the effect of the call on
*stat_loc is unreliable.
If any of the following conditions occur, then the waitpid system call returns
without waiting and returns a value of -1 and sets errno to the corresponding
value.
ECHILD The calling process has no suitable child processes (that is, child
processes that are in the set of child processes that is specified by
that waitpid system call's pid argument) not yet waited for.
EINTR The waitpid system call was interrupted by a signal. When a call to
the waitpid system call indicates this error, the effect of the call
on *stat_loc is not reliable.
EINVAL The value of the options argument is not valid.
EFAULT If this error is detected, the stat_loc points to an area outside the
process's allocated address space.
Processed November 7, 1990 WAIT(2,L) 5