From 8e3fccd2e9e6fe6cfbfddd1ef7a4e1d2b2f2fe9c Mon Sep 17 00:00:00 2001 From: Erick Wendel Date: Fri, 14 Nov 2025 17:56:08 -0300 Subject: [PATCH 1/2] util: add convertProcessSignalToExitCode utility Add convertProcessSignalToExitCode() to convert signal names to POSIX exit codes (128 + signal number). Exposed in public util API. --- doc/api/util.md | 32 ++++++++++++++++++++++++++++++++ lib/internal/util.js | 13 +++++++++++++ lib/util.js | 2 ++ 3 files changed, 47 insertions(+) diff --git a/doc/api/util.md b/doc/api/util.md index 4a2f9cb9ec56e4..8cb7448d3d2f64 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -89,6 +89,38 @@ callbackFunction((err, ret) => { }); ``` +## `util.convertProcessSignalToExitCode(signalCode)` + + + +* `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])` -* `code` {number} The exit code if the child process exited on its own, or - `null` if the child process terminated due to a signal. +* `code` {number} The exit code if the child process exited on its own. + When the process is terminated by a signal, this is set to the POSIX exit code. * `signal` {string} The signal by which the child process was terminated, or `null` if the child process did not terminated due to a signal. @@ -1459,10 +1464,10 @@ streams of a child process have been closed. This is distinct from the streams. The `'close'` event will always emit after [`'exit'`][] was already emitted, or [`'error'`][] if the child process failed to spawn. -If the process exited, `code` is the final exit code of the process, otherwise -`null`. If the process terminated due to receipt of a signal, `signal` is the -string name of the signal, otherwise `null`. One of the two will always be -non-`null`. +If the process exited, `code` is the final exit code of the process. If the +process terminated due to receipt of a signal, `signal` is the string name of +the signal, and `code` will be set to the POSIX exit code. One of the two +will always be non-`null`. ```cjs const { spawn } = require('node:child_process'); @@ -1535,17 +1540,23 @@ See also [`subprocess.kill()`][] and [`subprocess.send()`][]. -* `code` {number} The exit code if the child process exited on its own, or - `null` if the child process terminated due to a signal. +* `code` {number} The exit code if the child process exited on its own. + When the process is terminated by a signal, this is set to the POSIX exit code. * `signal` {string} The signal by which the child process was terminated, or `null` if the child process did not terminated due to a signal. The `'exit'` event is emitted after the child process ends. If the process -exited, `code` is the final exit code of the process, otherwise `null`. If the -process terminated due to receipt of a signal, `signal` is the string name of -the signal, otherwise `null`. One of the two will always be non-`null`. +exited, `code` is the final exit code of the process. If the process terminated +due to receipt of a signal, `signal` is the string name of the signal, and +`code` will be set to the POSIX exit code. One of the two will always be +non-`null`. When the `'exit'` event is triggered, child process stdio streams might still be open. @@ -1666,11 +1677,23 @@ within the child process to close the IPC channel as well. ### `subprocess.exitCode` + + * Type: {integer} The `subprocess.exitCode` property indicates the exit code of the child process. If the child process is still running, the field will be `null`. +When the process is terminated by a signal, `exitCode` is set to the POSIX +exit code. + ### `subprocess.kill([signal])`