wait (3p)
PROLOG
This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux.NAME
wait, waitpid — wait for a child process to stop or terminateSYNOPSIS
#include <sys/wait.h>
pid_t wait(int * stat_loc); pid_t waitpid(pid_t pid, int *stat_loc, int options);
DESCRIPTION
The wait() and waitpid() functions shall obtain status information pertaining to one of the caller's child processes. Various options permit status information to be obtained for child processes that have terminated or stopped. If status information is available for two or more child processes, the order in which their status is reported is unspecified. The wait() function shall suspend execution of the calling thread until status information for one of the terminated child processes of the calling process is available, or until delivery of a signal whose action is either to execute a signal-catching function or to terminate the process. If more than one thread is suspended in wait() or waitpid() awaiting termination of the same process, exactly one thread shall return the process status at the time of the target process termination. If status information is available prior to the call to wait(), return shall be immediate. The waitpid() function shall be equivalent to wait() if the pid argument is ( pid_t)−1 and the options argument is 0. Otherwise, its behavior shall be modified by the values of the pid and options arguments. The pid argument specifies a set of child processes for which status is requested. The waitpid() function shall only return the status of a child process from this set:- *
- If pid is equal to ( pid_t)−1, status is requested for any child process. In this respect, waitpid() is then equivalent to wait().
- *
- If pid is greater than 0, it specifies the process ID of a single child process for which status is requested.
- *
- If pid is 0, status is requested for any child process whose process group ID is equal to that of the calling process.
- *
- If pid is less than ( pid_t)−1, status is requested for any child process whose process group ID is equal to the absolute value of pid.
- WCONTINUED
- The waitpid() function shall report the status of any continued child process specified by pid whose status has not been reported since it continued from a job control stop.
- WNOHANG
- The waitpid() function shall not suspend execution of the calling thread if status is not immediately available for one of the child processes specified by pid.
- WUNTRACED
- The status of any child processes specified by pid that are stopped, and whose status has not yet been reported since they stopped, shall also be reported to the requesting process.
- 1.
- The process returned 0 from main().
- 2.
- The process called _exit() or exit() with a status argument of 0.
- 3.
- The process was terminated because the last thread in the process terminated.
- WIFEXITED(stat_val)
-
- WEXITSTATUS(stat_val)
-
- WIFSIGNALED(stat_val)
-
- WTERMSIG(stat_val)
-
- WIFSTOPPED(stat_val)
-
- WSTOPSIG(stat_val)
-
- WIFCONTINUED(stat_val)
-
RETURN VALUE
If wait() or waitpid() returns because the status of a child process is available, these functions shall return a value equal to the process ID of the child process for which status is reported. If wait() or waitpid() returns due to the delivery of a signal to the calling process, −1 shall be returned and errno set to [EINTR]. If waitpid() was invoked with WNOHANG set in options, it has at least one child process specified by pid for which status is not available, and status is not available for any process specified by pid, 0 is returned. Otherwise, −1 shall be returned, and errno set to indicate the error.ERRORS
The wait() function shall fail if:- ECHILD
- The calling process has no existing unwaited-for child processes.
- EINTR
- The function was interrupted by a signal. The value of the location pointed to by stat_loc is undefined.
- ECHILD
- The process specified by pid does not exist or is not a child of the calling process, or the process group specified by pid does not exist or does not have any member process that is a child of the calling process.
- EINTR
- The function was interrupted by a signal. The value of the location pointed to by stat_loc is undefined.
- EINVAL
- The options argument is not valid.
EXAMPLES
Waiting for a Child Process and then Checking its Status
The following example demonstrates the use of waitpid(), fork(), and the macros used to interpret the status value returned by waitpid() (and wait()). The code segment creates a child process which does some unspecified work. Meanwhile the parent loops performing calls to waitpid() to monitor the status of the child. The loop terminates when child termination is detected.#include <stdio.h> #include <stdlib.h> #include <unistd.h> #include <sys/wait.h> ...
pid_t child_pid, wpid; int status;
child_pid = fork(); if (child_pid == −1) { /* fork() failed */ perror("fork"); exit(EXIT_FAILURE); }
if (child_pid == 0) { /* This is the child */ /* Child does some work and then terminates */ ...
} else { /* This is the parent */ do { wpid = waitpid(child_pid, &status, WUNTRACED #ifdef WCONTINUED /* Not all implementations support this */ | WCONTINUED #endif ); if (wpid == −1) { perror("waitpid"); exit(EXIT_FAILURE); }
if (WIFEXITED(status)) { printf("child exited, status=%d\n", WEXITSTATUS(status));
} else if (WIFSIGNALED(status)) { printf("child killed (signal %d)\n", WTERMSIG(status));
} else if (WIFSTOPPED(status)) { printf("child stopped (signal %d)\n", WSTOPSIG(status));
#ifdef WIFCONTINUED /* Not all implementations support this */ } else if (WIFCONTINUED(status)) { printf("child continued\n"); #endif } else { /* Non-standard case -- may never happen */ printf("Unexpected status (0x%x)\n", status); } } while (!WIFEXITED(status) && !WIFSIGNALED(status)); }
Waiting for a Child Process in a Signal Handler for SIGCHLD
The following example demonstrates how to use waitpid() in a signal handler for SIGCHLD without passing −1 as the pid argument. (See the APPLICATION USAGE section below for the reasons why passing a pid of −1 is not recommended.) The method used here relies on the standard behavior of waitpid() when SIGCHLD is blocked. On historical non-conforming systems, the status of some child processes might not be reported.#include <stdlib.h> #include <stdio.h> #include <signal.h> #include <sys/types.h> #include <sys/wait.h> #include <unistd.h>
#define CHILDREN 10
static void handle_sigchld(int signum, siginfo_t *sinfo, void *unused) { int sav_errno = errno; int status;
/* * Obtain status information for the child which * caused the SIGCHLD signal and write its exit code * to stdout. */ if (sinfo->si_code != CLD_EXITED) { static char msg[] = "wrong si_code\n"; write(2, msg, sizeof msg − 1); } else if (waitpid(sinfo->si_pid, &status, 0) == −1) { static char msg[] = "waitpid() failed\n"; write(2, msg, sizeof msg − 1); } else if (!WIFEXITED(status)) { static char msg[] = "WIFEXITED was false\n"; write(2, msg, sizeof msg − 1); } else { int code = WEXITSTATUS(status); char buf[2]; buf[0] = '0' + code; buf[1] = '\n'; write(1, buf, 2); } errno = sav_errno; }
int main(void) { int i; pid_t pid; struct sigaction sa;
sa.sa_flags = SA_SIGINFO; sa.sa_sigaction = handle_sigchld; sigemptyset(&sa.sa_mask); if (sigaction(SIGCHLD, &sa, NULL) == −1) { perror("sigaction"); exit(EXIT_FAILURE); }
for (i = 0; i < CHILDREN; i++) { switch (pid = fork()) { case −1: perror("fork"); exit(EXIT_FAILURE); case 0: sleep(2); _exit(i); } }
/* Wait for all the SIGCHLD signals, then terminate on SIGALRM */ alarm(3); for (;;) pause();
return 0; /* NOTREACHED */ }
APPLICATION USAGE
Calls to wait() will collect information about any child process. This may result in interactions with other interfaces that may be waiting for their own children (such as by use of system()). For this and other reasons it is recommended that portable applications not use wait(), but instead use waitpid(). For these same reasons, the use of waitpid() with a pid argument of −1, and the use of waitid() with the idtype argument set to P_ALL, are also not recommended for portable applications.RATIONALE
A call to the wait() or waitpid() function only returns status on an immediate child process of the calling process; that is, a child that was produced by a single fork() call (perhaps followed by an exec or other function calls) from the parent. If a child produces grandchildren by further use of fork(), none of those grandchildren nor any of their descendants affect the behavior of a wait() from the original parent process. Nothing in this volume of POSIX.1‐2008 prevents an implementation from providing extensions that permit a process to get status from a grandchild or any other process, but a process that does not use such extensions must be guaranteed to see status from only its direct children. The waitpid() function is provided for three reasons:- 1.
- To support job control
- 2.
- To permit a non-blocking version of the wait() function
- 3.
- To permit a library routine, such as system() or pclose(), to wait for its children without interfering with other terminated children for which the process has not waited
stream = popen("/bin/true"); (void) system("sleep 100"); (void) pclose(stream);
- 1.
- If a SIGCHLD signal handler is established via sigaction() without the SA_RESETHAND flag, SIGCHLD signals can be accurately counted; that is, exactly one SIGCHLD signal will be delivered to or accepted by the process for every child process that terminates.
- 2.
- A single wait() issued from a SIGCHLD signal handler can be guaranteed to return immediately with status information for a child process.
- 3.
- When SA_SIGINFO is requested, the SIGCHLD signal handler can be guaranteed to receive a non-null pointer to a siginfo_t structure that describes a child process for which a wait via waitpid() or waitid() will not block or fail.
- 4.
- The system() function will not cause the SIGCHLD handler of a process to be called as a result of the fork()/exec executed within system() because system() will accept the SIGCHLD signal when it performs a waitpid() for its child process. This is a desirable behavior of system() so that it can be used in a library without causing side-effects to the application linked with the library.
- Guarantee #1
-
- Guarantees #2 and #3
-
- Guarantee #4
-