doc: add flags section to document all flags

Adds a section at the very end to document all flags and links
to it from every function that takes a flag argument.

Fixes: https://github.com/nodejs/node/issues/16971

PR-URL: https://github.com/nodejs/node/pull/20042
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>

doc/api/fs.md

@@ -917,7 +917,7 @@ changes:
 * `options` {Object|string}
   * `encoding` {string|null} **Default:** `'utf8'`
   * `mode` {integer} **Default:** `0o666`
-  * `flag` {string} **Default:** `'a'`
+  * `flag` {string} See [support of file system `flags`][]. **Default:** `'a'`.
 * `callback` {Function}
   * `err` {Error}
 
@@ -972,7 +972,7 @@ changes:
 * `options` {Object|string}
   * `encoding` {string|null} **Default:** `'utf8'`
   * `mode` {integer} **Default:** `0o666`
-  * `flag` {string} **Default:** `'a'`
+  * `flag` {string} See [support of file system `flags`][]. **Default:** `'a'`.
 
 Synchronously append data to a file, creating the file if it does not yet
 exist. `data` can be a string or a [`Buffer`][].
@@ -1305,7 +1305,8 @@ changes:
 
 * `path` {string|Buffer|URL}
 * `options` {string|Object}
-  * `flags` {string} **Default:** `'r'`
+  * `flags` {string} See [support of file system `flags`][]. **Default:**
+  `'r'`.
   * `encoding` {string} **Default:** `null`
   * `fd` {integer} **Default:** `null`
   * `mode` {integer} **Default:** `0o666`
@@ -1368,7 +1369,8 @@ changes:
 
 * `path` {string|Buffer|URL}
 * `options` {string|Object}
-  * `flags` {string} **Default:** `'w'`
+  * `flags` {string} See [support of file system `flags`][]. **Default:**
+  `'w'`.
   * `encoding` {string} **Default:** `'utf8'`
   * `fd` {integer} **Default:** `null`
   * `mode` {integer} **Default:** `0o666`
@@ -2110,92 +2112,19 @@ changes:
 -->
 
 * `path` {string|Buffer|URL}
-* `flags` {string|number}
+* `flags` {string|number} See [support of file system `flags`][].
 * `mode` {integer} **Default:** `0o666` (readable and writable)
 * `callback` {Function}
   * `err` {Error}
   * `fd` {integer}
 
-Asynchronous file open. See open(2). `flags` can be:
+Asynchronous file open. See open(2).
-
-* `'r'` - Open file for reading.
-An exception occurs if the file does not exist.
-
-* `'r+'` - Open file for reading and writing.
-An exception occurs if the file does not exist.
-
-* `'rs+'` - Open file for reading and writing in synchronous mode. Instructs
-  the operating system to bypass the local file system cache.
-
-  This is primarily useful for opening files on NFS mounts as it allows skipping
-  the potentially stale local cache. It has a very real impact on I/O
-  performance so using this flag is not recommended unless it is needed.
-
-  Note that this doesn't turn `fs.open()` into a synchronous blocking call.
-  If synchronous operation is desired `fs.openSync()` should be used.
-
-* `'w'` - Open file for writing.
-The file is created (if it does not exist) or truncated (if it exists).
-
-* `'wx'` - Like `'w'` but fails if `path` exists.
-
-* `'w+'` - Open file for reading and writing.
-The file is created (if it does not exist) or truncated (if it exists).
-
-* `'wx+'` - Like `'w+'` but fails if `path` exists.
-
-* `'a'` - Open file for appending.
-The file is created if it does not exist.
-
-* `'ax'` - Like `'a'` but fails if `path` exists.
-
-* `'as'` - Open file for appending in synchronous mode.
-The file is created if it does not exist.
-
-* `'a+'` - Open file for reading and appending.
-The file is created if it does not exist.
-
-* `'ax+'` - Like `'a+'` but fails if `path` exists.
-
-* `'as+'` - Open file for reading and appending in synchronous mode.
-The file is created if it does not exist.
 
 `mode` sets the file mode (permission and sticky bits), but only if the file was
 created.
 
 The callback gets two arguments `(err, fd)`.
 
