- V8 JavaScript, a C++ library. Used for interfacing with JavaScript:
creating objects, calling functions, etc. Documented mostly in the
`v8.h` header file (`deps/v8/include/v8.h` in the Node.js source
- tree), which is also available
- [online](https://v8docs.nodesource.com/).
+ tree), which is also available [online][].
- - [libuv](https://github.com/libuv/libuv), C event loop library.
- Anytime one needs to wait for a file descriptor to become readable,
- wait for a timer, or wait for a signal to be received one will need
- to interface with libuv. That is, if you perform any I/O, libuv will
- need to be used.
+ - [libuv][], C event loop library. Anytime one needs to wait for a file
+ descriptor to become readable, wait for a timer, or wait for a signal
+ to be received one will need to interface with libuv. That is, if you
+ perform any I/O, libuv will need to be used.
- Internal Node.js libraries. Most importantly is the `node::ObjectWrap`
class which you will likely want to derive from.
When compiling your module, you don't need to worry about linking to
any of these libraries.
-All of the following examples are available for
-[download](https://github.com/rvagg/node-addon-examples) and may be
-used as a starting-point for your own Addon.
+All of the following examples are available for [download][] and may
+be used as a starting-point for your own Addon.
## Hello world
The source code needs to be built into `addon.node`, the binary Addon. To
do this we create a file called `binding.gyp` which describes the configuration
to build your module in a JSON-like format. This file gets compiled by
-[node-gyp](https://github.com/nodejs/node-gyp).
+[node-gyp][].
{
"targets": [
## Addon patterns
Below are some addon patterns to help you get started. Consult the online
-[v8 reference](http://izs.me/v8-docs/main.html) for help with the various v8
-calls, and v8's [Embedder's Guide](http://code.google.com/apis/v8/embed.html)
-for an explanation of several concepts used such as handles, scopes,
-function templates, etc.
+[v8 reference][] for help with the various v8 calls, and v8's
+[Embedder's Guide][] for an explanation of several concepts used such as
+handles, scopes, function templates, etc.
In order to use these examples you need to compile them using `node-gyp`.
Create the following `binding.gyp` file:
// test.js
var addon = require('./build/Release/addon');
+
+[online]: https://v8docs.nodesource.com/
+[libuv]: https://github.com/libuv/libuv
+[download]: https://github.com/rvagg/node-addon-examples
+[node-gyp]: https://github.com/nodejs/node-gyp
+[v8 reference]: http://izs.me/v8-docs/main.html
+[Embedder's Guide]: http://code.google.com/apis/v8/embed.html
## assert.doesNotThrow(block[, error][, message])
-Expects `block` not to throw an error. See [assert.throws()](#assert_assert_throws_block_error_message) for more details.
+Expects `block` not to throw an error. See [assert.throws()][] for more details.
If `block` throws an error and if it is of a different type from `error`, the
thrown error will get propagated back to the caller. The following call will
},
"unexpected error"
);
+
+[assert.throws()]: #assert_assert_throws_block_error_message
* `buf1` {Buffer}
* `buf2` {Buffer}
-The same as [`buf1.compare(buf2)`](#buffer_buf_compare_otherbuffer). Useful
-for sorting an Array of Buffers:
+The same as [`buf1.compare(buf2)`][]. Useful for sorting an Array of Buffers:
var arr = [Buffer('1234'), Buffer('0123')];
arr.sort(Buffer.compare);
* `byteOffset` Number, Optional, Default: 0
* Return: Number
-Operates similar to
-[Array#indexOf()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf).
-Accepts a String, Buffer or Number. Strings are interpreted as UTF8. Buffers
-will use the entire buffer. So in order to compare a partial Buffer use
-`Buffer#slice()`. Numbers can range from 0 to 255.
+Operates similar to [Array#indexOf()][]. Accepts a String, Buffer or Number.
+Strings are interpreted as UTF8. Buffers will use the entire buffer. So in order
+to compare a partial Buffer use `Buffer#slice()`. Numbers can range from 0 to
+255.
### buf.length
Though this should be used sparingly and only be a last resort *after* a developer
has actively observed undue memory retention in their applications.
+
+[`buf1.compare(buf2)`]: #buffer_buf_compare_otherbuffer
+[Array#indexOf()]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf
To create a child process use `require('child_process').spawn()` or
`require('child_process').fork()`. The semantics of each are slightly
-different, and explained [below](#child_process_asynchronous_process_creation).
+different, and explained [below][].
-For scripting purposes you may find the
-[synchronous counterparts](#child_process_synchronous_process_creation) more
+For scripting purposes you may find the [synchronous counterparts][] more
convenient.
## Class: ChildProcess
you are listening on both events to fire a function, remember to guard against
calling your function twice.
-See also [`ChildProcess#kill()`](#child_process_child_kill_signal) and
-[`ChildProcess#send()`](#child_process_child_send_message_sendhandle_callback).
+See also [`ChildProcess#kill()`][] and [`ChildProcess#send()`][].
### Event: 'exit'
* `callback` {Function}
* Return: Boolean
-When using [`child_process.fork()`](#child_process_child_process_fork_modulepath_args_options) you can write to the child using
+When using [`child_process.fork()`][] you can write to the child using
`child.send(message[, sendHandle][, callback])` and messages are received by
a `'message'` event on the child.
* {Array}
A sparse array of pipes to the child process, corresponding with positions in
-the [stdio](#child_process_options_stdio) option to
-[spawn](#child_process_child_process_spawn_command_args_options) that have been
-set to `'pipe'`.
+the [stdio][] option to [spawn][] that have been set to `'pipe'`.
Note that streams 0-2 are also available as ChildProcess.stdin,
ChildProcess.stdout, and ChildProcess.stderr, respectively.
* `stderr` {Buffer}
* Return: ChildProcess object
-This is similar to [`child_process.exec()`](#child_process_child_process_exec_command_options_callback) except it does not execute a
+This is similar to [`child_process.exec()`][] except it does not execute a
subshell but rather the specified file directly. This makes it slightly
-leaner than [`child_process.exec()`](#child_process_child_process_exec_command_options_callback). It has the same options.
+leaner than [`child_process.exec()`][]. It has the same options.
### child_process.fork(modulePath[, args][, options])
* `gid` {Number} Sets the group identity of the process. (See setgid(2).)
* Return: ChildProcess object
-This is a special case of the [`child_process.spawn()`](#child_process_child_process_spawn_command_args_options) functionality for spawning Node.js
-processes. In addition to having all the methods in a normal ChildProcess
-instance, the returned object has a communication channel built-in. See
-[`child.send(message, [sendHandle])`](#child_process_child_send_message_sendhandle_callback) for details.
+This is a special case of the [`child_process.spawn()`][] functionality for
+spawning Node.js processes. In addition to having all the methods in a normal
+ChildProcess instance, the returned object has a communication channel built-in.
+See [`child.send(message, [sendHandle])`][] for details.
These child Node.js processes are still whole new instances of V8. Assume at
least 30ms startup and 10mb memory for each new Node.js. That is, you cannot
// startd-style interface.
spawn('prg', [], { stdio: ['pipe', null, null, null, 'pipe'] });
-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
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
-[`child_process.spawnSync()`](#child_process_child_process_spawnsync_command_args_options)
-
-[EventEmitter]: events.html#events_class_events_eventemitter
-[net.Server]: net.html#net_class_net_server
-[net.Socket]: net.html#net_class_net_socket
+[`child_process.spawnSync()`][]
### child_process.execSync(command[, options])
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
-[`child_process.spawnSync()`](#child_process_child_process_spawnsync_command_args_options)
+[`child_process.spawnSync()`][]
### child_process.spawnSync(command[, args][, options])
until the process has completely exited. That is to say, if the process handles
the `SIGTERM` signal and doesn't exit, your process will wait until the child
process has exited.
+
+[below]: #child_process_asynchronous_process_creation
+[synchronous counterparts]: #child_process_synchronous_process_creation
+[EventEmitter]: events.html#events_class_events_eventemitter
+[`ChildProcess#kill()`]: #child_process_child_kill_signal
+[`ChildProcess#send()`]: #child_process_child_send_message_sendhandle_callback
+[net.Server]: net.html#net_class_net_server
+[net.Socket]: net.html#net_class_net_socket
+[`child_process.fork()`]: #child_process_child_process_fork_modulepath_args_options
+[stdio]: #child_process_options_stdio
+[spawn]: #child_process_child_process_spawn_command_args_options
+[`child_process.exec()`]: #child_process_child_process_exec_command_options_callback
+[`child_process.spawn()`]: #child_process_child_process_spawn_command_args_options
+[`child.send(message, [sendHandle])`]: #child_process_child_send_message_sendhandle_callback
+[`child_process.spawnSync()`]: #child_process_child_process_spawnsync_command_args_options
In a worker you can also use `process.on('error')`.
-[ChildProcess.send()]: child_process.html#child_process_child_send_message_sendhandle_callback
-
### Event: 'exit'
* `code` {Number} the exit code, if it exited normally.
Note that after a server is closed, it will no longer accept new connections,
but connections may be accepted by any other listening worker. Existing
connections will be allowed to close as usual. When no more connections exist,
-see [server.close()](net.html#net_event_close), the IPC channel to the worker
-will close allowing it to die gracefully.
+see [server.close()][], the IPC channel to the worker will close allowing it to
+die gracefully.
The above applies *only* to server connections, client connections are not
automatically closed by workers, and disconnect does not wait for them to close
before exiting.
Note that in a worker, `process.disconnect` exists, but it is not this function,
-it is [disconnect](child_process.html#child_process_child_disconnect).
+it is [disconnect][].
Because long living server connections may block workers from disconnecting, it
may be useful to send a message, so application specific actions may be taken to
This method is aliased as `worker.destroy()` for backwards compatibility.
Note that in a worker, `process.kill()` exists, but it is not this function,
-it is [kill](process.html#process_process_kill_pid_signal).
+it is [kill][].
### worker.process
from this function is stored as `.process`. In a worker, the global `process`
is stored.
-See: [Child Process module](
-child_process.html#child_process_child_process_fork_modulepath_args_options)
+See: [Child Process module][]
Note that workers will call `process.exit(0)` if the `'disconnect'` event occurs
on `process` and `.suicide` is not `true`. This protects against accidental
cluster.fork();
});
-See [child_process event: 'exit'](child_process.html#child_process_event_exit).
+See [child_process event: 'exit'][].
## Event: 'fork'
Emitted when any worker receives a message.
-See
-[child_process event: 'message'](child_process.html#child_process_event_message).
+See [child_process event: 'message'][].
## Event: 'online'
socket.on('data', function(id) {
var worker = cluster.workers[id];
});
+
+[server.close()]: net.html#net_event_close
+[disconnect]: child_process.html#child_process_child_disconnect
+[kill]: process.html#process_process_kill_pid_signal
+[Child Process module]: child_process.html#child_process_child_process_fork_modulepath_args_options
+[ChildProcess.send()]: child_process.html#child_process_child_send_message_sendhandle_callback
+[child_process event: 'exit']: child_process.html#child_process_event_exit
+[child_process event: 'message']: child_process.html#child_process_event_message.
new Console(process.stdout, process.stderr);
-[assert.ok()]: assert.html#assert_assert_value_message_assert_ok_value_message
-[util.format()]: util.html#util_util_format_format
-[customizing util.inspect colors]: util.html#util_customizing_util_inspect_colors
-
## console
* {Object}
Used to calculate the duration of a specific operation. To start a timer, call
the `console.time()` method, giving it a name as only parameter. To stop the
timer, and to get the elapsed time in milliseconds, just call the
-[`console.timeEnd()`](#console_console_timeend_label) method, again passing the
+[`console.timeEnd()`][] method, again passing the
timer's name as the parameter.
### console.timeEnd(label)
Stops a timer that was previously started by calling
-[`console.time()`](#console_console_time_label) and print the result to the
+[`console.time()`][] and prints the result to the
console.
Example:
### console.warn([data][, ...])
Same as `console.error`.
+
+[assert.ok()]: assert.html#assert_assert_value_message_assert_ok_value_message
+[customizing util.inspect colors]: util.html#util_customizing_util_inspect_colors
+[util.format()]: util.html#util_util_format_format
+[`console.timeEnd()`]: #console_console_timeend_label
+[`console.time()`]: #console_console_time_label
Returned by `crypto.createCipher` and `crypto.createCipheriv`.
-Cipher objects are [streams](stream.html) that are both readable and
-writable. The written plain text data is used to produce the
-encrypted data on the readable side. The legacy `update` and `final`
-methods are also supported.
+Cipher objects are [streams][] that are both readable and writable.
+The written plain text data is used to produce the encrypted data on
+the readable side. The legacy `update` and `final` methods are also
+supported.
### cipher.final([output_encoding])
Returned by `crypto.createDecipher` and `crypto.createDecipheriv`.
-Decipher objects are [streams](stream.html) that are both readable and
-writable. The written enciphered data is used to produce the
-plain-text data on the the readable side. The legacy `update` and
-`final` methods are also supported.
+Decipher objects are [streams][] that are both readable and writable.
+The written enciphered data is used to produce the plain-text data on
+the the readable side. The legacy `update` and `final` methods are also
+supported.
### decipher.final([output_encoding])
The class for creating hash digests of data.
-It is a [stream](stream.html) that is both readable and writable. The
-written data is used to compute the hash. Once the writable side of
-the stream is ended, use the `read()` method to get the computed hash
-digest. The legacy `update` and `digest` methods are also supported.
+It is a [stream][] that is both readable and writable. The written data
+is used to compute the hash. Once the writable side of the stream is ended,
+use the `read()` method to get the computed hash digest. The legacy `update`
+and `digest` methods are also supported.
Returned by `crypto.createHash`.
Returned by `crypto.createSign`.
-Sign objects are writable [streams](stream.html). The written data is
-used to generate the signature. Once all of the data has been
-written, the `sign` method will return the signature. The legacy
-`update` method is also supported.
+Sign objects are writable [streams][]. The written data is used to
+generate the signature. Once all of the data has been written, the
+`sign` method will return the signature. The legacy `update` method
+is also supported.
### sign.sign(private_key[, output_format])
Returned by `crypto.createVerify`.
-Verify objects are writable [streams](stream.html). The written data
-is used to validate against the supplied signature. Once all of the
-data has been written, the `verify` method will return true if the
-supplied signature is valid. The legacy `update` method is also
-supported.
+Verify objects are writable [streams][]. The written data is used to
+validate against the supplied signature. Once all of the data has been
+written, the `verify` method will return true if the supplied signature
+is valid. The legacy `update` method is also supported.
### verifier.update(data)
`algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On
recent releases, `openssl list-cipher-algorithms` will display the
available cipher algorithms. `password` is used to derive key and IV,
-which must be a `'binary'` encoded string or a [buffer](buffer.html).
+which must be a `'binary'` encoded string or a [buffer][].
-It is a [stream](stream.html) that is both readable and writable. The
-written data is used to compute the hash. Once the writable side of
-the stream is ended, use the `read()` method to get the enciphered
-contents. The legacy `update` and `final` methods are also supported.
+It is a [stream][] that is both readable and writable. The written data
+is used to compute the hash. Once the writable side of the stream is ended,
+use the `read()` method to get the enciphered contents. The legacy `update`
+and `final` methods are also supported.
Note: `createCipher` derives keys with the OpenSSL function [EVP_BytesToKey][]
with the digest algorithm set to MD5, one iteration, and no salt. The lack of
iv.
`algorithm` is the same as the argument to `createCipher()`. `key` is
-the raw key used by the algorithm. `iv` is an [initialization
-vector](http://en.wikipedia.org/wiki/Initialization_vector).
+the raw key used by the algorithm. `iv` is an [initialization vector][].
-`key` and `iv` must be `'binary'` encoded strings or
-[buffers](buffer.html).
+`key` and `iv` must be `'binary'` encoded strings or [buffers][].
## crypto.createCredentials(details)
Creates and returns a hmac object, a cryptographic hmac with the given
algorithm and key.
-It is a [stream](stream.html) that is both readable and writable. The
-written data is used to compute the hmac. Once the writable side of
-the stream is ended, use the `read()` method to get the computed
-digest. The legacy `update` and `digest` methods are also supported.
+It is a [stream][] that is both readable and writable. The written
+data is used to compute the hmac. Once the writable side of the
+stream is ended, use the `read()` method to get the computed digest.
+The legacy `update` and `digest` methods are also supported.
`algorithm` is dependent on the available algorithms supported by
OpenSSL - see createHash above. `key` is the hmac key to be used.
Creates a predefined Diffie-Hellman key exchange object. The
supported groups are: `'modp1'`, `'modp2'`, `'modp5'` (defined in
-[RFC 2412][], but see [Caveats](#crypto_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 the keys (with [diffieHellman.setPublicKey()][] for example).
-The advantage of using this routine is that the parties do not have to
+[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
+the keys (with [diffieHellman.setPublicKey()][] for example). The
+advantage of using this routine is that the parties do not have to
generate nor exchange group modulus beforehand, saving both processor
and communication time.
console.log(key.toString('hex')); // 'c5e478d...1469e50'
});
-You can get a list of supported digest functions with
-[crypto.getHashes()](#crypto_crypto_gethashes).
+You can get a list of supported digest functions with [crypto.getHashes()][].
## crypto.pbkdf2Sync(password, salt, iterations, keylen[, digest])
See the reference for other recommendations and details.
+[stream]: stream.html
+[streams]: stream.html
+[buffer]: buffer.html
+[buffers]: buffer.html
[createCipher()]: #crypto_crypto_createcipher_algorithm_password
[createCipheriv()]: #crypto_crypto_createcipheriv_algorithm_key_iv
[getCurves()]: #crypto_crypto_getcurves
[crypto.pbkdf2]: #crypto_crypto_pbkdf2_password_salt_iterations_keylen_digest_callback
[EVP_BytesToKey]: https://www.openssl.org/docs/crypto/EVP_BytesToKey.html
[NIST SP 800-131A]: http://csrc.nist.gov/publications/nistpubs/800-131A/sp800-131A.pdf
+[initialization vector]: http://en.wikipedia.org/wiki/Initialization_vector
+[Caveats]: #crypto_caveats
+[crypto.getHashes()]: #crypto_crypto_gethashes
<!-- type=misc -->
V8 comes with an extensive debugger which is accessible out-of-process via a
-simple [TCP protocol](http://code.google.com/p/v8/wiki/DebuggerProtocol).
-Node.js has a built-in client for this debugger. To use this, start Node.js with
-the `debug` argument; a prompt will appear:
+simple [TCP protocol][]. Node.js has a built-in client for this debugger. To
+use this, start Node.js with the `debug` argument; a prompt will appear:
% node debug myscript.js
< debugger listening on port 5858
* `node debug -p <pid>` - Connects to the process via the `pid`
* `node debug <URI>` - Connects to the process via the URI such as localhost:5858
+
+[TCP protocol]: http://code.google.com/p/v8/wiki/DebuggerProtocol
### socket.close([callback])
Close the underlying socket and stop listening for data on it. If a callback is
-provided, it is added as a listener for the ['close'](#dgram_event_close) event.
+provided, it is added as a listener for the ['close'][] event.
### socket.dropMembership(multicastAddress[, multicastInterface])
not given, the error is emitted as an `'error'` event on the `socket` object.
With consideration for multi-byte characters, `offset` and `length` will
-be calculated with respect to
-[byte length](buffer.html#buffer_class_method_buffer_bytelength_string_encoding)
-and not the character position.
+be calculated with respect to [byte length][] and not the character position.
Example of sending a UDP packet to a random port on `localhost`;
router, it will not be forwarded. Changing TTL values is typically done for network
probes or when multicasting.
-The argument to `setTTL()` is a number of hops between 1 and 255. The default on most
-systems is 64.
+The argument to `setTTL()` is a number of hops between 1 and 255. The default
+on most systems is 64.
### socket.ref()
bind to the "all interfaces" address on a random port (it does the right thing
for both `udp4` and `udp6` sockets). You can then retrieve the address and port
with `socket.address().address` and `socket.address().port`.
+
+['close']: #dgram_event_close
+[byte length]: buffer.html#buffer_class_method_buffer_bytelength_string_encoding
name resolution, and that do not necessarily do any network communication.
This category contains only one function: `dns.lookup()`. __Developers looking
to perform name resolution in the same way that other applications on the same
-operating system behave should use [`dns.lookup()`][dns.lookup].__
+operating system behave should use [`dns.lookup()`][].__
Here is an example that does a lookup of `www.google.com`.
2) Functions that connect to an actual DNS server to perform name resolution,
and that _always_ use the network to perform DNS queries. This category
-contains all functions in the `dns` module but [`dns.lookup()`][dns.lookup]. These functions
-do not use the same set of configuration files than what [`dns.lookup()`][dns.lookup] uses.
+contains all functions in the `dns` module but [`dns.lookup()`][]. These functions
+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`_. These
functions should be used by developers who do not want to use the underlying
operating system's facilities for name resolution, and instead want to
});
There are subtle consequences in choosing one or another, please consult the
-[Implementation considerations section](#dns_implementation_considerations)
-for more information.
+[Implementation considerations section][] for more information.
## dns.getServers()
`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](#dns_supported_getaddrinfo_flags) below
- for more information on supported flags.
+ See [supported `getaddrinfo` flags][] below 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`.
Its implementation can have subtle but important consequences on the behavior
of any Node.js program. Please take some time to consult the [Implementation
-considerations section](#dns_implementation_considerations) before using it.
+considerations section][] before using it.
## dns.lookupService(address, port, callback)
## dns.resolve4(hostname, callback)
-The same as [`dns.resolve()`](#dns_dns_resolve_hostname_rrtype_callback), but only for IPv4 queries (`A` records).
+The same as [`dns.resolve()`][], but only for IPv4 queries (`A` records).
`addresses` is an array of IPv4 addresses (e.g.
`['74.125.79.104', '74.125.79.105', '74.125.79.106']`).
## dns.resolve6(hostname, callback)
-The same as [`dns.resolve4()`](#dns_dns_resolve4_hostname_callback) except for IPv6 queries (an `AAAA` query).
+The same as [`dns.resolve4()`][] except for IPv6 queries (an `AAAA` query).
## dns.resolveCname(hostname, callback)
-The same as [`dns.resolve()`](#dns_dns_resolve_hostname_rrtype_callback), but only for canonical name records (`CNAME`
+The same as [`dns.resolve()`][], but only for canonical name records (`CNAME`
records). `addresses` is an array of the canonical name records available for
`hostname` (e.g., `['bar.example.com']`).
## dns.resolveMx(hostname, callback)
-The same as [`dns.resolve()`](#dns_dns_resolve_hostname_rrtype_callback), but only for mail exchange queries (`MX` records).
+The same as [`dns.resolve()`][], but only for mail exchange queries (`MX` records).
`addresses` is an array of MX records, each with a priority and an exchange
attribute (e.g. `[{'priority': 10, 'exchange': 'mx.example.com'},...]`).
## dns.resolveNs(hostname, callback)
-The same as [`dns.resolve()`](#dns_dns_resolve_hostname_rrtype_callback), but only for name server records (`NS` records).
+The same as [`dns.resolve()`][], but only for name server records (`NS` records).
`addresses` is an array of the name server records available for `hostname`
(e.g., `['ns1.example.com', 'ns2.example.com']`).
## dns.resolveSoa(hostname, callback)
-The same as [`dns.resolve()`](#dns_dns_resolve_hostname_rrtype_callback), but only for start of authority record queries
+The same as [`dns.resolve()`][], but only for start of authority record queries
(`SOA` record).
`addresses` is an object with the following structure:
## dns.resolveSrv(hostname, callback)
-The same as [`dns.resolve()`](#dns_dns_resolve_hostname_rrtype_callback), but only for service records (`SRV` records).
+The same as [`dns.resolve()`][], but only for service records (`SRV` records).
`addresses` is an array of the SRV records available for `hostname`. Properties
of SRV records are priority, weight, port, and name (e.g.,
`[{'priority': 10, 'weight': 5, 'port': 21223, 'name': 'service.example.com'}, ...]`).
## dns.resolveTxt(hostname, callback)
-The same as [`dns.resolve()`](#dns_dns_resolve_hostname_rrtype_callback), but only for text queries (`TXT` records).
+The same as [`dns.resolve()`][], but only for text queries (`TXT` records).
`addresses` is a 2-d array of the text records available for `hostname` (e.g.,
`[ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]`). Each sub-array contains TXT chunks of
one record. Depending on the use case, the could be either joined together or
issue, one potential solution is to increase the size of libuv's threadpool by
setting the 'UV_THREADPOOL_SIZE' environment variable to a value greater than
4 (its current default value). For more information on libuv's threadpool, see
-[the official libuv
-documentation](http://docs.libuv.org/en/latest/threadpool.html).
+[the official libuv documentation][].
### dns.resolve, functions starting with dns.resolve and dns.reverse
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`_.
+[Implementation considerations section]: #dns_implementation_considerations
+[supported `getaddrinfo` flags]: #dns_supported_getaddrinfo_flags
+[`dns.resolve()`]: #dns_dns_resolve_hostname_rrtype_callback
+[`dns.resolve4()`]: #dns_dns_resolve4_hostname_callback
+[the official libuv documentation]: http://docs.libuv.org/en/latest/threadpool.html
+[`dns.lookup()`]: #dns_dns_lookup_hostname_options_callback
-[dns.lookup]: #dns_dns_lookup_hostname_options_callback
<!--type=misc-->
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.
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
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
<!--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');
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.
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.
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
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.
#### 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
#### 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.
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
#### 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.
#### 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
#### 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.
+
+[Error]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error
+[below]: #errors_error_propagation_and_interception
+[fs.readFileSync]: fs.html#fs_fs_readfilesync_filename_options
+[stream-based]: stream.html
+[event emitter-based]: events.html#events_class_events_eventemitter
+[domains]: domain.html
+[process.on('uncaughtException')]: process.html#process_event_uncaughtexception
+[V8's stack trace API]: https://code.google.com/p/v8-wiki/wiki/JavaScriptStackTraceApi
+[vm]: vm.html
+[online]: http://man7.org/linux/man-pages/man3/errno.3.html
+[syscall]: http://man7.org/linux/man-pages/man2/syscall.2.html
+[net]: net.html
+[http]: http.html
+[https]: https.html
+[file descriptors]: http://en.wikipedia.org/wiki/File_descriptor
+[fs]: fs.html
+[fs.readdir]: fs.html#fs_fs_readdir_path_callback
+[fs.unlink]: fs.html#fs_fs_unlink_path_callback
<!--type=module-->
-Many objects in Node.js emit events: a
-[`net.Server`](net.html#net_class_net_server) emits an event each time a peer
-connects to it, a [`fs.ReadStream`](fs.html#fs_class_fs_readstream) emits an
-event when the file is
-opened. All objects which emit events are instances of `events.EventEmitter`.
+Many objects in Node.js emit events: a [`net.Server`][] emits an event each
+time a peer connects to it, a [`fs.ReadStream`][] emits an event when the file
+is opened. All objects which emit events are instances of `events.EventEmitter`.
You can access this module by doing: `require("events");`
Typically, event names are represented by a camel-cased string, however,
### EventEmitter.defaultMaxListeners
-[`emitter.setMaxListeners(n)`](#events_emitter_setmaxlisteners_n) sets the
-maximum on a per-instance basis.
+[`emitter.setMaxListeners(n)`][] sets the maximum on a per-instance basis.
This class property lets you set it for *all* `EventEmitter` instances,
current and future, effective immediately. Use with care.
-Note that [`emitter.setMaxListeners(n)`](#events_emitter_setmaxlisteners_n)
-still has precedence over `EventEmitter.defaultMaxListeners`.
+Note that [`emitter.setMaxListeners(n)`][] still has precedence over
+`EventEmitter.defaultMaxListeners`.
### emitter.addListener(event, listener)
### emitter.getMaxListeners()
Returns the current max listener value for the emitter which is either set by
-[`emitter.setMaxListeners(n)`](#events_emitter_setmaxlisteners_n) or defaults to
-[`EventEmitter.defaultMaxListeners`](#events_eventemitter_defaultmaxlisteners).
+[`emitter.setMaxListeners(n)`][] or defaults to
+[`EventEmitter.defaultMaxListeners`][].
This can be useful to increment/decrement max listeners to avoid the warning
while not being irresponsible and setting a too big number.
Returns emitter, so calls can be chained.
+[`net.Server`]: net.html#net_class_net_server
+[`fs.ReadStream`]: fs.html#fs_class_fs_readstream
+[`emitter.setMaxListeners(n)`]: #events_emitter_setmaxlisteners_n
+[`EventEmitter.defaultMaxListeners`]: #events_eventemitter_defaultmaxlisteners
[emitter.listenerCount]: #events_emitter_listenercount_type
* `filename` {String} The filename that changed (if relevant/available)
Emitted when something changes in a watched directory or file.
-See more details in [fs.watch](#fs_fs_watch_filename_options_listener).
+See more details in [fs.watch][].
### Event: 'error'
## Class: fs.ReadStream
-`ReadStream` is a [Readable Stream](stream.html#stream_class_stream_readable).
+`ReadStream` is a [Readable Stream][].
### Event: 'open'
More details can be found in the [MDN JavaScript Reference][MDN-Date]
page.
-[MDN-Date]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date
-[MDN-Date-getTime]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date/getTime
-
### Stat Time Values
The times in the stat object have the following semantics:
## Class: fs.WriteStream
-`WriteStream` is a [Writable Stream](stream.html#stream_class_stream_writable).
+`WriteStream` is a [Writable Stream][].
### Event: 'open'
## fs.existsSync(path)
-Synchronous version of [`fs.exists`](fs.html#fs_fs_exists_path_callback).
+Synchronous version of [`fs.exists`][].
Returns `true` if the file exists, `false` otherwise.
Stability: 0 - Deprecated: Use [fs.statSync][] or [fs.accessSync][] instead.
## fs.stat(path, callback)
Asynchronous stat(2). The callback gets two arguments `(err, stats)` where
-`stats` is a [fs.Stats](#fs_class_fs_stats) object. See the [fs.Stats](#fs_class_fs_stats)
-section below for more information.
+`stats` is a [fs.Stats][] object. See the [fs.Stats][] section below for more
+information.
## fs.statSync(path)
## fs.watch(filename[, options][, listener])
Watch for changes on `filename`, where `filename` is either a file or a
-directory. The returned object is a [fs.FSWatcher](#fs_class_fs_fswatcher).
+directory. The returned object is a [fs.FSWatcher][].
The second argument is optional. The `options` if provided should be an object.
The supported boolean members are `persistent` and `recursive`. `persistent`
The callback will receive the arguments `(err, written, string)` where `written`
specifies how many _bytes_ the passed string required to be written. Note that
-bytes written is not the same as string characters. See
-[Buffer.byteLength](buffer.html#buffer_class_method_buffer_bytelength_string_encoding).
+bytes written is not the same as string characters. See [Buffer.byteLength][].
Unlike when writing `buffer`, the entire string must be written. No substring
may be specified. This is because the byte offset of the resulting data may not
Synchronous versions of `fs.write()`. Returns the number of bytes written.
+[fs.watch]: #fs_fs_watch_filename_options_listener
+[Readable Stream]: stream.html#stream_class_stream_readable
+[MDN-Date]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date
+[MDN-Date-getTime]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date/getTime
+[Writable Stream]: stream.html#stream_class_stream_writable
[fs.stat]: #fs_fs_stat_path_callback
+[`fs.exists`]: fs.html#fs_fs_exists_path_callback
[fs.access]: #fs_fs_access_path_mode_callback
[fs.statSync]: #fs_fs_statsync_path
[fs.accessSync]: #fs_fs_accesssync_path_mode
+[fs.Stats]: #fs_class_fs_stats
[Buffer]: buffer.html#buffer_buffer
+[fs.FSWatcher]: #fs_class_fs_fswatcher
+[Buffer.byteLength]: buffer.html#buffer_class_method_buffer_bytelength_string_encoding
The timer functions are global variables. See the [timers][] section.
-[buffer section]: buffer.html
-[module system documentation]: modules.html
-[Modules]: modules.html#modules_modules
-[process object]: process.html#process_process
-[console]: console.html
-[timers]: timers.html
-
## clearTimeout(t)
Stop a timer that was previously created with `setTimeout()`. The callback will
cannot span more than 24.8 days.
Returns an opaque value that represents the timer.
+
+[buffer section]: buffer.html
+[module system documentation]: modules.html
+[Modules]: modules.html#modules_modules
+[process object]: process.html#process_process
+[console]: console.html
+[timers]: timers.html
KeepAlive.
If you opt into using HTTP KeepAlive, you can create an Agent object
-with that flag set to `true`. (See the [constructor
-options](#http_new_agent_options) below.) 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()`](#http_agent_destroy)
-KeepAlive agents when they are no longer in use, so that the Sockets
-will be shut down.
+with that flag set to `true`. (See the [constructor options][] below.)
+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
+agents when they are no longer in use, so that the Sockets will be shut
+down.
Sockets are removed from the agent's pool when the socket emits either
a "close" event or a special "agentRemove" event. This means that if
Listening on a file descriptor is not supported on Windows.
This function is asynchronous. The last parameter `callback` will be added as
-a listener for the ['listening'](net.html#net_event_listening) event.
-See also [net.Server.listen()](net.html#net_server_listen_handle_callback).
+a listener for the ['listening'][] event. See also [net.Server.listen()][].
### server.listen(path[, callback])
## http.createServer([requestListener])
-Returns a new instance of [http.Server](#http_class_http_server).
+Returns a new instance of [http.Server][].
The `requestListener` is a function which is automatically
added to the `'request'` event.
* Sending an Authorization header will override using the `auth` option
to compute basic authentication.
+[constructor options]: #http_new_agent_options
+[`destroy()`]: #http_agent_destroy
['checkContinue']: #http_event_checkcontinue
['listening']: net.html#net_event_listening
['response']: #http_event_response
[http.Server]: #http_class_http_server
[http.request]: #http_http_request_options_callback
[net.Server.close()]: net.html#net_server_close_callback
+['listening']: net.html#net_event_listening
[net.Server.listen(path)]: net.html#net_server_listen_path_callback
[net.Server.listen(port)]: net.html#net_server_listen_port_hostname_backlog_callback
+[net.Server.listen()]: net.html#net_server_listen_handle_callback
[response.end()]: #http_response_end_data_encoding_callback
[response.write()]: #http_response_write_chunk_encoding_callback
[response.writeContinue()]: #http_response_writecontinue
Like `http.get()` but for HTTPS.
`options` can be an object or a string. If `options` is a string, it is
-automatically parsed with [url.parse()](url.html#url_url_parse_urlstr_parsequerystring_slashesdenotehost).
+automatically parsed with [url.parse()][].
Example:
Global instance of [https.Agent][] for all HTTPS client requests.
-[http.Server#setTimeout()]: http.html#http_server_settimeout_msecs_callback
-[http.Server#timeout]: http.html#http_server_timeout
-[Agent]: #https_class_https_agent
-[globalAgent]: #https_https_globalagent
-[http.listen()]: http.html#http_server_listen_port_hostname_backlog_callback
-[http.close()]: http.html#http_server_close_callback
-[http.Agent]: http.html#http_class_http_agent
-[http.request()]: http.html#http_http_request_options_callback
-[https.Agent]: #https_class_https_agent
-[https.request()]: #https_https_request_options_callback
-[tls.connect()]: tls.html#tls_tls_connect_options_callback
-[tls.createServer()]: tls.html#tls_tls_createserver_options_secureconnectionlistener
-[SSL_METHODS]: http://www.openssl.org/docs/ssl/ssl.html#DEALING_WITH_PROTOCOL_METHODS
-
## https.request(options, callback)
Makes a request to a secure web server.
`options` can be an object or a string. If `options` is a string, it is
-automatically parsed with [url.parse()](url.html#url_url_parse_urlstr_parsequerystring_slashesdenotehost).
+automatically parsed with [url.parse()][].
All options from [http.request()][] are valid.
var req = https.request(options, function(res) {
...
}
+
+[http.Server#setTimeout()]: http.html#http_server_settimeout_msecs_callback
+[http.Server#timeout]: http.html#http_server_timeout
+[Agent]: #https_class_https_agent
+[globalAgent]: #https_https_globalagent
+[http.listen()]: http.html#http_server_listen_port_hostname_backlog_callback
+[url.parse()]: url.html#url_url_parse_urlstr_parsequerystring_slashesdenotehost
+[http.close()]: http.html#http_server_close_callback
+[http.Agent]: http.html#http_class_http_agent
+[http.request()]: http.html#http_http_request_options_callback
+[https.Agent]: #https_class_https_agent
+[https.request()]: #https_https_request_options_callback
+[tls.connect()]: tls.html#tls_tls_connect_options_callback
+[tls.createServer()]: tls.html#tls_tls_createserver_options_secureconnectionlistener
+[SSL_METHODS]: http://www.openssl.org/docs/ssl/ssl.html#DEALING_WITH_PROTOCOL_METHODS
semicolons instead of colons.)
`NODE_PATH` was originally created to support loading modules from
-varying paths before the current
-[module resolution](https://nodejs.org/api/modules.html#modules_all_together)
-algorithm was frozen.
+varying paths before the current [module resolution][] algorithm was frozen.
`NODE_PATH` is still supported, but is less necessary now that the Node.js
ecosystem has settled on a convention for locating dependent modules.
object. Since `require()` returns the `module.exports`, and the `module` is
typically *only* available within a specific module's code, it must be
explicitly exported in order to be used.
+
+[module resolution]: https://nodejs.org/api/modules.html#modules_all_together
## net.connect(options[, connectListener])
-A factory function, which returns a new ['net.Socket'](#net_class_net_socket)
-and automatically connects with the supplied `options`.
+A factory function, which returns a new ['net.Socket'][] and automatically
+connects with the supplied `options`.
-The options are passed to both the ['net.Socket'](#net_class_net_socket)
-constructor and the ['socket.connect'](#net_socket_connect_options_connectlistener)
-method.
+The options are passed to both the ['net.Socket'][] constructor and the
+['socket.connect'][] method.
The `connectListener` parameter will be added as a listener for the
['connect'][] event once.
## net.connect(path[, connectListener])
-A factory function, which returns a new unix
-['net.Socket'](#net_class_net_socket) and automatically connects to the
-supplied `path`.
+A factory function, which returns a new unix ['net.Socket'][] and automatically
+connects to the supplied `path`.
The `connectListener` parameter will be added as a listener for the
['connect'][] event once.
## net.connect(port[, host][, connectListener])
-A factory function, which returns a new
-['net.Socket'](#net_class_net_socket) and automatically connects to the
-supplied `port` and `host`.
+A factory function, which returns a new ['net.Socket'][] and automatically
+connects to the supplied `port` and `host`.
If `host` is omitted, `'localhost'` will be assumed.
## net.createConnection(options[, connectListener])
-A factory function, which returns a new ['net.Socket'](#net_class_net_socket)
-and automatically connects with the supplied `options`.
+A factory function, which returns a new ['net.Socket'][] and automatically
+connects with the supplied `options`.
-The options are passed to both the ['net.Socket'](#net_class_net_socket)
-constructor and the ['socket.connect'](#net_socket_connect_options_connectlistener)
-method.
+The options are passed to both the ['net.Socket'][] constructor and the
+['socket.connect'][] method.
The `connectListener` parameter will be added as a listener for the
['connect'][] event once.
## net.createConnection(path[, connectListener])
-A factory function, which returns a new unix
-['net.Socket'](#net_class_net_socket) and automatically connects to the
-supplied `path`.
+A factory function, which returns a new unix ['net.Socket'][] and automatically
+connects to the supplied `path`.
The `connectListener` parameter will be added as a listener for the
['connect'][] event once.
## net.createConnection(port[, host][, connectListener])
-A factory function, which returns a new
-['net.Socket'](#net_class_net_socket) and automatically connects to the
-supplied `port` and `host`.
+A factory function, which returns a new ['net.Socket'][] and automatically
+connects to the supplied `port` and `host`.
If `host` is omitted, `'localhost'` will be assumed.
[server.getConnections]: #net_server_getconnections_callback
[Readable Stream]: stream.html#stream_class_stream_readable
[stream.setEncoding()]: stream.html#stream_readable_setencoding_encoding
+['net.Socket']: #net_class_net_socket
[dns.lookup()]: dns.html#dns_dns_lookup_hostname_options_callback
+['socket.connect']: #net_socket_connect_options_connectlistener
Close the IPC channel to the parent process, allowing this child to exit
gracefully once there are no other connections keeping it alive.
-Identical to the parent process's
-[ChildProcess.disconnect()](child_process.html#child_process_child_disconnect).
+Identical to the parent process's [ChildProcess.disconnect()][].
If Node.js was not spawned with an IPC channel, `process.disconnect()` will be
undefined.
Send a signal to a process. `pid` is the process id and `signal` is the
string describing the signal to send. Signal names are strings like
'SIGINT' or 'SIGHUP'. If omitted, the signal will be 'SIGTERM'.
-See [Signal Events](#process_signal_events) and kill(2) for more information.
+See [Signal Events][] and kill(2) for more information.
Will throw an error if target does not exist, and as a special case, a signal
of `0` can be used to test for the existence of a process.
process.kill(process.pid, 'SIGHUP');
Note: When SIGUSR1 is received by Node.js it starts the debugger, see
-[Signal Events](#process_signal_events).
+[Signal Events][].
## process.mainModule
-Alternate way to retrieve
-[`require.main`](modules.html#modules_accessing_the_main_module).
-The difference is that if the main module changes at runtime, `require.main`
-might still refer to the original main module in modules that were required
-before the change occurred. Generally it's safe to assume that the two refer
-to the same module.
+Alternate way to retrieve [`require.main`][]. The difference is that if the main
+module changes at runtime, `require.main` might still refer to the original main
+module in modules that were required before the change occurred. Generally it's
+safe to assume that the two refer to the same module.
As with `require.main`, it will be `undefined` if there was no entry script.
When Node.js is spawned with an IPC channel attached, it can send messages to its
parent process using `process.send()`. Each will be received as a
-['message'](child_process.html#child_process_event_message)
-event on the parent's `ChildProcess` object.
+['message'][] event on the parent's `ChildProcess` object.
If Node.js was not spawned with an IPC channel, `process.send()` will be undefined.
As a Stream, `process.stdin` can also be used in "old" mode that is compatible
with scripts written for node.js prior to v0.10.
-For more information see
-[Stream compatibility](stream.html#stream_compatibility_with_older_node_js_versions).
+For more information see [Stream compatibility][].
In "old" Streams mode the stdin stream is paused by default, so one
must call `process.stdin.resume()` to read from it. Note also that calling
$ node -p "Boolean(process.stdout.isTTY)" | cat
false
-See [the tty docs](tty.html#tty_tty) for more information.
+See [the tty docs][] for more information.
## process.title
icu: '55.1',
openssl: '1.0.1k' }
-
+[ChildProcess.disconnect()]: child_process.html#child_process_child_disconnect
[ChildProcess.send()]: child_process.html#child_process_child_send_message_sendhandle_callback
+[Signal Events]: #process_signal_events
[EventEmitter]: events.html#events_class_events_eventemitter
[net.Server]: net.html#net_class_net_server
[net.Socket]: net.html#net_class_net_socket
+[`require.main`]: modules.html#modules_accessing_the_main_module
+['message']: child_process.html#child_process_event_message
+[Stream compatibility]: stream.html#stream_compatibility_with_older_node_js_versions
+[the tty docs]: tty.html#tty_tty
Stability: 2 - Stable
-[Punycode.js](https://mths.be/punycode) is bundled with Node.js v0.6.2+. Use
-`require('punycode')` to access it. (To use it with other Node.js versions, use
-npm to install the `punycode` module first.)
+[Punycode.js][] is bundled with Node.js v0.6.2+. Use `require('punycode')` to
+access it. (To use it with other Node.js versions, use npm to install the
+`punycode` module first.)
## punycode.decode(string)
### punycode.ucs2.decode(string)
Creates an array containing the numeric code point values of each Unicode
-symbol in the string. While [JavaScript uses UCS-2
-internally](http://mathiasbynens.be/notes/javascript-encoding), this function
+symbol in the string. While [JavaScript uses UCS-2 internally][], this function
will convert a pair of surrogate halves (each of which UCS-2 exposes as
separate characters) into a single code point, matching UTF-16.
## punycode.version
A string representing the current Punycode.js version number.
+
+[Punycode.js]: https://mths.be/punycode
+[JavaScript uses UCS-2 internally]: http://mathiasbynens.be/notes/javascript-encoding
Stability: 2 - Stable
A stream is an abstract interface implemented by various objects in
-Node.js. For example a [request to an HTTP
-server](http.html#http_http_incomingmessage) is a stream, as is
+Node.js. For example a [request to an HTTP server][] is a stream, as is
[stdout][]. Streams are readable, writable, or both. All streams are
instances of [EventEmitter][]
Examples of readable streams include:
-* [http responses, on the client](http.html#http_http_incomingmessage)
-* [http requests, on the server](http.html#http_http_incomingmessage)
-* [fs read streams](fs.html#fs_class_fs_readstream)
+* [http responses, on the client][]
+* [http requests, on the server][]
+* [fs read streams][]
* [zlib streams][]
* [crypto streams][]
* [tcp sockets][]
Examples of writable streams include:
-* [http requests, on the client](http.html#http_class_http_clientrequest)
-* [http responses, on the server](http.html#http_class_http_serverresponse)
-* [fs write streams](fs.html#fs_class_fs_writestream)
+* [http requests, on the client][]
+* [http responses, on the server][]
+* [fs write streams][]
* [zlib streams][]
* [crypto streams][]
* [tcp sockets][]
-* [child process stdin](child_process.html#child_process_child_stdin)
+* [child process stdin][]
* [process.stdout][], [process.stderr][]
#### Event: 'drain'
approach, because it almost certainly indicates that something is
horribly wrong.
+[request to an HTTP server]: http.html#http_http_incomingmessage
[EventEmitter]: events.html#events_class_events_eventemitter
[Object mode]: #stream_object_mode
[`stream.push(chunk)`]: #stream_readable_push_chunk_encoding
[`unpipe()`]: #stream_readable_unpipe_destination
[unpiped]: #stream_readable_unpipe_destination
[tcp sockets]: net.html#net_class_net_socket
+[http responses, on the client]: http.html#http_http_incomingmessage
+[http requests, on the server]: http.html#http_http_incomingmessage
+[http requests, on the client]: http.html#http_class_http_clientrequest
+[http responses, on the server]: http.html#http_class_http_serverresponse
+[fs read streams]: fs.html#fs_class_fs_readstream
+[fs write streams]: fs.html#fs_class_fs_writestream
[zlib streams]: zlib.html
[zlib]: zlib.html
[crypto streams]: crypto.html
[process.stdout]: process.html#process_process_stdout
[process.stderr]: process.html#process_process_stderr
[child process stdout and stderr]: child_process.html#child_process_child_stdout
+[child process stdin]: child_process.html#child_process_child_stdin
[API for Stream Consumers]: #stream_api_for_stream_consumers
[API for Stream Implementors]: #stream_api_for_stream_implementors
[Readable]: #stream_class_stream_readable
<!--type=misc-->
-An example of a [web server](http.html) written with Node.js which responds with
+An example of a [web server][] written with Node.js which responds with
'Hello World':
var http = require('http');
Server running at http://127.0.0.1:8124/
All of the examples in the documentation can be run similarly.
+
+[web server]: http.html
This instance implements a duplex [Stream][] interfaces. It has all the
common stream methods and events.
-Methods that return TLS connection meta data (e.g.
-[getPeerCertificate](#tlssocketgetpeercertificate-detailed-))
-will only return data while the connection is open.
+Methods that return TLS connection meta data (e.g. [getPeerCertificate][] will
+only return data while the connection is open.
## new tls.TLSSocket(socket[, options])
[OCSP request]: http://en.wikipedia.org/wiki/OCSP_stapling
[TLS recommendations]: https://wiki.mozilla.org/Security/Server_Side_TLS
[TLS Session Tickets]: https://www.ietf.org/rfc/rfc5077.txt
+[getPeerCertificate]: #tls_tlssocket_getpeercertificate_detailed
`tty.ReadStream` to act either as a raw device or default. `isRaw` will be set
to the resulting mode.
-[tty.ReadStream#setRawMode]: #tty_rs_setrawmode_mode
-
## Class: WriteStream
A `net.Socket` subclass that represents the writable portion of a tty. In normal
## tty.setRawMode(mode)
Stability: 0 - Deprecated: Use [tty.ReadStream#setRawMode][] (i.e. process.stdin.setRawMode) instead.
+
+[tty.ReadStream#setRawMode]: #tty_rs_setrawmode_mode
## util.inherits(constructor, superConstructor)
-Inherit the prototype methods from one
-[constructor](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/constructor)
-into another. The prototype of `constructor` will be set to a new
-object created from `superConstructor`.
+Inherit the prototype methods from one [constructor][] into another. The
+prototype of `constructor` will be set to a new object created from
+`superConstructor`.
As an additional convenience, `superConstructor` will be accessible
through the `constructor.super_` property.
Stability: 0 - Deprecated: Use console.log() instead.
Deprecated predecessor of `console.log`.
+
+[constructor]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/constructor
The V8 options available for a version of node.js may be determined by running
`node --v8-options`. An unofficial, community-maintained list of options
-and their effects is available
-[here](https://github.com/thlorenz/v8-flags/blob/master/flags-0.11.md).
+and their effects is available [here][].
Usage:
```
[V8]: https://code.google.com/p/v8/
+[here]: https://github.com/thlorenz/v8-flags/blob/master/flags-0.11.md
used in calls to `vm.runInContext` or `script.runInContext`. Inside scripts run
as such, `sandbox` will be the global object, retaining all its existing
properties but also having the built-in objects and functions any standard
-[global object][2] has. Outside of scripts run by the vm module, `sandbox` will
+[global object][] has. Outside of scripts run by the vm module, `sandbox` will
be unchanged.
If not given a sandbox object, returns a new, empty contextified sandbox object
single sandbox representing a window's global object, then run all `<script>`
tags together inside that sandbox.
-[2]: http://es5.github.io/#x15.1
-
## vm.isContext(sandbox)
Returns whether or not a sandbox object has been contextified by calling
`vm.runInThisContext` does not have access to the local scope, so `localVar` is
unchanged. `eval` does have access to the local scope, so `localVar` is changed.
-In this way `vm.runInThisContext` is much like an [indirect `eval` call][1],
+In this way `vm.runInThisContext` is much like an [indirect `eval` call][],
e.g. `(0,eval)('code')`. However, it also has the following additional options:
- `filename`: allows you to control the filename that shows up in any stack
- `timeout`: a number of milliseconds to execute `code` before terminating
execution. If execution is terminated, an `Error` will be thrown.
-[1]: http://es5.github.io/#x10.4.2
+[indirect `eval` call]: http://es5.github.io/#x10.4.2
+[global object]: http://es5.github.io/#x15.1
}
});
-To use this module in an HTTP client or server, use the
-[accept-encoding](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3)
-on requests, and the
-[content-encoding](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11)
-header on responses.
+To use this module in an HTTP client or server, use the [accept-encoding][]
+on requests, and the [content-encoding][] header on responses.
**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](#zlib_memory_usage_tuning)
-below for more information on the speed/memory/compression
-tradeoffs involved in zlib usage.
+ought to be cached. See [Memory Usage Tuning][] below for more information
+on the speed/memory/compression tradeoffs involved in zlib usage.
// client request example
var zlib = require('zlib');
`require('zlib')`.
In the normal course of operations, you will not need to ever set any of
these. They are documented here so that their presence is not
-surprising. This section is taken almost directly from the [zlib
-documentation](http://zlib.net/manual.html#Constants). See
-<http://zlib.net/manual.html#Constants> for more details.
+surprising. This section is taken almost directly from the
+[zlib documentation][]. See <http://zlib.net/manual.html#Constants> for more
+details.
Allowed flush values.
## zlib.createDeflate([options])
-Returns a new [Deflate](#zlib_class_zlib_deflate) object with an
-[options](#zlib_options).
+Returns a new [Deflate][] object with an [options][].
## zlib.createDeflateRaw([options])
-Returns a new [DeflateRaw](#zlib_class_zlib_deflateraw) object with an
-[options](#zlib_options).
+Returns a new [DeflateRaw][] object with an [options][].
## zlib.createGunzip([options])
-Returns a new [Gunzip](#zlib_class_zlib_gunzip) object with an
-[options](#zlib_options).
+Returns a new [Gunzip][] object with an [options][].
## zlib.createGzip([options])
-Returns a new [Gzip](#zlib_class_zlib_gzip) object with an
-[options](#zlib_options).
+Returns a new [Gzip][] object with an [options][].
## zlib.createInflate([options])
-Returns a new [Inflate](#zlib_class_zlib_inflate) object with an
-[options](#zlib_options).
+Returns a new [Inflate][] object with an [options][].
## zlib.createInflateRaw([options])
-Returns a new [InflateRaw](#zlib_class_zlib_inflateraw) object with an
-[options](#zlib_options).
+Returns a new [InflateRaw][] object with an [options][].
## zlib.createUnzip([options])
-Returns a new [Unzip](#zlib_class_zlib_unzip) object with an
-[options](#zlib_options).
+Returns a new [Unzip][] object with an [options][].
## Convenience Methods
### zlib.unzipSync(buf[, options])
Decompress a raw Buffer with Unzip.
+
+[accept-encoding]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
+[content-encoding]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11
+[Memory Usage Tuning]: #zlib_memory_usage_tuning
+[zlib documentation]: http://zlib.net/manual.html#Constants
+[options]: #zlib_options
+[Deflate]: #zlib_class_zlib_deflate
+[DeflateRaw]: #zlib_class_zlib_deflateraw
+[Gunzip]: #zlib_class_zlib_gunzip
+[Gzip]: #zlib_class_zlib_gzip
+[Inflate]: #zlib_class_zlib_inflate
+[InflateRaw]: #zlib_class_zlib_inflateraw
+[Unzip]: #zlib_class_zlib_unzip
projects / platform / upstream / nodejs.git / commitdiff