NAME
wait,
waitid,
waitpid,
wait6,
wait4,
wait3
—
wait for process termination
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <sys/wait.h>
pid_t
wait(
int
*status);
pid_t
waitpid(
pid_t
wpid,
int *status,
int options);
int
waitid(
idtype_t
idtype,
id_t id,
siginfo_t *info,
int options);
#include <sys/resource.h>
pid_t
wait3(
int
*status,
int options,
struct rusage *rusage);
pid_t
wait4(
pid_t
wpid,
int *status,
int options,
struct rusage *rusage);
pid_t
wait6(
idtype_t
idtype,
id_t id,
int *status,
int options,
struct wrusage *wrusage,
siginfo_t *infop);
DESCRIPTION
The
wait() function suspends execution of its calling process
until
status information is available for a terminated
child process, or a signal is received. On return from a successful
wait() call, the
status area contains
termination information about the process that exited as defined below.
The
wait4() and
wait6() call provides a more
general interface for programs that need to wait for certain child processes,
that need resource utilization statistics accumulated by child processes, or
that require options. The other wait functions are implemented using
wait4(). or
wait6().
The
wait6() function is the most general function in this
family and its distinct features are:
All of the desired process statuses to be waited on must be explicitly specified
in
options. The
wait(),
waitpid(),
wait3(), and
wait4() functions all implicitly wait for exited and trapped
processes, but the
waitid() and
wait6()
functions require the corresponding
WEXITED
and
WTRAPPED
flags to be explicitly specified. This allows
waiting for processes which have experienced other status changes without
having to also handle the exit status from terminated processes.
The
wait6() function accepts a
wrusage
argument which points to a structure defined as:
struct wrusage {
struct rusage wru_self;
struct rusage wru_children;
};
This allows the calling process to collect resource usage statistics from both
its own child process as well as from its grand children. When no resource
usage statistics are needed this pointer can be
NULL
.
The last argument
infop must be either
NULL
or a pointer to a
siginfo_t
structure. If non-
NULL
, the structure is filled with
the same data as for a
SIGCHLD
signal delivered when
the process changed state.
The set of child processes to be queried is specified by the arguments
idtype and
id. The separate
idtype and
id arguments support
many other types of identifiers in addition to process IDs and process group
IDs.
- If idtype is
P_PID
, waitid() and
wait6() wait for the child process with a process ID
equal to (pid_t)id
.
- If idtype is
P_PGID
, waitid() and
wait6() wait for the child process with a process group
ID equal to (pid_t)id
.
- If idtype is
P_ALL
, waitid() and
wait6() wait for any child process and the
id
is ignored.
- If idtype is
P_PID
or P_PGID
and the
id
is zero, waitid() and
wait6() wait for any child process in the same process
group as the caller.
Non-standard identifier types supported by this implementation of
waitid() and
wait6() are:
-
-
P_UID
- Wait for processes whose effective user ID is equal to
(uid_t)
id.
-
-
P_GID
- Wait for processes whose effective group ID is equal to
(gid_t)
id.
-
-
P_SID
- Wait for processes whose session ID is equal to
id. If the child process started its own session,
its session ID will be the same as its process ID. Otherwise the session
ID of a child process will match the caller's session ID.
For the
waitpid() and
wait4() functions, the
single
wpid argument specifies the set of child
processes for which to wait. The following symbolic constants are defined in
<sys/wait.h>
#define WAIT_ANY (-1) /* any process */
#define WAIT_MYPGRP 0 /* any process in my process group */
- If wpid is
WAIT_ANY
, the call waits for any child
process.
- If wpid is
WAIT_MYPGRP
, the call waits for any child process
in the process group of the caller.
- If wpid is greater than zero, the
call waits for the process with process ID
wpid.
- If wpid is less than -1, the call
waits for any process whose process group ID equals the absolute value of
wpid.
The
status argument is defined below.
The
options argument contains the bitwise OR of any of the
following options.
-
-
WALLSIG
- If this option is specified, the call will wait for all
children regardless of what exit signal they post.
-
-
WALTSIG
- If this option is specified, the call will wait only for
processes that are configured to post a signal other than
SIGCHLD
when they exit. If
WALTSIG
is not specified, the call will wait only
for processes that are configured to post
SIGCHLD
.
-
-
WCONTINUED
- Report the status of selected processes that have continued
from a job control stop by receiving a
SIGCONT
signal.
-
-
WEXITED
- Report the status of selected processes which have
terminated. This flag is implicitly set for the functions
wait(), waitpid(),
wait3(), and wait4().
For the waitid() and wait6() functions,
the flag has to be explicitly included in options if
status reports from terminated processes are expected.
-
-
WNOHANG
- Do not block when there are no processes wishing to report
status.
-
-
WNOWAIT
- Keep the process whose status is returned in a waitable
state. The process may be waited for again after this call completes.
-
-
WNOZOMBIE
- Exclude zombie processes from the child selection
criteria.
-
-
WSTOPPED
- An alias for
WUNTRACED
.
-
-
WTRAPPED
- Report the status of selected processes which are being
traced via ptrace(2) and
have trapped or reached a breakpoint. This flag is implicitly set for the
functions wait(), waitpid(),
wait3(), and wait4().
For the waitid() and wait6() functions,
the flag has to be explicitly included in options if
status reports from trapped processes are expected.
-
-
WUNTRACED
- Report the status of selected processes which are stopped
due to a
SIGTTIN
, SIGTTOU
,
SIGTSTP
, or SIGSTOP
signal.
-
-
__WALL
- This is an alias for
WALLSIG
. It is
provided for compatibility with the Linux
clone(2) API .
-
-
__WCLONE
- This is an alias for
WALTSIG
. It is
provided for compatibility with the Linux
clone(2) API.
For the
waitid() and
wait6() functions, at
least one of the options
WEXITED
,
WUNTRACED
,
WSTOPPED
,
WTRAPPED
, or
WCONTINUED
must
be specified. Otherwise there will be no events for the call to report. To
avoid hanging indefinitely in such a case these functions return -1 with
errno
set to
EINVAL
.
If
rusage is non-
NULL
, a summary
of the resources used by the terminated process and all its children is
returned.
If
wrusage is non-
NULL
, separate
summaries are returned for the resources used by the terminated process and
the resources used by all its children.
If
infop is non-
NULL
, a
siginfo_t
structure is returned with the
si_signo field set to
SIGCHLD
and the
si_pid field set to the process ID of the
process reporting status. For the exited process, the
si_status field of the
siginfo_t
structure contains the full 32 bit exit status passed to
_exit(2); the
status argument of other calls only returns 8 lowest
bits of the exit status.
When the
WNOHANG
option is specified and no processes
wish to report status,
waitid() sets the
si_signo and
si_pid fields in
infop to zero. Checking these fields is the only way to
know if a status change was reported.
When the
WNOHANG
option is specified and no processes
wish to report status,
wait4() returns a process id of 0.
The
waitpid() call is identical to
wait4()
with an
rusage value of zero. The older
wait3() call is the same as
wait4() with a
wpid value of -1.
The following macros may be used to test the manner of exit of the process. Note
that these macros expect the
status value itself, not a
pointer to the
status value. One of the first three
macros will evaluate to a non-zero (true) value:
-
-
- WIFEXITED(status)
- True if the process terminated normally by a call to
_exit(2) or
exit(3).
-
-
- WIFSIGNALED(status)
- True if the process terminated due to receipt of a
signal.
-
-
- WIFSTOPPED(status)
- True if the process has not terminated, but has stopped and
can be restarted. This macro can be true only if the wait call specified
the
WUNTRACED
option or if the child process is
being traced (see
ptrace(2)).
-
-
- WIFCONTINUED(status)
- True if the process has not terminated, but has been
continued via the delivery of the
SIGCONT
signal.
This macro can be true only if the wait call specified the
WCONTINUED
option.
Depending on the values of those macros, the following macros produce the
remaining status information about the child process:
-
-
- WEXITSTATUS(status)
- If
WIFEXITED(status) is true,
evaluates to the low-order 8 bits of the argument passed to
_exit(2) or
exit(3) by the child.
-
-
- WTERMSIG(status)
- If
WIFSIGNALED(status) is true,
evaluates to the number of the signal that caused the termination of the
process.
-
-
- WCOREDUMP(status)
- If
WIFSIGNALED(status) is true,
evaluates as true if the termination of the process was accompanied by the
creation of a core file containing an image of the process when the signal
was received.
-
-
- WSTOPSIG(status)
- If
WIFSTOPPED(status) is true,
evaluates to the number of the signal that caused the process to
stop.
NOTES
See
sigaction(2) for a list of
termination signals. A status of 0 indicates normal termination.
If a parent process terminates without waiting for all of its child processes to
terminate, the remaining child processes are assigned the parent process 1 ID
(the init process ID).
If a signal is caught while any of the
wait() calls is
pending, the call may be interrupted or restarted when the signal-catching
routine returns, depending on the options in effect for the signal; see
siginterrupt(3).
RETURN VALUES
If
wait() returns due to a stopped or terminated child
process, the process ID of the child is returned to the calling process.
Otherwise, a value of -1 is returned and
errno is set to
indicate the error.
If
wait6(),
wait4(),
wait3() or
waitpid() returns due to a
stopped or terminated child process, the process ID of the child is returned
to the calling process. If there are no children not previously awaited, -1 is
returned with
errno set to
[
ECHILD
]. Otherwise, if
WNOHANG
is specified and there are no stopped or
exited children, 0 is returned. If an error is detected or a caught signal
aborts the call, a value of -1 is returned and
errno is
set to indicate the error.
If
waitid() returns because one or more processes have a state
change to report, 0 is returned. If an error is detected, a value of -1 is
returned and
errno is set to indicate the error. If
WNOHANG
is specified and there are no stopped,
continued or exited children, 0 is returned. The
si_signo and
si_pid fields of
infop must be checked against zero to determine if a
process reported status.
ERRORS
wait() will fail and return immediately if:
-
-
- [
ECHILD
]
- The calling process has no existing unwaited-for child
processes; or no status from the terminated child process is available
because the calling process has asked the system to discard such status by
ignoring the signal
SIGCHLD
or setting the flag
SA_NOCLDWAIT
for that signal.
-
-
- [
EFAULT
]
- The status or
rusage arguments point to an illegal address. (May
not be detected before exit of a child process.)
-
-
- [
EINTR
]
- The call was interrupted by a caught signal, or the signal
did not have the
SA_RESTART
flag set.
In addition,
wait6(),
wait3(),
wait4(),
waitid(), and
waitpid() will fail and return immediately if:
-
-
- [
EINVAL
]
- An invalid value was specified for
options.
SEE ALSO
_exit(2),
fork(2),
ptrace(2),
sigaction(2),
siginfo(2),
exit(3),
siginterrupt(3)
STANDARDS
The
wait() and
waitpid() functions conform
to
IEEE Std 1003.1-1990 (“POSIX.1”); the
waitid() function conforms to
IEEE Std
1003.1-2004 (“POSIX.1”); the
wait3()
function conforms to
X/Open Portability Guide Issue 4
(“XPG4”);
wait4() is an extension. The
WCOREDUMP() macro and the ability to restart a pending
wait() call are extensions to the POSIX interface.
HISTORY
A
wait() function call appeared in
Version 2 AT&T UNIX.