NAME
wait, waitpid, wait3, wait4, waitid - Waits for a child pro-
cess to stop or terminate
SYNOPSIS
#include <sys/types.h>
#include <sys/wait.h>
pid_t wait (
int *status_location );
pid_t waitpid (
pid_t process_id,
int *status_location,
int options );
#include <sys/resource.h>
pid_t wait3 (
union wait *status_location,
int options,
struct rusage *resource_usage );
pid_t wait4 (
pid_t pid;
int *status_location,
int options,
struct rusage *resource_usage );
int waitid (
idtype_t idtype,
id_t id,
siginfo_t *infop,
int options);
PARAMETERS
status_location
Points to a location that is filled in with the
child process termination status, as defined in
the sys/wait.h header file.
process_id
Specifies the child process.
options Modifies the behavior of the function.
resource_usage
Specifies the location of a structure to be filled
in with resource utilization information for ter-
minated child processes.
idtype and id
Specifies the children for which the waitid()
function will wait according to the following
rules:
o If the idtype parameter is P_PID, the
waitid() function waits for the child with a
process ID equal to (pid_t)id.
o If the idtype parameter is P_PGID, the
waitid() function waits for any child with a
process group ID equal to (pid_t)id.
o If the idtype parameter is P_ALL, the
waitid() function waits for any children and
id is ignored.
infop Points to a siginfo_t structure. The value of
siginfo_t is the status of the process being
waited for.
DESCRIPTION
The wait() function suspends the calling process until it
receives a signal that is to be caught, or until any one of
the calling process' child processes stops or terminates.
The wait() function returns without waiting if a child pro-
cess that has not been waited for has already stopped or
terminated prior to the call.
The effect of the wait() function can be modified by the
setting of the SIGCHLD signal. (See the sigaction() func-
tion for details.)
The waitpid() function behaves identically to the wait()
function if the process_id parameter has a value of -1 and
the options parameter has a value of 0 (zero). Otherwise,
its behavior is modified by the values of the process_id and
options parameters.
The waitid() function is an enhancement to the waitpid()
function. This function adds the idtype parameter to select
the process or group of processes for which to wait. It
records the current state of a child in the structure
pointed to the infop parameter. If a child process changes
state prior to the call to waitid(), the function returns
immediately.
The wait(), waitpid(), wait3(), wait4(), and waitid() func-
tions, which suspend the calling process until the request
is completed, are redefined so that only the calling thread
is suspended.
The process_id parameter of the waitpid() and wait4() func-
tions allows the calling process to gather status from a
specific set of child processes, according to the following
rules:
o If the process_id parameter is equal to -1, status is
requested for any child process. In this respect, the
waitpid() function is equivalent to the wait() func-
tion.
o If the process_id parameter is greater than 0 (zero),
it specifies the process ID of a single child process
for which status is requested.
o If the process_id parameter is equal to 0 (zero),
status is requested for any child process whose process
group ID is equal to that of the calling process.
o If the process_id parameter is less than -1, status is
requested for any child process whose process group ID
is equal to the absolute value of the process_id param-
eter.
The waitpid() and wait4() functions will only return the
status of a child process from this set.
The options parameter to the waitpid(), wait3(), and wait4()
functions modifies the behavior of the function. Four
values are defined, WNOHANG, WUNTRACED, WCONTINUED and
WNOWAIT, which can be combined by specifying their bitwise-
inclusive OR. The WNOHANG option prevents the calling pro-
cess from being suspended even if there are child processes
to wait for. In this case, 0 (zero) is returned indicating
that there are no child processes that have stopped or ter-
minated. If the WUNTRACED option is set, the call also
returns information when child processes of the current pro-
cess are stopped because they received a SIGTTIN, SIGTTOU,
SIGSTOP, or SIGTSTOP signal. The WCONTINUED option returns
information about any continued child process specified by
the process_id parameter whose status has remained
unreported since it has stopped. The WNOWAIT option keeps
the process whose status is returned in status_location in a
waitable state. The process may be waited for again with the
same results.
The options parameter to the waitid() function is used to
specify which state changes for which the function is to
wait. Any of the following flags can be ORed:
WEXITED Waits for processes that have exited.
WTRACED Waits for traced process that has stopped at a
breakpoint, or that has generated a trap.
WSTOPPED Returns information about the status of any child
that has stopped upon receipt of a signal.
WCONTINUED
Returns information about the status of any child
that had been stopped and has been continued.
WNOHANG Returns immediately if there are no children for
which to wait.
WNOWAIT Keeps the process whose status is returned in the
infop parameter in a waitable state. The process
may be waited for again with the same results.
If the wait(), waitpid(), waitid, wait3(), wait4() function
returns because the status of a child process is available,
they return the process ID of the child process. In this
case, if the status_location parameter is not null, informa-
tion will be stored in the location pointed to by
status_location. The value stored at the location pointed
to by status_location is 0 (zero) if and only if the status
returned is from a terminated child process that returned 0
(zero) from the main() routine, or passed 0 (zero) as the
status parameter to the _exit() or exit() function. Regard-
less of its value, this information can be interpreted using
the following macros, which are defined in the sys/wait.h
header file and evaluate to integral expressions; the
status_value parameter is the integer value pointed to by
status_location.
WIFEXITED(status_value)
Evaluates to a nonzero value if status was
returned for a child process that terminated nor-
mally.
WIFCONTINUED
Evaluates to a non-zero value if status was
returned for a child process that has continued.
WEXITSTATUS(status_value)
If the value of WIFEXITED(status_value) is
nonzero, this macro evaluates to the low-order 8
bits of the status parameter that the child pro-
cess passed to the _exit() or exit() functions, or
the value the child process returned from the
main() routine.
WIFSIGNALED(status_value)
Evaluates to nonzero value if status was returned
for a child process that terminated due to the
receipt of a signal that was not caught.
WTERMSIG(status_value)
If the value of WIFSIGNALED(status_value) is
nonzero, this macro evaluates to the number of the
signal that caused the termination of the child
process.
WIFSTOPPED(status_value)
Evaluates to a nonzero value if status was
returned for a child process that is currently
stopped.
WSTOPSIG(status_value)
If the value of WIFSTOPPED(status_value) is
nonzero, 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 the
status_location parameter was stored there by a call to the
waitpid(), wait3(), or wait4() function that specified the
WUNTRACED flag, exactly one of the
WIFEXITED(*status_location), WIFSIGNALED(*status_location),
and WIFSTOPPED(*status_location) macros will evaluate to a
nonzero value. If the information stored at the location
pointed to by the status_location function was stored there
by a call to waitpid(), wait3(), or wait4() that did not
specify the WUNTRACED flag or by a call to the wait() func-
tion, exactly one of the WIFEXITED(*status_location) and
WIFSIGNALED(*status_location) macros will evaluate to a
nonzero value.
The wait3() function is provided for compatibility with BSD
systems. A program that calls wait3() must be compiled with
the _BSD switch defined. In this case, the parameter to the
macros described above should be the w_status member of the
union pointed to by status_location. The wait3() and
wait4() functions also provide a resource_usage parameter
that points to a location in which resource usage informa-
tion for the child process is stored, as defined in the
sys/resource.h function.
If a parent process terminates without waiting for all of
its child processes to terminate, the remaining child
processes will be assigned a parent process ID equal to the
process ID of init.
NOTES
If a program that calls the wait() function is compiled with
the _BSD switch defined and linked with the libbsd compati-
bility library, the status_location parameter is of type
union wait * rather than int *, as described above for the
wait3() function.
AES Support Level:
Full use (wait(), waitpid())
RETURN VALUES
If the wait(), waitpid(), wait3(), or wait4() function
returns because the status of a child process is available,
the process ID of the child is returned to the calling pro-
cess. If they return because a signal was caught by the
calling process, -1 is returned and errno is set to [EINTR].
If the WNOHANG option was specified, and there are no
stopped or exited child processes, the waitpid(), wait3()
and wait4() functions return a value of 0 (zero). Other-
wise, -1 is returned and errno is set to indicate the error.
If the waitid() function returns because one of its children
changed state, a value of 0 is returned. Otherwise, -1 is
returned and errno is set to indicate the error.
ERRORS
If the wait(), waitpid(), wait3(), or wait4() function
fails, errno may be set to one of the following values:
[ECHILD] The calling process has no existing unwaited-for
child processes.
[EINTR] The function was terminated by receipt of a sig-
nal.
[EFAULT] The status_location or resource_usage parameter
points to a location outside of the address space
of the process.
The waitpid() function fails if one or both of the following
are true:
[ECHILD] The process or process group ID specified by the
process_id parameter does not exist or is not a
child process of the calling process.
The waitpid(), wait3(), and wait4() functions fail if the
following is true:
[EINVAL] The value of the options parameter is not valid.
If the waitid() function fails, errno may be set to one of
the following values:
[ECHILD] The calling process has no existing unwaited-for
child processes; or the set of processes specified
by the idtype and id parameters can never be in
the states specified by the options parameter.
[EINTR] The function was interrupted by receipt of a sig-
nal by the calling process.
[EINVAL] The value of the options parameter is not valid;
or the set of processes specified by the idtype or
id parameters are not valid.
RELATED INFORMATION
Functions: exec(2), exit(2), fork(2), getrusage(2),
pause(3), ptrace(2), sigaction(2)
Acknowledgement and Disclaimer