-The exclusive flag `'x'` (`O_EXCL` flag in open(2)) ensures that `path` is newly
-created. On POSIX systems, `path` is considered to exist even if it is a symlink
-to a non-existent file. The exclusive flag may or may not work with network file
-systems.
-
-`flags` can also be a number as documented by open(2); commonly used constants
-are available from `fs.constants`. On Windows, flags are translated to
-their equivalent ones where applicable, e.g. `O_WRONLY` to `FILE_GENERIC_WRITE`,
-or `O_EXCL|O_CREAT` to `CREATE_NEW`, as accepted by CreateFileW.
-
-On Linux, positional writes don't work when the file is opened in append mode.
-The kernel ignores the position argument and always appends the data to
-the end of the file.
-
-The behavior of `fs.open()` is platform-specific for some flags. As such,
-opening a directory on macOS and Linux with the `'a+'` flag - see example
-below - will return an error. In contrast, on Windows and FreeBSD, a file
-descriptor will be returned.
-
-```js
-// macOS and Linux
-fs.open('<directory>', 'a+', (err, fd) => {
-  // => [Error: EISDIR: illegal operation on a directory, open <directory>]
-});
-
-// Windows and FreeBSD
-fs.open('<directory>', 'a+', (err, fd) => {
-  // => null, <fd>
-});
-```
-
 Some characters (`< > : " / \ | ? *`) are reserved under Windows as documented
 by [Naming Files, Paths, and Namespaces][]. Under NTFS, if the filename contains
 a colon, Node.js will open a file system stream, as described by
@@ -2204,11 +2133,6 @@ a colon, Node.js will open a file system stream, as described by
 Functions based on `fs.open()` exhibit this behavior as well. eg.
 `fs.writeFile()`, `fs.readFile()`, etc.
 
-*Note:* On Windows, opening an existing hidden file using the `w` flag (either
-through `fs.open()` or `fs.writeFile()`) will fail with `EPERM`. Existing hidden
-files can be opened for writing with the `r+` flag. A call to `fs.ftruncate()`
-can be used to reset the file contents.
-
 ## fs.openSync(path, flags[, mode])
 <!-- YAML
 added: v0.1.21
@@ -2220,7 +2144,7 @@ changes:
 -->
 
 * `path` {string|Buffer|URL}
-* `flags` {string|number}
+* `flags` {string|number} See [support of file system `flags`][].
 * `mode` {integer} **Default:** `0o666`
 * Returns: {number}
 
@@ -2354,7 +2278,7 @@ changes:
 * `path` {string|Buffer|URL|integer} filename or file descriptor
 * `options` {Object|string}
   * `encoding` {string|null} **Default:** `null`
-  * `flag` {string} **Default:** `'r'`
+  * `flag` {string} See [support of file system `flags`][]. **Default:** `'r'`.
 * `callback` {Function}
   * `err` {Error}
   * `data` {string|Buffer}
@@ -2420,7 +2344,7 @@ changes:
 * `path` {string|Buffer|URL|integer} filename or file descriptor
 * `options` {Object|string}
   * `encoding` {string|null} **Default:** `null`
-  * `flag` {string} **Default:** `'r'`
+  * `flag` {string} See [support of file system `flags`][]. **Default:** `'r'`.
 * Returns: {string|Buffer}
 
 Synchronous version of [`fs.readFile()`][]. Returns the contents of the `path`.
@@ -3347,7 +3271,7 @@ changes:
 * `options` {Object|string}
   * `encoding` {string|null} **Default:** `'utf8'`
   * `mode` {integer} **Default:** `0o666`
-  * `flag` {string} **Default:** `'w'`
+  * `flag` {string} See [support of file system `flags`][]. **Default:** `'w'`.
 * `callback` {Function}
   * `err` {Error}
 
@@ -3397,7 +3321,7 @@ changes:
 * `options` {Object|string}
   * `encoding` {string|null} **Default:** `'utf8'`
   * `mode` {integer} **Default:** `0o666`
-  * `flag` {string} **Default:** `'w'`
+  * `flag` {string} See [support of file system `flags`][]. **Default:** `'w'`.
 
 The synchronous version of [`fs.writeFile()`][]. Returns `undefined`.
 
@@ -3473,7 +3397,7 @@ added: REPLACEME
 * `options` {Object|string}
   * `encoding` {string|null} **Default:** `'utf8'`
   * `mode` {integer} **Default:** `0o666`
-  * `flag` {string} **Default:** `'a'`
+  * `flag` {string} See [support of file system `flags`][]. **Default:** `'a'`.
 * Returns: {Promise}
 
 Asynchronously append data to this file, creating the file if it does not yet
@@ -3577,7 +3501,7 @@ added: REPLACEME
 -->
 * `options` {Object|string}
   * `encoding` {string|null} **Default:** `null`
-  * `flag` {string} **Default:** `'r'`
+  * `flag` {string} See [support of file system `flags`][]. **Default:** `'r'`.
 * Returns: {Promise}
 
 Asynchronously reads the entire contents of a file.
@@ -3711,7 +3635,7 @@ added: REPLACEME
 * `options` {Object|string}
   * `encoding` {string|null} **Default:** `'utf8'`
   * `mode` {integer} **Default:** `0o666`
