wait(2) wait(2)
NAME [Toc] [Back]
wait, waitpid - wait for child process to stop or terminate
SYNOPSIS [Toc] [Back]
#include <sys/types.h>
#include <sys/wait.h>
pid_t wait(int *stat_loc);
pid_t waitpid(pid_t pid, int *stat_loc, int options);
DESCRIPTION [Toc] [Back]
The wait() and waitpid() functions shall obtain status information
pertaining to one of the caller's 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 shall suspend execution of the calling thread
until status information for one of the terminated child processes of
the calling process is available, or until delivery of a signal whose
action is either to execute a signal-catching function or to terminate
the process. If more than one thread is suspended in wait() or
waitpid() awaiting termination of the same process, exactly one thread
shall return the process status at the time of the target process
termination. If status information is available prior to the call to
wait(), return shall be immediate.
The waitpid() function shall be equivalent to wait() if the pid
argument is (pid_t) -1 and the options argument is 0. Otherwise, its
behavior shall be modified by the values of the pid and options
arguments.
Note that if the parent process terminates without waiting for its
child processes to terminate, these processes are adopted by and
recognize the initialization process as their parent.
The pid argument specifies the child processes for which status is
requested. The waitpid() function shall only return the status of a
child process from this set:
+ If pid is equal to (pid_t) -1, status is requested for any
child process. In this respect, waitpid() is equivalent to
wait().
+ If pid is greater than 0, it specifies the process ID of a
single child process for which status is requested.
+ If pid is 0, status is requested for any child process whose
process group ID is equal to that of the calling process.
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
wait(2) wait(2)
+ If pid is less than (pid_t) -1, status is requested for any
child process whose process group ID is equal to the absolute
value of pid.
The stat_loc argument is the address where status of the specified
child processes is placed.
The options argument is constructed from the bitwise-inclusive OR of
zero or more of the following flags defined in the <sys/wait.h> header
file.
WCONTINUED The waitpid() function shall report the status
of any continued child process specified by pid
whose status has not been reported since it
continued from a job control stop.
WNOHANG The waitpid() function shall not suspend
execution of the calling thread if status is not
immediately available for one of the child
processes specified by pid.
WNOWAIT HP-UX EXTENSION: Keep the process whose status
is returned in stat_loc in a waitable state.
The process may be waited for again with
identical results, provided the state of the
process doesn't change in the interim.
WUNTRACED The status of any child processes specified by
pid that are stopped, and whose status has not
yet been reported since they stopped, shall also
be reported to the requesting process.
HP-UX EXTENSION: If and only if this flag is
set, waitpid() or wait3() returns information on
child or attached processes that are stopped but
not traced (with ptrace()) because they received
a SIGTTIN, SIGTTOU, SIGTSTP or SIGSTOP signal,
and whose status has not yet been reported.
Regardless of this flag, status is returned for
child or attached processes that have terminated
or are stopped and traced and whose status has
not yet been reported.
If the calling process has the signal action SA_NOCLDWAIT set or has
SIGCHLD set to SIG_IGN, and the process has no unwaited-for children
that were transformed into zombie processes, the calling thread shall
block until all of the children of the process containing the calling
thread terminate, and wait() and waitpid() shall fail and set errno to
[ECHILD].
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
wait(2) wait(2)
If wait() or waitpid() return because the status of a child process is
available, these functions shall return a value equal to the process
ID of the child process. In this case, if the value of the argument
stat_loc is not a null pointer, information shall be stored in the
location pointed to by stat_loc. The value stored at the location
pointed to by stat_loc shall be 0 if and only if the status returned
is from a terminated child process that terminated by one of the
following means:
+ 1. The process returned 0 from main().
+ 2. The process called _exit() or exit() with a status argument
of 0.
+ 3.The process was terminated because the last thread in the
process terminated.
Previous versions of HP-UX documented the bit encodings of the status
returned by wait() which could be interpreted directly and
applications doing this will continue to work correctly. However, new
applications should use the provided status interpretation macros
shown below for maximum portability.
Status Interpretation Macros [Toc] [Back]
Regardless of its value, this information may be interpreted using the
following macros, which are defined in <sys/wait.h> and evaluate to
integral expressions; the stat_val argument is the integer value
pointed to by stat_loc.
WCOREDUMP(stat_val) HP-UX EXTENSION: If the value of
WIFSIGNALED(stat_val) is non-zero, this macro
evaluates to a non-zero value if a "core
image" dump was produced (see signal(5)).
WEXITSTATUS(stat_val) If the value of WIFEXITED(stat_val) is
non-zero, this macro evaluates to the
low-order 8 bits of the status argument that
the child process passed to _exit() or exit()
or the value the child process returned from
main().
WIFCONTINUED(stat_val) Evaluates to a non-zero value if status was
returned for a child process that has
continued from a job control stop.
WIFEXITED(stat_val) Evaluates to a non-zero value if status was
reported for a child process that terminated
normally.
WIFSIGNALED(stat_val) Evaluates to a non-zero value if status was
reported for a child process that terminated
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
wait(2) wait(2)
due to the receipt of a signal that was not
caught (see <signal.h>).
WIFSTOPPED(stat_val) Evaluates to a non-zero value if status was
reported for a child process that is
currently stopped.
WSTOPSIG(stat_val) If the value of WIFSTOPPED(stat_val) is
non-zero, this macro evaluates to the number
of the signal that caused the child process
to stop.
WTERMSIG(stat_val) If the value of WIFSIGNALED(stat_val) is
non-zero, this macro evaluates to the number
of the signal that caused the termination of
the child process.
If the information pointed to by stat_loc was stored by a call to
waitpid() that specified the WUNTRACED flag and did not specify the
WCONTINUED flag, exactly one of the macros WIFEXITED(*stat_loc),
WIFSIGNALED(*stat_loc) and WIFSTOPPED(*stat_loc) shall evaluate to a
non-zero value.
If the information pointed to by stat_loc was stored by a call to
waitpid() that specified the WUNTRACED and WCONTINUED flags, exactly
one of the macros WIFEXITED(*stat_loc), WIFSIGNALED(*stat_loc),
WIFSTOPPED(*stat_loc) and WIFCONTINUED(*stat_loc) shall evaluate to a
non-zero value.
If the information pointed to by stat_loc was stored by a call to
waitpid() that did not specify the WUNTRACED or WCONTINUED flags, or
by a call to the wait() function, exactly one of the macros
WIFEXITED(*stat_loc) and WIFSIGNALED(*stat_loc) shall evaluate to a
non-zero value.
If the information pointed to by stat_loc was stored by a call to
waitpid() that did not specify the WUNTRACED flag and specified the
WCONTINUED lag, or by a call to the wait() function, exactly one of
the macros WIFEXITED(*stat_loc), WIFSIGNALED(*stat_loc), and
WIFCONTINUED(*stat_loc) shall evaluate to a non-zero value.
There may be additional implementation-dependent circumstances under
which wait(), waitpid() report status. This shall not occur unless
the calling process or one of its child processes explicitly makes use
of a non-standard extension. In these cases the interpretation of the
reported status is implementation-defined.
If a parent process terminates without waiting for all of its child
processes to terminate, the remaining child processes shall be
assigned a new parent process ID corresponding to an
implementation-defined system process.
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
wait(2) wait(2)
In earlier versions of HP-UX, the status interpretation macros
WIFEXITED, WIFSIGNALED and WIFSTOPPED have the same definitions as the
correspondingly named macros in BSD 4.3 and earlier systems, so
existing applications that depend on these definitions will continue
to work correctly. However, if the application is recompiled, the
feature test macro _BSD must be turned on so that the old definitions
of these macros override the new definitions of these macros that are
in effect by default. The only difference between the old and new
definitions is the argument typing. Type union wait is used in the
BSD definitions while type int is used in the default definitions.
RETURN VALUE [Toc] [Back]
If wait() or waitpid() returns because the status of a child process
is available, these functions shall return a value equal to the
process ID of the child process for which status is reported.
If wait() or waitpid() returns due to the delivery of a signal to the
calling process, -1 shall be returned and errno set to [EINTR].
If waitpid() was invoked with WNOHANG set in options, 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, 0 is
returned. Otherwise, (pid_t) -1 shall be returned, and errno set to
indicate the error.
ERRORS [Toc] [Back]
If the wait() call fails, errno is set to one of the following values:
[ECHILD] The calling process has no existing unwaited-for
child processes.
[EFAULT] The stat_loc argument points to an illegal address
or problems were encountered in the reporting of
the status information for the specified child
process. Note that the reliable detection of this
error is implementation-dependent.
[EINTR] The function was interrupted by a signal. The
value of the location pointed to by stat_loc
argument is undefined.
If the waitpid() call fails, errno is set to one of the following
values:
[ECHILD] The process specified by pid does not exist or is
not a child of the calling process, or the process
group specified by pid does not exist or does not
have any member process that is a child of the
calling process.
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003
wait(2) wait(2)
[EFAULT] The stat_loc argument points to an illegal address
or problems were encountered in the reporting of
the status information for the specified child
process. Note that the reliable detection of this
error is implementation-dependent.
[EINTR] The waitpid() was interrupted by a signal. The
value of the location pointed to by stat_loc is
undefined.
[EINVAL] The options argument is not valid.
WARNINGS [Toc] [Back]
HP-UX EXTENSION: The operation of wait(), waitpid() is affected if
the SIGCLD signal is set to SIG_IGN (see the WARNINGS section of
signal(5)). Signal handlers that cause system calls to be restarted
can affect the EINTR condition (see bsdproc(3C), sigaction(2) and
sigvector(2)).
APPLICATION USAGE [Toc] [Back]
Threads Considerations
In a multi-threaded application, only the calling thread is suspended
by wait(), waitpid() call.
wait() and waitpid() will not return until all threads in the process
have reached the desired state. For example, the wait(), waitpid()
calls will not return until all threads have terminated. If the
WUNTRACED or WCONTINUED options are specified for the waitpid() call,
it will not return until all threads have stopped or continued,
respectively.
SEE ALSO [Toc] [Back]
Exit conditions ($?) in sh(1); exec(2), exit(2), fork(2), pause(2),
ptrace(2), signal(5), wait3(2), waitid(2), <sys/types.h>,
<sys/wait.h>.
AUTHOR [Toc] [Back]
wait(), waitpid(), and wait3() were developed by HP, AT&T and the
University of California, Berkeley.
CHANGE HISTORY [Toc] [Back]
First released in Issue 1.
Derived from Issue 1 of the SVID.
Issue 4 [Toc] [Back]
The following change is incorporated for alignment with the ISO
POSIX-1 standard:
+ Text describing conditions under which 0 will be returned when
WNOHANG is set in options is added to the RETURN VALUE
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: August 2003
wait(2) wait(2)
section.
Other changes are incorporated as follows:
+ The header <sys/types.h> is now marked as optional (OH); this
header need not be included on XSI-conformant systems.
+ Error return values through out the DESCRIPTION and RETURN
VALUE sections are changed to show the proper casting (that
is, (pid_t) -1.
+ The words "If the implementation supports job control" are
removed from the description of WUNTRACED. This is because
job control is defined as mandatory for Issue 4 conforming
implementations.
Issue 4, Version 2
The following changes are incorporated in the DESCRIPTION for X/OPEN
UNIX conformance:
+ The WCONTINUED options flag and the WIFCONTINUED(stat_val)
macro are added.
+ Text following the list of options flags explains the
implications of setting the SA_NOCLDWAIT signal flag or
setting SIGCHILD to SIG_IGN.
+ Text following the list of macros, which explains what macros
return non-zero values in certain cases, is expanded and the
value of the WCONTINUED flag on the previous call to waitpid()
is taken into account.
STANDARDS CONFORMANCE [Toc] [Back]
wait(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1
waitpid(): AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: August 2003 [ Back ] |
