wait3(2) — AIX PS/2 1.2.1



WAIT3(2,L)                  AIX Technical Reference                  WAIT3(2,L)



-------------------------------------------------------------------------------
wait3



PURPOSE

Waits for a child process to stop or terminate.

SYNTAX

#include <sys/param.h>
#include <sys/time.h>
#include <sys/resource.h>
#include <sys/wait.h>

pid_t wait3(status, options, rusage)
union wait *status;
int options;
struct rusage *rusage;

DESCRIPTION

The status and option words are described by definitions and macros in the file
<sys/wait.h>; the union and its bitfield definitions and associated macros
given there provide convenient and mnemonic access to the word of status
returned by a wait3 call.  status->w_status is the same as the integer returned
in *stat_loc when using the wait call.

  o If WIFSTOPPED(*status) is nonzero, status->w_stopsig is the signal which
    caused the child process to stop.

  o If WIFSIGNALED(*status) is nonzero, status->w_termsig is the signal which
    caused the child process to terminate and status->w_coredump indicates
    whether or not a core dump was made.

  o If WIFEXITED (*status) is nonzero, status->w_retcode is the low order 8
    bits of the argument that the child process passed to exit.

  o Exactly one of WIFSTOPPED, WIFSIGNALED, or WIFEXITED will be nonzero.

There are two options, which may be combined by ORing them together.

  o The first is WNOHANG, which causes the wait3 to return immediately if there
    are no processes which wish to report status, returning a value of 0 in
    this case as the result of the wait3.

  o The second option is WUNTRACED, which causes wait3 to return information
    about child processes of the current process which are stopped (but not
    traced with ptrace) because they received a SIGTTIN, SIGTTOU, SIGTSTP, or
    SIGSTOP signal.  See "sigaction, sigvec, signal" for a description of these
    signals.



Processed November 7, 1990        WAIT3(2,L)                                  1



WAIT3(2,L)                  AIX Technical Reference                  WAIT3(2,L)




The rusage parameter may be NULL or else a pointer to an rusage structure, into
which information describing the resources used by the process whose process-ID
is returned by wait3 (and all of its child processes for which it has collected
similar information) is placed.  If rusage is NULL, no information on resource
usage is provided.  Currently this information is not available for stopped
processes.

If the Transparent Computing Facility is installed, the resource information
returned describes the resources used on all sites by the process whose
process-ID is returned by wait3.  This may include information combined from
sites of widely varying machine types.  Totaling statistics from different
sites, such as CPU times, may not be appropriate.

If the child process had been running on a cluster site which appears to the
parent process's site to have gone down, wait3 reports that the child process
has exited because of the SIGPWR signal.  In this case, as with stopped
processes, the rusage information is not returned.

RETURN VALUE

If wait3 returns due to a stopped or terminated child process, the process-ID
of the child process is returned to the calling process.  If WNOHANG is
specified and there are no child processes which are already stopped or
terminated, a value of 0 is returned.  Otherwise, a value of -1 is returned and
errno is set to indicate the error.

ERROR CONDITIONS

The wait3 system call 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    rusage points to an illegal address.

EINTR     The call was interrupted by a signal.

RELATED INFORMATION

In this book:  "exit, _exit," "fork, vfork," "sigaction, sigvec, signal," and
"wait, waitpid."













Processed November 7, 1990        WAIT3(2,L)                                  2

Museum

Related Articles