@@ -591,8 +591,8 @@ fs.appendFile('message.txt', 'data to append', 'utf8', callback);
591
591
592
592
Any specified file descriptor has to have been opened for appending.
593
593
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.
596
596
597
597
## fs.appendFileSync(file, data[ , options] )
598
598
<!-- YAML
@@ -1546,10 +1546,10 @@ On Linux, positional writes don't work when the file is opened in append mode.
1546
1546
The kernel ignores the position argument and always appends the data to
1547
1547
the end of the file.
1548
1548
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,
1550
1550
opening a directory on macOS and Linux with the ` 'a+' ` flag - see example
1551
1551
below - will return an error. In contrast, on Windows and FreeBSD, a file
1552
- descriptor will be returned._
1552
+ descriptor will be returned.
1553
1553
1554
1554
``` js
1555
1555
// macOS and Linux
@@ -1711,11 +1711,27 @@ If `options` is a string, then it specifies the encoding. Example:
1711
1711
``` js
1712
1712
fs .readFile (' /etc/passwd' , ' utf8' , callback);
1713
1713
```
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
+ ```
1714
1730
1715
1731
Any specified file descriptor has to support reading.
1716
1732
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.
1719
1735
1720
1736
## fs.readFileSync(path[ , options] )
1721
1737
<!-- YAML
@@ -1740,6 +1756,18 @@ Synchronous version of [`fs.readFile`][]. Returns the contents of the `file`.
1740
1756
If the ` encoding ` option is specified then this function returns a
1741
1757
string. Otherwise it returns a buffer.
1742
1758
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
+
1743
1771
## fs.readlink(path[ , options] , callback)
1744
1772
<!-- YAML
1745
1773
added: v0.1.31
@@ -2113,9 +2141,9 @@ effectively stopping watching of `filename`.
2113
2141
Calling ` fs.unwatchFile() ` with a filename that is not being watched is a
2114
2142
no-op, not an error.
2115
2143
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() ` .
2117
2145
` fs.watch() ` should be used instead of ` fs.watchFile() ` and ` fs.unwatchFile() `
2118
- when possible._
2146
+ when possible.
2119
2147
2120
2148
## fs.utimes(path, atime, mtime, callback)
2121
2149
<!-- YAML
@@ -2323,15 +2351,15 @@ These stat objects are instances of `fs.Stat`.
2323
2351
To be notified when the file was modified, not just accessed, it is necessary
2324
2352
to compare ` curr.mtime ` and ` prev.mtime ` .
2325
2353
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
2327
2355
invoke the listener once, with all the fields zeroed (or, for dates, the Unix
2328
2356
Epoch). In Windows, ` blksize ` and ` blocks ` fields will be ` undefined ` , instead
2329
2357
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.
2331
2359
2332
- _ Note : [ ` fs.watch() ` ] [ ] is more efficient than ` fs.watchFile ` and
2360
+ * Note * : [ ` fs.watch() ` ] [ ] is more efficient than ` fs.watchFile ` and
2333
2361
` fs.unwatchFile ` . ` fs.watch ` should be used instead of ` fs.watchFile ` and
2334
- ` fs.unwatchFile ` when possible._
2362
+ ` fs.unwatchFile ` when possible.
2335
2363
2336
2364
## fs.write(fd, buffer[ , offset[ , length[ , position]]] , callback)
2337
2365
<!-- YAML
@@ -2471,8 +2499,8 @@ Note that it is unsafe to use `fs.writeFile` multiple times on the same file
2471
2499
without waiting for the callback. For this scenario,
2472
2500
` fs.createWriteStream ` is strongly recommended.
2473
2501
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.
2476
2504
2477
2505
## fs.writeFileSync(file, data[ , options] )
2478
2506
<!-- YAML
0 commit comments