diff --git a/doc/api/addons.markdown b/doc/api/addons.markdown index f1f042f0d5bd9e..28a5457cca7c72 100644 --- a/doc/api/addons.markdown +++ b/doc/api/addons.markdown @@ -7,14 +7,12 @@ knowledge of several libraries: - 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. @@ -25,9 +23,8 @@ Node.js statically compiles all its dependencies into the executable. 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 @@ -77,7 +74,7 @@ The `module_name` needs to match the filename of the final binary (minus the 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": [ @@ -113,10 +110,9 @@ Please see patterns below for further information or ## 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: @@ -869,3 +865,10 @@ Test in JavaScript by running: // 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 diff --git a/doc/api/assert.markdown b/doc/api/assert.markdown index a607b92ead197f..6ea4071b79cc14 100644 --- a/doc/api/assert.markdown +++ b/doc/api/assert.markdown @@ -32,7 +32,7 @@ operator ( `===` ). ## 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 @@ -128,3 +128,5 @@ Custom error validation: }, "unexpected error" ); + +[assert.throws()]: #assert_assert_throws_block_error_message diff --git a/doc/api/buffer.markdown b/doc/api/buffer.markdown index f18da5c192f01f..96a4d3c483efba 100644 --- a/doc/api/buffer.markdown +++ b/doc/api/buffer.markdown @@ -114,8 +114,7 @@ Example: * `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); @@ -287,11 +286,10 @@ buffer. * `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 @@ -932,3 +930,6 @@ un-pooled Buffer instance using SlowBuffer and copy out the relevant bits. 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 diff --git a/doc/api/child_process.markdown b/doc/api/child_process.markdown index ad7ceeb9612dca..5f1aea770dce76 100644 --- a/doc/api/child_process.markdown +++ b/doc/api/child_process.markdown @@ -12,10 +12,9 @@ data you send to the child process may not be immediately consumed.) 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 @@ -61,8 +60,7 @@ Note that the `exit`-event may or may not fire after an error has occurred. If 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' @@ -161,7 +159,7 @@ Example: * `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. @@ -310,9 +308,7 @@ to the same object, or null. * {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. @@ -439,9 +435,9 @@ the existing process and uses a shell to execute the command.* * `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]) @@ -462,10 +458,10 @@ leaner than [`child_process.exec()`](#child_process_child_process_exec_command_o * `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 @@ -663,7 +659,7 @@ Example: // 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 @@ -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 -[`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]) @@ -741,7 +733,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 -[`child_process.spawnSync()`](#child_process_child_process_spawnsync_command_args_options) +[`child_process.spawnSync()`][] ### child_process.spawnSync(command[, args][, options]) @@ -774,3 +766,18 @@ timeout has been encountered and `killSignal` is sent, the method won't return 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 diff --git a/doc/api/cluster.markdown b/doc/api/cluster.markdown index 594dea0832908d..7b9887b7d9a250 100644 --- a/doc/api/cluster.markdown +++ b/doc/api/cluster.markdown @@ -123,8 +123,6 @@ This event is the same as the one provided by `child_process.fork()`. 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. @@ -232,15 +230,15 @@ Causes `.suicide` to be set. 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 @@ -313,7 +311,7 @@ Causes `.suicide` to be set. 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 @@ -323,8 +321,7 @@ All workers are created using `child_process.fork()`, the returned object 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 @@ -408,7 +405,7 @@ This can be used to restart the worker by calling `.fork()` again. cluster.fork(); }); -See [child_process event: 'exit'](child_process.html#child_process_event_exit). +See [child_process event: 'exit'][]. ## Event: 'fork' @@ -464,8 +461,7 @@ The `addressType` is one of: 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' @@ -647,3 +643,11 @@ the worker's unique id is the easiest way to find the worker. 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. diff --git a/doc/api/console.markdown b/doc/api/console.markdown index 25d02953605ebc..b481a7d17c98e1 100644 --- a/doc/api/console.markdown +++ b/doc/api/console.markdown @@ -43,10 +43,6 @@ The global `console` is a special `Console` whose output is sent to 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} @@ -113,14 +109,13 @@ is used on each argument. See [util.format()][] for more information. Starts a timer that can be used to compute the duration of an operation. Timers are identified by a unique name. Use the same name when you call -[`console.timeEnd()`](#console_console_timeend_label) to stop the timer and -output the elapsed time in milliseconds. Timer durations are accurate to the -sub-millisecond. +[`console.timeEnd()`][] to stop the timer and output the elapsed time in +milliseconds. Timer durations are accurate to the sub-millisecond. ### console.timeEnd(label) Stops a timer that was previously started by calling -[`console.time()`](#console_console_time_label) and prints the result to the +[`console.time()`][] and prints the result to the console. Example: @@ -140,3 +135,9 @@ to the current position. ### 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 diff --git a/doc/api/crypto.markdown b/doc/api/crypto.markdown index 113593a113f02f..048bc077785c92 100644 --- a/doc/api/crypto.markdown +++ b/doc/api/crypto.markdown @@ -36,10 +36,10 @@ Class for encrypting data. 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]) @@ -91,10 +91,10 @@ Class for decrypting data. 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]) @@ -287,10 +287,10 @@ expected. 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`. @@ -339,10 +339,10 @@ Class for generating signatures. 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]) @@ -375,11 +375,10 @@ Class for verifying signatures. 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) @@ -420,12 +419,12 @@ password. `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 @@ -443,11 +442,9 @@ Creates and returns a cipher object, with the given algorithm, key and 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) @@ -542,10 +539,10 @@ Example: this program that takes the sha256 sum of a file 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. @@ -583,12 +580,12 @@ Example: 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. @@ -631,8 +628,7 @@ Example: 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]) @@ -779,6 +775,10 @@ Based on the recommendations of [NIST SP 800-131A]: 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 @@ -790,3 +790,6 @@ See the reference for other recommendations and details. [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 diff --git a/doc/api/debugger.markdown b/doc/api/debugger.markdown index 3f9672bcb0f616..224f53eb45e2ba 100644 --- a/doc/api/debugger.markdown +++ b/doc/api/debugger.markdown @@ -5,9 +5,8 @@ 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 @@ -168,3 +167,5 @@ debugger. The syntax is: * `node debug -p ` - Connects to the process via the `pid` * `node debug ` - Connects to the process via the URI such as localhost:5858 + +[TCP protocol]: http://code.google.com/p/v8/wiki/DebuggerProtocol diff --git a/doc/api/dgram.markdown b/doc/api/dgram.markdown index fce88d0fdc2d2f..3db13305281f5a 100644 --- a/doc/api/dgram.markdown +++ b/doc/api/dgram.markdown @@ -143,7 +143,7 @@ shown below. ### 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]) @@ -186,9 +186,7 @@ given, the error will be the first argument to the callback. If a callback is 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`; @@ -261,8 +259,8 @@ gateway that forwards a packet decrements the TTL. If the TTL is decremented to 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() @@ -315,3 +313,6 @@ Call `socket.bind()` if you want to receive datagrams. `socket.bind()` will 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 diff --git a/doc/api/dns.markdown b/doc/api/dns.markdown index f905e8681a3702..e7b9fbb7987b93 100644 --- a/doc/api/dns.markdown +++ b/doc/api/dns.markdown @@ -10,7 +10,7 @@ This module contains functions that belong to two different categories: 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`. @@ -22,8 +22,8 @@ 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 @@ -51,8 +51,7 @@ resolves the IP addresses which are returned. }); 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() @@ -74,8 +73,8 @@ Alternatively, `options` can be an object containing these properties: `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`. @@ -109,7 +108,7 @@ and vice versa. 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) @@ -149,36 +148,36 @@ one of the error codes listed below. ## 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: @@ -197,14 +196,14 @@ The same as [`dns.resolve()`](#dns_dns_resolve_hostname_rrtype_callback), but on ## 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 @@ -296,8 +295,7 @@ operations) will experience degraded performance. In order to mitigate this 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 @@ -312,5 +310,10 @@ processing that happens on libuv's threadpool that `dns.lookup()` can have. 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 diff --git a/doc/api/errors.markdown b/doc/api/errors.markdown index 5e5f9acb99fc57..10f04e1ddbbd1a 100644 --- a/doc/api/errors.markdown +++ b/doc/api/errors.markdown @@ -3,7 +3,7 @@ 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. 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. + +[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 diff --git a/doc/api/events.markdown b/doc/api/events.markdown index c14994e5bf4a59..2d17ca2f83b6b8 100644 --- a/doc/api/events.markdown +++ b/doc/api/events.markdown @@ -4,11 +4,9 @@ -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, @@ -81,13 +79,12 @@ triggered, the listener has been removed from the array of listeners for the ### 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) @@ -102,8 +99,8 @@ Returns `true` if event had listeners, `false` otherwise. ### 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. @@ -190,4 +187,8 @@ allows that to be increased. Set to `Infinity` (or `0`) for unlimited. 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 diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown index 0692d697e258a6..582a222a6e69c6 100644 --- a/doc/api/fs.markdown +++ b/doc/api/fs.markdown @@ -94,7 +94,7 @@ Objects returned from `fs.watch()` are of this 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' @@ -108,7 +108,7 @@ Stop watching for changes on the given `fs.FSWatcher`. ## Class: fs.ReadStream -`ReadStream` is a [Readable Stream](stream.html#stream_class_stream_readable). +`ReadStream` is a [Readable Stream][]. ### Event: 'open' @@ -157,9 +157,6 @@ additional methods which can be used for displaying fuzzy information. 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: @@ -186,7 +183,7 @@ on Unix systems, it never was. ## Class: fs.WriteStream -`WriteStream` is a [Writable Stream](stream.html#stream_class_stream_writable). +`WriteStream` is a [Writable Stream][]. ### Event: 'open' @@ -367,7 +364,7 @@ non-existent. ## 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. @@ -652,8 +649,8 @@ Synchronous rmdir(2). Returns `undefined`. ## 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) @@ -723,7 +720,7 @@ Synchronous version of `fs.utimes()`. Returns `undefined`. ## 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` @@ -855,8 +852,7 @@ the current position. See pwrite(2). 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 @@ -915,8 +911,17 @@ The synchronous version of `fs.writeFile`. Returns `undefined`. 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 diff --git a/doc/api/globals.markdown b/doc/api/globals.markdown index b9ab51ad8da066..dd675c90664c49 100644 --- a/doc/api/globals.markdown +++ b/doc/api/globals.markdown @@ -55,13 +55,6 @@ will not execute. 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 @@ -185,3 +178,10 @@ outside that range, it's changed to 1 millisecond. Broadly speaking, a timer 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 diff --git a/doc/api/http.markdown b/doc/api/http.markdown index f36fcf77146174..51b2b57a3bae8d 100644 --- a/doc/api/http.markdown +++ b/doc/api/http.markdown @@ -56,13 +56,12 @@ require developers to manually close the HTTP clients using 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 @@ -506,8 +505,7 @@ already been bound to a port or domain socket. 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]) @@ -958,7 +956,7 @@ connected to. ## 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. @@ -1085,6 +1083,8 @@ There are a few special headers that should be noted. * 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 @@ -1100,8 +1100,10 @@ There are a few special headers that should be noted. [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 diff --git a/doc/api/https.markdown b/doc/api/https.markdown index 1c3af5557b0072..b2e917b72a8709 100644 --- a/doc/api/https.markdown +++ b/doc/api/https.markdown @@ -74,7 +74,7 @@ See [http.listen()][] for details. 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: @@ -96,26 +96,12 @@ 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. @@ -226,3 +212,18 @@ Example: 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 diff --git a/doc/api/modules.markdown b/doc/api/modules.markdown index 8212bd07c67627..e9db1e4b225cbc 100644 --- a/doc/api/modules.markdown +++ b/doc/api/modules.markdown @@ -372,9 +372,7 @@ are not found elsewhere. (Note: On Windows, `NODE_PATH` is delimited by 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. @@ -519,3 +517,5 @@ Note that in order to do this, you must get a reference to the `module` 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 diff --git a/doc/api/net.markdown b/doc/api/net.markdown index c2d8fb3e7c3669..0a44c6535b3dec 100644 --- a/doc/api/net.markdown +++ b/doc/api/net.markdown @@ -493,12 +493,11 @@ written out - this may not be immediately. ## 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. @@ -526,18 +525,16 @@ changed to ## 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. @@ -546,12 +543,11 @@ The `connectListener` parameter will be added as a listener for the ## 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. @@ -579,18 +575,16 @@ changed to ## 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. @@ -672,4 +666,6 @@ Returns true if input is a version 6 IP address, otherwise returns false. [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 diff --git a/doc/api/process.markdown b/doc/api/process.markdown index 24493f88803ade..327b16c82b4223 100644 --- a/doc/api/process.markdown +++ b/doc/api/process.markdown @@ -357,8 +357,7 @@ Returns the current working directory of the process. 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. @@ -545,7 +544,7 @@ Some care needs to be taken when dropping privileges. Example: 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. Windows platforms @@ -569,16 +568,14 @@ Example of sending a signal to yourself: 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. @@ -727,8 +724,7 @@ relied upon to exist. 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. @@ -853,8 +849,7 @@ Example of opening standard input and listening for both events: 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 @@ -892,7 +887,7 @@ on `process.stderr`, `process.stdout`, or `process.stdin`: $ 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 @@ -949,8 +944,13 @@ Will print something like: 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 diff --git a/doc/api/punycode.markdown b/doc/api/punycode.markdown index f86b32ba50db66..c54a981fedb45b 100644 --- a/doc/api/punycode.markdown +++ b/doc/api/punycode.markdown @@ -2,9 +2,9 @@ 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) @@ -47,8 +47,7 @@ you call it on a string that has already been converted to Unicode. ### 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. @@ -66,3 +65,6 @@ Creates a string based on an array of numeric code point values. ## 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 diff --git a/doc/api/stream.markdown b/doc/api/stream.markdown index 90289b7cf7400c..caf9daeaf21362 100644 --- a/doc/api/stream.markdown +++ b/doc/api/stream.markdown @@ -3,8 +3,7 @@ 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][] @@ -147,9 +146,9 @@ destinations drain and ask for more data. 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][] @@ -559,13 +558,13 @@ that you are writing data *to*. 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' @@ -1677,6 +1676,7 @@ find that you have to use `stream.push('')`, please consider another 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 @@ -1685,6 +1685,12 @@ horribly wrong. [`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 @@ -1695,6 +1701,7 @@ horribly wrong. [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 diff --git a/doc/api/synopsis.markdown b/doc/api/synopsis.markdown index a69273f78de8ac..f9e8b19ed6fcfe 100644 --- a/doc/api/synopsis.markdown +++ b/doc/api/synopsis.markdown @@ -2,7 +2,7 @@ -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'); @@ -21,3 +21,5 @@ it with the node program Server running at http://127.0.0.1:8124/ All of the examples in the documentation can be run similarly. + +[web server]: http.html diff --git a/doc/api/tls.markdown b/doc/api/tls.markdown index 7f21276c5409e0..60ad316ff5556f 100644 --- a/doc/api/tls.markdown +++ b/doc/api/tls.markdown @@ -339,9 +339,8 @@ of written data and all required TLS negotiation. 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]) @@ -940,3 +939,4 @@ Example: [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 diff --git a/doc/api/tty.markdown b/doc/api/tty.markdown index acb3bb480bb774..279a1dd0b9440e 100644 --- a/doc/api/tty.markdown +++ b/doc/api/tty.markdown @@ -32,8 +32,6 @@ of the `tty.ReadStream` instance. `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 @@ -70,3 +68,5 @@ terminal. ## tty.setRawMode(mode) Stability: 0 - Deprecated: Use [tty.ReadStream#setRawMode][] (i.e. process.stdin.setRawMode) instead. + +[tty.ReadStream#setRawMode]: #tty_rs_setrawmode_mode diff --git a/doc/api/util.markdown b/doc/api/util.markdown index 56f38e12362b7b..b1ab10a81e094f 100644 --- a/doc/api/util.markdown +++ b/doc/api/util.markdown @@ -116,10 +116,9 @@ Each argument is converted to a string with `util.inspect()`. ## 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. @@ -505,3 +504,5 @@ Deprecated predecessor of `stream.pipe()`. Stability: 0 - Deprecated: Use console.log() instead. Deprecated predecessor of `console.log`. + +[constructor]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/constructor diff --git a/doc/api/v8.markdown b/doc/api/v8.markdown index 1ed2179d8155ea..ea0d04d25b7efd 100644 --- a/doc/api/v8.markdown +++ b/doc/api/v8.markdown @@ -29,8 +29,7 @@ crashes and data loss. Or it may simply do nothing. 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: @@ -42,3 +41,4 @@ setTimeout(function() { v8.setFlagsFromString('--notrace_gc'); }, 60e3); ``` [V8]: https://code.google.com/p/v8/ +[here]: https://github.com/thlorenz/v8-flags/blob/master/flags-0.11.md diff --git a/doc/api/vm.markdown b/doc/api/vm.markdown index 20bca8770286ab..870a9551215abf 100644 --- a/doc/api/vm.markdown +++ b/doc/api/vm.markdown @@ -137,7 +137,7 @@ If given a `sandbox` object, will "contextify" that sandbox so that it can be 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 @@ -148,8 +148,6 @@ scripts, e.g. if you were emulating a web browser it could be used to create a single sandbox representing a window's global object, then run all `