pcntl_waitid
Waits for a child process to change state
Description
bool pcntl_waitid(
int $idtype
= P_ALL,
int $id
= null,
array &$info
= [],
int $flags
= WEXITED
)
Unless WNOHANG
flag is passed, the calling process will
become blocked until an error occurs, or status information becomes
available that satisfies all of the following:
-
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
flags
argument.
If matching status information is available prior to the call to
pcntl_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.
Note:
This documentation covers the POSIX specification of the
waitid
function, along with some additional parameters
specific to implementations on Linux, NetBSD and FreeBSD. Please see your
system's waitid(2)
man page for specific details as to
how waitid
works on your system.
Parameters
-
idtype
-
id
-
The
idtype
and id
arguments
are used to specify which children to wait for.
POSIX standard idtype
and id
arguments
If idtype is P_ALL |
wait for any child process, id is ignored.
|
If idtype is P_PID |
wait for the child with process ID equal to id .
|
If idtype is P_PGID |
wait for any child with process group ID equal to id .
|
Linux specific idtype
and id
arguments
If idtype is P_PIDFD (since Linux 5.4) |
wait for the child referred to by the PID file descriptor specified in
id .
(See the Linux pidfd_open(2) man page for further
information on PID file descriptors.)
|
NetBSD and FreeBSD specific idtype
and id
arguments
If idtype is P_UID
|
wait for processes whose effective user ID is equal to
id .
|
If idtype is P_GID
|
wait for processes whose effective group ID is equal to
id .
|
If idtype is P_SID
|
wait for processes whose session ID is equal to
id .
If the child process started its own session, its session ID will be
the same as its process ID. Otherwise the session ID of a child
process will match the caller's session ID.
|
FreeBSD specific idtype
and id
arguments
If idtype is P_JAILID
|
wait for processes within a jail whose jail identifier is equal to
id .
|
-
info
-
The info
parameter is set to an array
containing information about the signal.
info
array may contain the following keys:
signo
: Signal number
errno
: System error number
code
: Signal code
status
: Exit value or signal
pid
: Sending process ID
uid
: Real user ID of sending process
utime
: User time consumed
stime
: System time consumed
-
flags
-
The value of flags
is the value of zero or more of
the following constants OR'ed together:
possible values for 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
pcntl_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
info 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
pcntl_waitid with the
WNOWAIT flag set.
|
Return Values
pcntl_waitid returns true
if
WNOHANG
was specified and status is not available for
any process specified by idtype
and
id
.
pcntl_waitid returns true
due to the change of state
of one of its children.
Otherwise, false
is returned and pcntl_get_last_error
can be used to get the errno
error number.
Note:
Once an errno
error number has been obtained,
pcntl_strerror can be used to get the text message
associated with it.
Errors/Exceptions
Error number (errno
) values
ECHILD |
The calling process has no existing unwaited-for child processes.
|
EINTR |
pcntl_waitid was interrupted by a signal.
|
EINVAL |
An invalid value was specified for flags , or
idtype and id specify an
invalid set of processes.
|
See Also
- pcntl_waitpid
- pcntl_wait
- pcntl_fork
- pcntl_signal
- pcntl_wifexited
- pcntl_wifstopped
- pcntl_wifsignaled
- pcntl_wexitstatus
- pcntl_wtermsig
- pcntl_wstopsig