Skip to content

Commit

Permalink
doc: clarify fd behaviour with {read,write}File
Browse files Browse the repository at this point in the history
PR-URL: #23706
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
  • Loading branch information
thefourtheye authored and targos committed Nov 1, 2018
1 parent 539e123 commit da494ef
Showing 1 changed file with 27 additions and 8 deletions.
35 changes: 27 additions & 8 deletions doc/api/fs.md
Original file line number Diff line number Diff line change
Expand Up @@ -2554,14 +2554,18 @@ fs.readFile('<directory>', (err, data) => {
});
```

Any specified file descriptor has to support reading.

If a file descriptor is specified as the `path`, it will not be closed
automatically.

The `fs.readFile()` function buffers the entire file. To minimize memory costs,
when possible prefer streaming via `fs.createReadStream()`.

### File Descriptors
1. Any specified file descriptor has to support reading.
2. If a file descriptor is specified as the `path`, it will not be closed
automatically.
3. The reading will begin at the current position. For example, if the file
already had `'Hello World`' and six bytes are read with the file descriptor,
the call to `fs.readFile()` with the same file descriptor, would give
`'World'`, rather than `'Hello World'`.

## fs.readFileSync(path[, options])
<!-- YAML
added: v0.1.8
Expand Down Expand Up @@ -3547,14 +3551,19 @@ If `options` is a string, then it specifies the encoding:
fs.writeFile('message.txt', 'Hello Node.js', 'utf8', callback);
```

Any specified file descriptor has to support writing.

It is unsafe to use `fs.writeFile()` multiple times on the same file without
waiting for the callback. For this scenario, [`fs.createWriteStream()`][] is
recommended.

If a file descriptor is specified as the `file`, it will not be closed
### File Descriptors
1. Any specified file descriptor has to support writing.
2. If a file descriptor is specified as the `file`, it will not be closed
automatically.
3. The writing will begin at the beginning of the file. For example, if the
file already had `'Hello World'` and the newly written content is `'Aloha'`,
then the contents of the file would be `'Aloha World'`, rather than just
`'Aloha'`.


## fs.writeFileSync(file, data[, options])
<!-- YAML
Expand Down Expand Up @@ -3787,6 +3796,11 @@ returned.

The `FileHandle` has to support reading.

If one or more `filehandle.read()` calls are made on a file handle and then a
`filehandle.readFile()` call is made, the data will be read from the current
position till the end of the file. It doesn't always read from the beginning
of the file.

#### filehandle.stat([options])
<!-- YAML
added: v10.0.0
Expand Down Expand Up @@ -3949,6 +3963,11 @@ The `FileHandle` has to support writing.
It is unsafe to use `filehandle.writeFile()` multiple times on the same file
without waiting for the `Promise` to be resolved (or rejected).

If one or more `filehandle.write()` calls are made on a file handle and then a
`filehandle.writeFile()` call is made, the data will be written from the
current position till the end of the file. It doesn't always write from the
beginning of the file.

### fsPromises.access(path[, mode])
<!-- YAML
added: v10.0.0
Expand Down

0 comments on commit da494ef

Please sign in to comment.