waitpid(2) waitpid(2)NAME waitpid - wait for child process to stop or terminate SYNOPSIS #include <sys/types.h> #include <sys/wait.h> pid_t waitpid(pid, stat_loc, options) pid_t pid; int *stat_loc, options; DESCRIPTION The waitpid function allows the calling process to obtain status information regarding one of its direct descendants (child processes), created by calling fork(2). Unless an error occurs, the calling process is suspended until one of the specified children stops or terminates. waitpid pro- vides additional functionality over wait(2): control over which children will be waited for, non-blocking status col- lection and collection of the status of children that are stopped. The pid argument specifies the set of child processes from which status may be returned. If pid is equal to -1, all children of the calling pro- cess are included in the set. If pid is greater than zero, the set consists solely of the child process whose process ID is equal to pid. If pid is equal zero, all children whose process group ID matches that of the calling process are included in the set. If pid is less than -1, the set consists of all child processes whose process group ID is equal to the abso- lute value of pid. If stat_loc (taken as an integer) is not NULL, 16 bits of information called status are stored in the low order 16 bits of the location pointed to by stat_loc. status can be used to differentiate between stopped and terminated child processes. If the child process terminated, status identi- fies the cause of termination and passes useful information to the parent. This is accomplished in the following manner: If the child process stopped, the high order 8 bits of status will contain the number of the signal that caused the process to stop and the low order 8 bits will be set equal to 0177. April, 1990 1
waitpid(2) waitpid(2)If the child process terminated due to an exit call, the low order 8 bits of status will be zero and the high order 8 bits will contain the low order 8 bits of the argument that the child process passed to exit(2). If the child process terminated due to a signal, the high order 8 bits of status will be zero and the low order 8 bits will contain the number of the signal that caused the termination. In addition, if the low order seventh bit (i.e., bit 200) is set, a ``core image'' will have been produced; see signal(3). If pid is equal to -1 and options is zero, the behavior of waitpid is identical to wait(2). Otherwise, options con- sists of the logical OR of one or both of the following flags: WNOHANG Return immediately, even if there are no children to wait for. In this case, a return value of zero indicates that no children have terminated (or stopped, if WUNTRACED is also set). WUNTRACED Return the status of stopped children. If the child process has stopped due to the delivery of a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal, its status may be collected by setting this flag. If WUNTRACED is set and the status of a stopped child pro- cess is reported, the high order 8 bits of status shall con- tain the number of the signal that caused the process to stop and the low order eight bits shall be set to the octal value 0177. RETURN VALUE If waitpid returns successfully, i.e., one of the specified children has stopped or terminated, the return value shall equal the child's process ID. If WNOHANG is specified and there are no stopped or terminated children, the return value will be set to zero. Otherwise, an error has oc- curred: the value of -1 shall be returned and errno shall be set to indicate the error. ERRORS If any of the following conditions occur, waitpid will re- turn -1 and set errno to the corresponding value: [ECHILD] The calling process has no existing unwaited- for child processes. [EINTR] The calling process was interrupted while exe- cuting the waitpid function. 2 April, 1990
waitpid(2) waitpid(2)[EINVAL] waitpid was called with an invalid options value. SEE ALSO exit(2), wait(2), wait3(2N). April, 1990 3