ext/pcntl: Added new function pcntl_waitid

to obtain status information pertaining termination, stop, and/or
continue events in one the caller's child processes.

close GH-14617

Author: vrza

NEWS

@@ -190,6 +190,7 @@ PHP                                                                        NEWS
   . Added pcntl_getqos_class/pcntl_setqos_class for macOs. (David Carlier)
   . Added SIGCKPT/SIGCKPTEXIT constants for DragonFlyBSD. (David Carlier)
   . Added FreeBSD's SIGTRAP handling to pcntl_siginfo_to_zval. (David Carlier)
+  . Added POSIX pcntl_waitid. (Vladimir Vrzić)
 
 - PCRE:
   . Upgrade bundled pcre2lib to version 10.43. (nielsdos)

UPGRADING

@@ -594,6 +594,8 @@ PHP 8.4 UPGRADE NOTES
   . Added pcntl_getcpu to get the cpu id from where the current process runs.
   . Added pcntl_getqos_class to get the QoS level (aka performance and related
     energy consumption) of the current process and pcntl_setqos_class to set it.
+  . Added pcntl_waitid to obtain status information pertaining to termination, stop,
+    and/or continue events in one of the caller's child processes.
 
 - PDO_PGSQL:
   . Added Pdo\Pgsql::setNoticeCallback() to allow a callback to be triggered on
@@ -780,7 +782,18 @@ PHP 8.4 UPGRADE NOTES
   . QosClass::Utility (macOs only).
   . SIGCKPT (DragonFlyBSD only).
   . SIGCKPTEXIT (DragonFlyBSD only).
-
+  . WEXITED.
+  . WSTOPPED.
+  . WNOWAIT.
+  . P_ALL.
+  . P_PID.
+  . P_PGID.
+  . P_PIDFD (Linux only).
+  . P_UID (NetBSD only).
+  . P_GID (NetBSD only).
+  . P_SID (NetBSD only).
+  . P_JAILID (FreeBSD only).
+  
 - Standard:
   . PHP_ROUND_CEILING.
   . PHP_ROUND_FLOOR.

ext/pcntl/config.m4

@@ -24,8 +24,16 @@ if test "$PHP_PCNTL" != "no"; then
     unshare
     wait3
     wait4
+    waitid
   ]))
 
