wait3

Purpose

     Waits for process to terminate.

Library

     Berkeley Library (libbsd.a)

Syntax

     #include <bsd/sys/wait.h>
     #include <bsd/sys/resource.h>

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

Description

     The wait3 subroutine checks the status of child processes
     and, depending  on the options parameter,  either returns
     immediately with the information  available when the call
     is made or waits for  a child process to terminate.  This
     subroutine is  useful for  processes that must  not block
     when collecting the status of child processes.

     When  the  wait3  subroutine is  successful,  the  status
     parameter is nonzero.  The high-order byte of status con-
     tains the  low byte of  the argument to exit  supplied by
     the  child process,  while the  low-order byte  of status
     contains the  termination status  of the  process.  Addi-
     tional information on the  status parameter is located in
     the file bsd/sys/wait.h.

     The  options  parameter  has  only  one  possible  value,
     WNOHANG, which, when set,  indicates that the call should
     not block  if no  process wishes  to report  status.  The
     wait3 subroutine with the NOHANG option not set is equiv-
     alent to the wait system call.

     Note:  In the AIX  Operating System, the rusage parameter
     is unused.

     For  a  list  of  termination statuses  or  signals,  see
     "signal."  The  following   status  values  have  special
     meaning:

     o   A 0 status indicates normal termination.

     o   A status of 0177 indicates a stopped process that has
         not terminated and can be restarted.  For more infor-
         mation, see "ptrace."

     o   If the 0200 bit of the termination status is set, the
         process produces a core image of the process.

     If a  parent process  terminates without waiting  for its
     child processes to  terminate, the initialization process
     (init) inherits the child processes.

     When  a process  receives a  signal while  waiting for  a
     child process to terminate,  the wait3 system call allows
     the  signal to  be  handled,  then automatically  resumes
     waiting for the child process to terminate.

Return Value

     The wait3 subroutine returns the  process ID of the child
     when a child process has stopped or exited since the last
     call to wait  or wait3.  When there  are child processes,
     but none  of them have  stopped or exited since  the last
     call to wait or wait3, this subroutine returns a value of
     0.  A  value of -1  is returned  when there are  no child
     processes that the calling process has not already waited
     for.  In this case, errno is set to indicate the error.

Diagnostics

     The wait3  subroutine fails  if one or  more of  the fol-
     lowing is true:

     ECHILD     The  calling  process  has no  existing  child
                processes not yet waited for.

     EFAULT     The  status  parameter  points to  an  illegal
                address.

Related Information

     In this book:  "exit, _exit" and "wait."