Fix GH-15796: Add the exit_status() function

Author: alexandre-daubois

NEWS

@@ -73,6 +73,8 @@ PHP                                                                        NEWS
     opened directory has been deprecated. (Girgias)
   . Fixed bug GH-19153 (#[\Attribute] validation should error on
     trait/interface/enum/abstract class). (DanielEScherzer)
+  . Added the exit_status() function to retrieve the current exit
+    status. (alexandre-daubois)
 
 31 Jul 2025, PHP 8.5.0alpha4
 

UPGRADING

@@ -593,6 +593,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_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 {}