diff --git a/doc/api/child_process.md b/doc/api/child_process.md index ba7cc2af6bfb14..e3273446c3e517 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -1557,6 +1557,10 @@ re-raise the handled signal. See waitpid(2). +When `code` is `null` due to signal termination, you can use +[`util.convertProcessSignalToExitCode()`][] to convert the signal to a POSIX +exit code. + ### Event: `'message'` + +* `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])`