wait, waitpid, wait3, wait4 - Wait for a child process to
stop or terminate
#include <sys/wait.h>
pid_t wait(
int *status_location ); pid_t waitpid(
pid_t process_id,
int *status_location,
int options ); pid_t wait3(
int *status_location,
int options,
struct rusage *resource_usage );
The following function declarations do not conform to current
standards and are supported only for backward compatibility:
#include <sys/resource.h>
pid_t wait3(
union wait *status_location,
int options,
struct rusage *resource_usage ); pid_t wait4(
pid_t process_id,
union wait *status_location,
int options,
struct rusage *resource_usage );
Application developers may want to specify an #include
statement for <sys/types.h> before the one for
<sys/wait.h> if programs are being developed for multiple
platforms. The additional #include statement is not
required on Tru64 UNIX systems or by industry standards,
but may be required on other vendors' systems that conform
to these standards.
See NOTES for further information on the backward-compatible
versions of wait3() and wait4().
Interfaces documented on this reference page conform to
industry standards as follows:
wait(): XSH4.0, XSH4.2, XSH5.0
waitpid(), wait3(): XSH4.2, XSH5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Points to a location that contains the termination status
of the child process as defined in the <sys/wait.h> header
file. Specifies the child process or set of child processes.
Modifies the behavior of the function. The flags
for the options parameter are described in DESCRIPTION.
Specifies the location of a structure that will contain
the resource usage information for child processes that
have terminated.
The wait(), waitpid(), and wait3() functions allow the
calling process to obtain status information pertaining to
one of its child processes. Various options permit status
information to be obtained for child processes that have
terminated or stopped. If status information is available
for two or more child processes, the order in which their
status is reported is unspecified.
The wait() function suspends execution of the calling process
until status information for one of its terminated
child processes is available, or until delivery of a signal
whose action is either to execute a signal-catching
function or to terminate the process. If status information
is available prior to the call to wait(), return is
immediate.
The effect of the wait() function can be modified by setting
the SIGCHLD signal. See sigaction(2) for more information.
The waitpid() function behaves identically to wait() if
the process_id parameter has a value of (pid_t)-1 and the
options parameter specifies a value of zero (0). Should
these parameters contain other values, the waitpid() function
is changed as specified by those values.
The wait3() function is similar to waitpid() in allowing
the calling process to obtain status information for specified
child processes. The wait3() function also includes
a resource_usage parameter. If this parameter is not a
null pointer, the rusage structure pointed to by the third
argument is filled in for the child process identified by
the return value.
[Tru64 UNIX] The wait4() function is similar to wait3(),
except that wait4() waits for a specific child as indicated
by the process_id parameter. A program that calls
wait4() must be compiled with the _BSD switch defined. See
NOTES for further information.
In a multithreaded environment, the wait(), waitpid(),
wait3(), and wait4() functions block only the calling
thread.
The process_id parameter allows the calling process to
gather status from a specific set of child processes. The
waitpid() and wait4() functions return the status only of
child processes from this set. The following rules define
the set: If the process_id parameter is equal to
(pid_t)-1, status is requested for any child process. In
this respect, the waitpid() function is equivalent to the
wait() function. If the process_id parameter is greater
than zero (0), it specifies the process ID of a single
child process for which status is requested. If the process_id
parameter is equal to zero (0), status is
requested for any child process whose process group ID is
equal to that of the calling process. If the process_id
parameter is less than (pid_t)-1, status is requested for
any child process whose process group ID is equal to the
absolute value of the process_id parameter.
The options parameter to the waitpid(), wait3(), and
wait4() functions modifies the behavior of the function.
The flags for the options parameter can be combined by
specifying them in a bitwise-inclusive OR operation. The
flags are as follows: [XSH4.2] Specifies reporting the
status of any child process identified by the process_id
parameter whose status has not been reported since it continued
from a job control stop. [Tru64 UNIX] Specifies
that the process whose status is returned in status_location
will be kept in a waitable state. The process can be
waited for again with the same results. Prevents the
calling process from being suspended. If there are child
processes that have been stopped or terminated, one is
chosen and waitpid() returns its pid, just as when the
WNOHANG flag is not specified. If there are no such processes
(that is, if conditions are such that waitpid()
without the WNOHANG flag would have suspended the calling
process), zero (0) is returned. Because you can never wait
for process 0, there is no confusion arising from this
return. Specifies that the call return additional information
when the child process is stopped because it
received a SIGTTIN, SIGTTOU, SIGSTOP, or SIGTSTOP signal.
[XSH4.2] If the calling process has SA_NOCLDWAIT set or
has SIGCHLD set to SIG_IGN, and the process has no
unwaited-for child processes that were transformed into
zombie processes, it will block until all of its child
processes terminate, and wait() and waitpid() will fail
and set errno to [ECHILD].
If the wait(), waitpid(), wait3(), or wait4() functions
return because the status of a child process is available,
the process ID of the child process is returned. In this
instance, information is stored in the location pointed to
by the status_location parameter if the value of the status_location
is not null. The value stored in the location
pointed to by the status_location parameter is zero (0)
if, and only if, the status is returned from a terminated
child process that did one of the following: Returned zero
(0) from the main() routine. Passed zero (0) as the status
argument to the _exit() or exit() function.
Regardless of its value, this information can be defined
using the macros defined in the <sys/wait.h> header file
that evaluate to integral expressions. In the following
macro descriptions, the status_value parameter is equal to
the integer value pointed to by the status_location parameter:
Evaluates to a nonzero value if status was returned
for a child process that terminated normally. If the
value of WIFEXITED(status_value) is nonzero, this macro
evaluates to the low-order 8 bits of the status parameter
that the child process passed to the _exit() or exit()
function, or the value the child process returned from the
main() routine. Evaluates to nonzero value if status was
returned for a child process that terminated due to the
receipt of a signal that was not caught. If the value of
WIFSIGNALED(status_value) is nonzero, this macro evaluates
to the number of the signal that caused the termination of
the child process. Evaluates to a nonzero value if status
was returned for a child process that is currently
stopped. If the value of WIFSTOPPED(status_value) is
nonzero, this macro evaluates to the number of the signal
that caused the child process to stop. [XSH4.2] Evaluates
to a non-zero value if status was returned for a
child process that has continued from a job control stop.
Note
[Tru64 UNIX] The following behavior described for waitpid()
and wait3() also applies to the libbsd versions of
wait3() and wait4(), except the parameter to the macros
should be the w_status member of the union pointed to by
the status_location parameter.
If the information pointed to by the status_location
parameter was stored by a call to waitpid() or wait3()
that specified the WUNTRACED flag and did not specify the
WCONTINUED flag, one of the following macros evaluates to
a nonzero value: WIFEXITED(*status_location) WIFSIGNALED(*status_location)
WIFSTOPPED(*status_location)
If the information pointed to by status_location was
stored by a call to waitpid() or wait3() that specified
both the WUNTRACED and WCONTINUED flags, one of the following
macros evaluates to a nonzero value: WIFEXITED(*status_location)
WIFSIGNALED(*status_location) WIFSTOPPED(*status_location)
WIFCONTINUED(*status_location)
If the information pointed to by status_location was
stored by a call to waitpid() or wait3() that specified
neither the WUNTRACED nor the WCONTINUED flag, or by a
call to the wait() function, one of the following macros
evaluates to a nonzero value: WIFEXITED(*status_location)
WIFSIGNALED(*status_location)
If the information pointed to by status_location was
stored by a call to waitpid() or wait3() that did not
specify the WUNTRACED flag and specified the WCONTINUED
flag, or by a call to wait(), one of the following macros
evaluates to a nonzero value: WIFEXITED(*status_location)
WIFSIGNALED(*status_location) WIFCONTINUED(*status_location)
If a parent process terminates without waiting for all of
its child processes to terminate, the remaining child processes
will be assigned a parent process ID equal to the
process ID of the init process.
[Tru64 UNIX] Compiling with the _BSD switch defined and
then linking with the libbsd compatibility library redefines
the status_location parameter as the type union wait
* instead of int *. Programs using the backward-compatible
versions of wait3() and wait4() functions must be compiled
in this manner.
Paragraphs flagged with [XSH4.2] apply to applications
built in compilation environments conforming to XSH4.2 and
higher versions of the XSH specification.
If the wait(), waitpid(), wait3(), or wait4() function
returns because the status of a child process is available,
the process ID of the child is returned to the calling
process. If the function returns because a signal was
caught by the calling process, -1 is returned and errno is
set to [EINTR].
If the waitpid(), wait3(), or wait4() function was invoked
with the WNOHANG flag specified, it has at least one child
process specified by pid for which status is not available,
and status is not available for any process
specified by pid, a value of 0 (zero) is returned. Otherwise,
(pid_t)-1 is returned, and errno is set to indicate
the error.
The wait(), waitpid(), wait3(), and wait4() functions set
errno to the following values: The calling process has no
existing unwaited-for child processes. The function was
terminated by receipt of a signal. [Tru64 UNIX] The status_location
or resource_usage parameter points to a location
outside of the address space of the process.
The waitpid() function also fails if the following is
true: The process or process group ID specified by the
process_id parameter does not exist or is not a child process
of the calling process.
The waitpid(), wait3(), and wait4() functions also fail if
the following is true: The value of the options parameter
is not valid.
Functions: exec(2), exit(2), fork(2), getrusage(2),
ptrace(2), sigaction(2), pause(3)
Standards: standards(5)
wait(2)
[ Back ] |
