mirror of https://github.com/mkerrisk/man-pages
122 lines
4.0 KiB
Plaintext
122 lines
4.0 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "WAITID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" waitid
|
|
.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 .
|