Skip to content

Commit 2143b56

Browse files
TrottBridgeAR
authored andcommitted
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. PR-URL: #24090 Fixes: #23975 Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
1 parent a2e2c91 commit 2143b56

File tree

1 file changed

+50
-43
lines changed

1 file changed

+50
-43
lines changed

doc/api/errors.md

+50-43
Original file line numberDiff line numberDiff line change
@@ -441,86 +441,93 @@ checks or `abort()` calls in the C++ layer.
441441

442442
## System Errors
443443

444-
System errors are generated when exceptions occur within the Node.js
445-
runtime environment. Typically, these are operational errors that occur
446-
when an application violates an operating system constraint such as attempting
447-
to read a file that does not exist or when the user does not have sufficient
448-
permissions.
444+
Node.js generates system errors when exceptions occur within its runtime
445+
environment. These usually occur when an application violates an operating
446+
system constraint. For example, a system error will occur if an application
447+
attempts to read a file that does not exist.
449448

450-
System errors are typically generated at the syscall level: an exhaustive list
451-
of error codes and their meanings is available by running `man 2 intro` or
452-
`man 3 errno` on most Unices; or [online][].
449+
System errors are usually generated at the syscall level. For a comprehensive
450+
list, see the [`errno`(3) man page][].
453451

454-
In Node.js, system errors are represented as augmented `Error` objects with
455-
added properties.
452+
In Node.js, system errors are `Error` objects with extra properties.
456453

457454
### Class: SystemError
458455

459-
#### error.info
456+
* `address` {string} If present, the address to which a network connection
457+
failed
458+
* `code` {string} The string error code
459+
* `dest` {string} If present, the file path destination when reporting a file
460+
system error
461+
* `errno` {number|string} The system-provided error number
462+
* `info` {Object} If present, extra details about the error condition
463+
* `message` {string} A system-provided human-readable description of the error
464+
* `path` {string} If present, the file path when reporting a file system error
465+
* `port` {number} If present, the network connection port that is not available
466+
* `syscall` {string} The name of the system call that triggered the error
460467

461-
`SystemError` instances may have an additional `info` property whose
462-
value is an object with additional details about the error conditions.
468+
#### error.address
463469

464-
The following properties are provided:
470+
* {string}
465471

466-
* `code` {string} The string error code
467-
* `errno` {number} The system-provided error number
468-
* `message` {string} A system-provided human readable description of the error
469-
* `syscall` {string} The name of the system call that triggered the error
470-
* `path` {Buffer} When reporting a file system error, the `path` will identify
471-
the file path.
472-
* `dest` {Buffer} When reporting a file system error, the `dest` will identify
473-
the file path destination (if any).
472+
If present, `error.address` is a string describing the address to which a
473+
network connection failed.
474474

475475
#### error.code
476476

477477
* {string}
478478

479-
The `error.code` property is a string representing the error code, which is
480-
typically `E` followed by a sequence of capital letters.
479+
The `error.code` property is a string representing the error code.
480+
481+
#### error.dest
482+
483+
* {string}
484+
485+
If present, `error.dest` is the file path destination when reporting a file
486+
system error.
481487

482488
#### error.errno
483489

484490
* {string|number}
485491

486-
The `error.errno` property is a number or a string.
487-
The number is a **negative** value which corresponds to the error code defined
488-
in [`libuv Error handling`]. See `uv-errno.h` header file
489-
(`deps/uv/include/uv-errno.h` in the Node.js source tree) for details. In case
492+
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
493+
[`libuv Error handling`]. See the libuv `errno.h` header file
494+
(`deps/uv/include/uv/errno.h` in the Node.js source tree) for details. In case
490495
of a string, it is the same as `error.code`.
491496

492-
#### error.syscall
497+
#### error.info
493498

494-
* {string}
499+
* {Object}
495500

496-
The `error.syscall` property is a string describing the [syscall][] that failed.
501+
If present, `error.info` is an object with details about the error condition.
497502

498-
#### error.path
503+
#### error.message
499504

500505
* {string}
501506

502-
When present (e.g. in `fs` or `child_process`), the `error.path` property is a
503-
string containing a relevant invalid pathname.
507+
`error.message` is a system-provided human-readable description of the error.
504508

505-
#### error.address
509+
#### error.path
506510

507511
* {string}
508512

509-
When present (e.g. in `net` or `dgram`), the `error.address` property is a
510-
string describing the address to which the connection failed.
513+
If present, `error.path` is a string containing a relevant invalid pathname.
511514

512515
#### error.port
513516

514517
* {number}
515518

516-
When present (e.g. in `net` or `dgram`), the `error.port` property is a number
517-
representing the connection's port that is not available.
519+
If present, `error.port` is the network connection port that is not available.
520+
521+
#### error.syscall
522+
523+
* {string}
524+
525+
The `error.syscall` property is a string describing the [syscall][] that failed.
518526

519527
### Common System Errors
520528

521-
This list is **not exhaustive**, but enumerates many of the common system
522-
errors encountered when writing a Node.js program. An exhaustive list may be
523-
found [here][online].
529+
This is a list of system errors commonly-encountered when writing a Node.js
530+
program. For a comprehensive list, see the [`errno`(3) man page][].
524531

525532
- `EACCES` (Permission denied): An attempt was made to access a file in a way
526533
forbidden by its file access permissions.
@@ -2126,6 +2133,7 @@ such as `process.stdout.on('data')`.
21262133
[`crypto.scryptSync()`]: crypto.html#crypto_crypto_scryptsync_password_salt_keylen_options
21272134
[`crypto.timingSafeEqual()`]: crypto.html#crypto_crypto_timingsafeequal_a_b
21282135
[`dgram.createSocket()`]: dgram.html#dgram_dgram_createsocket_options_callback
2136+
[`errno`(3) man page]: http://man7.org/linux/man-pages/man3/errno.3.html
21292137
[`fs.readFileSync`]: fs.html#fs_fs_readfilesync_path_options
21302138
[`fs.readdir`]: fs.html#fs_fs_readdir_path_options_callback
21312139
[`fs.symlink()`]: fs.html#fs_fs_symlink_target_path_type_callback
@@ -2165,7 +2173,6 @@ such as `process.stdout.on('data')`.
21652173
[domains]: domain.html
21662174
[event emitter-based]: events.html#events_class_eventemitter
21672175
[file descriptors]: https://en.wikipedia.org/wiki/File_descriptor
2168-
[online]: http://man7.org/linux/man-pages/man3/errno.3.html
21692176
[stream-based]: stream.html
21702177
[syscall]: http://man7.org/linux/man-pages/man2/syscalls.2.html
21712178
[try-catch]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch

0 commit comments

Comments
 (0)