diff options
author | Vse Mozhet Byt <vsemozhetbyt@gmail.com> | 2017-02-13 04:49:35 +0200 |
---|---|---|
committer | Sam Roberts <vieuxtech@gmail.com> | 2017-02-20 13:11:11 -0800 |
commit | 52b253677a96021739d4c31ab4e3a01c3464e6db (patch) | |
tree | e29b83c574a9e6d015f2888040c09ebb38b0de10 | |
parent | dfa8abe1b500b86ffb3951736c209e57d83ed3ed (diff) | |
download | android-node-v8-52b253677a96021739d4c31ab4e3a01c3464e6db.tar.gz android-node-v8-52b253677a96021739d4c31ab4e3a01c3464e6db.tar.bz2 android-node-v8-52b253677a96021739d4c31ab4e3a01c3464e6db.zip |
doc: fix sorting in API references
PR-URL: https://github.com/nodejs/node/pull/11331
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
-rw-r--r-- | doc/api/buffer.md | 192 | ||||
-rw-r--r-- | doc/api/crypto.md | 32 | ||||
-rw-r--r-- | doc/api/dgram.md | 32 | ||||
-rw-r--r-- | doc/api/dns.md | 18 | ||||
-rw-r--r-- | doc/api/domain.md | 152 | ||||
-rw-r--r-- | doc/api/fs.md | 36 | ||||
-rw-r--r-- | doc/api/http.md | 24 | ||||
-rw-r--r-- | doc/api/process.md | 154 | ||||
-rw-r--r-- | doc/api/tls.md | 100 | ||||
-rw-r--r-- | doc/api/url.md | 84 | ||||
-rw-r--r-- | doc/api/util.md | 42 | ||||
-rw-r--r-- | doc/api/v8.md | 78 |
12 files changed, 472 insertions, 472 deletions
diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 51ea87687d..56545e3cb1 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -313,32 +313,6 @@ Example: const buf = new Buffer([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]); ``` -### new Buffer(buffer) -<!-- YAML -deprecated: v6.0.0 ---> - -> Stability: 0 - Deprecated: Use [`Buffer.from(buffer)`] instead. - -* `buffer` {Buffer} An existing `Buffer` to copy data from - -Copies the passed `buffer` data onto a new `Buffer` instance. - -Example: - -```js -const buf1 = new Buffer('buffer'); -const buf2 = new Buffer(buf1); - -buf1[0] = 0x61; - -// Prints: auffer -console.log(buf1.toString()); - -// Prints: buffer -console.log(buf2.toString()); -``` - ### new Buffer(arrayBuffer[, byteOffset [, length]]) <!-- YAML deprecated: v6.0.0 @@ -383,6 +357,32 @@ arr[1] = 6000; console.log(buf); ``` +### new Buffer(buffer) +<!-- YAML +deprecated: v6.0.0 +--> + +> Stability: 0 - Deprecated: Use [`Buffer.from(buffer)`] instead. + +* `buffer` {Buffer} An existing `Buffer` to copy data from + +Copies the passed `buffer` data onto a new `Buffer` instance. + +Example: + +```js +const buf1 = new Buffer('buffer'); +const buf2 = new Buffer(buf1); + +buf1[0] = 0x61; + +// Prints: auffer +console.log(buf1.toString()); + +// Prints: buffer +console.log(buf2.toString()); +``` + ### new Buffer(size) <!-- YAML deprecated: v6.0.0 @@ -1113,6 +1113,47 @@ Example: Fill a `Buffer` with a two-byte character console.log(Buffer.allocUnsafe(3).fill('\u0222')); ``` +### buf.includes(value[, byteOffset][, encoding]) +<!-- YAML +added: v5.3.0 +--> + +* `value` {String | Buffer | Integer} What to search for +* `byteOffset` {Integer} Where to begin searching in `buf`. **Default:** `0` +* `encoding` {String} If `value` is a string, this is its encoding. + **Default:** `'utf8'` +* Returns: {Boolean} `true` if `value` was found in `buf`, `false` otherwise + +Equivalent to [`buf.indexOf() !== -1`][`buf.indexOf()`]. + +Examples: + +```js +const buf = Buffer.from('this is a buffer'); + +// Prints: true +console.log(buf.includes('this')); + +// Prints: true +console.log(buf.includes('is')); + +// Prints: true +console.log(buf.includes(Buffer.from('a buffer'))); + +// Prints: true +// (97 is the decimal ASCII value for 'a') +console.log(buf.includes(97)); + +// Prints: false +console.log(buf.includes(Buffer.from('a buffer example'))); + +// Prints: true +console.log(buf.includes(Buffer.from('a buffer example').slice(0, 8))); + +// Prints: false +console.log(buf.includes('this', 4)); +``` + ### buf.indexOf(value[, byteOffset][, encoding]) <!-- YAML added: v1.5.0 @@ -1192,47 +1233,6 @@ console.log(b.indexOf('b', null)); console.log(b.indexOf('b', [])); ``` -### buf.includes(value[, byteOffset][, encoding]) -<!-- YAML -added: v5.3.0 ---> - -* `value` {String | Buffer | Integer} What to search for -* `byteOffset` {Integer} Where to begin searching in `buf`. **Default:** `0` -* `encoding` {String} If `value` is a string, this is its encoding. - **Default:** `'utf8'` -* Returns: {Boolean} `true` if `value` was found in `buf`, `false` otherwise - -Equivalent to [`buf.indexOf() !== -1`][`buf.indexOf()`]. - -Examples: - -```js -const buf = Buffer.from('this is a buffer'); - -// Prints: true -console.log(buf.includes('this')); - -// Prints: true -console.log(buf.includes('is')); - -// Prints: true -console.log(buf.includes(Buffer.from('a buffer'))); - -// Prints: true -// (97 is the decimal ASCII value for 'a') -console.log(buf.includes(97)); - -// Prints: false -console.log(buf.includes(Buffer.from('a buffer example'))); - -// Prints: true -console.log(buf.includes(Buffer.from('a buffer example').slice(0, 8))); - -// Prints: false -console.log(buf.includes('this', 4)); -``` - ### buf.keys() <!-- YAML added: v1.1.0 @@ -1878,6 +1878,35 @@ buf2.swap64(); Note that JavaScript cannot encode 64-bit integers. This method is intended for working with 64-bit floats. +### buf.toJSON() +<!-- YAML +added: v0.9.2 +--> + +* Returns: {Object} + +Returns a JSON representation of `buf`. [`JSON.stringify()`] implicitly calls +this function when stringifying a `Buffer` instance. + +Example: + +```js +const buf = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5]); +const json = JSON.stringify(buf); + +// Prints: {"type":"Buffer","data":[1,2,3,4,5]} +console.log(json); + +const copy = JSON.parse(json, (key, value) => { + return value && value.type === 'Buffer' + ? Buffer.from(value.data) + : value; +}); + +// Prints: <Buffer 01 02 03 04 05> +console.log(copy); +``` + ### buf.toString([encoding[, start[, end]]]) <!-- YAML added: v0.1.90 @@ -1921,35 +1950,6 @@ console.log(buf2.toString('utf8', 0, 3)); console.log(buf2.toString(undefined, 0, 3)); ``` -### buf.toJSON() -<!-- YAML -added: v0.9.2 ---> - -* Returns: {Object} - -Returns a JSON representation of `buf`. [`JSON.stringify()`] implicitly calls -this function when stringifying a `Buffer` instance. - -Example: - -```js -const buf = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5]); -const json = JSON.stringify(buf); - -// Prints: {"type":"Buffer","data":[1,2,3,4,5]} -console.log(json); - -const copy = JSON.parse(json, (key, value) => { - return value && value.type === 'Buffer' - ? Buffer.from(value.data) - : value; -}); - -// Prints: <Buffer 01 02 03 04 05> -console.log(copy); -``` - ### buf.values() <!-- YAML added: v1.1.0 diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 69ba366264..c713f563a1 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -1427,22 +1427,6 @@ keys: All paddings are defined in `crypto.constants`. -### crypto.timingSafeEqual(a, b) -<!-- YAML -added: v6.6.0 ---> - -Returns true if `a` is equal to `b`, without leaking timing information that -would allow an attacker to guess one of the values. This is suitable for -comparing HMAC digests or secret values like authentication cookies or -[capability urls](https://www.w3.org/TR/capability-urls/). - -`a` and `b` must both be `Buffer`s, and they must have the same length. - -**Note**: Use of `crypto.timingSafeEqual` does not guarantee that the -*surrounding* code is timing-safe. Care should be taken to ensure that the -surrounding code does not introduce timing vulnerabilities. - ### crypto.privateEncrypt(private_key, buffer) <!-- YAML added: v1.1.0 @@ -1576,6 +1560,22 @@ is a bit field taking one of or a mix of the following flags (defined in * `crypto.constants.ENGINE_METHOD_ALL` * `crypto.constants.ENGINE_METHOD_NONE` +### crypto.timingSafeEqual(a, b) +<!-- YAML +added: v6.6.0 +--> + +Returns true if `a` is equal to `b`, without leaking timing information that +would allow an attacker to guess one of the values. This is suitable for +comparing HMAC digests or secret values like authentication cookies or +[capability urls](https://www.w3.org/TR/capability-urls/). + +`a` and `b` must both be `Buffer`s, and they must have the same length. + +**Note**: Use of `crypto.timingSafeEqual` does not guarantee that the +*surrounding* code is timing-safe. Care should be taken to ensure that the +surrounding code does not introduce timing vulnerabilities. + ## Notes ### Legacy Streams API (pre Node.js v0.10) diff --git a/doc/api/dgram.md b/doc/api/dgram.md index 7d70645b47..7511641b60 100644 --- a/doc/api/dgram.md +++ b/doc/api/dgram.md @@ -225,6 +225,22 @@ never have reason to call this. If `multicastInterface` is not specified, the operating system will attempt to drop membership on all valid interfaces. +### socket.ref() +<!-- YAML +added: v0.9.1 +--> + +By default, binding a socket will cause it to block the Node.js process from +exiting as long as the socket is open. The `socket.unref()` method can be used +to exclude the socket from the reference counting that keeps the Node.js +process active. The `socket.ref()` method adds the socket back to the reference +counting and restores the default behavior. + +Calling `socket.ref()` multiples times will have no additional effect. + +The `socket.ref()` method returns a reference to the socket so calls can be +chained. + ### socket.send(msg, [offset, length,] port [, address] [, callback]) <!-- YAML added: v0.1.99 @@ -379,22 +395,6 @@ Changing TTL values is typically done for network probes or when multicasting. The argument to `socket.setTTL()` is a number of hops between 1 and 255. The default on most systems is 64 but can vary. -### socket.ref() -<!-- YAML -added: v0.9.1 ---> - -By default, binding a socket will cause it to block the Node.js process from -exiting as long as the socket is open. The `socket.unref()` method can be used -to exclude the socket from the reference counting that keeps the Node.js -process active. The `socket.ref()` method adds the socket back to the reference -counting and restores the default behavior. - -Calling `socket.ref()` multiples times will have no additional effect. - -The `socket.ref()` method returns a reference to the socket so calls can be -chained. - ### socket.unref() <!-- YAML added: v0.9.1 diff --git a/doc/api/dns.md b/doc/api/dns.md index f705d96246..bb52ad0b5c 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -288,6 +288,15 @@ Uses the DNS protocol to resolve name server records (`NS` records) for the contain an array of name server records available for `hostname` (e.g. `['ns1.example.com', 'ns2.example.com']`). +## dns.resolvePtr(hostname, callback) +<!-- YAML +added: v6.0.0 +--> + +Uses the DNS protocol to resolve pointer records (`PTR` records) for the +`hostname`. The `addresses` argument passed to the `callback` function will +be an array of strings containing the reply records. + ## dns.resolveSoa(hostname, callback) <!-- YAML added: v0.11.10 @@ -340,15 +349,6 @@ be an array of objects with the following properties: } ``` -## dns.resolvePtr(hostname, callback) -<!-- YAML -added: v6.0.0 ---> - -Uses the DNS protocol to resolve pointer records (`PTR` records) for the -`hostname`. The `addresses` argument passed to the `callback` function will -be an array of strings containing the reply records. - ## dns.resolveTxt(hostname, callback) <!-- YAML added: v0.1.27 diff --git a/doc/api/domain.md b/doc/api/domain.md index 1cc25e0cf8..00cb149bbd 100644 --- a/doc/api/domain.md +++ b/doc/api/domain.md @@ -269,42 +269,6 @@ uncaught exceptions to the active Domain object. Domain is a child class of [`EventEmitter`][]. To handle the errors that it catches, listen to its `'error'` event. -### domain.run(fn[, ...args]) - -* `fn` {Function} -* `...args` {any} - -Run the supplied function in the context of the domain, implicitly -binding all event emitters, timers, and lowlevel requests that are -created in that context. Optionally, arguments can be passed to -the function. - -This is the most basic way to use a domain. - -Example: - -```js -const domain = require('domain'); -const fs = require('fs'); -const d = domain.create(); -d.on('error', (er) => { - console.error('Caught error!', er); -}); -d.run(() => { - process.nextTick(() => { - setTimeout(() => { // simulating some various async stuff - fs.open('non-existent file', 'r', (er, fd) => { - if (er) throw er; - // proceed... - }); - }, 100); - }); -}); -``` - -In this example, the `d.on('error')` handler will be triggered, rather -than crashing the program. - ### domain.members * {Array} @@ -328,13 +292,6 @@ the domain 'error' handler. If the Timer or EventEmitter was already bound to a domain, it is removed from that one, and bound to this one instead. -### domain.remove(emitter) - -* `emitter` {EventEmitter|Timer} emitter or timer to be removed from the domain - -The opposite of [`domain.add(emitter)`][]. Removes domain handling from the -specified emitter. - ### domain.bind(callback) * `callback` {Function} The callback function @@ -363,6 +320,49 @@ d.on('error', (er) => { }); ``` +### domain.dispose() + +> Stability: 0 - Deprecated. Please recover from failed IO actions +> explicitly via error event handlers set on the domain. + +Once `dispose` has been called, the domain will no longer be used by callbacks +bound into the domain via `run`, `bind`, or `intercept`, and a `'dispose'` event +is emitted. + +### domain.enter() + +The `enter` method is plumbing used by the `run`, `bind`, and `intercept` +methods to set the active domain. It sets `domain.active` and `process.domain` +to the domain, and implicitly pushes the domain onto the domain stack managed +by the domain module (see [`domain.exit()`][] for details on the domain stack). The +call to `enter` delimits the beginning of a chain of asynchronous calls and I/O +operations bound to a domain. + +Calling `enter` changes only the active domain, and does not alter the domain +itself. `enter` and `exit` can be called an arbitrary number of times on a +single domain. + +If the domain on which `enter` is called has been disposed, `enter` will return +without setting the domain. + +### domain.exit() + +The `exit` method exits the current domain, popping it off the domain stack. +Any time execution is going to switch to the context of a different chain of +asynchronous calls, it's important to ensure that the current domain is exited. +The call to `exit` delimits either the end of or an interruption to the chain +of asynchronous calls and I/O operations bound to a domain. + +If there are multiple, nested domains bound to the current execution context, +`exit` will exit any domains nested within this domain. + +Calling `exit` changes only the active domain, and does not alter the domain +itself. `enter` and `exit` can be called an arbitrary number of times on a +single domain. + +If the domain on which `exit` is called has been disposed, `exit` will return +without exiting the domain. + ### domain.intercept(callback) * `callback` {Function} The callback function @@ -401,48 +401,48 @@ d.on('error', (er) => { }); ``` -### domain.enter() - -The `enter` method is plumbing used by the `run`, `bind`, and `intercept` -methods to set the active domain. It sets `domain.active` and `process.domain` -to the domain, and implicitly pushes the domain onto the domain stack managed -by the domain module (see [`domain.exit()`][] for details on the domain stack). The -call to `enter` delimits the beginning of a chain of asynchronous calls and I/O -operations bound to a domain. - -Calling `enter` changes only the active domain, and does not alter the domain -itself. `enter` and `exit` can be called an arbitrary number of times on a -single domain. +### domain.remove(emitter) -If the domain on which `enter` is called has been disposed, `enter` will return -without setting the domain. +* `emitter` {EventEmitter|Timer} emitter or timer to be removed from the domain -### domain.exit() +The opposite of [`domain.add(emitter)`][]. Removes domain handling from the +specified emitter. -The `exit` method exits the current domain, popping it off the domain stack. -Any time execution is going to switch to the context of a different chain of -asynchronous calls, it's important to ensure that the current domain is exited. -The call to `exit` delimits either the end of or an interruption to the chain -of asynchronous calls and I/O operations bound to a domain. +### domain.run(fn[, ...args]) -If there are multiple, nested domains bound to the current execution context, -`exit` will exit any domains nested within this domain. +* `fn` {Function} +* `...args` {any} -Calling `exit` changes only the active domain, and does not alter the domain -itself. `enter` and `exit` can be called an arbitrary number of times on a -single domain. +Run the supplied function in the context of the domain, implicitly +binding all event emitters, timers, and lowlevel requests that are +created in that context. Optionally, arguments can be passed to +the function. -If the domain on which `exit` is called has been disposed, `exit` will return -without exiting the domain. +This is the most basic way to use a domain. -### domain.dispose() +Example: -> Stability: 0 - Deprecated. Please recover from failed IO actions -> explicitly via error event handlers set on the domain. +```js +const domain = require('domain'); +const fs = require('fs'); +const d = domain.create(); +d.on('error', (er) => { + console.error('Caught error!', er); +}); +d.run(() => { + process.nextTick(() => { + setTimeout(() => { // simulating some various async stuff + fs.open('non-existent file', 'r', (er, fd) => { + if (er) throw er; + // proceed... + }); + }, 100); + }); +}); +``` -Once `dispose` has been called, the domain will no longer be used by callbacks -bound into the domain via `run`, `bind`, or `intercept`, and a `'dispose'` event -is emitted. +In this example, the `d.on('error')` handler will be triggered, rather +than crashing the program. [`domain.add(emitter)`]: #domain_domain_add_emitter [`domain.bind(callback)`]: #domain_domain_bind_callback diff --git a/doc/api/fs.md b/doc/api/fs.md index 187c7d9edc..11becd313c 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -164,22 +164,22 @@ added: v0.1.93 `ReadStream` is a [Readable Stream][]. -### Event: 'open' +### Event: 'close' <!-- YAML added: v0.1.93 --> -* `fd` {Integer} Integer file descriptor used by the ReadStream. - -Emitted when the ReadStream's file is opened. +Emitted when the `ReadStream`'s underlying file descriptor has been closed +using the `fs.close()` method. -### Event: 'close' +### Event: 'open' <!-- YAML added: v0.1.93 --> -Emitted when the `ReadStream`'s underlying file descriptor has been closed -using the `fs.close()` method. +* `fd` {Integer} Integer file descriptor used by the ReadStream. + +Emitted when the ReadStream's file is opened. ### readStream.bytesRead <!-- YAML @@ -278,22 +278,22 @@ added: v0.1.93 `WriteStream` is a [Writable Stream][]. -### Event: 'open' +### Event: 'close' <!-- YAML added: v0.1.93 --> -* `fd` {Integer} Integer file descriptor used by the WriteStream. - -Emitted when the WriteStream's file is opened. +Emitted when the `WriteStream`'s underlying file descriptor has been closed +using the `fs.close()` method. -### Event: 'close' +### Event: 'open' <!-- YAML added: v0.1.93 --> -Emitted when the `WriteStream`'s underlying file descriptor has been closed -using the `fs.close()` method. +* `fd` {Integer} Integer file descriptor used by the WriteStream. + +Emitted when the WriteStream's file is opened. ### writeStream.bytesWritten <!-- YAML @@ -1753,10 +1753,10 @@ watching the *original* inode. Events for the new inode will not be emitted. This is expected behavior. In AIX, save and close of a file being watched causes two notifications - -one for adding new content, and one for truncation. Moreover, save and -close operations on some platforms cause inode changes that force watch -operations to become invalid and ineffective. AIX retains inode for the -lifetime of a file, that way though this is different from Linux / OS X, +one for adding new content, and one for truncation. Moreover, save and +close operations on some platforms cause inode changes that force watch +operations to become invalid and ineffective. AIX retains inode for the +lifetime of a file, that way though this is different from Linux / OS X, this improves the usability of file watching. This is expected behavior. #### Filename Argument diff --git a/doc/api/http.md b/doc/api/http.md index 681fb21eb5..aed82481f5 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -1316,6 +1316,18 @@ Calls `message.connection.setTimeout(msecs, callback)`. Returns `message`. +### message.socket +<!-- YAML +added: v0.3.0 +--> + +* {net.Socket} + +The [`net.Socket`][] object associated with the connection. + +With HTTPS support, use [`request.socket.getPeerCertificate()`][] to obtain the +client's authentication details. + ### message.statusCode <!-- YAML added: v0.1.1 @@ -1338,18 +1350,6 @@ added: v0.11.10 The HTTP response status message (reason phrase). E.G. `OK` or `Internal Server Error`. -### message.socket -<!-- YAML -added: v0.3.0 ---> - -* {net.Socket} - -The [`net.Socket`][] object associated with the connection. - -With HTTPS support, use [`request.socket.getPeerCertificate()`][] to obtain the -client's authentication details. - ### message.trailers <!-- YAML added: v0.3.0 diff --git a/doc/api/process.md b/doc/api/process.md index 42ca444e5c..d1cfdf0645 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -629,83 +629,6 @@ process's [`ChildProcess.disconnect()`][]. If the Node.js process was not spawned with an IPC channel, `process.disconnect()` will be `undefined`. -## process.env -<!-- YAML -added: v0.1.27 ---> - -* {Object} - -The `process.env` property returns an object containing the user environment. -See environ(7). - -An example of this object looks like: - -```js -{ - TERM: 'xterm-256color', - SHELL: '/usr/local/bin/bash', - USER: 'maciej', - PATH: '~/.bin/:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin', - PWD: '/Users/maciej', - EDITOR: 'vim', - SHLVL: '1', - HOME: '/Users/maciej', - LOGNAME: 'maciej', - _: '/usr/local/bin/node' -} -``` - -It is possible to modify this object, but such modifications will not be -reflected outside the Node.js process. In other words, the following example -would not work: - -```console -$ node -e 'process.env.foo = "bar"' && echo $foo -``` - -While the following will: - -```js -process.env.foo = 'bar'; -console.log(process.env.foo); -``` - -Assigning a property on `process.env` will implicitly convert the value -to a string. - -Example: - -```js -process.env.test = null; -console.log(process.env.test); -// => 'null' -process.env.test = undefined; -console.log(process.env.test); -// => 'undefined' -``` - -Use `delete` to delete a property from `process.env`. - -Example: - -```js -process.env.TEST = 1; -delete process.env.TEST; -console.log(process.env.TEST); -// => undefined -``` - -On Windows operating systems, environment variables are case-insensitive. - -Example: - -```js -process.env.TEST = 1; -console.log(process.env.test); -// => 1 -``` - ## process.emitWarning(warning[, type[, code]][, ctor]) <!-- YAML added: v6.0.0 @@ -803,6 +726,83 @@ emitMyWarning(); // Emits nothing ``` +## process.env +<!-- YAML +added: v0.1.27 +--> + +* {Object} + +The `process.env` property returns an object containing the user environment. +See environ(7). + +An example of this object looks like: + +```js +{ + TERM: 'xterm-256color', + SHELL: '/usr/local/bin/bash', + USER: 'maciej', + PATH: '~/.bin/:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin', + PWD: '/Users/maciej', + EDITOR: 'vim', + SHLVL: '1', + HOME: '/Users/maciej', + LOGNAME: 'maciej', + _: '/usr/local/bin/node' +} +``` + +It is possible to modify this object, but such modifications will not be +reflected outside the Node.js process. In other words, the following example +would not work: + +```console +$ node -e 'process.env.foo = "bar"' && echo $foo +``` + +While the following will: + +```js +process.env.foo = 'bar'; +console.log(process.env.foo); +``` + +Assigning a property on `process.env` will implicitly convert the value +to a string. + +Example: + +```js +process.env.test = null; +console.log(process.env.test); +// => 'null' +process.env.test = undefined; +console.log(process.env.test); +// => 'undefined' +``` + +Use `delete` to delete a property from `process.env`. + +Example: + +```js +process.env.TEST = 1; +delete process.env.TEST; +console.log(process.env.TEST); +// => undefined +``` + +On Windows operating systems, environment variables are case-insensitive. + +Example: + +```js +process.env.TEST = 1; +console.log(process.env.test); +// => 1 +``` + ## process.execArgv <!-- YAML added: v0.7.7 diff --git a/doc/api/tls.md b/doc/api/tls.md index 158d41a0a2..ffd7440230 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -214,19 +214,6 @@ added: v0.3.2 The `tls.Server` class is a subclass of `net.Server` that accepts encrypted connections using TLS or SSL. -### Event: 'tlsClientError' -<!-- YAML -added: v6.0.0 ---> - -The `'tlsClientError'` event is emitted when an error occurs before a secure -connection is established. The listener callback is passed two arguments when -called: - -* `exception` {Error} The `Error` object describing the error -* `tlsSocket` {tls.TLSSocket} The `tls.TLSSocket` instance from which the - error originated. - ### Event: 'newSession' <!-- YAML added: v0.9.2 @@ -353,6 +340,19 @@ When ALPN has no selected protocol, `tlsSocket.alpnProtocol` returns `false`. The `tlsSocket.servername` property is a string containing the server name requested via SNI. +### Event: 'tlsClientError' +<!-- YAML +added: v6.0.0 +--> + +The `'tlsClientError'` event is emitted when an error occurs before a secure +connection is established. The listener callback is passed two arguments when +called: + +* `exception` {Error} The `Error` object describing the error +* `tlsSocket` {tls.TLSSocket} The `tls.TLSSocket` instance from which the + error originated. + ### server.addContext(hostname, context) <!-- YAML added: v0.5.3 @@ -531,21 +531,21 @@ underlying socket as reported by the operating system. Returns an object with three properties, e.g., `{ port: 12346, family: 'IPv4', address: '127.0.0.1' }` -### tlsSocket.authorized +### tlsSocket.authorizationError <!-- YAML added: v0.11.4 --> -Returns `true` if the peer certificate was signed by one of the CAs specified -when creating the `tls.TLSSocket` instance, otherwise `false`. +Returns the reason why the peer's certificate was not been verified. This +property is set only when `tlsSocket.authorized === false`. -### tlsSocket.authorizationError +### tlsSocket.authorized <!-- YAML added: v0.11.4 --> -Returns the reason why the peer's certificate was not been verified. This -property is set only when `tlsSocket.authorized === false`. +Returns `true` if the peer certificate was signed by one of the CAs specified +when creating the `tls.TLSSocket` instance, otherwise `false`. ### tlsSocket.encrypted <!-- YAML @@ -741,37 +741,6 @@ and their processing can be delayed due to packet loss or reordering. However, smaller fragments add extra TLS framing bytes and CPU overhead, which may decrease overall server throughput. -## tls.connect(port[, host][, options][, callback]) -<!-- YAML -added: v0.11.3 ---> - -* `port` {number} Default value for `options.port`. -* `host` {string} Optional default value for `options.host`. -* `options` {Object} See [`tls.connect()`][]. -* `callback` {Function} See [`tls.connect()`][]. - -Same as [`tls.connect()`][] except that `port` and `host` can be provided -as arguments instead of options. - -*Note*: A port or host option, if specified, will take precedence over any port -or host argument. - -## tls.connect(path[, options][, callback]) -<!-- YAML -added: v0.11.3 ---> - -* `path` {string} Default value for `options.path`. -* `options` {Object} See [`tls.connect()`][]. -* `callback` {Function} See [`tls.connect()`][]. - -Same as [`tls.connect()`][] except that `path` can be provided -as an argument instead of an option. - -*Note*: A path option, if specified, will take precedence over the path -argument. - ## tls.connect(options[, callback]) <!-- YAML added: v0.11.3 @@ -884,6 +853,37 @@ socket.on('end', () => { }); ``` +## tls.connect(path[, options][, callback]) +<!-- YAML +added: v0.11.3 +--> + +* `path` {string} Default value for `options.path`. +* `options` {Object} See [`tls.connect()`][]. +* `callback` {Function} See [`tls.connect()`][]. + +Same as [`tls.connect()`][] except that `path` can be provided +as an argument instead of an option. + +*Note*: A path option, if specified, will take precedence over the path +argument. + +## tls.connect(port[, host][, options][, callback]) +<!-- YAML +added: v0.11.3 +--> + +* `port` {number} Default value for `options.port`. +* `host` {string} Optional default value for `options.host`. +* `options` {Object} See [`tls.connect()`][]. +* `callback` {Function} See [`tls.connect()`][]. + +Same as [`tls.connect()`][] except that `port` and `host` can be provided +as arguments instead of options. + +*Note*: A port or host option, if specified, will take precedence over any port +or host argument. + ## tls.createSecureContext(options) <!-- YAML diff --git a/doc/api/url.md b/doc/api/url.md index 8d9483cb12..a38c79aa12 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -34,24 +34,22 @@ illustrate each. (all spaces in the "" line should be ignored -- they are purely for formatting) ``` -### urlObject.href - -The `href` property is the full URL string that was parsed with both the -`protocol` and `host` components converted to lower-case. - -For example: `'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'` +### urlObject.auth -### urlObject.protocol +The `auth` property is the username and password portion of the URL, also +referred to as "userinfo". This string subset follows the `protocol` and +double slashes (if present) and precedes the `host` component, delimited by an +ASCII "at sign" (`@`). The format of the string is `{username}[:{password}]`, +with the `[:{password}]` portion being optional. -The `protocol` property identifies the URL's lower-cased protocol scheme. +For example: `'user:pass'` -For example: `'http:'` +### urlObject.hash -### urlObject.slashes +The `hash` property consists of the "fragment" portion of the URL including +the leading ASCII hash (`#`) character. -The `slashes` property is a `boolean` with a value of `true` if two ASCII -forward-slash characters (`/`) are required following the colon in the -`protocol`. +For example: `'#hash'` ### urlObject.host @@ -60,16 +58,6 @@ the `port` if specified. For example: `'host.com:8080'` -### urlObject.auth - -The `auth` property is the username and password portion of the URL, also -referred to as "userinfo". This string subset follows the `protocol` and -double slashes (if present) and precedes the `host` component, delimited by an -ASCII "at sign" (`@`). The format of the string is `{username}[:{password}]`, -with the `[:{password}]` portion being optional. - -For example: `'user:pass'` - ### urlObject.hostname The `hostname` property is the lower-cased host name portion of the `host` @@ -77,11 +65,21 @@ component *without* the `port` included. For example: `'host.com'` -### urlObject.port +### urlObject.href -The `port` property is the numeric port portion of the `host` component. +The `href` property is the full URL string that was parsed with both the +`protocol` and `host` components converted to lower-case. -For example: `'8080'` +For example: `'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'` + +### urlObject.path + +The `path` property is a concatenation of the `pathname` and `search` +components. + +For example: `'/p/a/t/h?query=string'` + +No decoding of the `path` is performed. ### urlObject.pathname @@ -94,23 +92,17 @@ For example `'/p/a/t/h'` No decoding of the path string is performed. -### urlObject.search - -The `search` property consists of the entire "query string" portion of the -URL, including the leading ASCII question mark (`?`) character. - -For example: `'?query=string'` +### urlObject.port -No decoding of the query string is performed. +The `port` property is the numeric port portion of the `host` component. -### urlObject.path +For example: `'8080'` -The `path` property is a concatenation of the `pathname` and `search` -components. +### urlObject.protocol -For example: `'/p/a/t/h?query=string'` +The `protocol` property identifies the URL's lower-cased protocol scheme. -No decoding of the `path` is performed. +For example: `'http:'` ### urlObject.query @@ -124,12 +116,20 @@ For example: `'query=string'` or `{'query': 'string'}` If returned as a string, no decoding of the query string is performed. If returned as an object, both keys and values are decoded. -### urlObject.hash +### urlObject.search -The `hash` property consists of the "fragment" portion of the URL including -the leading ASCII hash (`#`) character. +The `search` property consists of the entire "query string" portion of the +URL, including the leading ASCII question mark (`?`) character. -For example: `'#hash'` +For example: `'?query=string'` + +No decoding of the query string is performed. + +### urlObject.slashes + +The `slashes` property is a `boolean` with a value of `true` if two ASCII +forward-slash characters (`/`) are required following the colon in the +`protocol`. ## url.format(urlObject) <!-- YAML diff --git a/doc/api/util.md b/doc/api/util.md index 3843f80ce7..15921b85d9 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -343,6 +343,14 @@ util.inspect(obj); // Returns: "{ bar: 'baz' }" ``` +### util.inspect.custom +<!-- YAML +added: v6.6.0 +--> + +A Symbol that can be used to declare custom inspect functions, see +[Custom inspection functions on Objects][]. + ### util.inspect.defaultOptions <!-- YAML added: v6.4.0 @@ -363,18 +371,24 @@ util.inspect.defaultOptions.maxArrayLength = null; console.log(arr); // logs the full array ``` -### util.inspect.custom +## Deprecated APIs + +The following APIs have been deprecated and should no longer be used. Existing +applications and modules should be updated to find alternative approaches. + +### util.\_extend(target, source) <!-- YAML -added: v6.6.0 +added: v0.7.5 +deprecated: v6.0.0 --> -A Symbol that can be used to declare custom inspect functions, see -[Custom inspection functions on Objects][]. +> Stability: 0 - Deprecated: Use [`Object.assign()`] instead. -## Deprecated APIs +The `util._extend()` method was never intended to be used outside of internal +Node.js modules. The community found and used it anyway. -The following APIs have been deprecated and should no longer be used. Existing -applications and modules should be updated to find alternative approaches. +It is deprecated and should not be used in new code. JavaScript comes with very +similar built-in functionality through [`Object.assign()`]. ### util.debug(string) <!-- YAML @@ -829,20 +843,6 @@ deprecated: v0.11.3 Deprecated predecessor of `console.log`. -### util.\_extend(target, source) -<!-- YAML -added: v0.7.5 -deprecated: v6.0.0 ---> - -> Stability: 0 - Deprecated: Use [`Object.assign()`] instead. - -The `util._extend()` method was never intended to be used outside of internal -Node.js modules. The community found and used it anyway. - -It is deprecated and should not be used in new code. JavaScript comes with very -similar built-in functionality through [`Object.assign()`]. - [`Array.isArray`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray [constructor]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/constructor [semantically incompatible]: https://github.com/nodejs/node/issues/4179 diff --git a/doc/api/v8.md b/doc/api/v8.md index 8cec6bdfdf..528f8967e2 100644 --- a/doc/api/v8.md +++ b/doc/api/v8.md @@ -9,45 +9,6 @@ const v8 = require('v8'); *Note*: The APIs and implementation are subject to change at any time. -## v8.getHeapStatistics() -<!-- YAML -added: v1.0.0 ---> - -Returns an object with the following properties: - -* `total_heap_size` {number} -* `total_heap_size_executable` {number} -* `total_physical_size` {number} -* `total_available_size` {number} -* `used_heap_size` {number} -* `heap_size_limit` {number} -* `malloced_memory` {number} -* `peak_malloced_memory` {number} -* `does_zap_garbage` {number} - -`does_zap_garbage` is a 0/1 boolean, which signifies whether the `--zap_code_space` -option is enabled or not. This makes V8 overwrite heap garbage with a bit -pattern. The RSS footprint (resident memory set) gets bigger because it -continuously touches all heap pages and that makes them less likely to get -swapped out by the operating system. - -For example: - -```js -{ - total_heap_size: 7326976, - total_heap_size_executable: 4194304, - total_physical_size: 7326976, - total_available_size: 1152656, - used_heap_size: 3476208, - heap_size_limit: 1535115264, - malloced_memory: 16384, - peak_malloced_memory: 1127496, - does_zap_garbage: 0 -} -``` - ## v8.getHeapSpaceStatistics() <!-- YAML added: v6.0.0 @@ -108,6 +69,45 @@ For example: ] ``` +## v8.getHeapStatistics() +<!-- YAML +added: v1.0.0 +--> + +Returns an object with the following properties: + +* `total_heap_size` {number} +* `total_heap_size_executable` {number} +* `total_physical_size` {number} +* `total_available_size` {number} +* `used_heap_size` {number} +* `heap_size_limit` {number} +* `malloced_memory` {number} +* `peak_malloced_memory` {number} +* `does_zap_garbage` {number} + +`does_zap_garbage` is a 0/1 boolean, which signifies whether the `--zap_code_space` +option is enabled or not. This makes V8 overwrite heap garbage with a bit +pattern. The RSS footprint (resident memory set) gets bigger because it +continuously touches all heap pages and that makes them less likely to get +swapped out by the operating system. + +For example: + +```js +{ + total_heap_size: 7326976, + total_heap_size_executable: 4194304, + total_physical_size: 7326976, + total_available_size: 1152656, + used_heap_size: 3476208, + heap_size_limit: 1535115264, + malloced_memory: 16384, + peak_malloced_memory: 1127496, + does_zap_garbage: 0 +} +``` + ## v8.setFlagsFromString(string) <!-- YAML added: v1.0.0 |