table of contents
other sections
WAIT(2) | System Calls Manual | WAIT(2) |
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¶
Thewait
() 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; };
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.
- If idtype is
P_PID
,waitid
() andwait6
() wait for the child process with a process ID equal to(pid_t)id
. - If idtype is
P_PGID
,waitid
() andwait6
() wait for the child process with a process group ID equal to(pid_t)id
. - If idtype is
P_ALL
,waitid
() andwait6
() wait for any child process and theid
is ignored. - If idtype is
P_PID
orP_PGID
and theid
is zero,waitid
() andwait6
() wait for any child process in the same process group as the caller.
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 toid
. 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 toid
.
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.
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
, orSIGSTOP
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
(), andwait4
().waitid
() andwait6
() 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.
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)).
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 thewait
()
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¶
Ifwait
() 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¶
Thewait
() 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 flagSA_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¶
Thewait
(),
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¶
Thewait
() function appeared in
Version 6 AT&T UNIX.September 7, 2013 | Debian |