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

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).