diff --git a/doc/api/child_process.md b/doc/api/child_process.md index ba7cc2af6bfb14..41c908c329d7ad 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -1446,10 +1446,15 @@ instances of `ChildProcess`. -* `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])` + +* `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])`