NAME¶
wait
,
waitid
,
waitpid
,
wait3
,
wait4
,
wait6
—
wait for processes to change status
LIBRARY¶
Standard C Library (libc, -lc)
SYNOPSIS¶
#include
<sys/types.h>
#include
<sys/wait.h>
pid_t
wait
(
int
*status);
pid_t
waitpid
(
pid_t
wpid,
int
*status,
int
options);
#include
<signal.h>
int
waitid
(
idtype_t
idtype,
id_t
id,
siginfo_t
*info,
int
options);
#include
<sys/time.h>
#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
wait
() call is the same as
wait4
() with a
wpid value of -1, with an
options value of zero, and a
rusage value of zero.
The
wait4
() system 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 broadest interface of all functions in this family is
wait6
() which is otherwise very much like
wait4
() but with a few very important
distinctions. To wait for exited processes, the option flag
WEXITED
need to be explicitly specified.
This allows for waiting for processes which have experienced other status
changes without having to handle also the exit status from the terminated
processes. Instead of the traditional
rusage
argument, a pointer to a new
structure
struct __wrusage {
struct rusage wru_self;
struct rusage wru_children;
};
can be passed. 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. When specified, the
structure is filled the same as for
SIGNCHLD
signal, delivered at the process
state change.
The process, which state is queried, is specified by two arguments
idtype and
id. The separate
idtype and
id arguments allows to support many other
types of IDs as well in addition to PID and PGID.
- 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 specifiers for the process to wait for, supported by this
implementation of
waitid
() and
wait6
(), are:
- The idtype value
P_UID
waits for processes which
effective UID is equal to
(uid_t)id
.
- The idtype value
P_GID
waits for processes which
effective GID is equal to
(gid_t)id
.
- The idtype value
P_SID
waits for processes which session
ID is equal to id
. In case the child
process started its own new session, SID will be the same as its own PID.
Otherwise the SID of a child process will match the caller's SID.
- The idtype value
P_JAILID
waits for processes within a
jail which jail identifier is equal to
id
.
For
wait
(),
wait3
(), and
wait4
() functions, the single
wpid argument specifies the set of child
processes for which to wait.
- If wpid is -1, the call waits for any
child process.
- If wpid is 0, 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.
WCONTINUED
- indicates that children of the current process that have continued from a
job control stop, by receiving a
SIGCONT
signal, should also have their
status reported.
WNOHANG
- is used to indicate that the call should not block when there are no
processes wishing to report status.
WUNTRACED
- indicates that children of the current process which are stopped due to a
SIGTTIN
,
SIGTTOU
,
SIGTSTP
, or
SIGSTOP
signal shall have their status
reported.
WSTOPPED
- is an alias for
WUNTRACED
.
WTRAPPED
- allows waiting for processes which have trapped or reached a
breakpoint.
WEXITED
- indicates that the caller is wants to receive status reports from
terminated processes. 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 the options, if
status reports from terminated processes are expected.
WNOWAIT
- keeps the process whose status is returned in a waitable state. The
process may be waited for again after this call completes.
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 argument is non-NULL, a resource
usage statistics from both its own child process as well as from its grand
children is returned.
If
infop is non-NULL, it must point to a
siginfo_t
structure which is filled on
return such that the
si_signo
field is
always
SIGCHLD
and the field
si_pid
if be non-zero, if there is a status
change to report. If there are no status changes to report and WNOHANG is
applied, both of these fields are returned zero. When using the
waitid
() function with the
WNOHANG
option set, checking these fields
is the only way to know whether there were any status changes to report,
because the return value from
waitid
() is
be zero as it is for any successful return from
waitid
().
When the
WNOHANG
option is specified and no
processes wish to report status,
wait4
()
returns a process id of 0.
The
waitpid
() function 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
wait6
() call, with the bits
WEXITED
and
WTRAPPED
set in the
options and with
infop set to
NULL
, is similar to
wait4
().
The following macros may be used to test the manner of exit of the process. One
of the first four macros will evaluate to a non-zero (true) value:
WIFCONTINUED
(status)
- True if the process has not terminated, and has continued after a job
control stop. This macro can be true only if the wait call specified the
WCONTINUED
option).
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)).
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 are pending, the call may be interrupted or restarted when the
signal-catching routine returns, depending on the options in effect for the
signal; see discussion of
SA_RESTART
in
sigaction(2).
The implementation queues one
SIGCHLD
signal
for each child process whose status has changed, if
wait
() returns because the status of a
child process is available, the pending SIGCHLD signal associated with the
process ID of the child process will be discarded. Any other pending
SIGCHLD
signals remain pending.
If
SIGCHLD
is blocked,
wait
() returns because the status of a
child process is available, the pending
SIGCHLD
signal will be cleared unless
another status of the child process is available.
RETURN VALUES¶
If
wait
() returns due to a stopped,
continued, 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,
continued, 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, continued 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. To indicate an error,
-1 will be returned and
errno
set to an
appropriate value. If
WNOHANG
was used, 0
can be returned indicating no error, but no processes may have changed state
either, if si_signo and/or si_pid are zero.
ERRORS¶
The
wait
() function will fail and return
immediately if:
- [
ECHILD
]
- The calling process has no existing unwaited-for child processes.
- [
ECHILD
]
- 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 argument points 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.
- [
EINVAL
]
- An invalid value was specified for
options, or
idtype and
id do not specify a valid set of
processes.
SEE ALSO¶
_exit(2),
ptrace(2),
sigaction(2),
exit(3),
siginfo(3)
STANDARDS¶
The
wait
(),
waitpid
(), and
waitid
() functions are defined by POSIX;
wait6
(),
wait4
(), and
wait3
() are not specified by POSIX. The
WCOREDUMP
() macro is an extension to the
POSIX interface.
The ability to use the
WNOWAIT
flag with
waitpid
() is an extension; POSIX only
permits this flag with
waitid
().
POSIX requires
waitid
() to return the full 32
bits passed to
_exit(2); this implementation only
returns 8 bits like in the other calls.
HISTORY¶
The
wait
() function appeared in
Version 6 AT&T UNIX.