the event loop until the spawned process either exits of is terminated.
For convenience, the `child_process` module provides a handful of synchronous
-and asynchronous alternatives to `child_process.spawn()` and
-`child_process.spawnSync()`, each of which are documented fully [below][].
-*Note that each of these alternatives are implemented on top of
-`child_process.spawn()` or `child_process.spawnSync()`.*
+and asynchronous alternatives to [`child_process.spawn()`][] and
+[`child_process.spawnSync()`][]. *Note that each of these alternatives are
+implemented on top of `child_process.spawn()` or `child_process.spawnSync()`.*
* `child_process.exec()`: spawns a shell and runs a command within that shell,
passing the `stdout` and `stderr` to a callback function when complete.
(Default: `process.execArgv`)
* `silent` {Boolean} If true, stdin, stdout, and stderr of the child will be
piped to the parent, otherwise they will be inherited from the parent, see
- the `'pipe'` and `'inherit'` options for [`spawn()`][]'s [`stdio`][] for more details
+ the `'pipe'` and `'inherit'` options for [`spawn()`][]'s [`stdio`][] for
+ more details
(default is false)
* `uid` {Number} Sets the user identity of the process. (See setuid(2).)
* `gid` {Number} Sets the group identity of the process. (See setgid(2).)
* `cwd` {String} Current working directory of the child process
* `env` {Object} Environment key-value pairs
* `stdio` {Array|String} Child's stdio configuration. (See
- [below](#child_process_options_stdio))
+ [`options.stdio`][])
* `detached` {Boolean} Prepare child to run independently of its parent
process. Specific behavior depends on the platform, see
- [below](#child_process_options_detached))
+ [`options.detached`][])
* `uid` {Number} Sets the user identity of the process. (See setuid(2).)
* `gid` {Number} Sets the group identity of the process. (See setgid(2).)
* return: {ChildProcess object}
[`EventEmitters`]: events.html#events_class_events_eventemitter
[`net.Server`]: net.html#net_class_net_server
[`net.Socket`]: net.html#net_class_net_socket
+[`options.detached`]: #child_process_options_detached
+[`options.stdio`]: #child_process_options_stdio
[`stdio`]: #child_process_options_stdio
-[below]: #child_process_asynchronous_process_creation
[synchronous counterparts]: #child_process_synchronous_process_creation
[RFC 2412][], but see [Caveats][]) and `'modp14'`, `'modp15'`,
`'modp16'`, `'modp17'`, `'modp18'` (defined in [RFC 3526][]). The
returned object mimics the interface of objects created by
-[`crypto.createDiffieHellman()`][] above, but will not allow changing
+[`crypto.createDiffieHellman()`][], but will not allow changing
the keys (with [`diffieHellman.setPublicKey()`][] for example). The
advantage of using this method is that the parties do not have to
generate nor exchange a group modulus beforehand, saving both processor
[OpenSSL's SPKAC implementation]: https://www.openssl.org/docs/apps/spkac.html
[`createCipher()`]: #crypto_crypto_createcipher_algorithm_password
[`createCipheriv()`]: #crypto_crypto_createcipheriv_algorithm_key_iv
+[`createHash()`]: #crypto_crypto_createhash_algorithm
[`crypto.createDecipher`]: #crypto_crypto_createdecipher_algorithm_password
[`crypto.createDecipheriv`]: #crypto_crypto_createdecipheriv_algorithm_key_iv
[`crypto.createDiffieHellman()`]: #crypto_crypto_creatediffiehellman_prime_prime_encoding_generator_generator_encoding
`getaddrinfo` flags. If `hints` is not provided, then no flags are passed to
`getaddrinfo`. Multiple flags can be passed through `hints` by logically
`OR`ing their values.
- See [supported `getaddrinfo` flags][] below for more information on supported
+ See [supported `getaddrinfo` flags][] for more information on supported
flags.
* `all`: {Boolean} - When `true`, the callback returns all resolved addresses
in an array, otherwise returns a single address. Defaults to `false`.
The `callback` function has arguments `(err, addresses)`. When successful,
`addresses` will be an array. The type of each item in `addresses` is
determined by the record type, and described in the documentation for the
-corresponding lookup methods below.
+corresponding lookup methods.
On error, `err` is an [`Error`][] object, where `err.code` is
-one of the error codes listed below.
+one of the error codes listed [here](#dns_error_codes).
## dns.resolve4(hostname, callback)
is an array of resolved hostnames for the given `ip`.
On error, `err` is an [`Error`][] object, where `err.code` is
-one of the error codes listed below.
+one of the [DNS error codes][].
## dns.setServers(servers)
They do not use the same set of configuration files than what [`dns.lookup()`][]
uses. For instance, _they do not use the configuration from `/etc/hosts`_.
+[DNS error codes]: #dns_error_codes
[`dns.lookup()`]: #dns_dns_lookup_hostname_options_callback
[`dns.resolve()`]: #dns_dns_resolve_hostname_rrtype_callback
[`dns.resolve4()`]: #dns_dns_resolve4_hostname_callback
loop tick.
System-level errors are generated as augmented `Error` instances, which are
-detailed [below](#errors_system_errors).
+detailed [here](#errors_system_errors).
## Class: RangeError
[`process.on('uncaughtException')`]: process.html#process_event_uncaughtexception
[`try / catch` construct]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch
[`try { } catch(err) { }`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch
-[below]: #errors_error_propagation_and_interception
[domains]: domain.html
[event emitter-based]: events.html#events_class_events_eventemitter
[file descriptors]: https://en.wikipedia.org/wiki/File_descriptor
## fs.stat(path, callback)
Asynchronous stat(2). The callback gets two arguments `(err, stats)` where
-`stats` is a [`fs.Stats`][] object. See the [`fs.Stats`][] section below for more
+`stats` is a [`fs.Stats`][] object. See the [`fs.Stats`][] section for more
information.
## fs.statSync(path)
indicates whether the process should continue to run as long as files are being
watched. `recursive` indicates whether all subdirectories should be watched, or
only the current directory. This applies when a directory is specified, and only
-on supported platforms (See Caveats below).
+on supported platforms (See [Caveats][]).
The default is `{ persistent: true, recursive: false }`.
[`Buffer.byteLength`]: buffer.html#buffer_class_method_buffer_bytelength_string_encoding
[`Buffer`]: buffer.html#buffer_buffer
+[Caveats]: #fs_caveats
[`fs.access()`]: #fs_fs_access_path_mode_callback
[`fs.accessSync()`]: #fs_fs_accesssync_path_mode
[`fs.appendFile()`]: fs.html#fs_fs_appendfile_file_data_options_callback
KeepAlive.
If you opt into using HTTP KeepAlive, you can create an Agent object
-with that flag set to `true`. (See the [constructor options][] below.)
+with that flag set to `true`. (See the [constructor options][].)
Then, the Agent will keep unused sockets in a pool for later use. They
will be explicitly marked so as to not keep the Node.js process running.
However, it is still a good idea to explicitly [`destroy()`][] KeepAlive
collide or form cycles.
Since Node.js looks up the `realpath` of any modules it loads (that is,
-resolves symlinks), and then looks for their dependencies in the
-`node_modules` folders as described above, this situation is very simple to
-resolve with the following architecture:
+resolves symlinks), and then looks for their dependencies in the `node_modules`
+folders as described [here](#modules_loading_from_node_modules_folders), this
+situation is very simple to resolve with the following architecture:
* `/usr/lib/node/foo/1.2.3/` - Contents of the `foo` package, version 1.2.3.
* `/usr/lib/node/bar/4.3.2/` - Contents of the `bar` package that `foo`
## path.format(pathObject)
-Returns a path string from an object, the opposite of `path.parse` above.
+Returns a path string from an object, the opposite of [`path.parse`][].
path.format({
root : "/",
Provide access to aforementioned `path` methods but always interact in a win32
compatible way.
+
+[`path.parse`]: #path_path_parse_pathstring
error like you would for other `'unhandledRejection'` events. To address
this, you can either attach a dummy `.catch(function() { })` handler to
`resource.loaded`, preventing the `'unhandledRejection'` event from being
-emitted, or you can use the `'rejectionHandled'` event. Below is an
-explanation of how to do that.
+emitted, or you can use the [`'rejectionHandled'`][] event.
## Exit Codes
[`net.Socket`]: net.html#net_class_net_socket
[`process.exit()`]: #process_process_exit_code
[`promise.catch(...)`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch
+[`'rejectionHandled'`]: #process_event_rejectionhandled
[`require.main`]: modules.html#modules_accessing_the_main_module
[`setTimeout(fn, 0)`]: timers.html#timers_settimeout_callback_delay_arg
[Signal Events]: #process_signal_events
format. This variable has now been deprecated, and your REPL history will
automatically be converted to using plain text. The new file will be saved to
either your home directory, or a directory defined by the `NODE_REPL_HISTORY`
-variable, as documented below.
+variable, as documented [here](#repl_environment_variable_options).
## REPL Features
Duplex.
If a stream is both Readable and Writable, then it implements all of
-the methods and events below. So, a [Duplex][] or [Transform][] stream is
+the methods and events. So, a [Duplex][] or [Transform][] stream is
fully described by this API, though their implementation may be
somewhat different.
It is not necessary to implement Stream interfaces in order to consume
streams in your programs. If you **are** implementing streaming
interfaces in your own program, please also refer to
-[API for Stream Implementors][] below.
+[API for Stream Implementors][].
Almost all Node.js programs, no matter how simple, use Streams in some
way. Here is an example of using Streams in an Node.js program:
### Class: stream.Duplex
Duplex streams are streams that implement both the [Readable][] and
-[Writable][] interfaces. See above for usage.
+[Writable][] interfaces.
Examples of Duplex streams include:
has been triggered; a runtime error will be raised.
If you find that you must often call `stream.unshift(chunk)` in your
-programs, consider implementing a [Transform][] stream instead. (See API
-for Stream Implementors, below.)
+programs, consider implementing a [Transform][] stream instead. (See [API
+for Stream Implementors][].)
```javascript
// Pull off a header delimited by \n\n
* `stream` {Stream} An "old style" readable stream
Versions of Node.js prior to v0.10 had streams that did not implement the
-entire Streams API as it is today. (See "Compatibility" below for
+entire Streams API as it is today. (See [Compatibility][] for
more information.)
If you are using an older Node.js library that emits `'data'` events and
Transform streams are [Duplex][] streams where the output is in some way
computed from the input. They implement both the [Readable][] and
-[Writable][] interfaces. See above for usage.
+[Writable][] interfaces.
Examples of Transform streams include:
</table>
In your implementation code, it is very important to never call the
-methods described in [API for Stream Consumers][] above. Otherwise, you
+methods described in [API for Stream Consumers][]. Otherwise, you
can potentially cause adverse side effects in programs that consume
your streaming interfaces.
`stream.Readable` is an abstract class designed to be extended with an
underlying implementation of the [`_read(size)`][] method.
-Please see above under [API for Stream Consumers][] for how to consume
+Please see [API for Stream Consumers][] for how to consume
streams in your programs. What follows is an explanation of how to
implement Readable streams in your programs.
#### Example: SimpleProtocol v1 (Sub-optimal)
-This is similar to the `parseHeader` function described above, but
-implemented as a custom stream. Also, note that this implementation
-does not convert the incoming data to a string.
+This is similar to the `parseHeader` function described
+[here](#stream_readable_unshift_chunk), but implemented as a custom stream.
+Also, note that this implementation does not convert the incoming data to a
+string.
However, this would be better implemented as a [Transform][] stream. See
-below for a better implementation.
+[SimpleProtocol v2][] for a better implementation.
```javascript
// A parser for a simple data protocol.
#### Example: `SimpleProtocol` parser v2
-The example above of a simple protocol parser can be implemented
-simply by using the higher level [Transform][] stream class, similar to
-the `parseHeader` and `SimpleProtocol v1` examples above.
+The example [here](#stream_example_simpleprotocol_v1_sub_optimal) of a simple
+protocol parser can be implemented simply by using the higher level
+[Transform][] stream class, similar to the `parseHeader` and `SimpleProtocol
+v1` examples.
In this example, rather than providing the input as an argument, it
would be piped into the parser, which is a more idiomatic Node.js stream
`stream.Writable` is an abstract class designed to be extended with an
underlying implementation of the [`_write(chunk, encoding, callback)`][] method.
-Please see above under [API for Stream Consumers][] for how to consume
+Please see [API for Stream Consumers][] for how to consume
writable streams in your programs. What follows is an explanation of
how to implement Writable streams in your programs.
meant that you still had to be prepared to receive `'data'` events
even when the stream was in a paused state.
-In Node.js v0.10, the Readable class described below was added.
+In Node.js v0.10, the [Readable][] class was added.
For backwards compatibility with older Node.js programs, Readable streams
switch into "flowing mode" when a `'data'` event handler is added, or
when the [`resume()`][] method is called. The effect is that, even if
[API for Stream Implementors]: #stream_api_for_stream_implementors
[child process stdin]: child_process.html#child_process_child_stdin
[child process stdout and stderr]: child_process.html#child_process_child_stdout
+[Compatibility]: #stream_compatibility_with_older_node_js_versions
[crypto streams]: crypto.html
[crypto]: crypto.html
[Duplex]: #stream_class_stream_duplex
[Object mode]: #stream_object_mode
[Readable]: #stream_class_stream_readable
[request to an HTTP server]: http.html#http_http_incomingmessage
+[SimpleProtocol v2]: #stream_example_simpleprotocol_parser_v2
[tcp sockets]: net.html#net_class_net_socket
[Transform]: #stream_class_stream_transform
[unpiped]: #stream_readable_unpipe_destination
`2`. To make it recurse indefinitely pass `null`.
- `colors` - if `true`, then the output will be styled with ANSI color codes.
- Defaults to `false`. Colors are customizable, see below.
+ Defaults to `false`. Colors are customizable, see [Customizing
+ `util.inspect` colors][].
- `customInspect` - if `false`, then custom `inspect(depth, opts)` functions
defined on the objects being inspected won't be called. Defaults to `true`.
[`Array.isArray`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray
[constructor]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/constructor
+[Customizing `util.inspect` colors]: #util_customizing_util_inspect_colors
+[here]: #util_customizing_util_inspect_colors
[`Error`]: errors.html#errors_class_error
**Note: these examples are drastically simplified to show
the basic concept.** Zlib encoding can be expensive, and the results
-ought to be cached. See [Memory Usage Tuning][] below for more information
+ought to be cached. See [Memory Usage Tuning][] for more information
on the speed/memory/compression tradeoffs involved in zlib usage.
// client request example
projects / platform / upstream / nodejs.git / commitdiff