-  * `flag` {string} **Default:** `'w'`
+  * `flag` {string} See [support of file system `flags`][]. **Default:** `'w'`.
 * Returns: {Promise}
 
 Asynchronously writes data to a file, replacing the file if it already exists.
@@ -3777,7 +3701,7 @@ added: REPLACEME
 * `options` {Object|string}
   * `encoding` {string|null} **Default:** `'utf8'`
   * `mode` {integer} **Default:** `0o666`
-  * `flag` {string} **Default:** `'a'`
+  * `flag` {string} See [support of file system `flags`][]. **Default:** `'a'`.
 * Returns: {Promise}
 
 Asynchronously append data to a file, creating the file if it does not yet
@@ -4086,89 +4010,21 @@ added: REPLACEME
 -->
 
 * `path` {string|Buffer|URL}
-* `flags` {string|number}
+* `flags` {string|number} See [support of file system `flags`][].
 * `mode` {integer} **Default:** `0o666` (readable and writable)
 * Returns: {Promise}
 
 Asynchronous file open that returns a `Promise` that, when resolved, yields a
 `FileHandle` object. See open(2).
 
-The `flags` argument can be:
-
-* `'r'` - Open file for reading.
-An exception occurs if the file does not exist.
-
-* `'r+'` - Open file for reading and writing.
-An exception occurs if the file does not exist.
-
-* `'rs+'` - Open file for reading and writing in synchronous mode. Instructs
-  the operating system to bypass the local file system cache.
-
-  This is primarily useful for opening files on NFS mounts as it allows skipping
-  the potentially stale local cache. It has a very real impact on I/O
-  performance so using this flag is not recommended unless it is needed.
-
-  Note that this does not turn `fsPromises.open()` into a synchronous blocking
-  call.
-
-* `'w'` - Open file for writing.
-The file is created (if it does not exist) or truncated (if it exists).
-
-* `'wx'` - Like `'w'` but fails if `path` exists.
-
-* `'w+'` - Open file for reading and writing.
-The file is created (if it does not exist) or truncated (if it exists).
-
-* `'wx+'` - Like `'w+'` but fails if `path` exists.
-
-* `'a'` - Open file for appending.
-The file is created if it does not exist.
-
-* `'ax'` - Like `'a'` but fails if `path` exists.
-
-* `'as'` - Open file for appending in synchronous mode.
-The file is created if it does not exist.
-
-* `'a+'` - Open file for reading and appending.
-The file is created if it does not exist.
-
-* `'ax+'` - Like `'a+'` but fails if `path` exists.
-
-* `'as+'` - Open file for reading and appending in synchronous mode.
-The file is created if it does not exist.
-
 `mode` sets the file mode (permission and sticky bits), but only if the file was
 created.
 
-The exclusive flag `'x'` (`O_EXCL` flag in open(2)) ensures that `path` is newly
-created. On POSIX systems, `path` is considered to exist even if it is a symlink
-to a non-existent file. The exclusive flag may or may not work with network file
-systems.
-
-`flags` can also be a number as documented by open(2); commonly used constants
-are available from `fs.constants`. On Windows, flags are translated to
-their equivalent ones where applicable, e.g. `O_WRONLY` to `FILE_GENERIC_WRITE`,
-or `O_EXCL|O_CREAT` to `CREATE_NEW`, as accepted by CreateFileW.
-
-On Linux, positional writes don't work when the file is opened in append mode.
-The kernel ignores the position argument and always appends the data to
-the end of the file.
-
-The behavior of `fsPromises.open()` is platform-specific for some
-flags. As such, opening a directory on macOS and Linux with the `'a+'` flag will
-return an error. In contrast, on Windows and FreeBSD, a `FileHandle` will be
-returned.
-
 Some characters (`< > : " / \ | ? *`) are reserved under Windows as documented
 by [Naming Files, Paths, and Namespaces][]. Under NTFS, if the filename contains
 a colon, Node.js will open a file system stream, as described by
 [this MSDN page][MSDN-Using-Streams].
 
-*Note:* On Windows, opening an existing hidden file using the `w` flag (e.g.
-using `fsPromises.open()`) will fail with `EPERM`. Existing hidden
-files can be opened for writing with the `r+` flag. A call to
-`fsPromises.ftruncate()` can be used to reset the file contents.
-
 ### fsPromises.read(filehandle, buffer, offset, length, position)
 <!-- YAML
 added: REPLACEME
@@ -4224,7 +4080,7 @@ added: REPLACEME
 * `path` {string|Buffer|URL|FileHandle} filename or `FileHandle`
 * `options` {Object|string}
   * `encoding` {string|null} **Default:** `null`
-  * `flag` {string} **Default:** `'r'`
+  * `flag` {string} See [support of file system `flags`][]. **Default:** `'r'`.
 * Returns: {Promise}
 
 Asynchronously reads the entire contents of a file.
