wait3(2)                       DG/UX R4.11MU05                      wait3(2)


NAME
       wait3 - wait for child process to stop or terminate

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

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

   where:
       waitstatus    NULL or address of a status word

       options        Modifications to the action of wait3

       rusage         NULL or address of a resource usage structure

DESCRIPTION
       The wait3 system call suspends the calling process until a child
       process stops or terminates, then reports the identity, status, and
       resource usage of the child process to the calling process.  If more
       than one child process has stopped or terminated, the manner in which
       one is chosen is undefined.

       ·      A process stops when it is being traced (see ptrace) and
              either hits a break point or receives a signal that is set to
              be caught.

       ·      A process terminates when it calls exit or when it receives a
              signal that causes it to terminate.

       ·      A process that has terminated but whose status has not been
              reported on by wait may consume system resources.  The wait
              operation cleans up the terminated process and recovers
              remaining system resources.

       wait3 returns the PID of the child process.

       The status of the child process is optionally obtained by the
       waitstatus parameter.  If waitstatus is NULL, status information is
       not returned.  Otherwise, status information stored in the location
       pointed to by waitstatus can be used to determine the reason for the
       child process' termination.

       The following macros are provided in sys/wait.h for use in
       interpreting waitstatus.  When using these macros with wait3, the
       program must define _BSD_WAIT_FLAVOR either in the executable or at
       compile time.

       WIFSTOPPED(*waitstatus)
              Evaluates to a non-zero value if status was returned for a
              child process that is currently stopped.

       WIFSIGNALED(*waitstatus)
              Evaluates to a non-zero value if status was returned for a
              child process that terminated due to the receipt of a signal
              that was not caught (see <signal.h>).

       WIFEXITED(*waitstatus)
              Evaluates to a non-zero value if status was returned for a
              child process that terminated normally.

       A summary of the resources used by a child process that has
       terminated is obtained by the rusage parameter.  If rusage is NULL, a
       summary is not returned.  Otherwise, summary information is stored in
       the location pointed to by rusage.

       The following statement:

          wait(status)

       is identical to this one:

          wait3(status, 0, NULL)

       However, the action taken by wait3 may be modified by setting bits in
       the options parameter as follows.

       ·      The WNOHANG bit specifies that the calling process should not
              be suspended by wait3.

       ·      A process that is not being traced may be stopped by the
              SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signals.  The WUNTRACED
              bit specifies that the status of all stopped child processes
              should be reported, not just those being traced.

       If a parent process terminates without waiting for its child
       processes to terminate, a special system process inherits the child
       processes.

       If an error occurs, wait3 will not clean-up any process and the
       values of status and rusage are undefined.

       If, while waiting for a child to terminate or stop, the process
       receives a signal that causes it to invoke a handler, wait3 will be
       restarted if the handler was established using sigvec without the
       SV_INTERRUPT flag or sigaction with the SA_RESTART flag.  See
       sigvec(2) and sigaction(2).

ACCESS CONTROL
       None.

RETURN VALUE
       child-process-id  Completed successfully.

       0                 The WNOHANG bit in options was set, and the calling
                         process would otherwise have been suspended by
                         wait3.

       -1                An error occurred.  errno is set to indicate the
                         error.

DIAGNOSTICS
       Errno may be set to one of the following error codes:

       ECHILD    The calling process has no child processes.  This condition
                 implies that the calling process was not suspended by
                 wait3.

       EFAULT    The status or rusage arguments point to an illegal address.
                 This condition implies that the calling process was not
                 suspended by wait3.

SEE ALSO
       exec(2), exit(2), exit(2), fork(2), ptrace(2), sigpause(2),
       sigvec(2), sigaction(2), wait(2), wait4(2).

STANDARDS
       When using m88kbcs as the Software Development Environment target,
       the wait3 function will be an incomplete emulation of Berkeley
       semantics.  Since we are using BCS system calls, resource usage
       information is not available.  If rusage is non-NULL, wait3 will fail
       with errno set to EINVAL.


Licensed material--property of copyright holder(s)