Waits for a child process to stop or terminate.
Format
#include <wait.h>
pid_t wait3 (int *status_location, int options, struct rusage
*resource_usage);
1 – Arguments
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 wait3 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.
resource_usage
The location of a structure that contains the resource
utilization information for terminated child processes.
2 – Description
The wait3 function suspends the calling process until the request
is completed, and redefines it so that only the calling thread is
suspended.
The options argument modifies the behavior of the function. You
can combine the flags for the options argument by specifying
their bitwise inclusive OR. The flags are:
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 suspension of the calling process.
If there are child processes that stopped or
terminated, one is chosen and the waitpid function
returns its process ID, 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 wait3 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 (zero) 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 status_location value, you can define this
information using the macros defined in the <wait.h> header file,
which evaluate to integral expressions. In the following macro
descriptions, the status_value argument is equal to the integer
value pointed to by the status_location argument:
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 was
value) returned for a child process that terminated
due to the receipt of a signal that was 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) was returned for a child process that has
continued.
If the information stored at the location pointed to by status_
location was stored there by a call to wait3 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 location pointed to by status_
location resulted from a call to wait3 without the WUNTRACED flag
specified, one of the following macros evaluates to a nonzero
value:
o WIFEXITED(*status_value)
o WIFSIGNALED(*status_value)
The wait3 function provides compatibility with BSD systems.
The resource_usage argument points to a location that contains
resource usage information for the child processes as defined in
the <resource.h> header file.
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 init.
3 – Return Values
0 Indicates success. There are no stopped or
exited child processes, the WNOHANG option is
specified.
x The process_id of the child process. The
status of a child process is available.
-1 Indicates an error; errno is set to one of the
following values:
o ECHILD - There are no child processes to
wait for.
o EINTR - Terminated by receipt of a signal
intercepted by the calling process.
o EFAULT - The status_location or resource_
usage argument points to a location outside
of the address space of the process.
o EINVAL- The value of the options argument
is not valid.