doc: update spawnSync() status value possibilities #26680
Conversation
The object returned by `child_process.spawnSync()` can have the `status` property set to `null` if the process terminated due to a signal. We even test for this in test/parallel/test-child-process-spawnsync-kill-signal.js. Update the documentation to reflect this.
nodejs-github-bot
added
child_process
Trott
added
the
author ready
doc/api/child_process.md
Outdated
| @@ -868,7 +868,8 @@ changes: | |||
| * `output` {Array} Array of results from stdio output. | |||
| * `stdout` {Buffer|string} The contents of `output[1]`. | |||
| * `stderr` {Buffer|string} The contents of `output[2]`. | |||
| * `status` {number} The exit code of the child process. | |||
| * `status` {number|null} The exit code of the subprocess, or `null` if the | |||
| child process exited due to a signal. | |||
There was a problem hiding this comment.
"exited due to a signal" --> "terminated due to a signal" (if it terminated due to a signal, it didn't exit, which is why there is no exit code).
the signal docs below have the same problem, they should be changed to something like
The signal that terminated the child process, or null if the child process exited.
(or "if the child process terminated due to exiting.", but that is maybe too verbose).
Perhaps its obvious from the above, but you may want to emphasize that either status will be non-null, or signal will be non-null, but they will NEVER both have non-null values.
There was a problem hiding this comment.
@sam-github OK, I think I've addressed this. I went with end due to signal instead of terminate due to signal. PTAL.
|
https://nodejs.org/api/child_process.html#child_process_event_exit has decent text, might want to copy some of it. https://nodejs.org/api/child_process.html#child_process_event_close has the same problem as spawnSync, it assumes the reader has already read and understood the exit event docs. Searching the docs for "exit code" will find all kinds of references to "its an error when it is non-zero". This is technically correct, but subtle. You must understand that terminating by signal gives a code of Its unfortunate that spawnSync uses |
Yes, unintentional API/terminology inconsistencies are going to become more and more of an issue over time. 😞 |
doc/api/child_process.md
Outdated
| * `status` {number} The exit code of the child process. | ||
| * `signal` {string} The signal used to kill the child process. | ||
| * `status` {number|null} The exit code of the subprocess, or `null` if the | ||
| subprocess ended due to a signal. |
There was a problem hiding this comment.
I don't object to "ended", but please be aware that its non-standard terminology: streams end, processes terminate, on both posixy and windowsy operating systems, see:
There was a problem hiding this comment.
I'll switch to terminate since it's the best term for this.
|
Landed in 5fc6c1d |
The object returned by `child_process.spawnSync()` can have the `status` property set to `null` if the process terminated due to a signal. We even test for this in test/parallel/test-child-process-spawnsync-kill-signal.js. Update the documentation to reflect this. PR-URL: nodejs#26680 Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
The object returned by `child_process.spawnSync()` can have the `status` property set to `null` if the process terminated due to a signal. We even test for this in test/parallel/test-child-process-spawnsync-kill-signal.js. Update the documentation to reflect this. PR-URL: nodejs#26680 Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
The object returned by `child_process.spawnSync()` can have the `status` property set to `null` if the process terminated due to a signal. We even test for this in test/parallel/test-child-process-spawnsync-kill-signal.js. Update the documentation to reflect this. PR-URL: #26680 Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
The object returned by `child_process.spawnSync()` can have the `status` property set to `null` if the process terminated due to a signal. We even test for this in test/parallel/test-child-process-spawnsync-kill-signal.js. Update the documentation to reflect this. PR-URL: #26680 Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
The object returned by
child_process.spawnSync()can have thestatusproperty set to
nullif the process terminated due to a signal. Weeven test for this in
test/parallel/test-child-process-spawnsync-kill-signal.js.
Update the documentation to reflect this.
Checklist
make -j4 test(UNIX), orvcbuild test(Windows) passes