Waits for a child process to stop or terminate.
Format
#include <wait.h>
pid_t waitpid (pid_t process_id, int *status_location, int options);
1 – Arguments
process_id
The child process or set of child processes.
status_location
A pointer to a location that contains the termination status of
the child process as defined in the <wait.h> header file.
Beginning with OpenVMS Version 7.2, when compiled with the _
VMS_WAIT macro defined, the waitpid function puts the OpenVMS
completion code of the child process at the address specified in
the status_location argument.
options
Flags that modify the behavior of the function. These flags are
defined in the Description section.
2 – Description
The waitpid function suspends the calling process until the
request is completed. It is redefined so that only the calling
thread is suspended.
If the process_id argument is -1 and the options argument is
0, the waitpid function behaves the same as the wait function.
If these arguments have other values, the waitpid function is
changed as specified by those values.
The process_id argument allows the calling process to gather
status from a specific set of child processes, according to the
following rules:
If the
process_
id is Then status is requested
Equal to -1 For any child process. In this respect, the
waitpid function is equivalent to the wait
function.
Greater than For a single child process and specifies the
0 process ID.
The waitpid function only returns the status of a child process
from this set.
The options argument to the waitpid function modifies the
behavior of the function. You can combine the flags for the
options argument by specifying their bitwise-inclusive OR. The
flags are:
WCONTINUED Specifies that the following is reported to the
calling process: the status of any continued child
process specified by the process_id argument whose
status is unreported since it continued.
WNOWAIT Specifies that the process whose status is
returned in status_location is kept in a waitable
state. You can wait for the process again with the
same results.
WNOHANG Prevents the calling process from being suspended.
If there are child processes that stopped or
terminated, one is chosen and waitpid returns its
PID, as when you do not specify the WNOHANG flag.
If there are no terminated processes (that is,
if waitpid suspends the calling process without
the WNOHANG flag), 0 (zero) is returned. Because
you can never wait for process 0, there is no
confusion arising from this return.
WUNTRACED Specifies that the call return additional
information when the child processes of the
current process stop because the child process
received a SIGTTIN, SIGTTOU, SIGSTOP, or SIGTSTOP
signal.
If the waitpid function returns because the status of a child
process is available, the process ID of the child process is
returned. Information is stored in the location pointed to by
status_location, if this pointer is not null. The value stored
in the location pointed to by status_location is 0 only if the
status is returned from a terminated child process that did one
of the following:
o Returned 0 from the main function.
o Passed 0 as the status argument to the _exit or exit function.
Regardless of the value of status_location, you can define this
information using the macros defined in the <wait.h> header file,
which evaluate to integral expressions. In the following function
descriptions, status_value is equal to the integer value pointed
to by status_location:
WIFEXITED(status_ Evaluates to a nonzero value if status was
value) returned for a child process that terminated
normally.
WEXITSTATUS(status_If the value of WIFEXITED(status_value) is
value) nonzero, this macro evaluates to the low-order
8 bits of the status argument that the child
process passed to the _exit or exit function,
or to the value the child process returned
from the main function.
WIFSIGNALED(status_Evaluates to a nonzero value if status
value) returned for a child process that terminated
due to the receipt of a signal not
intercepted.
WTERMSIG(status_ If the value of WIFSIGNALED(status_value) is
value) nonzero, this macro evaluates to the number of
the signal that caused the termination of the
child process.
WIFSTOPPED(status_ Evaluates to a nonzero value if status was
value) returned for a child process that is currently
stopped.
WSTOPSIG(status_ If the value of WIFSTOPPED(status_value) is
value) nonzero, this macro evaluates to the number
of the signal that caused the child process to
stop.
WIFCONTINUED(status_valuates to a nonzero value if status
value) returned for a child process that continued.
If the information stored at the location pointed to by status_
location is stored there by a call to waitpid that specified
the WUNTRACED flag, one of the following macros evaluates to a
nonzero value:
o WIFEXITED(*status_value)
o WIFSIGNALED(*status_value)
o WIFSTOPPED(*status_value)
o WIFCONTINUED(*status_value)
If the information stored in the buffer pointed to by status_
location resulted from a call to waitpid without the WUNTRACED
flag specified, one of the following macros evaluates to a
nonzero value:
o WIFEXITED(*status_value)
o WIFSIGNALED(*status_value)
If a parent process terminates without waiting for all of its
child processes to terminate, the remaining child processes is
assigned a parent process ID equal to the process ID of the init
process.
See also exit, _exit, and wait.
3 – Return Values
0 Indicates success. If the WNOHANG option was
specified, and there are no stopped or exited
child processes, the waitpid function also
returns a value of 0.
-1 Indicates an error; errno is set to one of the
following values:
o ECHILD-The calling process has no existing
unwaited-for child processes. The process
or process group ID specified by the
process_id argument does not exist or is
not a child process of the calling process.
o EINTR-The function was terminated by
receipt of a signal.
If the waitpid function returns because
the status of a child process is available,
the process ID of the child is returned to
the calling process. If they return because
a signal was intercepted by the calling
process, -1 is returned.
o EFAULT- The status_location argument points
to a location outside of the address space
of the process.
o EINVAL- The value of the options argument
is not valid.