NAME
wait, waitpid - wait for process to terminate
SYNOPSIS
#include <sys/types.h>
#include <sys/wait.h>
pid_t wait(int *status)
pid_t waitpid(pid_t pid, int *status, int options)
DESCRIPTION
Wait causes its caller to delay until a signal is received
or one of its child processes terminates. If any child has
died since the last wait, return is immediate, returning the
process id and exit status of one of the terminated chil-
dren. If there are no children, return is immediate with
the value -1 returned.
On return from a successful wait call, status is nonzero,
and the high byte of status contains the low byte of the
argument to exit supplied by the child process; the low byte
of status contains the termination status of the process. A
more precise definition of the status word is given in
<sys/wait.h>. Wait can be called with a null pointer argu-
ment to indicate that no status need be returned.
Waitpid provides an alternate interface for programs that
must not block when collecting the status of child
processes, or that wish to wait for one particular child.
The pid parameter is the process ID of the child to wait
for, -1 for any child. The status parameter is defined as
above. The options parameter is used to indicate the call
should not block if there are no processes that wish to
report status (WNOHANG), and/or that children of the current
process that are stopped due to a SIGTTIN, SIGTTOU, SIGTSTP,
or SIGSTOP signal should also have their status reported
(WUNTRACED). (Job control is not implemented for MINIX 3,
but these symbols and signals are.)
When the WNOHANG option is specified and no processes wish
to report status, waitpid either returns 0 under some imple-
mentations, or -1 with errno set to EAGAIN under others.
(Under MINIX 3 it returns 0.) The WNOHANG and WUNTRACED
options may be combined by or'ing the two values.
NOTES
The call wait(&status) is equivalent to waitpid(-1, &status,
0).
See sigaction(2) for a list of termination statuses (sig-
nals); 0 status indicates normal termination. A special
status (0177) is returned for a stopped process that has not
terminated and can be restarted; see ptrace(2). If the 0200
bit of the termination status is set, a core image of the
process was produced by the system.
If the parent process terminates without waiting on its
children, the initialization process (process ID = 1) inher-
its the children.
<sys/wait.h> defines a number of macros that operate on a
status word:
WIFEXITED(status)
True if normal exit.
WEXITSTATUS(status)
Exit status if the process returned by a normal exit,
zero otherwise.
WTERMSIG(status)
Signal number if the process died by a signal, zero
otherwise.
WIFSIGNALED(status)
True if the process died by a signal.
WIFSTOPPED(status)
True if the process is stopped. (Never true under
MINIX 3.)
WSTOPSIG(status)
Signal number of the signal that stopped the process.
RETURN VALUE
If wait returns due to a stopped or terminated child pro-
cess, 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.
Waitpid returns -1 if there are no children not previously
waited for or if the process that it wants to wait for
doesn't exist.
Waitpid returns 0 if WNOHANG is specified and there are no
stopped or exited children. (Under other implementations it
may return -1 instead. Portable code should test for both
possibilities.)
ERRORS
Wait will fail and return immediately if one or more of the
following are true:
[ECHILD] The calling process has no existing
unwaited-for child processes.
[EFAULT] The status argument points to an illegal
address.
[EAGAIN] Waitpid is called with the WNOHANG option and
no child has exited yet. (Not under MINIX 3,
it'll return 0 in this case and leave errno
alone.)
SEE ALSO
execve(2), exit(2), sigaction(2).