@@ -4425,7 +4281,7 @@ added: REPLACEME
 * `options` {Object|string}
   * `encoding` {string|null} **Default:** `'utf8'`
   * `mode` {integer} **Default:** `0o666`
-  * `flag` {string} **Default:** `'w'`
+  * `flag` {string} See [support of file system `flags`][]. **Default:** `'w'`.
 * Returns: {Promise}
 
 Asynchronously writes data to a file, replacing the file if it already exists.
@@ -4697,6 +4553,94 @@ The following constants are meant for use with the [`fs.Stats`][] object's
   </tr>
 </table>
 
+## File System Flags
+
+The following flags are available wherever the `flag` option takes a
+string:
+
+* `'a'` - Open file for appending.
+  The file is created if it does not exist.
+
+* `'ax'` - Like `'a'` but fails if the path exists.
+
+* `'a+'` - Open file for reading and appending.
+  The file is created if it does not exist.
+
+* `'ax+'` - Like `'a+'` but fails if the path exists.
+
+* `'as'` - Open file for appending in synchronous mode.
+  The file is created if it does not exist.
+
+* `'as+'` - Open file for reading and appending in synchronous mode.
+  The file is created if it does not exist.
+
+* `'r'` - Open file for reading.
+  An exception occurs if the file does not exist.
+
+* `'r+'` - Open file for reading and writing.
+  An exception occurs if the file does not exist.
+
+* `'rs+'` - Open file for reading and writing in synchronous mode. Instructs
+  the operating system to bypass the local file system cache.
+
+  This is primarily useful for opening files on NFS mounts as it allows
+  skipping the potentially stale local cache. It has a very real impact on
+  I/O performance so using this flag is not recommended unless it is needed.
+
+  Note that this doesn't turn `fs.open()` or `fsPromises.open()` into a
+  synchronous blocking call. If synchronous operation is desired, something
+  like `fs.openSync()` should be used.
+
+* `'w'` - Open file for writing.
+  The file is created (if it does not exist) or truncated (if it exists).
+
+* `'wx'` - Like `'w'` but fails if the path exists.
+
+* `'w+'` - Open file for reading and writing.
+The file is created (if it does not exist) or truncated (if it exists).
+
+* `'wx+'` - Like `'w+'` but fails if the path exists.
+
+`flag` can also be a number as documented by open(2); commonly used constants
+are available from `fs.constants`. On Windows, flags are translated to
+their equivalent ones where applicable, e.g. `O_WRONLY` to `FILE_GENERIC_WRITE`,
+or `O_EXCL|O_CREAT` to `CREATE_NEW`, as accepted by CreateFileW.
+
+The exclusive flag `'x'` (`O_EXCL` flag in open(2)) ensures that path is newly
+created. On POSIX systems, path is considered to exist even if it is a symlink
+to a non-existent file. The exclusive flag may or may not work with network
+file systems.
+
+On Linux, positional writes don't work when the file is opened in append mode.
+The kernel ignores the position argument and always appends the data to
+the end of the file.
+
+Modifying a file rather than replacing it may require a flags mode of `'r+'`
+rather than the default mode `'w'`.
+
+The behavior of some flags are platform-specific. As such, opening a directory
+on macOS and Linux with the `'a+'` flag - see example below - will return an
+error. In contrast, on Windows and FreeBSD, a file descriptor or a `FileHandle`
+will be returned.
+
+```js
+// macOS and Linux
+fs.open('<directory>', 'a+', (err, fd) => {
+  // => [Error: EISDIR: illegal operation on a directory, open <directory>]
+});
+
+// Windows and FreeBSD
+fs.open('<directory>', 'a+', (err, fd) => {
+  // => null, <fd>
+});
+```
+
+On Windows, opening an existing hidden file using the `'w'` flag (either
+through `fs.open()` or `fs.writeFile()` or `fsPromises.open()`) will fail with
+`EPERM`. Existing hidden files can be opened for writing with the `'r+'` flag.
+
+A call to `fs.ftruncate()` or `fsPromises.ftruncate()` can be used to reset
+the file contents.
 
 [`AHAFS`]: https://www.ibm.com/developerworks/aix/library/au-aix_event_infrastructure/
 [`Buffer.byteLength`]: buffer.html#buffer_class_method_buffer_bytelength_string_encoding
@@ -4747,3 +4691,4 @@ The following constants are meant for use with the [`fs.Stats`][] object's
 [inode]: https://en.wikipedia.org/wiki/Inode
 [Naming Files, Paths, and Namespaces]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247(v=vs.85).aspx
 [MSDN-Using-Streams]: https://msdn.microsoft.com/en-us/library/windows/desktop/bb540537.aspx
+[support of file system `flags`]: #fs_file_system_flags