wait(2)                                                             wait(2)




 NAME
      wait, waitpid - wait for child process to stop or terminate

 SYNOPSIS
      #include <sys/types.h>   OH #include <sys/wait.h>

      pid_t wait(int *stat_loc);

      pid_t waitpid(pid_t pid, int *stat_loc, int options);

 DESCRIPTION
      The wait() and waitpid() functions allow the calling process to obtain
      status information pertaining to one of its 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 wait() function will suspend execution of the calling  process
      until status information for one of its terminated child processes is
      available, or until delivery of a signal whose action is either to
      execute a signal-catching function or to terminate the process. If
      status information is available prior to the call to wait(), return
      will be immediate.

      The waitpid() function will behave identically to wait(), if the pid
      argument is (pid_t)-1 and the options argument is  0. Otherwise, its
      behaviour will be modified by the values of the pid and options
      arguments.

      The pid argument specifies a set of child  processes for which status
      is requested. The waitpid() function will only return the status of a
      child process from this set:

           o  If pid is equal to (pid_t)-1, status is requested for any
              child process. In this respect, waitpid() is then equivalent
              to wait().

           o  If pid is greater  than  0,  it  specifies  the process  ID of
              a single child process for which status is requested.

           o  If pid is 0, status is requested for any  child process whose
              process group ID is equal to that of the calling process.

           o  If pid is less than (pid_t)-1, status is requested for any
              child process whose process group ID is equal to the absolute
              value of pid.

           The options argument is constructed from the bitwise-inclusive OR
           of zero or more of the following flags, defined in the header
           <sys/wait.h>.



 Hewlett-Packard Company            - 1 -    HP-UX Release 10.20:  July 1996






 wait(2)                                                             wait(2)




                WCONTINUED               The waitpid() function will report
                                         the status of any continued child
                                         process specified by pid whose
                                         status has not been reported since
                                         it continued from a job control
                                         stop.

                WNOHANG                  The waitpid() function will not
                                         suspend execution of the calling
                                         process if status is not
                                         immediately available for one of
                                         the child processes specified by
                                         pid.

                WUNTRACED                The status of any child processes
                                         specified by pid that are stopped,
                                         and whose status has not yet been
                                         reported since they stopped, will
                                         also be reported to the requesting
                                         process.

           If the calling process has SA_NOCLDWAIT set or has SIGCHLD set to
           SIG_IGN, and the process has no unwaited for children that were
           transformed into zombie processes, it will block until all of its
           children terminate, and wait() and waitpid() will fail and set
           errno to ECHILD.

           If wait() or waitpid() return because the status of a child
           process is available, these functions will 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
           will be stored in the location pointed to by stat_loc.  If and
           only if the status returned is from a terminated child process
           that returned 0 from main() or passed 0 as the status argument to
           _exit() or exit(), the value stored at the location pointed to by
           stat_loc will be 0. Regardless of its value, this information may
           be interpreted using the following macros, which are defined in
           <sys/wait.h> and evaluate to integral expressions; the stat_val
           argument is the integer value pointed to by stat_loc.

                WIFEXITED(stat_val)      Evaluates to a non-zero value if
                                         status was returned for a child
                                         process that terminated normally.
                                         WEXITSTATUS(stat_val) If the value
                                         of WIFEXITED(stat_val) is non-zero,
                                         this macro evaluates to the
                                         low-order 8 bits of the status
                                         argument that the child process
                                         passed to _exit() or exit(), or the
                                         value the child  process returned
                                         from main().



 Hewlett-Packard Company            - 2 -    HP-UX Release 10.20:  July 1996






 wait(2)                                                             wait(2)




                WIFSIGNALED(stat_val)    Evaluates to 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>).

                WTERMSIG(stat_val)       If the value of
                                         WIFSIGNALED(stat_val) is non-zero,
                                         this macro evaluates to the number
                                         of the signal that caused the
                                         termination of the child process.
                                         WIFSTOPPED(stat_val) Evaluates to a
                                         non-zero value if status was
                                         returned for a child process that
                                         is currently stopped.

                WSTOPSIG(stat_val)       If the value of
                                         WIFSTOPPED(stat_val) is non-zero,
                                         this macro evaluates to the number
                                         of the signal that caused the child
                                         process to stop.

                WIFCONTINUED(stat_val)   Evaluates to a non-zero value if
                                         status was returned for a child
                                         process that has continued from a
                                         job control stop.

           If the information pointed to by stat_loc was stored by a call to
           waitpid() that specified the WUNTRACED flag and did not specify
           the WCONTINUED flag, exactly one of the macros
           WIFEXITED(*stat_loc), WIFSIGNALED(*stat_loc), and
           WIFSTOPPED(*stat_loc) will evaluate to a non-zero value.

           If the information pointed to by stat_loc was stored by a call to
           waitpid() that specified the WUNTRACED and WCONTINUED flags,
           exactly one of the macros WIFEXITED(*stat_loc),
           WIFSIGNALED(*stat_loc), WIFSTOPPED(*stat_loc), and WIFCONTINUED
           (*stat_loc) will evaluate to a non-zero value.

           If the information pointed to by stat_loc was stored by a call to
           waitpid() that did not specify the WUNTRACED or WCONTINUED flags,
           or by a call to the wait() function, exactly one of the  macros
           WIFEXITED(*stat_loc) and WIFSIGNALED(*stat_loc) will evaluate to
           a non-zero value.

           If the information pointed to by stat_loc was stored by a call to
           waitpid() that did not specify the WUNTRACED flag and specified
           the WCONTINUED flag, by a call to the wait() function, exactly
           one of the macros WIFEXITED(*stat_loc), WIFSIGNALED(*stat_loc),
           and WIFCONTINUED(*stat_loc) will evaluate to a non-zero value.




 Hewlett-Packard Company            - 3 -    HP-UX Release 10.20:  July 1996






 wait(2)                                                             wait(2)




           There may be additional implementation-dependent circumstances
           under which wait() or waitpid() report status. This will 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-dependent.

           If a parent process terminates without waiting for all of its
           child processes to terminate, the remaining child processes will
           be assigned a new parent process ID corresponding to an
           implementation-dependent system process.

 RETURN VALUE
      If wait() or waitpid() returns because the status of a child process
      is available, these functions will return a value equal to the process
      ID of the  child process for which status is reported. If wait() or
      waitpid() returns due to the delivery of a signal to the calling
      process, -1 will be returned and errno will be set to EINTR.  If
      waitpid() was invoked with WNOHANG 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 will be
      returned. Otherwise, (pid_t)-1 will be returned, and errno will be set
      to indicate the error.

 ERRORS
      The wait() function will fail if:

      [ECHILD]       The calling process has no existing unwaited-for child
                     processes.

      [EINTR]        The function was interrupted by a signal. The value of
                     the location pointed to by stat_loc is undefined.

      The waitpid() function will fail if:

      [ECHILD]       The process or process group specified by pid does not
                     exist or is not a child of the calling process.

      [EINTR]        The function was interrupted by a signal. The value of
                     the location pointed to by stat_loc is undefined.

      [EINVAL]       The options argument is not valid.

 SEE ALSO
      exec, exit(), fork(), wait3(), waitid(), <sys/types.h>, <sys/wait.h>.

 CHANGE HISTORY
      First released in Issue 1.

      Derived from Issue 1 of the SVID.




 Hewlett-Packard Company            - 4 -    HP-UX Release 10.20:  July 1996






 wait(2)                                                             wait(2)




 Issue 4
      The following change is incorporated for alignment with the ISO
      POSIX-1 standard:

           o  Text describing conditions under which 0 will be returned when
              WNOHUNG is set in options is added to the RETURN VALUE
              section.

      Other changes are incorporated as follows:

           o  The  header <sys/types.h> is now marked as optional (OH); this
              header need not be included on XSI-conformant systems.

           o  Error return values throughout the  DESCRIPTION and  RETURN
              VALUE sections are changed to show the proper casting (that
              is, (pid_t)-1.

           o  The words "If the implementation supports job control" are
              removed from the description of WUNTRACED.  This is because
              job control is defined as mandatory for Issue 4 conforming
              implementations.

 Issue 4, Version 2
      The following changes are incorporated in the DESCRIPTION for X/OPEN
      UNIX conformance:

           o  The WCONTINUED options flag and the WIFCONTINUED(stat_val)
              macro are added.

           o  Text following the list of options flags explains the
              implications of setting the SA_NOCLDWAIT signal flag, or
              setting SIGCHILD to SIG_IGN.

           o  Text following the list of macros, which explains what macros
              return non-zero values in certain cases, is expanded and the
              value of the WCONTINUED flag on the previous call to waitpid()
              is taken into account.

















                                    - 5 -         Formatted:  April 25, 2001






 wait(2)                                                             wait(2)




                                 HP-UX EXTENSIONS



 NAME
      wait(), waitpid() - wait for child or traced process to stop or
      terminate

 DESCRIPTION
 wait()
      If a parent process terminates without waiting for its child processes
      to terminate, the parent process ID of each child process is set to 1.
      This means the initialization process inherits the child processes.

           WCOREDUMP(*stat_loc)     If the value of WIFSIGNALED(*stat_loc)
                                    is nonzero, this macro evaluates to a
                                    nonzero value if a "core image" was
                                    produced (see signal(5)).

 waitpid()
           WNOWAIT                  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.

           WUNTRACED                If and only if this flag is set,
                                    waitpid() or wait3() returns information
                                    on child or attached processes that are
                                    stopped but not traced (with ptrace(2))
                                    because they received a SIGTTIN,
                                    SIGTTOU, SIGTSTP, or SIGSTOP 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 status has not yet been
                                    reported.

 Notes
      Earlier HP-UX versions documented the bit encodings of the status
      returned by wait() rather than the macros WCOREDUMP, WEXITSTATUS,
      WIFEXITED, WIFSIGNALED, WIFSTOPPED, WSTOPSIG, and WTERMSIG.
      Applications using those bit encodings will continue to work
      correctly.  However, new applications should use the macros for
      maximum portability.

      In earlier HP-UX versions, the macros WIFEXITED, WIFSIGNALED, and
      WIFSTOPPED have the same definitions as the correspondingly named
      macros in the BSD 4.3 and earlier systems. Existing applications that



 Hewlett-Packard Company            - 1 -    HP-UX Release 10.20:  July 1996






 wait(2)                                                             wait(2)




      depend on these definitions will continue to work correctly. However,
      if the application is recompiled, the feature test macro _BSD must be
      turned on for the compilation so that the old definitions of these
      macros are obtained. New definitions of these macros are in effect by
      default. The only difference between the old and new definitions is
      the type of the argument. Type union wait is used in the BSD
      definitions while type int is used in the default definitions.

 ERRORS
      If wait() or waitpid() fails, errno is set to one of the following
      values.

           [EACCES]                 The calling process of waitpid() does
                                    not have read permission to the pid.

           [EFAULT]                 stat_loc points to an illegal address.
                                    The reliable detection of this error is
                                    implementation-dependent.

 WARNINGS
      The behavior of wait() and waitpid() is affected if the SIGCLD signal
      is set to SIG_IGN.  See the WARNINGS section of signal(5).  Signal
      handlers that cause system calls to be restarted can affect the EINTR
      condition described above (see bsdproc(2), sigaction(2), and
      sigvector(2)).

 AUTHOR
      wait(), waitpid(), and wait3() were developed by HP, AT&T, and the
      University of California, Berkeley.

 SEE ALSO
      Exit conditions ($?) in sh(1); exec(2), exit(2), fork(2), pause(2),
      ptrace(2), signal(5).

 STANDARDS CONFORMANCE
      wait(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

      waitpid(): AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1
















 Hewlett-Packard Company            - 2 -    HP-UX Release 10.20:  July 1996