From 978acdc58daa4304edf56c8d7b69f54d65c4d6c6 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 4 Nov 2018 11:59:14 -0800 Subject: [PATCH 1/6] doc: update System Errors documentation Simplify text. Add explanation that `code` is the most stable way to identify an error, in contrast with `message` which is subject to change between patch-level versions of Node.js. Synchronize list of properties with text. Order properties alphabetically. --- doc/api/errors.md | 95 ++++++++++++++++++++++++++--------------------- 1 file changed, 52 insertions(+), 43 deletions(-) diff --git a/doc/api/errors.md b/doc/api/errors.md index aecb5282e79808..e516903e9517f4 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -441,86 +441,95 @@ checks or `abort()` calls in the C++ layer. ## System Errors -System errors are generated when exceptions occur within the Node.js -runtime environment. Typically, these are operational errors that occur -when an application violates an operating system constraint such as attempting -to read a file that does not exist or when the user does not have sufficient -permissions. +Node.js generates system errors when exceptions occur within its runtime +environment. These usually occur when an application violates an operating +system constraint. For example, a system error will occur if an application +attempts to read a file that does not exist. -System errors are typically generated at the syscall level: an exhaustive list -of error codes and their meanings is available by running `man 2 intro` or -`man 3 errno` on most Unices; or [online][]. +System errors are usually generated at the syscall level. For a comprehensive +list, see the [`errno`(3) man page][]. -In Node.js, system errors are represented as augmented `Error` objects with -added properties. +In Node.js, system errors are `Error` objects with extra properties. ### Class: SystemError -#### error.info +* `address` {string} If present, the address to which a network connection + failed +* `code` {string} The string error code +* `dest` {Buffer} If present, the file path destination when reporting a file + system error +* `errno` {number|string} The system-provided error number +* `info` {Object} If present, extra details about the error condition +* `message` {string} A system-provided human-readable description of the error +* `path` {Buffer} If present, the file path when reporting a file system error +* `port` {number} If present, the network connection port that is not available +* `syscall` {string} The name of the system call that triggered the error -`SystemError` instances may have an additional `info` property whose -value is an object with additional details about the error conditions. +#### error.address -The following properties are provided: +* {string} -* `code` {string} The string error code -* `errno` {number} The system-provided error number -* `message` {string} A system-provided human readable description of the error -* `syscall` {string} The name of the system call that triggered the error -* `path` {Buffer} When reporting a file system error, the `path` will identify - the file path. -* `dest` {Buffer} When reporting a file system error, the `dest` will identify - the file path destination (if any). +If present, `error.address` is a string describing the address to which a +network connection failed. #### error.code * {string} -The `error.code` property is a string representing the error code, which is -typically `E` followed by a sequence of capital letters. +The `error.code` property is a string representing the error code. + +#### error.dest + +* {string} + +If present, `error.dest` is the file path destination when reporting a file +system error. #### error.errno * {string|number} -The `error.errno` property is a number or a string. -The number is a **negative** value which corresponds to the error code defined -in [`libuv Error handling`]. See `uv-errno.h` header file +The `error.errno` property is a number or a string. If it is a number, it is a negative value which corresponds to the error code defined in +[`libuv Error handling`]. See `uv-errno.h` header file (`deps/uv/include/uv-errno.h` in the Node.js source tree) for details. In case of a string, it is the same as `error.code`. -#### error.syscall +#### error.info -* {string} +* {Object} -The `error.syscall` property is a string describing the [syscall][] that failed. +If present, `error.info` is an object with details about the error condition. -#### error.path +#### error.message -* {string} +* {string} -When present (e.g. in `fs` or `child_process`), the `error.path` property is a -string containing a relevant invalid pathname. +`error.message` is a system-provided human-readable description of the error. +It is subject to change between versions of Node.js. Use `code` for a more +stable indicator of the type of error. -#### error.address +#### error.path * {string} -When present (e.g. in `net` or `dgram`), the `error.address` property is a -string describing the address to which the connection failed. +If present, `error.path` is a string containing a relevant invalid pathname. #### error.port * {number} -When present (e.g. in `net` or `dgram`), the `error.port` property is a number -representing the connection's port that is not available. +If present, `error.port` is the network connection port that is not available. + +#### error.syscall + +* {string} + +The `error.syscall` property is a string describing the [syscall][] that failed. ### Common System Errors -This list is **not exhaustive**, but enumerates many of the common system -errors encountered when writing a Node.js program. An exhaustive list may be -found [here][online]. +This is a list of system errors commonly-encountered when writing a Node.js +program. For a comprehensive list, see the [`errno`(3) man page][]. - `EACCES` (Permission denied): An attempt was made to access a file in a way forbidden by its file access permissions. @@ -2126,6 +2135,7 @@ such as `process.stdout.on('data')`. [`crypto.scryptSync()`]: crypto.html#crypto_crypto_scryptsync_password_salt_keylen_options [`crypto.timingSafeEqual()`]: crypto.html#crypto_crypto_timingsafeequal_a_b [`dgram.createSocket()`]: dgram.html#dgram_dgram_createsocket_options_callback +[`errno`(3) man page]: http://man7.org/linux/man-pages/man3/errno.3.html [`fs.readFileSync`]: fs.html#fs_fs_readfilesync_path_options [`fs.readdir`]: fs.html#fs_fs_readdir_path_options_callback [`fs.symlink()`]: fs.html#fs_fs_symlink_target_path_type_callback @@ -2165,7 +2175,6 @@ such as `process.stdout.on('data')`. [domains]: domain.html [event emitter-based]: events.html#events_class_eventemitter [file descriptors]: https://en.wikipedia.org/wiki/File_descriptor -[online]: http://man7.org/linux/man-pages/man3/errno.3.html [stream-based]: stream.html [syscall]: http://man7.org/linux/man-pages/man2/syscalls.2.html [try-catch]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch From e027cdbd28debc254c76fc46ff4c5412369a70cb Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 4 Nov 2018 14:29:45 -0800 Subject: [PATCH 2/6] doc: add text about error.code stability Fixes: https://github.com/nodejs/node/issues/23975 --- doc/api/errors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/errors.md b/doc/api/errors.md index e516903e9517f4..82739ca85de7aa 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -260,7 +260,7 @@ not capture any frames. * {string} The `error.code` property is a string label that identifies the kind of error. -See [Node.js Error Codes][] for details about specific codes. +`error.code` is the most stable way to identify an error. It will only change between major versions of Node.js. In contrast, `error.message` strings may change between any versions of Node.js. See [Node.js Error Codes][] for details about specific codes. ### error.message From 9fdc9b9a27709d5037f42723a2e86c1faab89c5a Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 4 Nov 2018 14:35:13 -0800 Subject: [PATCH 3/6] fixup! doc: update System Errors documentation --- doc/api/errors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/errors.md b/doc/api/errors.md index 82739ca85de7aa..70313913e1954a 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -456,7 +456,7 @@ In Node.js, system errors are `Error` objects with extra properties. * `address` {string} If present, the address to which a network connection failed * `code` {string} The string error code -* `dest` {Buffer} If present, the file path destination when reporting a file +* `dest` {string} If present, the file path destination when reporting a file system error * `errno` {number|string} The system-provided error number * `info` {Object} If present, extra details about the error condition From 01fa7780b1a486ae9214855880ab9e450ba0b005 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 4 Nov 2018 14:36:12 -0800 Subject: [PATCH 4/6] fixup! fixup! doc: update System Errors documentation --- doc/api/errors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/errors.md b/doc/api/errors.md index 70313913e1954a..2d101522559451 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -461,7 +461,7 @@ In Node.js, system errors are `Error` objects with extra properties. * `errno` {number|string} The system-provided error number * `info` {Object} If present, extra details about the error condition * `message` {string} A system-provided human-readable description of the error -* `path` {Buffer} If present, the file path when reporting a file system error +* `path` {string} If present, the file path when reporting a file system error * `port` {number} If present, the network connection port that is not available * `syscall` {string} The name of the system call that triggered the error From d67788feb31630558e651d0fcbc157f63a6639da Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 4 Nov 2018 14:37:50 -0800 Subject: [PATCH 5/6] fixup! fixup! fixup! doc: update System Errors documentation --- doc/api/errors.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api/errors.md b/doc/api/errors.md index 2d101522559451..f734af57dfa0a1 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -490,8 +490,8 @@ system error. * {string|number} The `error.errno` property is a number or a string. If it is a number, it is a negative value which corresponds to the error code defined in -[`libuv Error handling`]. See `uv-errno.h` header file -(`deps/uv/include/uv-errno.h` in the Node.js source tree) for details. In case +[`libuv Error handling`]. See the libuv `errno.h` header file +(`deps/uv/include/uv/errno.h` in the Node.js source tree) for details. In case of a string, it is the same as `error.code`. #### error.info From fac7bbc01d5ddb50e093327de913a4cd76601280 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 4 Nov 2018 14:39:07 -0800 Subject: [PATCH 6/6] fixup! fixup! fixup! fixup! doc: update System Errors documentation --- doc/api/errors.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/doc/api/errors.md b/doc/api/errors.md index f734af57dfa0a1..f61a2ab2a8f3ab 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -505,8 +505,6 @@ If present, `error.info` is an object with details about the error condition. * {string} `error.message` is a system-provided human-readable description of the error. -It is subject to change between versions of Node.js. Use `code` for a more -stable indicator of the type of error. #### error.path