[php-src] master: ext/sockets: socket_cmsg_space() returns int, never null (#23345)

Author: Louis-Arnaud (lacatoire)
Committer: GitHub (web-flow)
Pusher: devnexen
Date: 2026-08-19T13:22:25+01:00

Commit: https://github.com/php/php-src/commit/a183f1162e231739e8877dff2de65f51efaeba0f
Raw diff: https://github.com/php/php-src/commit/a183f1162e231739e8877dff2de65f51efaeba0f.diff

ext/sockets: socket_cmsg_space() returns int, never null (#23345)

* ext/sockets: socket_cmsg_space() returns int, never null

The nullable return type dates from the stub introduction, when the
error paths were warnings followed by a bare return. PHP 8.0 turned
them into ValueError, so every exit is now either RETURN_LONG or
RETURN_THROWS.

Co-authored-by: NickSdot <[email protected]>

Changed paths:
  A  ext/sockets/tests/socket_cmsg_space_return_type.phpt
  M  UPGRADING
  M  ext/sockets/sockets.stub.php
  M  ext/sockets/sockets_arginfo.h


Diff:

diff --git a/UPGRADING b/UPGRADING
index d6e24356ee3a..350d30b12631 100644
--- a/UPGRADING
+++ b/UPGRADING
@@ -604,6 +604,9 @@ PHP 8.6 UPGRADE NOTES
   . socket_addrinfo_lookup() now has an additional optional argument $error
     when not null, and on failure, gives the error code (one of the EAI_*
     constants).
+  . socket_cmsg_space() return type has been narrowed from ?int to int. Every
+    failure path has thrown a ValueError since PHP 8.0, so null was never
+    returned.
 
 - Standard:
   . ini_get_all() now includes a "builtin_default_value" element for each
diff --git a/ext/sockets/sockets.stub.php b/ext/sockets/sockets.stub.php
index 56b2ac07e868..fab32628544d 100644
--- a/ext/sockets/sockets.stub.php
+++ b/ext/sockets/sockets.stub.php
@@ -2313,7 +2313,7 @@ function socket_sendmsg(Socket $socket, array $message, int $flags = 0): int|fal
 
 function socket_recvmsg(Socket $socket, array &$message, int $flags = 0): int|false {}
 
-function socket_cmsg_space(int $level, int $type, int $num = 0): ?int {}
+function socket_cmsg_space(int $level, int $type, int $num = 0): int {}
 
 /**
  * @return array<int, AddressInfo>|false
diff --git a/ext/sockets/sockets_arginfo.h b/ext/sockets/sockets_arginfo.h
index 2592cb740865..cfd792244084 100644
--- a/ext/sockets/sockets_arginfo.h
+++ b/ext/sockets/sockets_arginfo.h
@@ -1,5 +1,5 @@
 /* This is a generated file, edit sockets.stub.php instead.
- * Stub hash: 5e71ef16f2121bd6c75794673d0e0a394759ff8b */
+ * Stub hash: 711d3b84051445917c4a8a1d0cdc1d0c6328be07 */
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_MASK_EX(arginfo_socket_select, 0, 4, MAY_BE_LONG|MAY_BE_FALSE)
 	ZEND_ARG_TYPE_INFO(1, read, IS_ARRAY, 1)
@@ -174,7 +174,7 @@ ZEND_BEGIN_ARG_WITH_RETURN_TYPE_MASK_EX(arginfo_socket_recvmsg, 0, 2, MAY_BE_LON
 	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, flags, IS_LONG, 0, "0")
 ZEND_END_ARG_INFO()
 
-ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_socket_cmsg_space, 0, 2, IS_LONG, 1)
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_socket_cmsg_space, 0, 2, IS_LONG, 0)
 	ZEND_ARG_TYPE_INFO(0, level, IS_LONG, 0)
 	ZEND_ARG_TYPE_INFO(0, type, IS_LONG, 0)
 	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, num, IS_LONG, 0, "0")
diff --git a/ext/sockets/tests/socket_cmsg_space_return_type.phpt b/ext/sockets/tests/socket_cmsg_space_return_type.phpt
new file mode 100644
index 000000000000..f8b0b7364611
--- /dev/null
+++ b/ext/sockets/tests/socket_cmsg_space_return_type.phpt
@@ -0,0 +1,47 @@
+--TEST--
+socket_cmsg_space() always returns int, never null
+--EXTENSIONS--
+sockets
+--SKIPIF--
+<?php
+if (PHP_OS_FAMILY === 'Windows') {
+    die('skip SCM_RIGHTS not available on Windows');
+}
+if (!defined('SCM_RIGHTS')) {
+    die('skip SCM_RIGHTS not defined on this platform');
+}
+?>
+--FILE--
+<?php
+// Happy path: returns int, never null
+$r = socket_cmsg_space(SOL_SOCKET, SCM_RIGHTS, 1);
+var_dump(get_debug_type($r));
+
+// Unknown level/type pair
+try {
+    socket_cmsg_space(999999, 999999);
+} catch (Throwable $e) {
+    echo $e::class, ': ', $e->getMessage(), "\n";
+}
+
+// Negative $num
+try {
+    socket_cmsg_space(SOL_SOCKET, SCM_RIGHTS, -1);
+} catch (Throwable $e) {
+    echo $e::class, ': ', $e->getMessage(), "\n";
+}
+
+// $num overflows int (64-bit only: PHP_INT_MAX > INT_MAX)
+if (PHP_INT_SIZE >= 8) {
+    try {
+        socket_cmsg_space(SOL_SOCKET, SCM_RIGHTS, PHP_INT_MAX);
+    } catch (Throwable $e) {
+        echo $e::class, ': ', $e->getMessage(), "\n";
+    }
+}
+?>
+--EXPECT--
+string(3) "int"
+ValueError: Pair level 999999 and/or type 999999 is not supported
+ValueError: socket_cmsg_space(): Argument #3 ($num) must be greater than or equal to 0
+ValueError: socket_cmsg_space(): Argument #3 ($num) must be between -2147483648 and 2147483647