Skip to content

Commit bd37c00

Browse files
committed
doc: updated readFileSync in fs.md
Updated fs.md stating fs.readFileAsync is platform specific Refs: #10962
1 parent 9802d46 commit bd37c00

File tree

1 file changed

+42
-14
lines changed

1 file changed

+42
-14
lines changed

doc/api/fs.md

Lines changed: 42 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -492,8 +492,8 @@ fs.appendFile('message.txt', 'data to append', 'utf8', callback);
492492

493493
Any specified file descriptor has to have been opened for appending.
494494

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

498498
## fs.appendFileSync(file, data[, options])
499499
<!-- YAML
@@ -1377,10 +1377,10 @@ On Linux, positional writes don't work when the file is opened in append mode.
13771377
The kernel ignores the position argument and always appends the data to
13781378
the end of the file.
13791379

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

13851385
```js
13861386
// macOS and Linux
@@ -1524,11 +1524,27 @@ If `options` is a string, then it specifies the encoding. Example:
15241524
```js
15251525
fs.readFile('/etc/passwd', 'utf8', callback);
15261526
```
1527+
*Note*: When the path is a directory, the behavior of
1528+
`fs.readFile()` and [`fs.readFileSync()`][] is platform-specific. On macOS,
1529+
Linux, and Windows, an error will be returned. On FreeBSD, a representation
1530+
of the directory's contents will be returned.
1531+
1532+
```js
1533+
// macOS, Linux and Windows
1534+
fs.readFile('<directory>', (err, data) => {
1535+
// => [Error: EISDIR: illegal operation on a directory, read <directory>]
1536+
});
1537+
1538+
// FreeBSD
1539+
fs.readFile('<directory>', (err, data) => {
1540+
// => null, <data>
1541+
});
1542+
```
15271543

15281544
Any specified file descriptor has to support reading.
15291545

1530-
_Note: If a file descriptor is specified as the `file`, it will not be closed
1531-
automatically._
1546+
*Note*: If a file descriptor is specified as the `file`, it will not be closed
1547+
automatically.
15321548

15331549
## fs.readFileSync(file[, options])
15341550
<!-- YAML
@@ -1549,6 +1565,18 @@ Synchronous version of [`fs.readFile`][]. Returns the contents of the `file`.
15491565
If the `encoding` option is specified then this function returns a
15501566
string. Otherwise it returns a buffer.
15511567

1568+
*Note*: Similar to [`fs.readFile()`][], when the path is a directory, the
1569+
behavior of `fs.readFileSync()` is platform-specific.
1570+
1571+
```js
1572+
// macOS, Linux and Windows
1573+
fs.readFileSync('<directory>');
1574+
// => [Error: EISDIR: illegal operation on a directory, read <directory>]
1575+
1576+
// FreeBSD
1577+
fs.readFileSync('<directory>'); // => null, <data>
1578+
```
1579+
15521580
## fs.readlink(path[, options], callback)
15531581
<!-- YAML
15541582
added: v0.1.31
@@ -1855,9 +1883,9 @@ effectively stopping watching of `filename`.
18551883
Calling `fs.unwatchFile()` with a filename that is not being watched is a
18561884
no-op, not an error.
18571885

1858-
_Note: [`fs.watch()`][] is more efficient than `fs.watchFile()` and `fs.unwatchFile()`.
1886+
*Note*: [`fs.watch()`][] is more efficient than `fs.watchFile()` and `fs.unwatchFile()`.
18591887
`fs.watch()` should be used instead of `fs.watchFile()` and `fs.unwatchFile()`
1860-
when possible._
1888+
when possible.
18611889

18621890
## fs.utimes(path, atime, mtime, callback)
18631891
<!-- YAML
@@ -2048,15 +2076,15 @@ These stat objects are instances of `fs.Stat`.
20482076
To be notified when the file was modified, not just accessed, it is necessary
20492077
to compare `curr.mtime` and `prev.mtime`.
20502078

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

2057-
_Note: [`fs.watch()`][] is more efficient than `fs.watchFile` and
2085+
*Note*: [`fs.watch()`][] is more efficient than `fs.watchFile` and
20582086
`fs.unwatchFile`. `fs.watch` should be used instead of `fs.watchFile` and
2059-
`fs.unwatchFile` when possible._
2087+
`fs.unwatchFile` when possible.
20602088

20612089
## fs.write(fd, buffer[, offset[, length[, position]]], callback)
20622090
<!-- YAML
@@ -2196,8 +2224,8 @@ Note that it is unsafe to use `fs.writeFile` multiple times on the same file
21962224
without waiting for the callback. For this scenario,
21972225
`fs.createWriteStream` is strongly recommended.
21982226

2199-
_Note: If a file descriptor is specified as the `file`, it will not be closed
2200-
automatically._
2227+
*Note*: If a file descriptor is specified as the `file`, it will not be closed
2228+
automatically.
22012229

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

0 commit comments

Comments
 (0)