PROLOG

       This  manual  page  is part of the POSIX Programmer's Manual.  The Linux implementation of
       this interface may differ (consult the corresponding Linux  manual  page  for  details  of
       Linux behavior), or the interface may not be implemented on Linux.

NAME

       waitid — wait for a child process to change state

SYNOPSIS

       #include <sys/wait.h>

       int waitid(idtype_t idtype, id_t id, siginfo_t *infop, int options);

DESCRIPTION

       The   waitid()  function  shall  obtain  status  information  (see  Section  2.13,  Status
       Information) pertaining to termination,  stop,  and/or  continue  events  in  one  of  the
       caller's child processes.

       The  waitid()  function  shall  cause  the calling thread to become blocked until an error
       occurs or status information becomes available to the calling thread that satisfies all of
       the following properties (``matching status information''):

        *  The  status  information  is  from  one  of  the  child  processes in the set of child
           processes specified by the idtype and id arguments.

        *  The state change in the status information matches one of the state change  flags  set
           in the options argument.

       If matching status information is available prior to the call to waitid(), return shall be
       immediate. If matching status information is available for two or  more  child  processes,
       the order in which their status is reported is unspecified.

       As  described  in  Section  2.13,  Status  Information, the waitid() function consumes the
       status information it obtains unless the WNOWAIT flag is set in the options argument.

       The behavior when multiple threads are  blocked  in  wait(),  waitid(),  or  waitpid()  is
       described in Section 2.13, Status Information.

       The  waitid()  function  shall  record  the  obtained  status information in the structure
       pointed to by infop.  The fields of the structure pointed to by infop shall be  filled  in
       as described under ``Pointer to a Function'' in Section 2.4.3, Signal Actions.

       The idtype and id arguments are used to specify which children waitid() waits for.

       If  idtype  is  P_PID,  waitid()  shall  wait  for  the  child  with a process ID equal to
       (pid_t)id.

       If idtype is P_PGID, waitid() shall wait for any child with a process group  ID  equal  to
       (pid_t)id.

       If idtype is P_ALL, waitid() shall wait for any children and id is ignored.

       The options argument is used to specify which state changes waitid() shall wait for. It is
       formed by OR'ing together the following flags:

       WCONTINUED  Status shall be returned for any continued child process whose  status  either
                   has  not  been reported since it continued from a job control stop or has been
                   reported only by calls to waitid() with the WNOWAIT flag set.

       WEXITED     Wait for processes that have exited.

       WNOHANG     Do not hang if no status is available; return immediately.

       WNOWAIT     Keep the process whose status is returned in infop in a waitable  state.  This
                   shall not affect the state of the process; the process may be waited for again
                   after this call completes.

       WSTOPPED    Status shall be returned for any child that has  stopped  upon  receipt  of  a
                   signal,  and whose status either has not been reported since it stopped or has
                   been reported only by calls to waitid() with the WNOWAIT flag set.

       Applications shall specify at least one of the flags WEXITED, WSTOPPED, or  WCONTINUED  to
       be OR'ed in with the options argument.

       The  application  shall ensure that the infop argument points to a siginfo_t structure. If
       waitid() returns because a child process was found that satisfied the conditions indicated
       by  the  arguments  idtype  and  options,  then the structure pointed to by infop shall be
       filled in by the system with the status of the process; the si_signo member shall  be  set
       equal  to  SIGCHLD.   If  waitid() returns because WNOHANG was specified and status is not
       available for any process specified by idtype and id, then the si_signo and si_pid members
       of  the structure pointed to by infop shall be set to zero and the values of other members
       of the structure are unspecified.

RETURN VALUE

       If WNOHANG was specified and status is not available for any process specified  by  idtype
       and  id, 0 shall be returned. If waitid() returns due to the change of state of one of its
       children, 0 shall be returned. Otherwise, -1 shall be returned and errno set  to  indicate
       the error.

ERRORS

       The waitid() function shall fail if:

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

       EINTR  The waitid() function was interrupted by a signal.

       EINVAL An invalid value was specified for options, or idtype and id specify an invalid set
              of processes.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       Calls to waitid() with idtype equal to P_ALL will  collect  information  about  any  child
       process.  This  may  result  in interactions with other interfaces that may be waiting for
       their own children (such as by use of system()).  For this reason it is  recommended  that
       portable  applications  not  use waitid() with idtype of P_ALL. See also APPLICATION USAGE
       for wait().

       As  specified  in  Consequences  of  Process  Termination,  if  the  calling  process  has
       SA_NOCLDWAIT  set  or  has SIGCHLD set to SIG_IGN, then the termination of a child process
       will not cause status information to become available  to  a  thread  blocked  in  wait(),
       waitid(),  or  waitpid().  Thus, a thread blocked in one of the wait functions will remain
       blocked unless some other condition causes the thread to  resume  execution  (such  as  an
       [ECHILD] failure due to no remaining children in the set of waited-for children).

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       Section 2.4.3, Signal Actions, Section 2.13, Status Information, exec, exit(), wait()

       The Base Definitions volume of POSIX.1‐2017, <signal.h>, <sys_wait.h>

COPYRIGHT

       Portions  of  this  text  are  reprinted  and  reproduced in electronic form from IEEE Std
       1003.1-2017, Standard for Information Technology -- Portable  Operating  System  Interface
       (POSIX),  The  Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by
       the Institute of Electrical and Electronics Engineers, Inc and The  Open  Group.   In  the
       event  of  any  discrepancy  between this version and the original IEEE and The Open Group
       Standard, the original IEEE and The Open Group  Standard  is  the  referee  document.  The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

       Any  typographical  or  formatting errors that appear in this page are most likely to have
       been introduced during the conversion of the source files to man page  format.  To  report
       such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .