@@ -492,8 +492,8 @@ fs.appendFile('message.txt', 'data to append', 'utf8', callback);
492
492
493
493
Any specified file descriptor has to have been opened for appending.
494
494
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.
497
497
498
498
## fs.appendFileSync(file, data[ , options] )
499
499
<!-- YAML
@@ -1377,10 +1377,10 @@ On Linux, positional writes don't work when the file is opened in append mode.
1377
1377
The kernel ignores the position argument and always appends the data to
1378
1378
the end of the file.
1379
1379
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,
1381
1381
opening a directory on macOS and Linux with the ` 'a+' ` flag - see example
1382
1382
below - will return an error. In contrast, on Windows and FreeBSD, a file
1383
- descriptor will be returned._
1383
+ descriptor will be returned.
1384
1384
1385
1385
``` js
1386
1386
// macOS and Linux
@@ -1524,11 +1524,27 @@ If `options` is a string, then it specifies the encoding. Example:
1524
1524
``` js
1525
1525
fs .readFile (' /etc/passwd' , ' utf8' , callback);
1526
1526
```
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
+ ```
1527
1543
1528
1544
Any specified file descriptor has to support reading.
1529
1545
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.
1532
1548
1533
1549
## fs.readFileSync(file[ , options] )
1534
1550
<!-- YAML
@@ -1549,6 +1565,18 @@ Synchronous version of [`fs.readFile`][]. Returns the contents of the `file`.
1549
1565
If the ` encoding ` option is specified then this function returns a
1550
1566
string. Otherwise it returns a buffer.
1551
1567
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
+
1552
1580
## fs.readlink(path[ , options] , callback)
1553
1581
<!-- YAML
1554
1582
added: v0.1.31
@@ -1855,9 +1883,9 @@ effectively stopping watching of `filename`.
1855
1883
Calling ` fs.unwatchFile() ` with a filename that is not being watched is a
1856
1884
no-op, not an error.
1857
1885
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() ` .
1859
1887
` fs.watch() ` should be used instead of ` fs.watchFile() ` and ` fs.unwatchFile() `
1860
- when possible._
1888
+ when possible.
1861
1889
1862
1890
## fs.utimes(path, atime, mtime, callback)
1863
1891
<!-- YAML
@@ -2048,15 +2076,15 @@ These stat objects are instances of `fs.Stat`.
2048
2076
To be notified when the file was modified, not just accessed, it is necessary
2049
2077
to compare ` curr.mtime ` and ` prev.mtime ` .
2050
2078
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
2052
2080
invoke the listener once, with all the fields zeroed (or, for dates, the Unix
2053
2081
Epoch). In Windows, ` blksize ` and ` blocks ` fields will be ` undefined ` , instead
2054
2082
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.
2056
2084
2057
- _ Note : [ ` fs.watch() ` ] [ ] is more efficient than ` fs.watchFile ` and
2085
+ * Note * : [ ` fs.watch() ` ] [ ] is more efficient than ` fs.watchFile ` and
2058
2086
` fs.unwatchFile ` . ` fs.watch ` should be used instead of ` fs.watchFile ` and
2059
- ` fs.unwatchFile ` when possible._
2087
+ ` fs.unwatchFile ` when possible.
2060
2088
2061
2089
## fs.write(fd, buffer[ , offset[ , length[ , position]]] , callback)
2062
2090
<!-- YAML
@@ -2196,8 +2224,8 @@ Note that it is unsafe to use `fs.writeFile` multiple times on the same file
2196
2224
without waiting for the callback. For this scenario,
2197
2225
` fs.createWriteStream ` is strongly recommended.
2198
2226
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.
2201
2229
2202
2230
## fs.writeFileSync(file, data[ , options] )
2203
2231
<!-- YAML
0 commit comments