wait(2)wait(2)NAMEwait(), waitpid() - wait for child process to stop or terminate
SYNOPSISDESCIPTION
The and functions 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 function suspends 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 or awaiting termina‐
tion of the same process, exactly one thread returns the process status
at the time of the target process termination. If status information
is available prior to the call to return is immediate.
The function is equivalent to if the pid argument is and the options
argument is 0. Otherwise, its behavior is 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 recog‐
nize the initialization process as their parent.
The pid argument specifies the child processes for which status is
requested. The function only returns the status of a child process
from this set:
· If pid is equal to status is requested for any child process. In
this respect, is equivalent to
· 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.
· If pid is less than 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 header file.
The function reports the status of any continued child
process specified by pid whose status has not been
reported since it continued from a job control
stop.
The function does not suspend execution of the calling
thread if status is not immediately available for
one of the child processes specified by pid.
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.
The status of any child processes specified by
pid that are stopped, and whose status has not yet
been reported since they stopped, is also reported
to the requesting process.
HP-UX EXTENSION: If and only if this flag is set,
or (see wait3(2)) returns information on child or
attached processes that are stopped because they
received a or 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 sta‐
tus has not yet been reported.
If the calling process has the signal action set or has set to and the
process has no unwaited-for children that were transformed into zombie
processes, the calling thread blocks until all of the children of the
process containing the calling thread terminate, and and fail and set
to
If or return because the status of a child process is available, these
functions 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 is stored in the location pointed to by stat_loc.
The value stored at the location pointed to by stat_loc is 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 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
Regardless of its value, this information may be interpreted using the
following macros, which are defined in and evaluate to integral expres‐
sions; the stat_val argument is the integer value pointed to by
stat_loc.
HP-UX EXTENSION: If the value of is nonzero, this macro evaluates to a
nonzero value if a "core image" dump was produced (see signal(5)).
If the value of
is nonzero, this macro evaluates to the low-order 8 bits of the
status argument that the child process passed to or or the value
the child process returned from
Evaluates to a nonzero value if
status was returned for a child process that has continued from
a job control stop.
Evaluates to a nonzero value if
status was reported for a child process that terminated nor‐
mally.
Evaluates to a nonzero value if
status was reported for a child process that terminated due to
the receipt of a signal that was not caught (see
Evaluates to a nonzero value if
status was reported for a child process that is currently
stopped.
If the value of
is nonzero, this macro evaluates to the number of the signal
that caused the child process to stop.
If the value of
is nonzero, 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 that
specified the flag and did not specify the flag, exactly one of the
macros and evaluates to a nonzero value.
If the information pointed to by stat_loc was stored by a call to that
specified the and flags, exactly one of the macros and evaluates to a
nonzero value.
If the information pointed to by stat_loc was stored by a call to that
did not specify the or flags, or by a call to the wait() function,
exactly one of the macros and evaluates to a nonzero value.
If the information pointed to by stat_loc was stored by a call to that
did not specify the flag and specified the lag, or by a call to the
wait() function, exactly one of the macros and evaluates to a nonzero
value.
There may be additional implementation-dependent circumstances under
which and report status. This does 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 are assigned a
new parent process ID corresponding to an implementation-defined system
process.
In earlier versions of HP-UX, the status interpretation macros and have
the same definitions as the correspondingly named macros in BSD 4.3 and
earlier systems, so existing applications that depend on these defini‐
tions will continue to work correctly. However, if the application is
recompiled, the feature test macro 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 is used in
the BSD definitions while type int is used in the default definitions.
RETURN VALUE
If or returns because the status of a child process is available, these
functions return a value equal to the process ID of the child process
for which status is reported.
If or returns due to the delivery of a signal to the calling process,
is returned and is set to
If was invoked with 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,
is returned, and is set to indicate the error.
ERRORS
If the call fails, is set to one of the following values:
The calling process has no existing unwaited-for child processes.
The stat_loc argument points to an illegal address or prob‐
lems 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.
The function was interrupted by a signal.
The value of the location pointed to by stat_loc argu‐
ment is undefined.
If the call fails, is set to one of the following values:
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.
The stat_loc argument points to an illegal address or prob‐
lems 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.
The was interrupted by a signal. The value of the location
pointed to by stat_loc is undefined.
The options argument is not valid.
WARNINGS
HP-UX EXTENSION: The operation of is affected if the signal is set to
(see the section of signal(5)). Signal handlers that cause system
calls to be restarted can affect the condition (see bsdproc(3C) and
sigaction(2)).
APPLICATION USAGE
Threads Considerations
In a multithreaded application, only the calling thread is suspended by
call.
and will not return until all threads in the process have reached the
desired state. For example, the calls will not return until all
threads have terminated. If the or options are specified for the call,
it will not return until all threads have stopped or continued, respec‐
tively.
SEE ALSO
Exit conditions in sh(1), exec(2), exit(2), fork(2), pause(2),
ttrace(2), wait3(2), waitid(2), signal(5),
AUTHOR
and were developed by HP, AT&T and the University of California, Berke‐
ley.
STANDARDS CONFORMANCEwait(2)