+  AC_CHECK_FUNCS([WIFCONTINUED],,
+    [AC_CHECK_DECL([WIFCONTINUED], [AC_DEFINE([HAVE_WIFCONTINUED], [1])],,
+      [#include <sys/wait.h>])])
+
+  AC_CHECK_DECLS([WCONTINUED, WEXITED, WSTOPPED, WNOWAIT, P_ALL, P_PIDFD, P_UID, P_JAILID],,,
+    [#include <sys/wait.h>])
+
   dnl if unsupported, -1 means automatically ENOSYS in this context
   AC_CACHE_CHECK([if sched_getcpu is supported], [php_cv_func_sched_getcpu],
   [AC_RUN_IFELSE([AC_LANG_SOURCE([

ext/pcntl/pcntl.c

@@ -29,7 +29,6 @@
 
 #include "php.h"
 #include "ext/standard/info.h"
-#include "php_pcntl.h"
 #include "php_signal.h"
 #include "php_ticks.h"
 #include "zend_fibers.h"
@@ -40,6 +39,22 @@
 #include <sys/resource.h>
 #endif
 
+#ifdef HAVE_WAITID
+#if defined (HAVE_DECL_P_ALL) && HAVE_DECL_P_ALL == 1
+#define HAVE_POSIX_IDTYPES 1
+#endif
+#if defined (HAVE_DECL_P_PIDFD) && HAVE_DECL_P_PIDFD == 1
+#define HAVE_LINUX_IDTYPES 1
+#endif
+#if defined (HAVE_DECL_P_UID) && HAVE_DECL_P_UID == 1
+#define HAVE_NETBSD_IDTYPES 1
+#endif
+#if defined (HAVE_DECL_P_JAILID) && HAVE_DECL_P_JAILID == 1
+#define HAVE_FREEBSD_IDTYPES 1
+#endif
+#endif
+
+#include "php_pcntl.h"
 #include <errno.h>
 #if defined(HAVE_UNSHARE) || defined(HAVE_SCHED_SETAFFINITY) || defined(HAVE_SCHED_GETCPU)
 #include <sched.h>
@@ -385,6 +400,39 @@ PHP_FUNCTION(pcntl_waitpid)
 }
 /* }}} */
 
+#if defined (HAVE_WAITID) && defined (HAVE_POSIX_IDTYPES) && defined (HAVE_DECL_WEXITED) && HAVE_DECL_WEXITED == 1
+PHP_FUNCTION(pcntl_waitid)
+{
+	zend_long idtype = P_ALL;
+	zend_long id = 0;
+	bool id_is_null = 1;
+	zval *user_siginfo = NULL;
+	zend_long options = WEXITED;
+
+	ZEND_PARSE_PARAMETERS_START(0, 4)
+		Z_PARAM_OPTIONAL
+		Z_PARAM_LONG(idtype)
+		Z_PARAM_LONG_OR_NULL(id, id_is_null)
+		Z_PARAM_ZVAL(user_siginfo)
+		Z_PARAM_LONG(options)
+	ZEND_PARSE_PARAMETERS_END();
+
+	errno = 0;
+	siginfo_t siginfo;
+
+	int status = waitid((idtype_t) idtype, (id_t) id, &siginfo, (int) options);
+
+	if (status == -1) {
+		PCNTL_G(last_error) = errno;
+		RETURN_FALSE;
+	}
+
+	pcntl_siginfo_to_zval(SIGCHLD, &siginfo, user_siginfo);
+
+	RETURN_TRUE;
+}
+#endif
+
 /* {{{ Waits on or returns the status of a forked child as defined by the waitpid() system call */
 PHP_FUNCTION(pcntl_wait)
 {

ext/pcntl/pcntl.stub.php

@@ -25,6 +25,82 @@
  */
 const WCONTINUED = UNKNOWN;
 #endif
+#if defined (HAVE_DECL_WEXITED) && HAVE_DECL_WEXITED == 1
+/**
+ * @var int
+ * @cvalue LONG_CONST(WEXITED)
+ */
+const WEXITED = UNKNOWN;
+#endif
+#if defined (HAVE_DECL_WSTOPPED) && HAVE_DECL_WSTOPPED == 1
+/**
+ * @var int
+ * @cvalue LONG_CONST(WSTOPPED)
+ */
+const WSTOPPED = UNKNOWN;
+#endif
+#if defined (HAVE_DECL_WNOWAIT) && HAVE_DECL_WNOWAIT== 1
+/**
+ * @var int
+ * @cvalue LONG_CONST(WNOWAIT)
+ */
+const WNOWAIT = UNKNOWN;
+#endif
+
+#ifdef HAVE_WAITID
+/* First argument to waitid */
+#ifdef HAVE_POSIX_IDTYPES
+/**
+ * @var int
+ * @cvalue LONG_CONST(P_ALL)
+ */
+const P_ALL = UNKNOWN;
+/**
+ * @var int
+ * @cvalue LONG_CONST(P_PID)
+ */
+const P_PID = UNKNOWN;
+/**
+ * @var int
+ * @cvalue LONG_CONST(P_PGID)
+ */
+const P_PGID = UNKNOWN;
+#endif
+/* Linux specific idtype */
+#ifdef HAVE_LINUX_IDTYPES
+/**
+ * @var int
+ * @cvalue LONG_CONST(P_PIDFD)
+ */
+const P_PIDFD = UNKNOWN;
+#endif
+/* NetBSD specific idtypes */
+#ifdef HAVE_NETBSD_IDTYPES
+/**
+ * @var int
+ * @cvalue LONG_CONST(P_UID)
+ */
+const P_UID = UNKNOWN;
+/**
+ * @var int
+ * @cvalue LONG_CONST(P_GID)
+ */
+const P_GID = UNKNOWN;
+/**
+ * @var int
+ * @cvalue LONG_CONST(P_SID)
+ */
+const P_SID = UNKNOWN;
+#endif
+/* FreeBSD specific idtype */
+#ifdef HAVE_FREEBSD_IDTYPES
+/**
+ * @var int
+ * @cvalue LONG_CONST(P_JAILID)
+ */
+const P_JAILID = UNKNOWN;
+#endif
+#endif
 
 /* Signal Constants */
 
@@ -927,6 +1003,11 @@ function pcntl_fork(): int {}
  */
 function pcntl_waitpid(int $process_id, &$status, int $flags = 0, &$resource_usage = []): int {}
 
+#if defined (HAVE_WAITID) && defined (HAVE_POSIX_IDTYPES) && defined (HAVE_DECL_WEXITED) && HAVE_DECL_WEXITED == 1
+/** @param array $info */
+function pcntl_waitid(int $idtype = P_ALL, ?int $id = null, &$info = [], int $flags = WEXITED): bool {}
+#endif
+
 /**
  * @param int $status
  * @param array $resource_usage

ext/pcntl/pcntl_arginfo.h

@@ -17,7 +17,7 @@
 #ifndef PHP_PCNTL_H
 #define PHP_PCNTL_H
 
-#if defined(WCONTINUED) && defined(WIFCONTINUED)
+#if defined(HAVE_DECL_WCONTINUED) && HAVE_DECL_WCONTINUED == 1 && defined(HAVE_WIFCONTINUED) && HAVE_WIFCONTINUED == 1
 #define HAVE_WCONTINUED 1
 #endif
 

ext/pcntl/php_pcntl.h

@@ -0,0 +1,41 @@
+--TEST--
+pcntl_waitid()
+--EXTENSIONS--
+pcntl
+posix
+--SKIPIF--
+<?php
+    if (!function_exists('pcntl_waitid')) die('skip pcntl_waitid unavailable');
+?>
+--FILE--
+<?php
+$pid = pcntl_fork();
+if ($pid == -1) {
+    die("failed");
+} else if ($pid) {
+    // invalid flags
+    var_dump(pcntl_waitid(P_PID, $pid, $siginfo, 0));
+    var_dump(pcntl_get_last_error() == PCNTL_EINVAL);
+
+    var_dump(pcntl_waitid(P_PID, $pid, $siginfo, WSTOPPED));
+    posix_kill($pid, SIGCONT);
+    var_dump(pcntl_waitid(P_PID, $pid, $siginfo, WCONTINUED));
+    posix_kill($pid, SIGUSR1);
+    var_dump(pcntl_waitid(P_PID, $pid, $siginfo, WEXITED));
+    var_dump($siginfo["status"]);
+} else {
+    pcntl_signal(SIGUSR1, function ($_signo, $_siginfo) { exit(42); });
+    posix_kill(posix_getpid(), SIGSTOP);
+    pcntl_signal_dispatch();
+    sleep(42);
+    pcntl_signal_dispatch();
+    exit(6);
+}
+?>
+--EXPECTF--
+bool(false)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+int(42)