Fix GH-15796: Add the exit_status() function

Author: alexandre-daubois

NEWS

@@ -58,6 +58,8 @@ PHP                                                                        NEWS
   . The socket_set_timeout() alias function has been deprecated. (timwolla)
   . Passing null to to readdir(), rewinddir(), and closedir() to use the last
     opened directory has been deprecated. (Girgias)
+  . Added the exit_status() function to retrieve the current exit
+    status. (alexandre-daubois)
 
 31 Jul 2025, PHP 8.5.0alpha4
 

UPGRADING

@@ -574,6 +574,7 @@ PHP 8.5 UPGRADE NOTES
 - Standard:
   . Added array_first() and array_last().
     RFC: https://wiki.php.net/rfc/array_first_last
+  . Added exit_status().
 
 ========================================
 7. New Classes and Interfaces

Zend/tests/exit_status/exit_status_basic.phpt

@@ -0,0 +1,12 @@
+--TEST--
+exit_status() basic functionality test
+--FILE--
+<?php
+var_dump(exit_status());
+var_dump(function_exists('exit_status'));
+var_dump(is_int(exit_status()));
+?>
+--EXPECT--
+int(0)
+bool(true)
+bool(true)

Zend/tests/exit_status/exit_status_error.phpt

@@ -0,0 +1,21 @@
+--TEST--
+exit_status() error with parameters
+--FILE--
+<?php
+try {
+    exit_status(42);
+    echo "ERROR: Should have thrown ArgumentCountError\n";
+} catch (ArgumentCountError $e) {
+    echo "PASS: Caught expected ArgumentCountError\n";
+}
+
+try {
+    exit_status(1, 2, 3);
+    echo "ERROR: Should have thrown ArgumentCountError\n";  
+} catch (ArgumentCountError $e) {
+    echo "PASS: Caught expected ArgumentCountError for multiple params\n";
+}
+?>
+--EXPECT--
+PASS: Caught expected ArgumentCountError
+PASS: Caught expected ArgumentCountError for multiple params

Zend/tests/exit_status/exit_status_exception.phpt

@@ -0,0 +1,17 @@
+--TEST--
+exit_status() with uncaught exceptions setting exit code
+--FILE--
+<?php
+register_shutdown_function(function() {
+    echo "Exit status is: " . exit_status() . "\n";
+});
+
+// set exit status to 255
+throw new Exception("Test exception");
+?>
+--EXPECTF--
+Fatal error: Uncaught Exception: Test exception in %s:%d
+Stack trace:
+#0 {main}
+  thrown in %s on line %d
+Exit status is: 255

Zend/tests/exit_status/exit_status_shutdown.phpt

@@ -0,0 +1,20 @@
+--TEST--
+exit_status() in shutdown handler preserving original exit code
+--FILE--
+<?php
+register_shutdown_function(function() {
+    echo "Current exit status: " . exit_status() . "\n";
+
+    $original_status = exit_status();
+    $final_status = $original_status ?: 255;
+
+    echo "Final status will be: " . $final_status . "\n";
+});
+
+echo "Setting exit status to 42\n";
+exit(42);
+?>
+--EXPECT--
+Setting exit status to 42
+Current exit status: 42
+Final status will be: 42

Zend/tests/exit_status/exit_status_string.phpt

@@ -0,0 +1,14 @@
+--TEST--
+exit_status() with string exit codes
+--FILE--
+<?php
+register_shutdown_function(function() {
+    echo "Exit status: " . exit_status() . "\n";
+});
+
+echo "Before exit with string\n";
+exit("Error message");
+?>
+--EXPECT--
+Before exit with string
+Error messageExit status: 0

Zend/zend_builtin_functions.c

@@ -501,6 +501,13 @@ ZEND_FUNCTION(error_reporting)
 }
 /* }}} */
 
+ZEND_FUNCTION(exit_status)
+{
+	ZEND_PARSE_PARAMETERS_NONE();
+
+	RETURN_LONG(EG(exit_status));
+}
+
 static bool validate_constant_array_argument(HashTable *ht, int argument_number) /* {{{ */
 {
 	bool ret = 1;

Zend/zend_builtin_functions.stub.php

@@ -41,6 +41,8 @@ function strncasecmp(string $string1, string $string2, int $length): int {}
 
 function error_reporting(?int $error_level = null): int {}
 
+function exit_status(): int {}
+
 function define(string $constant_name, mixed $value, bool $case_insensitive = false): bool {}
 
 function defined(string $constant_name): bool {}