child_process.execFile returns strings where doc says it should return a Buffer

[nixar]

Doc says:

callback Function called with the output when process terminates

• error Error
• stdout Buffer
• stderr Buffer

This was known back in 2013 already

This points out the options parameter's encoding field can force a buffer response. However the default value is supposed to be 'utf8' according to the doc, which strongly implies that it means character encoding, not the type of the return value. The name of this option is terribly misleading.

Demo code:

"use strict";
var child_process = require('child_process');
console.log('node version=%s',process.version);

for (let options of [{}, {encoding:'buffer'}]) {
  child_process.execFile(
    'uname', ['-o'], options,
    (error, stdout, stderr) => {
      console.log(
        'options is %s → stdout is a %s', 
        JSON.stringify(options), 
        typeof stdout
      )
    }
  );
}

Output:

node version=v4.2.1
options is {"encoding":"buffer"} → stdout is a object
options is {} → stdout is a string

The behavior or the documentation need to be changed. If the current behavior is kept, the semantic of 'encoding' should be clarified, and the name of the property should be changed (to 'return_type' for example).

[cjihrig]

If you think there is a problem with the documentation, feel free to submit a PR improving it :-)

[nixar]

I considered it but I'm trying to understand the logic first. How do you explain the baffling yet ostensibly deliberate semantic of 'encoding'?

[cjihrig]

encoding specifies how the stderr and stdout data is interpreted. The default is utf8, which is why stdout is a string in your example. When you explicitly set it to a buffer, you get a Buffer object. Does that help?

[nixar]

No, that does not, because I long figured it out, since that's precisely
what my code is meant to show. I'm trying to understand the logic of
calling something "encoding" when you mean return value type, and "utf8" to
mean string.

Le ven. 16 oct. 2015 02:01, Colin Ihrig notifications@github.com a écrit :

encoding specifies how the stderr and stdout data is interpreted. The
default is utf8, which is why stdout is a string in your example. When
you explicitly set it to a buffer, you get a Buffer object. Does that
help?

—
Reply to this email directly or view it on GitHub
#3389 (comment).

[cjihrig]

utf8 does not mean string. It's one of several types of string encoding supported by Node.

[Fishrock123]

It should probably say like Buffer | String (in which ever format we use throughout the docs).