Status of the spawned process is null

[advanceddeveloper]

• Version: v8.5.0 v10.0.0
• Platform: Linux tio2 4.15.13-300.fc27.x86_64 #1 SMP Mon Mar 26 19:06:57 UTC 2018 x86_64 x86_64 x86_64 GNU/Linux
• Subsystem: child_process

In the documentation for child_process.spawnSync it says that the status property of the returned object is of type <number> and it nowhere mentions that it may be null. However, the following script prints null (expected is 139):

'use strict';

var fs = require('fs');
var path = require('path');
var os = require('os');
var cp = require('child_process');

var dir = path.join(os.tmpdir(), `${Date.now()}`);
fs.mkdirSync(dir);

var name = 'test.cc';
var file = path.join(dir, name);
fs.writeFileSync(file, 'int main(){++*(int*)0;}');
cp.spawnSync('gcc', [file], {cwd: dir});

var files = fs.readdirSync(dir);
var output = files.find(file => file !== name);
var obj = cp.spawnSync(path.join(dir, output));

console.log(obj.status);

On windows it prints 3221225477 which is expected result on windows.

[bnoordhuis]

However, the following script prints null (expected is 139)

The process is terminated by a signal. As with the other child_process APIs, there's no status code in that case but .signal is set to the signal name.

If you feel the documentation for .spawnSync() is unclear, can you open a pull request with suggestions for improvement?

[advanceddeveloper]

Updating the documentation sounds like a good idea, but I'm not sure which behavior should be documented?

• On windows, shouldn't the signal be SIGSEGV and status null like on linux?
• On linux, there are four extra properties of the returned object envPairs, options, args, file, is it documented somewhere? It doesn't happen with v10.0.0

[advanceddeveloper]

Ping @bnoordhuis ....

[bnoordhuis]

Windows doesn't have signals, SIGSEGV is not a thing on that platform.

[advanceddeveloper]

@bnoordhuis

Ok, then. How about this?

doc/api/child_process.md:

  * Returns: {Object}
    * `pid` {number} Pid of the child process.
    * `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} The exit code of the child process if the child exited on its own.
    * `signal` {string} The signal used to kill the child process.
    * `error` {Error} The error object if the child process failed or timed out.

[bnoordhuis]

I suspect an inquiring reader will ask what "on its own" means. A process that sends itself a signal exits on its own but has no exit status. I'd probably write "...unless it was terminated by a signal."

[advanceddeveloper]

@bnoordhuis

I agree that what you said sounds more descriptive, but "if the child exited on its own" is the exact clause that is used in other child process methods in the documentation, so I was thinking that it is for consistency.

So, you're suggesting the following change?

  * Returns: {Object}
    * `pid` {number} Pid of the child process.
    * `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} The exit code of the child process unless it was terminated by a signal.
    * `signal` {string} The signal used to kill the child process.
    * `error` {Error} The error object if the child process failed or timed out.

If that's it, I think it is ready for a pr.

[AyushG3112]

Wouldn't it be better to be more explicit? Something like:

The exit code of the child process. null if it was terminated by a signal.

[advanceddeveloper]

@AyushG3112

Sounds good. Feel free to submit the pr yourself then. I'm not a big fan of submitting pr myself, so I'm happy to hear that someone wants to do it instead.

[Trott]

Closing due to resolution/inactivity. Leave a comment if there's something more to discuss here and/or it should be re-opened.

[samuela]

Another question that doesn't seem to be addressed by any of the documentation I've seen: Under what conditions are signals sent to the process? Is it a timeout? Resource constraints? Something else? And when a signal is sent to the process, which signal is it?