Next: Process Completion Status, Previous: Executing a File, Up: Processes
The functions described in this section are used to wait for a child process to terminate or stop, and determine its status. These functions are declared in the header file sys/wait.h.
The
waitpidfunction is used to request status information from a child process whose process ID is pid. Normally, the calling process is suspended until the child process makes status information available by terminating.Other values for the pid argument have special interpretations. A value of
-1orWAIT_ANYrequests status information for any child process; a value of0orWAIT_MYPGRPrequests information for any child process in the same process group as the calling process; and any other negative value − pgid requests information for any child process whose process group ID is pgid.If status information for a child process is available immediately, this function returns immediately without waiting. If more than one eligible child process has status information available, one of them is chosen randomly, and its status is returned immediately. To get the status from the other eligible child processes, you need to call
waitpidagain.The options argument is a bit mask. Its value should be the bitwise OR (that is, the `|' operator) of zero or more of the
WNOHANGandWUNTRACEDflags. You can use theWNOHANGflag to indicate that the parent process shouldn't wait; and theWUNTRACEDflag to request status information from stopped processes as well as processes that have terminated.The status information from the child process is stored in the object that status-ptr points to, unless status-ptr is a null pointer.
This function is a cancellation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time
waitpidis called. If the thread gets canceled these resources stay allocated until the program ends. To avoid this calls towaitpidshould be protected using cancellation handlers.The return value is normally the process ID of the child process whose status is reported. If there are child processes but none of them is waiting to be noticed,
waitpidwill block until one is. However, if theWNOHANGoption was specified,waitpidwill return zero instead of blocking.If a specific PID to wait for was given to
waitpid, it will ignore all other children (if any). Therefore if there are children waiting to be noticed but the child whose PID was specified is not one of them,waitpidwill block or return zero as described above.A value of
-1is returned in case of error. The followingerrnoerror conditions are defined for this function:
EINTR- The function was interrupted by delivery of a signal to the calling process. See Interrupted Primitives.
ECHILD- There are no child processes to wait for, or the specified pid is not a child of the calling process.
EINVAL- An invalid value was provided for the options argument.
These symbolic constants are defined as values for the pid argument
to the waitpid function.
WAIT_ANY-1) specifies that
waitpid should return status information about any child process.
WAIT_MYPGRP0) specifies that waitpid should
return status information about any child process in the same process
group as the calling process.
These symbolic constants are defined as flags for the options
argument to the waitpid function. You can bitwise-OR the flags
together to obtain a value to use as the argument.
WNOHANGwaitpid should return immediately
instead of waiting, if there is no child process ready to be noticed.
WUNTRACEDwaitpid should report the status of any
child processes that have been stopped as well as those that have
terminated.
This is a simplified version of
waitpid, and is used to wait until any one child process terminates. The call:wait (&status)is exactly equivalent to:
waitpid (-1, &status, 0)This function is a cancellation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time
waitis called. If the thread gets canceled these resources stay allocated until the program ends. To avoid this calls towaitshould be protected using cancellation handlers.
If usage is a null pointer,
wait4is equivalent towaitpid (pid,status-ptr,options).If usage is not null,
wait4stores usage figures for the child process in*rusage (but only if the child has terminated, not if it has stopped). See Resource Usage.This function is a BSD extension.
Here's an example of how to use waitpid to get the status from
all child processes that have terminated, without ever waiting. This
function is designed to be a handler for SIGCHLD, the signal that
indicates that at least one child process has terminated.
void
sigchld_handler (int signum)
{
int pid, status, serrno;
serrno = errno;
while (1)
{
pid = waitpid (WAIT_ANY, &status, WNOHANG);
if (pid < 0)
{
perror ("waitpid");
break;
}
if (pid == 0)
break;
notice_termination (pid, status);
}
errno = serrno;
}