doc: add emitClose option for fs streams

PR-URL: https://github.com/nodejs/node/pull/29212
Fixes: https://github.com/nodejs/node/issues/29177
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
This commit is contained in:
Rich Trott 2019-08-21 22:13:56 -07:00
parent cb92126955
commit 47ff44e08e

View File

@ -1504,6 +1504,9 @@ fs.copyFileSync('source.txt', 'destination.txt', COPYFILE_EXCL);
<!-- YAML <!-- YAML
added: v0.1.31 added: v0.1.31
changes: changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/29212
description: Enable `emitClose` option.
- version: v11.0.0 - version: v11.0.0
pr-url: https://github.com/nodejs/node/pull/19898 pr-url: https://github.com/nodejs/node/pull/19898
description: Impose new restrictions on `start` and `end`, throwing description: Impose new restrictions on `start` and `end`, throwing
@ -1529,6 +1532,7 @@ changes:
* `fd` {integer} **Default:** `null` * `fd` {integer} **Default:** `null`
* `mode` {integer} **Default:** `0o666` * `mode` {integer} **Default:** `0o666`
* `autoClose` {boolean} **Default:** `true` * `autoClose` {boolean} **Default:** `true`
* `emitClose` {boolean} **Default:** `false`
* `start` {integer} * `start` {integer}
* `end` {integer} **Default:** `Infinity` * `end` {integer} **Default:** `Infinity`
* `highWaterMark` {integer} **Default:** `64 * 1024` * `highWaterMark` {integer} **Default:** `64 * 1024`
@ -1555,6 +1559,10 @@ If `fd` points to a character device that only supports blocking reads
available. This can prevent the process from exiting and the stream from available. This can prevent the process from exiting and the stream from
closing naturally. closing naturally.
By default, the stream will not emit a `'close'` event after it has been
destroyed. This is the opposite of the default for other `Readable` streams.
Set the `emitClose` option to `true` to change this behavior.
```js ```js
const fs = require('fs'); const fs = require('fs');
// Create a stream from some character device. // Create a stream from some character device.
@ -1592,6 +1600,9 @@ If `options` is a string, then it specifies the encoding.
<!-- YAML <!-- YAML
added: v0.1.31 added: v0.1.31
changes: changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/29212
description: Enable `emitClose` option.
- version: v7.6.0 - version: v7.6.0
pr-url: https://github.com/nodejs/node/pull/10739 pr-url: https://github.com/nodejs/node/pull/10739
description: The `path` parameter can be a WHATWG `URL` object using description: The `path` parameter can be a WHATWG `URL` object using
@ -1615,6 +1626,7 @@ changes:
* `fd` {integer} **Default:** `null` * `fd` {integer} **Default:** `null`
* `mode` {integer} **Default:** `0o666` * `mode` {integer} **Default:** `0o666`
* `autoClose` {boolean} **Default:** `true` * `autoClose` {boolean} **Default:** `true`
* `emitClose` {boolean} **Default:** `false`
* `start` {integer} * `start` {integer}
* Returns: {fs.WriteStream} See [Writable Stream][]. * Returns: {fs.WriteStream} See [Writable Stream][].
@ -1631,6 +1643,10 @@ then the file descriptor won't be closed, even if there's an error.
It is the application's responsibility to close it and make sure there's no It is the application's responsibility to close it and make sure there's no
file descriptor leak. file descriptor leak.
By default, the stream will not emit a `'close'` event after it has been
destroyed. This is the opposite of the default for other `Writable` streams.
Set the `emitClose` option to `true` to change this behavior.
Like [`ReadStream`][], if `fd` is specified, [`WriteStream`][] will ignore the Like [`ReadStream`][], if `fd` is specified, [`WriteStream`][] will ignore the
`path` argument and will use the specified file descriptor. This means that no `path` argument and will use the specified file descriptor. This means that no
`'open'` event will be emitted. `fd` should be blocking; non-blocking `fd`s `'open'` event will be emitted. `fd` should be blocking; non-blocking `fd`s