wait(2) CLIX wait(2)
NAME
wait, waitpid - Waits for a child process to stop or terminate
LIBRARY
Standard C Library (libc.a)
SYNOPSIS
#include <sys/types.h>
#include <sys/time.h>
#include <sys/resource.h>
#include <sys/wait.h>
pid_t wait(
int *status_location );
pid_t waitpid(
pid_t process_id ,
int *status_location ,
int options );
PARAMETERS
status_location Points to a structure that is filled in with the child
process termination status, as defined in the
<sys/wait.h> header file.
process_id Specifies the child process.
options Modifies the behavior of the function.
DESCRIPTION
The wait() function suspends the calling process until one of the
immediate children stops or terminates. The wait() function returns
prematurely if a signal is received, and if a child process stopped or
terminated prior to the call to wait, return is immediate.
The waitpid() function behaves identically to wait(), if process_id has a
value of -1 and options has a value of 0. Otherwise, its behavior will be
modified by the values of the process_id and options parameters.
The process_id parameter allows the calling process to gather status from
a specific set of child processes, according to the following rules:
⊕ If process_id is equal to a value of -1, status is requested for any
2/94 - Intergraph Corporation 1
wait(2) CLIX wait(2)
child process. In this respect, waitpid() is equivalent to wait().
⊕ If process_id is greater than 0, it specifies the process ID of a
single child process for which status is requested.
⊕ If process_id is equal to 0, status is requested for any child process
whose process group ID is equal to that of the calling process.
⊕ If process_id is less than -1, status is requested for any child
process whose process group ID is equal to the absolute value of the
process_id parameter.
The waitpid() function will only return the status of a child process from
this set.
The options parameter to waitpid() modifies the behavior of the function.
Two values are defined, WNOHANG and WUNTRACED, which can be combined by
specifying their bitwise-inclusive OR. The WNOHANG option prevents the
calling process from being suspended even if there are child processes to
wait for. If the WUNTRACED option is set, the call should also return
information when children of the current process are stopped because they
received a SIGTTIN, SIGTTOU, SIGSTOP, or SIGTSTP signal.
If wait() or waitpid() return because the status of a child process is
available, they return the process ID of the child process. In this case,
if status_location is not null, information will be stored in the location
pointed to by status_location.
If status_location is nonzero, 16 bits of information called status are
stored in the low order 16 bits of the status; the status parameter is the
integer value pointed to by status_location. The status parameter can be
used to differentiate between stopped and terminated child processes. If
the child process terminated, status identifies the cause of termination
and passes useful information to the parent. The status parameter is
evaluated as follows:
⊕ If the child process stopped, the high order 8 bits of status will
contain the number of the signal that caused the process to stop and
the low order 8 bits will be set equal to 0177.
⊕ If the child process terminated due to an exit() call, the low order 8
bits of status will be 0 and the high order 8 bits will contain the low
order 8 bits of the argument that the child process passed to exit().
(See the exit() function.)
⊕ If the child process terminated due to a signal, the high order 8 bits
of status will be 0 and the low order 8 bits will contain the number of
the signal that caused the termination. In addition, if the low order
seventh bit (that is, bit 200) is set, a core image will have been
produced. (See the signal() function.)
2 Intergraph Corporation - 2/94
wait(2) CLIX wait(2)
Regardless of its value, the information stored at the location pointed to
be status_location may be interpreted using the following macros, which
are defined in <sys/wait.h> and evaluate to integral expressions.
WIFEXITED(status)
Evaluates to a nonzero value if status was returned for a child
process that terminated normally.
WEXITSTATUS(status)
If the value of WIFEXITED(status) is nonzero, this macro evaluates
either to the low-order 8 bits of the status parameter that the
child process passed to _exit() or exit(), or to the value the
child process returned from main.
WIFSIGNALED(status)
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)
If the value of WIFSIGNALED(status) is 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 returned for a child
process that is currently stopped.
WSTOPSIG(status)
If the value of WIFSTOPPED(status) is nonzero, this macro evaluates
to the number of the signal that caused the child process to stop.
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 1. This means that the initialization process
inherits the child processes.
EXAMPLES
1. the following waits for any child process to stop or complete:
int stat_loc;
int child_pid;
child_pid = wait(&statloc);
if (child_pid == -1)
perror("wait failed\n");
2. The following determines the status of a particular child process
without waiting for it to stop or terminate:
2/94 - Intergraph Corporation 3
wait(2) CLIX wait(2)
int stat_loc;
int return_value;
return_value = waitpid(child_pid, &stat_loc, WNOHANG);
switch(return_value) {
case -1:
perror("waitpid failed");
return(-1);
case 0:
/* child process not yet done */
return(0);
default:
/* child process done or stopped */
...
}
RETURN VALUES
If the wait() or 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 the wait() or waitpid() function returns due to the
receipt of a signal, a value of -1 is returned to the calling process and
errno is set to EINTR.
If the WNOHANG option was specified, and there are stopped, exited, or
nonexistent children, the waitpid() function returns a value of -1 and
sets errno to indicate the error. Otherwise, the operation returns a
value of 0.
Otherwise, -1 is returned and errno is set to indicate the error.
ERRORS
The wait() and waitpid() functions fail if one or more of the following
are true:
[ECHILD] The calling process has no existing unwaited-for child
processes.
[EINTR] The function was terminated by receipt of a signal.
[EINVAL] The value of the options parameter is not valid.
RELATED INFORMATION
Functions: exec(2), exit(2), fork(2), intro(2), pause(2), ptrace(2),
sigaction(2), signal(2)
4 Intergraph Corporation - 2/94