waitpid function 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
WAIT_ANY requests status information for
any child process; a value of
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
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
The options argument is a bit mask. Its value should be the
bitwise OR (that is, the `|' operator) of zero or more of the
WUNTRACED flags. You can use the
WNOHANG flag to indicate that the parent process shouldn't wait;
WUNTRACED flag 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
called. If the thread gets canceled these resources stay allocated
until the program ends. To avoid this calls to
waitpid should 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,
waitpid will block until one is. However,
WNOHANG option was specified,
waitpid will 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
waitpid will block or return zero as described above.
A value of
-1 is returned in case of error. The following
errno error conditions are defined for this function:
- The function was interrupted by delivery of a signal to the calling
process. See Interrupted Primitives.
- There are no child processes to wait for, or the specified pid
is not a child of the calling process.
- An invalid value was provided for the options argument.