wait(3BSD) (BSD System Compatibility) wait(3BSD)
NAME
wait: wait3, WIFSTOPPED, WIFSIGNALED, WIFEXITED - (BSD) wait
for process to terminate or stop
SYNOPSIS
/usr/ucb/cc [flag . . . ] file . . .
#include <sys/wait.h>
#include <sys/time.h>
#include <sys/resource.h>
int wait3(union wait *statusp, int options, struct rusage *rusage);
WIFSTOPPED(union wait status);
WIFSIGNALED(union wait status);
WIFEXITED(union wait status);
DESCRIPTION
wait delays its caller until a signal is received or one of
its child processes terminates or stops due to tracing. If
any child has died or stopped due to tracing and this has not
been reported using wait, return is immediate, returning the
process ID and exit status of one of those children. If that
child had died, it is discarded. If there are no children,
return is immediate with the value -1 returned. If there are
only running or stopped but reported children, the calling
process is blocked.
If status is not a NULL pointer, then on return from a
successful wait call the status of the child process whose
process ID is the return value of wait is stored in the wait
union pointed to by status. The w_status member of that union
is an int; it indicates the cause of termination and other
information about the terminated process in the following
manner:
If the low-order 8 bits of w_status are equal to 0177,
the child process has stopped; the 8 bits higher up from
the low-order 8 bits of w_status contain the number of
the signal that caused the process to stop. See
ptrace(2) and sigvec(3BSD).
If the low-order 8 bits of w_status are non-zero and are
not equal to 0177, the child process terminated due to a
signal; the low-order 7 bits of w_status contain the
number of the signal that terminated the process. In
addition, if the low-order seventh bit of w_status (that
is, bit 0200) is set, a ``core image'' of the process
was produced; see sigvec(3BSD).
Copyright 1994 Novell, Inc. Page 1
wait(3BSD) (BSD System Compatibility) wait(3BSD)
Otherwise, the child process terminated due to an exit
call; the 8 bits higher up from the low-order 8 bits of
w_status contain the low-order 8 bits of the argument
that the child process passed to exit; see exit(2).
Other members of the wait union can be used to extract this
information more conveniently:
If the w_stopval member has the value WSTOPPED, the
child process has stopped; the value of the w_stopsig
member is the signal that stopped the process.
If the w_termsig member is non-zero, the child process
terminated due to a signal; the value of the w_termsig
member is the number of the signal that terminated the
process. If the w_coredump member is non-zero, a core
dump was produced.
Otherwise, the child process terminated due to an exit
call; the value of the w_retcode member is the low-order
8 bits of the argument that the child process passed to
exit.
The other members of the wait union merely provide an
alternate way of analyzing the status. The value stored in
the w_status field is compatible with the values stored by
other versions of the UNIX system, and an argument of type int
* may be provided instead of an argument of type union wait *
for compatibility with those versions.
wait3 is an alternate interface to wait(2) that allows both
non-blocking status collection and the collection of the
status of children stopped by any means. The status parameter
is defined as above. The options parameter is used to
indicate the call should not block if there are no processes
that have status to report (WNOHANG), and/or that children of
the current process that are stopped due to a SIGTTIN,
SIGTTOU, SIGTSTP, or SIGSTOP signal are eligible to have their
status reported as well (WUNTRACED). A terminated child is
discarded after it reports status, and a stopped process will
not report its status more than once. If rusage is not a NULL
pointer, a summary of the resources used by the terminated
process and all its children is returned. Only the user time
used and the system time used are currently available. They
are returned in rusage.ru_utime and rusage.ru_stime,
respectively.
Copyright 1994 Novell, Inc. Page 2
wait(3BSD) (BSD System Compatibility) wait(3BSD)
When the WNOHANG option is specified and no processes have
status to report, wait3 returns 0. The WNOHANG and WUNTRACED
options may be combined by an OR of the two values.
WIFSTOPPED, WIFSIGNALED, WIFEXITED, are macros that take an
argument status, of type `union wait', as returned by wait3.
WIFSTOPPED evaluates to true (1) when the process for which
the wait call was made is stopped, or to false (0) otherwise.
WIFSIGNALED evaluates to true when the process was terminated
with a signal. WIFEXITED evaluates to true when the process
exited by using an exit(2) call.
RETURN VALUE
wait3 returns 0 if WNOHANG is specified and there are no
stopped or exited children, and returns the process ID of the
child process if it returns due to a stopped or terminated
child process. Otherwise, wait3 returns a value of -1 and
sets errno to indicate the error.
ERRORS
wait3 will fail and return immediately if one or more of the
following are true:
ECHILD The calling process has no existing unwaited-
for child processes.
EFAULT The status or rusage arguments point to an
illegal address.
wait3 will terminate prematurely, return -1, and set errno to
EINTR upon the arrival of a signal whose SV_INTERRUPT bit in
its flags field is set [see sigvec(3BSD) and
siginterrupt(3BSD)]. signal(3BSD), in the System V
compatibility library, sets this bit for any signal it
catches.
Since System V Release 4 does not implement this function
directly as a system call, an illegal address (status or
rusage) argument may result in a core dump as opposed to
returning EFAULT.
REFERENCES
exit(2), getrusage(3BSD), ptrace(2), siginterrupt(3BSD),
signal(2), signal(3BSD), sigvec(3BSD), wait(2), waitpid(2)
Copyright 1994 Novell, Inc. Page 3
wait(3BSD) (BSD System Compatibility) wait(3BSD)
NOTICES
wait [see wait(2)] is found in libc, not libucb. However, its
description is provided here to offer a comparison to the
wait3 functionality.
If a parent process terminates without waiting on its
children, the initialization process (process ID = 1) inherits
the children.
wait3 is automatically restarted when a process receives a
signal while awaiting termination of a child process, unless
the SV_INTERRUPT bit is set in the flags for that signal.
Copyright 1994 Novell, Inc. Page 4