.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "WAITID" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" waitid 
.SH 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.
.SH NAME
waitid \- wait for a child process to change state
.SH SYNOPSIS
.LP
\fB#include <sys/wait.h>
.br
.sp
int waitid(idtype_t\fP \fIidtype\fP\fB, id_t\fP \fIid\fP\fB, siginfo_t
*\fP\fIinfop\fP\fB, int\fP
\fIoptions\fP\fB); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIwaitid\fP() function shall suspend the calling thread until
one child of the process containing the calling thread
changes state. It records the current state of a child in the structure
pointed to by \fIinfop\fP. If a child process changed
state prior to the call to \fIwaitid\fP(), \fIwaitid\fP() shall return
immediately. If more than one thread is suspended in \fIwait\fP()
or \fIwaitpid\fP() waiting for termination
of the same process, exactly one thread shall return the process status
at the time of the target process termination.
.LP
The \fIidtype\fP and \fIid\fP arguments are used to specify which
children \fIwaitid\fP() waits for.
.LP
If \fIidtype\fP is P_PID, \fIwaitid\fP() shall wait for the child
with a process ID equal to (\fBpid_t\fP)\fIid\fP.
.LP
If \fIidtype\fP is P_PGID, \fIwaitid\fP() shall wait for any child
with a process group ID equal to
(\fBpid_t\fP)\fIid\fP.
.LP
If \fIidtype\fP is P_ALL, \fIwaitid\fP() shall wait for any children
and \fIid\fP is ignored.
.LP
The \fIoptions\fP argument is used to specify which state changes
\fIwaitid\fP() shall wait for. It is formed by OR'ing
together one or more of the following flags:
.TP 7
WEXITED
Wait for processes that have exited.
.TP 7
WSTOPPED
Status shall be returned for any child that has stopped upon receipt
of a signal.
.TP 7
WCONTINUED
Status shall be returned for any child that was stopped and has been
continued.
.TP 7
WNOHANG
Return immediately if there are no children to wait for.
.TP 7
WNOWAIT
Keep the process whose status is returned in \fIinfop\fP in a waitable
state. This shall not affect the state of the process;
the process may be waited for again after this call completes.
.sp
.LP
The application shall ensure that the \fIinfop\fP argument points
to a \fBsiginfo_t\fP structure. If \fIwaitid\fP() returns
because a child process was found that satisfied the conditions indicated
by the arguments \fIidtype\fP and \fIoptions\fP, then
the structure pointed to by \fIinfop\fP shall be filled in by the
system with the status of the process. The \fIsi_signo\fP
member shall always be equal to SIGCHLD.
.SH RETURN VALUE
.LP
If WNOHANG was specified and there are no children to wait for, 0
shall be returned. If \fIwaitid\fP() returns due to the
change of state of one of its children, 0 shall be returned. Otherwise,
-1 shall be returned and \fIerrno\fP set to indicate the
error.
.SH ERRORS
.LP
The \fIwaitid\fP() function shall fail if:
.TP 7
.B ECHILD
The calling process has no existing unwaited-for child processes.
.TP 7
.B EINTR
The \fIwaitid\fP() function was interrupted by a signal.
.TP 7
.B EINVAL
An invalid value was specified for \fIoptions\fP, or \fIidtype\fP
and \fIid\fP specify an invalid set of processes.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
None.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIexec\fP(), \fIexit\fP(), \fIwait\fP(), the Base Definitions
volume of IEEE\ Std\ 1003.1-2001, \fI<sys/wait.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 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 .