child_process: set exitCode when process is killed by signal

When a child process is terminated by a signal, the exitCode property
is now set to the POSIX standard exit code (128 + signal number)
instead of null. A new utility function convertProcessSignalToExitCode()
has been added to both internal/util and the public util API to convert
signal names to their corresponding exit codes.

Fixes: #60285

Author: ErickWendel

doc/api/util.md

@@ -89,6 +89,38 @@ callbackFunction((err, ret) => {
 });
 ```
 
+## `util.convertProcessSignalToExitCode(signalCode)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `signalCode` {string} A signal name (e.g., `'SIGTERM'`, `'SIGKILL'`).
+* Returns: {number|null} The exit code, or `null` if the signal is invalid.
+
+The `util.convertProcessSignalToExitCode()` method converts a signal name to its
+corresponding POSIX exit code. Following the POSIX standard, the exit code
+for a process terminated by a signal is calculated as `128 + signal number`.
+
+```mjs
+import { convertProcessSignalToExitCode } from 'node:util';
+
+console.log(convertProcessSignalToExitCode('SIGTERM')); // 143 (128 + 15)
+console.log(convertProcessSignalToExitCode('SIGKILL')); // 137 (128 + 9)
+console.log(convertProcessSignalToExitCode('INVALID')); // null
+```
+
+```cjs
+const { convertProcessSignalToExitCode } = require('node:util');
+
+console.log(convertProcessSignalToExitCode('SIGTERM')); // 143 (128 + 15)
+console.log(convertProcessSignalToExitCode('SIGKILL')); // 137 (128 + 9)
+console.log(convertProcessSignalToExitCode('INVALID')); // null
+```
+
+This is particularly useful when working with processes to determine
+the exit code based on the signal that terminated the process.
+
 ## `util.debuglog(section[, callback])`
 
 <!-- YAML

lib/internal/child_process.js

@@ -55,7 +55,7 @@ const { TTY } = internalBinding('tty_wrap');
 const { UDP } = internalBinding('udp_wrap');
 const SocketList = require('internal/socket_list');
 const { owner_symbol } = require('internal/async_hooks').symbols;
-const { convertToValidSignal } = require('internal/util');
+const { convertProcessSignalToExitCode, convertToValidSignal } = require('internal/util');
 const { isArrayBufferView } = require('internal/util/types');
 const spawn_sync = internalBinding('spawn_sync');
 const { kStateSymbol } = require('internal/dgram');
