1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: update System Errors documentation

Browse Source 
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.

PR-URL: https://github.com/nodejs/node/pull/24090
Fixes: https://github.com/nodejs/node/issues/23975
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
This commit is contained in:
Rich Trott 2018-11-04 11:59:14 -08:00
parent 18a4550f34
commit 366f9b9b55
1 changed files with 61 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
doc/api/errors.md
View File

@ -441,86 +441,93 @@ checks or `abort()` calls in the C++ layer.
## System Errors ## System Errors
System errors are generated when exceptions occur within the Node.js Node.js generates system errors when exceptions occur within its runtime
runtime environment. Typically, these are operational errors that occur environment. These usually occur when an application violates an operating
when an application violates an operating system constraint such as attempting system constraint. For example, a system error will occur if an application
to read a file that does not exist or when the user does not have sufficient attempts to read a file that does not exist.
permissions.
System errors are typically generated at the syscall level: an exhaustive list System errors are usually generated at the syscall level. For a comprehensive
of error codes and their meanings is available by running `man 2 intro` or list, see the [`errno`(3) man page][].
`man 3 errno` on most Unices; or [online][].
In Node.js, system errors are represented as augmented `Error` objects with In Node.js, system errors are `Error` objects with extra properties.
added properties.
### Class: SystemError ### Class: SystemError
#### error.info * `address` {string} If present, the address to which a network connection
failed
`SystemError` instances may have an additional `info` property whose
value is an object with additional details about the error conditions.
The following properties are provided:
* `code` {string} The string error code * `code` {string} The string error code
* `errno` {number} The system-provided error number * `dest` {string} If present, the file path destination when reporting a file
* `message` {string} A system-provided human readable description of the error 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` {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 * `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. #### error.address
* `dest` {Buffer} When reporting a file system error, the `dest` will identify
the file path destination (if any). * {string}
If present, `error.address` is a string describing the address to which a
network connection failed.
#### error.code #### error.code
* {string} * {string}
The `error.code` property is a string representing the error code, which is The `error.code` property is a string representing the error code.
typically `E` followed by a sequence of capital letters.
#### error.dest
* {string}
If present, `error.dest` is the file path destination when reporting a file
system error.
#### error.errno #### error.errno
* {string|number} * {string|number}
The `error.errno` property is a number or a string. 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
The number is a **negative** value which corresponds to the error code defined [`libuv Error handling`]. See the libuv `errno.h` header file
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
(`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`. of a string, it is the same as `error.code`.
#### error.info
* {Object}
If present, `error.info` is an object with details about the error condition.
#### error.message
* {string}
`error.message` is a system-provided human-readable description of the error.
#### error.path
* {string}
If present, `error.path` is a string containing a relevant invalid pathname.
#### error.port
* {number}
If present, `error.port` is the network connection port that is not available.
#### error.syscall #### error.syscall
* {string} * {string}
The `error.syscall` property is a string describing the [syscall][] that failed. The `error.syscall` property is a string describing the [syscall][] that failed.
#### error.path
* {string}
When present (e.g. in `fs` or `child_process`), the `error.path` property is a
string containing a relevant invalid pathname.
#### error.address
* {string}
When present (e.g. in `net` or `dgram`), the `error.address` property is a
string describing the address to which the connection failed.
#### 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.
### Common System Errors ### Common System Errors
This list is **not exhaustive**, but enumerates many of the common system This is a list of system errors commonly-encountered when writing a Node.js
errors encountered when writing a Node.js program. An exhaustive list may be program. For a comprehensive list, see the [`errno`(3) man page][].
found [here][online].
- `EACCES` (Permission denied): An attempt was made to access a file in a way - `EACCES` (Permission denied): An attempt was made to access a file in a way
forbidden by its file access permissions. forbidden by its file access permissions.
@ -2126,6 +2133,7 @@ such as `process.stdout.on('data')`.
[`crypto.scryptSync()`]: crypto.html#crypto_crypto_scryptsync_password_salt_keylen_options [`crypto.scryptSync()`]: crypto.html#crypto_crypto_scryptsync_password_salt_keylen_options
[`crypto.timingSafeEqual()`]: crypto.html#crypto_crypto_timingsafeequal_a_b [`crypto.timingSafeEqual()`]: crypto.html#crypto_crypto_timingsafeequal_a_b
[`dgram.createSocket()`]: dgram.html#dgram_dgram_createsocket_options_callback [`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.readFileSync`]: fs.html#fs_fs_readfilesync_path_options
[`fs.readdir`]: fs.html#fs_fs_readdir_path_options_callback [`fs.readdir`]: fs.html#fs_fs_readdir_path_options_callback
[`fs.symlink()`]: fs.html#fs_fs_symlink_target_path_type_callback [`fs.symlink()`]: fs.html#fs_fs_symlink_target_path_type_callback
@ -2165,7 +2173,6 @@ such as `process.stdout.on('data')`.
[domains]: domain.html [domains]: domain.html
[event emitter-based]: events.html#events_class_eventemitter [event emitter-based]: events.html#events_class_eventemitter
[file descriptors]: https://en.wikipedia.org/wiki/File_descriptor [file descriptors]: https://en.wikipedia.org/wiki/File_descriptor
[online]: http://man7.org/linux/man-pages/man3/errno.3.html
[stream-based]: stream.html [stream-based]: stream.html
[syscall]: http://man7.org/linux/man-pages/man2/syscalls.2.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 [try-catch]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch