doc: System Error description incorrectly equates errno and code properties

[pabigot]

The documentation for System Errors specifies:

Returns a string representing the error code, which is always E followed by a sequence of capital letters, and may be referenced in man 2 intro.
The properties error.code and error.errno are aliases of one another and return the same value.

In 4.x and (by inspection) 6.x this is incorrect; the error.errno property is an integer error code, as set by this code for ErrnoException in src/node.cc:

Local<Object> obj = e->ToObject(env->isolate());
obj->Set(env->errno_string(), Integer::New(env->isolate(), errorno));
obj->Set(env->code_string(), estring);

Reproduce with anything like:

try {
  require('fs').openSync('/no/such/file', 'r');
} catch (e) {
  console.log(e);
}

[evanlucas]

Hmmm I'm getting different results:

$ node -e 'try { require("fs").openSync("/no/such", "r") } catch (err) { console.log(process.version, err.code) }'
v4.4.4 ENOENT

$ node -e 'try { require("fs").openSync("/no/such", "r") } catch (err) { console.log(process.version, err.code) }'
v5.11.1 ENOENT

$ node -e 'try { require("fs").openSync("/no/such", "r") } catch (err) { console.log(process.version, err.code) }'
v6.1.0 ENOENT

[evanlucas]

ah scratch that, you're checking errno, not code

[evanlucas]

I would say that this is a documentation issue. Want to submit a PR?

[pabigot]

@evanlucas I'm going to say "no". errno values are generally positive integers with a system-specific value for a given string representation. That the fs.openSync call sets the property to -2 indicates somebody's encoding additional information (possibly just indicating an error through a return value that would otherwise be a non-negative descriptor, as on my system 2 corresponds to ENOENT). I could guess that taking the absolute value of errno would provide something interpretable, but it'd just be a guess. This should be documented by somebody who knows how Node.js decides what to put in the property and can provide guidance on how module writers should use it.

[addaleax]

@pabigot The value of errno on Unices is explained in http://docs.libuv.org/en/v1.x/errors.html, and Node.js uses that value for code. That’s undocumented on Node.js’s side, though.

I don’t think there is a reason not to use .code instead of the .errno property, and I think @evanlucas is right, this is an error in the documentation.

[pabigot]

@addaleax Thanks; with that I can work up some reasonable text. I agree it's a documentation issue and that most users are better off using .code. I'll get a PR in sometime in the next couple days.

[Trott]

This issue has been inactive for sufficiently long that it seems like perhaps it should be closed. Feel free to re-open (or leave a comment requesting that it be re-opened) if you disagree. I'm just tidying up and not acting on a super-strong opinion or anything like that.