From 0fb1db3c6c086b76e5bcd455b887d76cfa4efcb2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladimir=20Vrzi=C4=87?= Date: Mon, 1 Jul 2024 12:31:55 +0200 Subject: [PATCH 01/12] Added function pcntl_waitid --- reference/pcntl/functions/pcntl-waitid.xml | 308 +++++++++++++++++++++ reference/pcntl/versions.xml | 1 + 2 files changed, 309 insertions(+) create mode 100644 reference/pcntl/functions/pcntl-waitid.xml diff --git a/reference/pcntl/functions/pcntl-waitid.xml b/reference/pcntl/functions/pcntl-waitid.xml new file mode 100644 index 000000000000..da76e726cfb7 --- /dev/null +++ b/reference/pcntl/functions/pcntl-waitid.xml @@ -0,0 +1,308 @@ + + + + + pcntl_waitid + Waits for a child process to change state + + + + &reftitle.description; + + boolpcntl_waitid + intidtypeP_ALL + intidnull + arraysiginfo[] + intflagsWEXITED + + + Obtains status information pertaining to termination, stop, and/or continue events in one of the caller's child processes. + + + + 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 process_id 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. + + + + + 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. + + + + + + &reftitle.parameters; + + + + idtype + id + + + The idtype and id arguments are used to specify which children to wait for. + + + + POSIX standard <parameter>idtype</parameter> and <parameter>id</parameter> 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 <parameter>idtype</parameter> and <parameter>id</parameter> 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 <parameter>idtype</parameter> and <parameter>id</parameter> 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 <parameter>idtype</parameter> and <parameter>id</parameter> arguments + + + + If idtype is P_JAILID + + wait for processes within a jail whose jail identifier is equal to id. + + + + +
+ + + + + siginfo + + + The siginfo parameter is set to an array containing + information about the signal. + + + siginfo 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 <parameter>flags</parameter> + + + + 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 siginfo 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. + + + + +
+ + + + + + + + + &reftitle.returnvalues; + + 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 user can use pcntl_get_last_error to get the errno error number. + + + + + Once an errno error number has been obtained, pcntl_strerror can be used to get the text message associated with it. + + + + + + &reftitle.errors; + + + Error number (<literal>errno</literal>) 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 options, or idtype and id specify an invalid set of processes. + + + + +
+ + + + + &reftitle.seealso; + + + pcntl_waitpid + pcntl_wait + pcntl_fork + pcntl_signal + pcntl_wifexited + pcntl_wifstopped + pcntl_wifsignaled + pcntl_wexitstatus + pcntl_wtermsig + pcntl_wstopsig + + + + + + diff --git a/reference/pcntl/versions.xml b/reference/pcntl/versions.xml index f785a3edd488..b99f1190e4db 100644 --- a/reference/pcntl/versions.xml +++ b/reference/pcntl/versions.xml @@ -23,6 +23,7 @@ + From d3f1466eb176cbb837d0f1a92556d42c74ce0d41 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladimir=20Vrzi=C4=87?= Date: Mon, 1 Jul 2024 12:58:05 +0200 Subject: [PATCH 02/12] Added pcntl constants used by waitid --- reference/pcntl/constants.xml | 126 ++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) diff --git a/reference/pcntl/constants.xml b/reference/pcntl/constants.xml index e3fed42bd42a..aab5cdd818cc 100644 --- a/reference/pcntl/constants.xml +++ b/reference/pcntl/constants.xml @@ -42,6 +42,36 @@ + + + WEXITED + (int) + + + + + + + + + WSTOPPED + (int) + + + + + + + + + WNOWAIT + (int) + + + + + + @@ -1568,6 +1598,102 @@ + + First argument to <literal>waitid</literal> (<literal>idtype</literal>) + + + P_ALL + (int) + + + + Select any children. + + + + + + P_PID + (int) + + + + Select by process ID. + + + + + + P_PGID + (int) + + + + Select by process group ID. + + + + + + P_PIDFD + (int) + + + + Select by PID file descriptor. + Specific to Linux (since Linux 5.4). + + + + + + P_UID + (int) + + + + Select by effective user ID. + Specific to NetBSD and FreeBSD. + + + + + + P_GID + (int) + + + + Select by effective group ID. + Specific to NetBSD and FreeBSD. + + + + + + P_SID + (int) + + + + Select by session ID. + Specific to NetBSD and FreeBSD. + + + + + + P_JAILID + (int) + + + + Select by jail identifier. + Specific to FreeBSD. + + + +