Moved all the URLs in API docs to the bottom of the files as
reference-style links.
PR-URL: https://github.com/nodejs/node/pull/3845
Reviewed-By: James M Snell <jasnell@gmail.com>
See also: [`child_process.exec()`](#child_process_child_process_exec_command_options_callback) and [`child_process.fork()`](#child_process_child_process_fork_modulepath_args_options)
See also: [`child_process.exec()`][] and [`child_process.fork()`][]
## Synchronous Process Creation
@ -703,11 +699,7 @@ process has exited.
If the process times out, or has a non-zero exit code, this method ***will***
throw. The `Error` object will contain the entire result from
Errors generated by Node.js fall into two categories: JavaScript errors and system
errors. All errors inherit from or are instances of JavaScript's [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)
errors. All errors inherit from or are instances of JavaScript's [Error][]
class and are guaranteed to provide *at least* the attributes available on that
class.
@ -16,7 +16,7 @@ opportunity to **intercept** this error based on how the API **propagates** it.
The style of API called determines how generated errors are handed back, or
**propagated**, to client code, which in turn informs how the client may **intercept**
the error. Exceptions can be intercepted using the `try / catch` construct;
other propagation strategies are covered [below](#errors_error_propagation_and_interception).
other propagation strategies are covered [below][].
## Error Propagation and Interception
@ -26,11 +26,9 @@ All Node.js APIs will treat invalid arguments as exceptional -- that is, if pass
invalid arguments, they will *immediately* generate and throw the error as an
exception, even if they are an otherwise asynchronous API.
Synchronous APIs (like
[fs.readFileSync](fs.html#fs_fs_readfilesync_filename_options)) will throw the
error. The act of *throwing* a value (in this case, the error) turns the value
into an **exception**. Exceptions may be caught using the `try { } catch(err)
{ }` construct.
Synchronous APIs (like [fs.readFileSync][]) will throw the error. The act of
*throwing* a value (in this case, the error) turns the value into an **exception**.
Exceptions may be caught using the `try { } catch(err) { }` construct.
Asynchronous APIs have **two** mechanisms for error propagation; one mechanism
for APIs that represent a single operation, and one for APIs that represent
@ -41,12 +39,12 @@ multiple operations over time.
<!--type=misc-->
The other mechanism for providing errors is the "error" event. This is
typically used by [stream-based](stream.html) and [event emitter-based](events.html#events_class_events_eventemitter) APIs, which
typically used by [stream-based][] and [event emitter-based][] APIs, which
themselves represent a series of asynchronous operations over time (versus a
single operation that may pass or fail). If no "error" event handler is
attached to the source of the error, the error will be thrown. At this point,
it will crash the process as an unhandled exception unless [domains](domain.html) are
employed appropriately or [process.on('uncaughtException')](process.html#process_event_uncaughtexception) has a handler.
it will crash the process as an unhandled exception unless [domains][] are
employed appropriately or [process.on('uncaughtException')][] has a handler.
```javascript
var net = require('net');
@ -131,7 +129,7 @@ try {
This will not work! By the time the node style callback has been called, the
surrounding code (including the `try { } catch(err) { }` will have already
exited. Throwing an error inside a node style callback **will crash the process** in most cases.
If [domains](domain.html) are enabled, they may intercept the thrown error; similarly, if a
If [domains][] are enabled, they may intercept the thrown error; similarly, if a
handler has been added to `process.on('uncaughtException')`, it will intercept
the error.
@ -158,7 +156,7 @@ errors as well as plain JavaScript errors.
Instantiates a new Error object and sets its `.message` property to the provided
message. Its `.stack` will represent the point in the program at which `new Error`
was called. Stack traces are subject to [V8's stack trace API](https://code.google.com/p/v8-wiki/wiki/JavaScriptStackTraceApi).
was called. Stack traces are subject to [V8's stack trace API][].
Stack traces only extend to the beginning of synchronous code execution, *or* a number of frames given by
`Error.stackTraceLimit`, whichever is smaller.
@ -328,7 +326,7 @@ dependencies.
A subclass of Error that indicates that a program is not valid JavaScript.
These errors may only be generated and propagated as a result of code
evaluation. Code evaluation may happen as a result of `eval`, `Function`,
`require`, or [vm](vm.html). These errors are almost always indicative of a broken
`require`, or [vm][]. These errors are almost always indicative of a broken
program.
```javascript
@ -372,7 +370,7 @@ System errors are generated in response to a program's runtime environment.
Ideally, they represent operational errors that the program needs to be able to
react to. They are 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](http://man7.org/linux/man-pages/man3/errno.3.html).
on most Unices; or [online][].
In Node.js, system errors are represented as augmented Error objects -- not full
subclasses, but instead an error instance with added members.
@ -387,12 +385,12 @@ letters, and may be referenced in `man 2 intro`.
#### error.syscall
A string representing the [syscall](http://man7.org/linux/man-pages/man2/syscall.2.html) that failed.
A string representing the [syscall][] that failed.
### Common System Errors
This list is **not exhaustive**, but enumerates many of the common system errors when
writing a Node.js program. An exhaustive list may be found [here](http://man7.org/linux/man-pages/man3/errno.3.html).
writing a Node.js program. An exhaustive list may be found [here][online].
#### EACCES: Permission denied
@ -401,7 +399,7 @@ permissions.
#### EADDRINUSE: Address already in use
An attempt to bind a server ([net](net.html), [http](http.html), or [https](https.html)) to a local
An attempt to bind a server ([net][], [http][], or [https][]) to a local
address failed due to another server on the local system already occupying
that address.
@ -415,7 +413,7 @@ on the foreign host.
A connection was forcibly closed by a peer. This normally results
from a loss of the connection on the remote socket due to a timeout
or reboot. Commonly encountered via the [http](http.html) and [net](net.html) modules.
or reboot. Commonly encountered via the [http][] and [net][] modules.
#### EEXIST: File exists
@ -428,7 +426,7 @@ An operation expected a file, but the given pathname was a directory.
#### EMFILE: Too many open files in system
Maximum number of [file descriptors](http://en.wikipedia.org/wiki/File_descriptor) allowable on the system has
Maximum number of [file descriptors][] allowable on the system has
been reached, and requests for another descriptor cannot be fulfilled until
at least one has been closed.
@ -439,18 +437,18 @@ that will run the Node.js process.
#### ENOENT: No such file or directory
Commonly raised by [fs](fs.html) operations; a component of the specified pathname
Commonly raised by [fs][] operations; a component of the specified pathname
does not exist -- no entity (file or directory) could be found by the given path.
#### ENOTDIR: Not a directory
A component of the given pathname existed, but was not a directory as expected.
Commonly raised by [fs.readdir](fs.html#fs_fs_readdir_path_callback).
Commonly raised by [fs.readdir][].
#### ENOTEMPTY: Directory not empty
A directory with entries was the target of an operation that requires
an empty directory -- usually [fs.unlink](fs.html#fs_fs_unlink_path_callback).
an empty directory -- usually [fs.unlink][].
#### EPERM: Operation not permitted
@ -460,11 +458,30 @@ privileges.
#### EPIPE: Broken pipe
A write on a pipe, socket, or FIFO for which there is no process to read the
data. Commonly encountered at the [net](net.html) and [http](http.html) layers, indicative that
data. Commonly encountered at the [net][] and [http][] layers, indicative that
the remote side of the stream being written to has been closed.
#### ETIMEDOUT: Operation timed out
A connect or send request failed because the connected party did not properly
respond after a period of time. Usually encountered by [http](http.html) or [net](net.html) --
respond after a period of time. Usually encountered by [http][] or [net][] --
often a sign that a connected socket was not `.end()`'d appropriately.
Bryan English
9 years ago
Jeremiah Senkpiel