Skip to content

Commit 623e111

Browse files
benglcodebytere
authored andcommitted
doc: correct filehandle.[read|write|append]File()
* Remove `mode` and `flag` options for all three functions, since they all ignore those options. * Remove mention of `path` argument for `readFile`, since it isn't actually an option to this method. * Clarify that for file handles, `appendFile` and `writeFile` are equivalent. PR-URL: #31235 Reviewed-By: Rich Trott <[email protected]> Reviewed-By: Anto Aravinth <[email protected]>
1 parent 73c4729 commit 623e111

File tree

1 file changed

+6
-16
lines changed

1 file changed

+6
-16
lines changed

doc/api/fs.md

Lines changed: 6 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -4233,17 +4233,13 @@ added: v10.0.0
42334233
* `data` {string|Buffer}
42344234
* `options` {Object|string}
42354235
* `encoding` {string|null} **Default:** `'utf8'`
4236-
* `mode` {integer} **Default:** `0o666`
4237-
* `flag` {string} See [support of file system `flags`][]. **Default:** `'a'`.
42384236
* Returns: {Promise}
42394237

4240-
Asynchronously append data to this file, creating the file if it does not yet
4241-
exist. `data` can be a string or a [`Buffer`][]. The `Promise` will be
4242-
resolved with no arguments upon success.
4238+
Alias of [`filehandle.writeFile()`][].
42434239

4244-
If `options` is a string, then it specifies the encoding.
4245-
4246-
The `FileHandle` must have been opened for appending.
4240+
When operating on file handles, the mode cannot be changed from what it was set
4241+
to with [`fsPromises.open()`][]. Therefore, this is equivalent to
4242+
[`filehandle.writeFile()`][].
42474243

42484244
#### `filehandle.chmod(mode)`
42494245
<!-- YAML
@@ -4344,7 +4340,6 @@ added: v10.0.0
43444340

43454341
* `options` {Object|string}
43464342
* `encoding` {string|null} **Default:** `null`
4347-
* `flag` {string} See [support of file system `flags`][]. **Default:** `'r'`.
43484343
* Returns: {Promise}
43494344

43504345
Asynchronously reads the entire contents of a file.
@@ -4355,11 +4350,6 @@ object. Otherwise, the data will be a string.
43554350

43564351
If `options` is a string, then it specifies the encoding.
43574352

4358-
When the `path` is a directory, the behavior of `fsPromises.readFile()` is
4359-
platform-specific. On macOS, Linux, and Windows, the promise will be rejected
4360-
with an error. On FreeBSD, a representation of the directory's contents will be
4361-
returned.
4362-
43634353
The `FileHandle` has to support reading.
43644354

43654355
If one or more `filehandle.read()` calls are made on a file handle and then a
@@ -4549,8 +4539,6 @@ added: v10.0.0
45494539
* `data` {string|Buffer|Uint8Array}
45504540
* `options` {Object|string}
45514541
* `encoding` {string|null} **Default:** `'utf8'`
4552-
* `mode` {integer} **Default:** `0o666`
4553-
* `flag` {string} See [support of file system `flags`][]. **Default:** `'w'`.
45544542
* Returns: {Promise}
45554543

45564544
Asynchronously writes data to a file, replacing the file if it already exists.
@@ -5524,6 +5512,7 @@ the file contents.
55245512
[`UV_THREADPOOL_SIZE`]: cli.html#cli_uv_threadpool_size_size
55255513
[`WriteStream`]: #fs_class_fs_writestream
55265514
[`event ports`]: https://illumos.org/man/port_create
5515+
[`filehandle.writeFile()`]: #fs_filehandle_writefile_data_options
55275516
[`fs.Dir`]: #fs_class_fs_dir
55285517
[`fs.Dirent`]: #fs_class_fs_dirent
55295518
[`fs.FSWatcher`]: #fs_class_fs_fswatcher
@@ -5558,6 +5547,7 @@ the file contents.
55585547
[`fs.write(fd, string...)`]: #fs_fs_write_fd_string_position_encoding_callback
55595548
[`fs.writeFile()`]: #fs_fs_writefile_file_data_options_callback
55605549
[`fs.writev()`]: #fs_fs_writev_fd_buffers_position_callback
5550+
[`fsPromises.open()`]: #fs_fspromises_open_path_flags_mode
55615551
[`fsPromises.opendir()`]: #fs_fspromises_opendir_path_options
55625552
[`inotify(7)`]: http://man7.org/linux/man-pages/man7/inotify.7.html
55635553
[`kqueue(2)`]: https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2

0 commit comments

Comments
 (0)