wait, waitpid - wait for process termination |
#include <sys/types.h> #include <sys/wait.h> |
pid_t wait(int *status) pid_t waitpid(pid_t pid, int *status, int options); |
The wait function suspends execution of the current process until a child has exited, or until a signal is delivered whose action is to terminate the current process or to call a signal handling function. If a child has already exited by the time of the call (a so-called "zombie" process), the function returns immediately. Any system resources used by the child are freed. |
The waitpid function suspends execution of the current process until a child as specified by the pid argument has exited, or until a signal is delivered whose action is to terminate the current process or to call a signal handling function. If a child as requested by pid has already exited by the time of the call (a so-called "zombie" process), the function returns immediately. Any system resources used by the child are freed. |
The value of pid can be one of: |
< -1 |
which means to wait for any child process whose process group ID is equal to the absolute value of pid. |
-1 |
which means to wait for any child process; this is the same behaviour which wait exhibits. |
0 |
which means to wait for any child process whose process group ID is equal to that of the calling process. |
> 0 |
which means to wait for the child whose process ID is equal to the value of pid. |
The value of options is an OR of zero or more of the following constants: |
WNOHANG |
which means to return immediately if no child has exited. |
WUNTRACED |
which means to also return for children which are stopped, and whose status has not been reported. |
If status is not NULL, wait or waitpid store status information in the location pointed to by status. |
This status can be evaluated with the following macros (these macros take the stat buffer (an int) as an argument -- not a pointer to the buffer!): |
WIFEXITED(status) |
is non-zero if the child exited normally. |
WEXITSTATUS(status) |
evaluates to the least significant eight bits of the return code of the child which terminated, which may have been set as the argument to a call to exit() or as the argument for a return statement in the main program. This macro can only be evaluated if WIFEXITED returned non-zero. |
WIFSIGNALED(status) |
returns true if the child process exited because of a signal which was not caught. |
WTERMSIG(status) |
returns the number of the signal that caused the child process to terminate. This macro can only be evaluated if WIFSIGNALED returned non-zero. |
WIFSTOPPED(status) |
returns true if the child process which caused the return is currently stopped; this is only possible if the call was done using WUNTRACED. |
WSTOPSIG(status) |
returns the number of the signal which caused the child to stop. This macro can only be evaluated if WIFSTOPPED returned non-zero. |
Some versions of Unix (e.g. Linux, Solaris, but not AIX, SunOS) also define a macro WCOREDUMP(status) to test whether the child process dumped core. Only use this enclosed in #ifdef WCOREDUMP ... #endif. |
The process ID of the child which exited, or zero if WNOHANG was used and no child was available, or -1 on error (in which case errno is set to an appropriate value). |
ECHILD |
if the process specified in pid does not exist or is not a child of the calling process. (This can happen for one's own child if the action for SIGCHLD is set to SIG_IGN. See also the NOTES section about threads.) |
EINVAL |
if the options argument was invalid. |
EINTR |
if WNOHANG was not set and an unblocked signal or a SIGCHLD was caught. |
The Single Unix Specification describes a flag SA_NOCLDWAIT (not present under Linux) such that if either this flag is set, or the action for SIGCHLD is set to SIG_IGN (which, by the way, is not allowed by POSIX), then children that exit do not become zombies and a call to wait() or waitpid() will block until all children have exited, and then fail with errno set to ECHILD. |
In the Linux kernel, a kernel-scheduled thread is not a distinct construct from a process. Instead, a thread is simply a process that is created using the Linux-unique clone(2) system call; other routines such as the portable pthread_create(3) call are implemented using clone(2). Thus, if two threads A and B are siblings, then thread A cannot wait on any processes forked by thread B or its descendents, because an uncle cannot wait on his nephews. In some other Unix-like systems, where multiple threads are implemented as belonging to a single process, thread A can wait on any processes forked by sibling thread B; you will have to rewrite any code that makes this assumption for it to work on Linux. |
SVr4, POSIX.1 |
clone(2), signal(2), wait4(2), pthread_create(3), signal(7) |