unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

WAIT(2V)                                                              WAIT(2V)



NAME
       wait, wait3, wait4, waitpid, WIFSTOPPED, WIFSIGNALED, WIFEXITED, WEXIT-
       STATUS, WTERMSIG, WSTOPSIG - wait for process  to  terminate  or  stop,
       examine returned status

SYNOPSIS
       #include <&lt;sys/wait.h>&gt;

       int wait(statusp)
       int *statusp;

       int waitpid(pid, statusp, options)
       int pid;
       int *statusp;
       int options;

       #include <&lt;sys/time.h>&gt;
       #include <&lt;sys/resource.h>&gt;

       int wait3(statusp, options, rusage)
       int *statusp;
       int options;
       struct rusage *rusage;

       int wait4(pid, statusp, options, rusage)
       int pid;
       int *statusp;
       int options;
       struct rusage *rusage;

       WIFSTOPPED(status)
       int status;

       WIFSIGNALED(status)
       int status;

       WIFEXITED(status)
       int status

       WEXITSTATUS(status)
       int status

       WTERMSIG(status)
       int status

       WSTOPSIG(status)
       int status

SYSTEM V SYNOPSIS
       #include <&lt;sys/types.h>&gt;
       #include <&lt;sys/wait.h>&gt;

       pid_t wait(statusp)
       int *statusp;

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

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 statusp 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 location pointed to by statusp.
       It  indicates  the cause of termination and other information about the
       terminated process in the following manner:

              o  If the first byte (the low-order 8 bits) are equal  to  0177,
                 the  child  process  has stopped.  The next byte contains the
                 number of the signal that caused the process  to  stop.   See
                 ptrace(2) and sigvec(2).

              o  If the first byte (the low-order 8 bits) are non-zero and are
                 not equal to 0177, the child process terminated due to a sig-
                 nal.   The  low-order 7 bits contain the number of the signal
                 that terminated the process.  In addition, if  the  low-order
                 seventh  bit  (that is, bit 0200) is set, a ``core image'' of
                 the process was produced (see sigvec(2)).

              o  Otherwise, the child process terminated  due  to  a  call  to
                 exit(2V).  The next byte contains the low-order 8 bits of the
                 argument that the child process passed to exit().

       waitpid() behaves identically to wait() if pid has a value  of  -1  and
       options  has  a value of zero.  Otherwise, the behavior of waitpid() is
       modified by the values of pid and options as follows:

       pid specifies a set of child processes for which status  is  requested.
       waitpid() only returns the status of a child process from this set.

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

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

              o  If pid is equal to zero, status is requested  for  any  child
                 process  whose process group ID is equal to that of the call-
                 ing process.

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

       options is constructed from the bitwise inclusive OR of zero or more of
       the following flags, defined in the header <&lt;sys/wait.h>&gt;:

              WNOHANG
                     waitpid()  does  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, are also reported to the requesting
                     process.

       wait3() is an alternate interface 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  parame-
       ter  is used to indicate the call should not block if there are no pro-
       cesses that have status to report (WNOHANG), and/or  that  children  of
       the  current  process that are stopped due to a SIGTTIN, SIGTTOU, SIGT-
       STP, 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.   (This
       information is currently not available for stopped processes.)

       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 ORing the two values.

       wait4()  is  another alternate interface.  With a pid argument of 0, it
       is equivalent to wait3().  If pid has a  nonzero  value,  then  wait4()
       returns status only for the indicated process ID, but not for any other
       child processes.

       WIFSTOPPED, WIFSIGNALED, WIFEXITED, WEXITSTATUS, WTERMSIG, and WSTOPSIG
       are  macros that take an argument status, of type `int', as returned by
       wait(), wait3(), or wait4().  WIFSTOPPED evaluates to true (1) when the
       process  for which the wait() call was made is stopped, or to false (0)
       otherwise.  If WIFSTOPPED(status) is non-zero,  WSTOPSIG  evaluates  to
       the  number  of  the  signal  that  caused  the  child process to stop.
       WIFSIGNALED evaluates to true when the process was  terminated  with  a
       signal.   If WIFSIGNALED(status) is non-zero, WTERMSIG evaluates to the
       number of the signal that caused the termination of the child  process.
       WIFEXITED  evaluates  to  true  when  the  process  exited  by using an
       exit(2V) call.  If WIFEXITED(status) is non-zero, WEXITSTATUS evaluates
       to  the low-order byte of the argument that the child process passed to
       _exit() (see exit(2V)) or exit(3),  or  the  value  the  child  process
       returned from main() (see execve(2V)).

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

       If a parent process terminates witout waiting for all of its child pro-
       cesses  to  terminate,  the  remaining child processes are assigned the
       parent process ID of 1, corresponding to init(8).

RETURN VALUES
       If wait() or waitpid() returns due to a  stopped  or  terminated  child
       process,  the  process  ID  of  the  child  is  returned to the calling
       process.  Otherwise, a value of -1 is returned  and  errno  is  set  to
       indicate the error.

       If  wait()  or  waitpid() return due to the delivery of a signal to the
       calling process, a value of -1 is returned and errno is set  to  EINTR.
       If  waitpid()  function 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, a value of  zero  is  returned.   Otherwise,  a  value  of  -1  is
       returned, and errno is set to indicate the error.

       wait3()  and  wait4() return 0 if WNOHANG is specified and there are no
       stopped or exited children, and return the  process  ID  of  the  child
       process  if  they  return due to a stopped or terminated child process.
       Otherwise, they return a value of -1 and  set  errno  to  indicate  the
       error.

ERRORS
       wait(),  wait3(), or wait4() 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         statusp or rusage points to an illegal address.

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

       waitpid() may set errno to:

       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 statusp is undefined.

       EINVAL         The value of options is not valid.

       wait(), wait3(), and wait4() 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(2) and  siginterrupt(3V)).   sig-
       nal(3V),  in  the System V compatibility library, sets this bit for any
       signal it catches.

SEE ALSO
       exit(2V), fork(2V), getrusage(2), ptrace(2), sigvec(2), pause(3V), sig-
       interrupt(3V), signal(3V), times(3V)

NOTES
       If  a  parent  process  terminates without waiting on its children, the
       initialization process (process ID = 1) inherits the children.

       wait(), wait3(), and wait4() are 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.

       Previous SunOS releases used union wait *statusp and union wait  status
       in  place  of int *statusp and intstatus.  The union contained a member
       w_status that could be treated in the same way as status.

       Other members of the wait union could be used to extract this  informa-
       tion more conveniently:

              o  If  the  w_stopval  member  had the value WSTOPPED, the child
                 process had stopped; the value of the  w_stopsig  member  was
                 the signal that stopped the process.

              o  If  the w_termsig member was non-zero, the child process ter-
                 minated due to a signal; the value of  the  w_termsig  member
                 was the number of the signal that terminated the process.  If
                 the w_coredump member was non-zero, a core dump was produced.

              o  Otherwise, the child process terminated  due  to  a  call  to
                 exit().   The value of the w_retcode member was the low-order
                 8 bits of the argument  that  the  child  process  passed  to
                 exit().

       union  wait  is obsolete in light of the new specifications provided by
       IEEE Std 1003.1-1988 and endorsed by SVID89 and  XPG3.   SunOS  Release
       4.1  supports union wait for backward compatibility, but it will disap-
       pear in a future release.



                                21 January 1990                       WAIT(2V)