 |
Index for
Section 2 |
|
 |
Alphabetical
listing for W |
|
 |
Bottom of
page |
|
wait(2)
NAME
wait, waitpid, wait3, wait4 - Wait for a child process to stop or terminate
SYNOPSIS
#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().
STANDARDS
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.
PARAMETERS
status_location
Points to a location that contains the termination status of the
child process as defined in the <sys/wait.h> header file.
process_id
Specifies the child process or set of child processes.
options Modifies the behavior of the function. The flags for the options
parameter are described in DESCRIPTION.
resource_usage
Specifies the location of a structure that will contain the
resource usage information for child processes that have
terminated.
DESCRIPTION
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:
WCONTINUED
[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.
WNOWAIT
[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.
WNOHANG
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.
WUNTRACED
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:
WIFEXITED(status_value)
Evaluates to a nonzero value if status was returned for a child process
that terminated normally.
WEXITSTATUS(status_value)
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.
WIFSIGNALED(status_value)
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.
WTERMSIG(status_value)
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.
WIFSTOPPED(status_value)
Evaluates to a nonzero value if status was returned for a child process
that is currently stopped.
WSTOPSIG(status_value)
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.
WIFCONTINUED(status_value)
[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.
NOTES
[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.
RETURN VALUES
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.
ERRORS
The wait(), waitpid(), wait3(), and wait4() functions set errno to the
following values:
[ECHILD]
The calling process has no existing unwaited-for child processes.
[EINTR] The function was terminated by receipt of a signal.
[EFAULT]
[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:
[ECHILD]
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:
[EINVAL]
The value of the options parameter is not valid.
SEE ALSO
Functions: exec(2), exit(2), fork(2), getrusage(2), ptrace(2),
sigaction(2), pause(3)
Standards: standards(5)
|
Index for
Section 2 |
|
|
Alphabetical
listing for W |
|
 |
Top of
page |
|