@@ -269,8 +269,11 @@ function ChildProcess() {
   this._handle.onexit = (exitCode, signalCode) => {
     if (signalCode) {
       this.signalCode = signalCode;
+      this.exitCode = convertProcessSignalToExitCode(signalCode);
     } else {
+      // Normal exit: use the exit code directly
       this.exitCode = exitCode;
+      this.signalCode = null;
     }
 
     if (this.stdin) {

lib/internal/util.js

@@ -393,6 +393,20 @@ function convertToValidSignal(signal) {
   throw new ERR_UNKNOWN_SIGNAL(signal);
 }
 
+function convertProcessSignalToExitCode(signalCode) {
+  if (typeof signalCode !== 'string') {
+    return null;
+  }
+
+  const signalNumber = signals[signalCode];
+  if (signalNumber === undefined) {
+    return null;
+  }
+
+  // POSIX standard: exit code for signal termination is 128 + signal number
+  return 128 + signalNumber;
+}
+
 function getConstructorOf(obj) {
   while (obj) {
     const descriptor = ObjectGetOwnPropertyDescriptor(obj, 'constructor');
@@ -956,6 +970,7 @@ module.exports = {
   assignFunctionName,
   cachedResult,
   constructSharedArrayBuffer,
+  convertProcessSignalToExitCode,
   convertToValidSignal,
   createClassWrapper,
   decorateErrorStack,

lib/util.js

@@ -84,6 +84,7 @@ const { getOptionValue } = require('internal/options');
 const binding = internalBinding('util');
 
 const {
+  convertProcessSignalToExitCode,
   deprecate: internalDeprecate,
   getLazy,
   getSystemErrorMap,
@@ -472,6 +473,7 @@ module.exports = {
                              'The `util._extend` API is deprecated. Please use Object.assign() instead.',
                              'DEP0060'),
   callbackify,
+  convertProcessSignalToExitCode,
   debug: debuglog,
   debuglog,
   deprecate,

test/parallel/test-child-process-destroy.js

@@ -1,20 +1,22 @@
 'use strict';
 const common = require('../common');
 const assert = require('assert');
+const { convertProcessSignalToExitCode } = require('util');
 const spawn = require('child_process').spawn;
 const cat = spawn(common.isWindows ? 'cmd' : 'cat');
 
 cat.stdout.on('end', common.mustCall());
 cat.stderr.on('data', common.mustNotCall());
 cat.stderr.on('end', common.mustCall());
 
+const exitCode = convertProcessSignalToExitCode('SIGTERM');
 cat.on('exit', common.mustCall((code, signal) => {
-  assert.strictEqual(code, null);
+  assert.strictEqual(code, exitCode);
   assert.strictEqual(signal, 'SIGTERM');
   assert.strictEqual(cat.signalCode, 'SIGTERM');
 }));
 cat.on('exit', common.mustCall((code, signal) => {
-  assert.strictEqual(code, null);
+  assert.strictEqual(code, exitCode);
   assert.strictEqual(signal, 'SIGTERM');
   assert.strictEqual(cat.signalCode, 'SIGTERM');
 }));

test/parallel/test-child-process-exec-timeout-expire.js

@@ -5,6 +5,7 @@
 const common = require('../common');
 const assert = require('assert');
 const cp = require('child_process');
+const { convertProcessSignalToExitCode } = require('util');
 
 const {
   cleanupStaleProcess,
@@ -34,7 +35,7 @@ cp.exec(cmd, {
     assert.strictEqual(err.code, 143);
     sigterm = null;
   } else {
-    assert.strictEqual(err.code, null);
+    assert.strictEqual(err.code, convertProcessSignalToExitCode(sigterm));
   }
   // At least starting with Darwin Kernel Version 16.4.0, sending a SIGTERM to a
   // process that is still starting up kills it with SIGKILL instead of SIGTERM.

test/parallel/test-child-process-exec-timeout-kill.js

@@ -5,6 +5,7 @@
 const common = require('../common');
 const assert = require('assert');
 const cp = require('child_process');
+const { convertProcessSignalToExitCode } = require('util');
 
 const {
   cleanupStaleProcess,
@@ -30,7 +31,7 @@ cp.exec(cmd, {
   console.log('[stderr]', stderr.trim());
 
   assert.strictEqual(err.killed, true);
-  assert.strictEqual(err.code, null);
+  assert.strictEqual(err.code, convertProcessSignalToExitCode('SIGKILL'));
   assert.strictEqual(err.signal, 'SIGKILL');
   assert.strictEqual(err.cmd, cmd);
   assert.strictEqual(stdout.trim(), '');

test/parallel/test-child-process-fork-abort-signal.js

@@ -4,6 +4,7 @@ const { mustCall, mustNotCall } = require('../common');
 const assert = require('assert');
 const fixtures = require('../common/fixtures');
 const { fork } = require('child_process');
+const { convertProcessSignalToExitCode } = require('util');
 
 {
   // Test aborting a forked child_process after calling fork
@@ -13,7 +14,7 @@ const { fork } = require('child_process');
     signal
   });
   cp.on('exit', mustCall((code, killSignal) => {
-    assert.strictEqual(code, null);
+    assert.strictEqual(code, convertProcessSignalToExitCode('SIGTERM'));
     assert.strictEqual(killSignal, 'SIGTERM');
   }));
   cp.on('error', mustCall((err) => {
@@ -30,7 +31,7 @@ const { fork } = require('child_process');
     signal
   });
   cp.on('exit', mustCall((code, killSignal) => {
-    assert.strictEqual(code, null);
+    assert.strictEqual(code, convertProcessSignalToExitCode('SIGTERM'));
     assert.strictEqual(killSignal, 'SIGTERM');
   }));
   cp.on('error', mustCall((err) => {
@@ -48,7 +49,7 @@ const { fork } = require('child_process');
     signal
   });
   cp.on('exit', mustCall((code, killSignal) => {
-    assert.strictEqual(code, null);
+    assert.strictEqual(code, convertProcessSignalToExitCode('SIGTERM'));
     assert.strictEqual(killSignal, 'SIGTERM');
   }));
   cp.on('error', mustCall((err) => {
@@ -63,7 +64,7 @@ const { fork } = require('child_process');
     signal
   });
   cp.on('exit', mustCall((code, killSignal) => {
-    assert.strictEqual(code, null);
+    assert.strictEqual(code, convertProcessSignalToExitCode('SIGTERM'));
     assert.strictEqual(killSignal, 'SIGTERM');
   }));
   cp.on('error', mustCall((err) => {
@@ -81,7 +82,7 @@ const { fork } = require('child_process');
     killSignal: 'SIGKILL',
   });
   cp.on('exit', mustCall((code, killSignal) => {
-    assert.strictEqual(code, null);
+    assert.strictEqual(code, convertProcessSignalToExitCode('SIGKILL'));
     assert.strictEqual(killSignal, 'SIGKILL');
   }));
   cp.on('error', mustCall((err) => {

test/parallel/test-child-process-kill.js

@@ -16,12 +16,13 @@
 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
 // NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
 // DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
-// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
-// USE OR OTHER DEALINGS IN THE SOFTWARE.
+// OTHERWISE, ARISING IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+// DEALINGS IN THE SOFTWARE.
 
 'use strict';
 const common = require('../common');
 const assert = require('assert');
+const { convertProcessSignalToExitCode } = require('util');
 const spawn = require('child_process').spawn;
 const cat = spawn(common.isWindows ? 'cmd' : 'cat');
 
@@ -30,9 +31,11 @@ cat.stderr.on('data', common.mustNotCall());
 cat.stderr.on('end', common.mustCall());
 
 cat.on('exit', common.mustCall((code, signal) => {
-  assert.strictEqual(code, null);
+  const expectedExitCode = convertProcessSignalToExitCode('SIGTERM');
+  assert.strictEqual(code, expectedExitCode);
   assert.strictEqual(signal, 'SIGTERM');
   assert.strictEqual(cat.signalCode, 'SIGTERM');
+  assert.strictEqual(cat.exitCode, expectedExitCode);
 }));
 
 assert.strictEqual(cat.signalCode, null);
@@ -45,16 +48,21 @@ if (common.isWindows) {
   for (const sendSignal of ['SIGTERM', 'SIGKILL', 'SIGQUIT', 'SIGINT']) {
     const process = spawn('cmd');
     process.on('exit', (code, signal) => {
-      assert.strictEqual(code, null);
+      const expectedExitCode = convertProcessSignalToExitCode(sendSignal);
+      assert.strictEqual(code, expectedExitCode);
       assert.strictEqual(signal, sendSignal);
+      assert.strictEqual(process.exitCode, expectedExitCode);
     });
     process.kill(sendSignal);
   }
 
   const process = spawn('cmd');
   process.on('exit', (code, signal) => {
-    assert.strictEqual(code, null);
+    const expectedExitCode = convertProcessSignalToExitCode('SIGKILL');
+    assert.strictEqual(code, expectedExitCode);
     assert.strictEqual(signal, 'SIGKILL');
+    assert.strictEqual(process.exitCode, expectedExitCode);
+    assert.strictEqual(process.signalCode, 'SIGKILL');
   });
   process.kill('SIGHUP');
 }
@@ -70,6 +78,8 @@ const checkProcess = spawn(process.execPath, ['-e', code]);
 checkProcess.on('exit', common.mustCall((code, signal) => {
   assert.strictEqual(code, 0);
   assert.strictEqual(signal, null);
+  assert.strictEqual(checkProcess.exitCode, 0);
+  assert.strictEqual(checkProcess.signalCode, null);
 }));
 
 checkProcess.stdout.on('data', common.mustCall((chunk) => {

test/parallel/test-child-process-spawn-controller.js

@@ -4,6 +4,7 @@ const common = require('../common');
 const assert = require('assert');
 const { spawn } = require('child_process');
 const fixtures = require('../common/fixtures');
+const { convertProcessSignalToExitCode } = require('util');
 
 const aliveScript = fixtures.path('child-process-stay-alive-forever.js');
 {
@@ -16,7 +17,7 @@ const aliveScript = fixtures.path('child-process-stay-alive-forever.js');
   });
 
   cp.on('exit', common.mustCall((code, killSignal) => {
-    assert.strictEqual(code, null);
+    assert.strictEqual(code, convertProcessSignalToExitCode('SIGTERM'));
     assert.strictEqual(killSignal, 'SIGTERM');
   }));
 
@@ -36,7 +37,7 @@ const aliveScript = fixtures.path('child-process-stay-alive-forever.js');
   });
 
   cp.on('exit', common.mustCall((code, killSignal) => {
-    assert.strictEqual(code, null);
+    assert.strictEqual(code, convertProcessSignalToExitCode('SIGTERM'));
     assert.strictEqual(killSignal, 'SIGTERM');
   }));
 
@@ -57,7 +58,7 @@ const aliveScript = fixtures.path('child-process-stay-alive-forever.js');
   });
 
   cp.on('exit', common.mustCall((code, killSignal) => {
-    assert.strictEqual(code, null);
+    assert.strictEqual(code, convertProcessSignalToExitCode('SIGTERM'));
     assert.strictEqual(killSignal, 'SIGTERM');
   }));
 
@@ -77,7 +78,7 @@ const aliveScript = fixtures.path('child-process-stay-alive-forever.js');
     signal,
   });
   cp.on('exit', common.mustCall((code, killSignal) => {
-    assert.strictEqual(code, null);
+    assert.strictEqual(code, convertProcessSignalToExitCode('SIGTERM'));
     assert.strictEqual(killSignal, 'SIGTERM');
   }));
 
@@ -94,7 +95,7 @@ const aliveScript = fixtures.path('child-process-stay-alive-forever.js');
     signal,
   });
   cp.on('exit', common.mustCall((code, killSignal) => {
-    assert.strictEqual(code, null);
+    assert.strictEqual(code, convertProcessSignalToExitCode('SIGTERM'));
     assert.strictEqual(killSignal, 'SIGTERM');
   }));
 
@@ -111,7 +112,7 @@ const aliveScript = fixtures.path('child-process-stay-alive-forever.js');
     signal,
   });
   cp.on('exit', common.mustCall((code, killSignal) => {
-    assert.strictEqual(code, null);
+    assert.strictEqual(code, convertProcessSignalToExitCode('SIGTERM'));
     assert.strictEqual(killSignal, 'SIGTERM');
   }));
 
@@ -131,7 +132,7 @@ const aliveScript = fixtures.path('child-process-stay-alive-forever.js');
   });
 
   cp.on('exit', common.mustCall((code, killSignal) => {
-    assert.strictEqual(code, null);
+    assert.strictEqual(code, convertProcessSignalToExitCode('SIGTERM'));
     assert.strictEqual(killSignal, 'SIGTERM');
   }));
 
@@ -153,7 +154,7 @@ const aliveScript = fixtures.path('child-process-stay-alive-forever.js');
   });
 
   cp.on('exit', common.mustCall((code, killSignal) => {
-    assert.strictEqual(code, null);
+    assert.strictEqual(code, convertProcessSignalToExitCode('SIGKILL'));
     assert.strictEqual(killSignal, 'SIGKILL');
   }));