Skip to content

Commit 2614d24

Browse files
thelostone-mcrefack
authored andcommitted
doc: update readFileSync in fs.md
* Updated fs.md stating fs.readFileAsync is platform specific * Fix formatting of `note`s PR-URL: #12800 Refs: #10962 Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Colin Ihrig <[email protected]>
1 parent 8b76c3e commit 2614d24

File tree

1 file changed

+42
-14
lines changed

1 file changed

+42
-14
lines changed

doc/api/fs.md

+42-14
Original file line numberDiff line numberDiff line change
@@ -591,8 +591,8 @@ fs.appendFile('message.txt', 'data to append', 'utf8', callback);
591591

592592
Any specified file descriptor has to have been opened for appending.
593593

594-
_Note: If a file descriptor is specified as the `file`, it will not be closed
595-
automatically._
594+
*Note*: If a file descriptor is specified as the `file`, it will not be closed
595+
automatically.
596596

597597
## fs.appendFileSync(file, data[, options])
598598
<!-- YAML
@@ -1546,10 +1546,10 @@ On Linux, positional writes don't work when the file is opened in append mode.
15461546
The kernel ignores the position argument and always appends the data to
15471547
the end of the file.
15481548

1549-
_Note: The behavior of `fs.open()` is platform specific for some flags. As such,
1549+
*Note*: The behavior of `fs.open()` is platform-specific for some flags. As such,
15501550
opening a directory on macOS and Linux with the `'a+'` flag - see example
15511551
below - will return an error. In contrast, on Windows and FreeBSD, a file
1552-
descriptor will be returned._
1552+
descriptor will be returned.
15531553

15541554
```js
15551555
// macOS and Linux
@@ -1711,11 +1711,27 @@ If `options` is a string, then it specifies the encoding. Example:
17111711
```js
17121712
fs.readFile('/etc/passwd', 'utf8', callback);
17131713
```
1714+
*Note*: When the path is a directory, the behavior of
1715+
`fs.readFile()` and [`fs.readFileSync()`][] is platform-specific. On macOS,
1716+
Linux, and Windows, an error will be returned. On FreeBSD, a representation
1717+
of the directory's contents will be returned.
1718+
1719+
```js
1720+
// macOS, Linux and Windows
1721+
fs.readFile('<directory>', (err, data) => {
1722+
// => [Error: EISDIR: illegal operation on a directory, read <directory>]
1723+
});
1724+
1725+
// FreeBSD
1726+
fs.readFile('<directory>', (err, data) => {
1727+
// => null, <data>
1728+
});
1729+
```
17141730

17151731
Any specified file descriptor has to support reading.
17161732

1717-
_Note: If a file descriptor is specified as the `path`, it will not be closed
1718-
automatically._
1733+
*Note*: If a file descriptor is specified as the `path`, it will not be closed
1734+
automatically.
17191735

17201736
## fs.readFileSync(path[, options])
17211737
<!-- YAML
@@ -1740,6 +1756,18 @@ Synchronous version of [`fs.readFile`][]. Returns the contents of the `file`.
17401756
If the `encoding` option is specified then this function returns a
17411757
string. Otherwise it returns a buffer.
17421758

1759+
*Note*: Similar to [`fs.readFile()`][], when the path is a directory, the
1760+
behavior of `fs.readFileSync()` is platform-specific.
1761+
1762+
```js
1763+
// macOS, Linux and Windows
1764+
fs.readFileSync('<directory>');
1765+
// => [Error: EISDIR: illegal operation on a directory, read <directory>]
1766+
1767+
// FreeBSD
1768+
fs.readFileSync('<directory>'); // => null, <data>
1769+
```
1770+
17431771
## fs.readlink(path[, options], callback)
17441772
<!-- YAML
17451773
added: v0.1.31
@@ -2113,9 +2141,9 @@ effectively stopping watching of `filename`.
21132141
Calling `fs.unwatchFile()` with a filename that is not being watched is a
21142142
no-op, not an error.
21152143

2116-
_Note: [`fs.watch()`][] is more efficient than `fs.watchFile()` and `fs.unwatchFile()`.
2144+
*Note*: [`fs.watch()`][] is more efficient than `fs.watchFile()` and `fs.unwatchFile()`.
21172145
`fs.watch()` should be used instead of `fs.watchFile()` and `fs.unwatchFile()`
2118-
when possible._
2146+
when possible.
21192147

21202148
## fs.utimes(path, atime, mtime, callback)
21212149
<!-- YAML
@@ -2323,15 +2351,15 @@ These stat objects are instances of `fs.Stat`.
23232351
To be notified when the file was modified, not just accessed, it is necessary
23242352
to compare `curr.mtime` and `prev.mtime`.
23252353

2326-
_Note: when an `fs.watchFile` operation results in an `ENOENT` error, it will
2354+
*Note*: when an `fs.watchFile` operation results in an `ENOENT` error, it will
23272355
invoke the listener once, with all the fields zeroed (or, for dates, the Unix
23282356
Epoch). In Windows, `blksize` and `blocks` fields will be `undefined`, instead
23292357
of zero. If the file is created later on, the listener will be called again,
2330-
with the latest stat objects. This is a change in functionality since v0.10._
2358+
with the latest stat objects. This is a change in functionality since v0.10.
23312359

2332-
_Note: [`fs.watch()`][] is more efficient than `fs.watchFile` and
2360+
*Note*: [`fs.watch()`][] is more efficient than `fs.watchFile` and
23332361
`fs.unwatchFile`. `fs.watch` should be used instead of `fs.watchFile` and
2334-
`fs.unwatchFile` when possible._
2362+
`fs.unwatchFile` when possible.
23352363

23362364
## fs.write(fd, buffer[, offset[, length[, position]]], callback)
23372365
<!-- YAML
@@ -2471,8 +2499,8 @@ Note that it is unsafe to use `fs.writeFile` multiple times on the same file
24712499
without waiting for the callback. For this scenario,
24722500
`fs.createWriteStream` is strongly recommended.
24732501

2474-
_Note: If a file descriptor is specified as the `file`, it will not be closed
2475-
automatically._
2502+
*Note*: If a file descriptor is specified as the `file`, it will not be closed
2503+
automatically.
24762504

24772505
## fs.writeFileSync(file, data[, options])
24782506
<!-- YAML

0 commit comments

Comments
 (0)