From 15887968e8e9f300acaac602357e13655ed9056b Mon Sep 17 00:00:00 2001 From: Indranil Dasgupta Date: Sun, 15 Apr 2018 03:50:48 +0200 Subject: [PATCH 1/7] 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 --- doc/api/fs.md | 100 +++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 83 insertions(+), 17 deletions(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index 6fc7075d182451..a4c5a757f89dfd 100644 --- a/doc/api/fs.md +++ b/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,7 +2112,7 @@ 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} @@ -2220,7 +2222,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 +2356,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 +2422,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 +3349,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 +3399,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 +3475,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 +3579,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 +3713,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 +3779,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,7 +4088,7 @@ 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} @@ -4224,7 +4226,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 +4427,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 +4699,69 @@ The following constants are meant for use with the [`fs.Stats`][] object's +### File System Flags + +The following flags are available wherever the `flag` option takes a +string: + +* `'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. + +* `'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. + +`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'`. + +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. + + + [`AHAFS`]: https://www.ibm.com/developerworks/aix/library/au-aix_event_infrastructure/ [`Buffer.byteLength`]: buffer.html#buffer_class_method_buffer_bytelength_string_encoding @@ -4739,6 +4804,7 @@ The following constants are meant for use with the [`fs.Stats`][] object's [Caveats]: #fs_caveats [Common System Errors]: errors.html#errors_common_system_errors [FS Constants]: #fs_fs_constants_1 +[support of file system `flags`]: #fs_file_system_flags [MDN-Date]: https://developer.mozilla.org/en-US/JavaScript/Reference/Global_Objects/Date [MDN-Number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type [MSDN-Rel-Path]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247.aspx#fully_qualified_vs._relative_paths From 241b7cd811bc0e6298bd4e5e3e59fcd1368d577b Mon Sep 17 00:00:00 2001 From: Indranil Dasgupta Date: Sun, 15 Apr 2018 11:18:17 +0200 Subject: [PATCH 2/7] doc: consolidated flag options in one central place and rearranged list Removed description of flags into one place, linking to it from all other references. Also rearranged the flags alphabetically, keeping connected ones together. Fixes: https://github.com/nodejs/node/issues/16971 --- doc/api/fs.md | 206 +++++++++++--------------------------------------- 1 file changed, 43 insertions(+), 163 deletions(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index a4c5a757f89dfd..8c0c8fa387cad3 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -2118,86 +2118,13 @@ changes: * `err` {Error} * `fd` {integer} -Asynchronous file open. See open(2). `flags` 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 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. +Asynchronous file open. See open(2). `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('', 'a+', (err, fd) => { - // => [Error: EISDIR: illegal operation on a directory, open ] -}); - -// Windows and FreeBSD -fs.open('', 'a+', (err, fd) => { - // => null, -}); -``` - 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 @@ -2206,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]) * `path` {string|Buffer|URL} -* `flags` {string|number} See [support of file system `flags`][] +* `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: - -* `'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. +Asynchronous file open. See open(2). `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('', 'a+', (err, fd) => { - // => [Error: EISDIR: illegal operation on a directory, open ] -}); - -// Windows and FreeBSD -fs.open('', 'a+', (err, fd) => { - // => null, -}); -``` - 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 @@ -2206,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]) * `path` {string|Buffer|URL} -* `flags` {string|number} See [support of file system `flags`][] +* `flags` {string|number} See [support of file system `flags`][]. * `mode` {integer} **Default:** `0o666` * Returns: {number} @@ -2356,7 +2278,7 @@ changes: * `path` {string|Buffer|URL|integer} filename or file descriptor * `options` {Object|string} * `encoding` {string|null} **Default:** `null` - * `flag` {string} See [support of file system `flags`][] **Default:** `'r'` + * `flag` {string} See [support of file system `flags`][]. **Default:** `'r'`. * `callback` {Function} * `err` {Error} * `data` {string|Buffer} @@ -2422,7 +2344,7 @@ changes: * `path` {string|Buffer|URL|integer} filename or file descriptor * `options` {Object|string} * `encoding` {string|null} **Default:** `null` - * `flag` {string} See [support of file system `flags`][] **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`. @@ -3349,7 +3271,7 @@ changes: * `options` {Object|string} * `encoding` {string|null} **Default:** `'utf8'` * `mode` {integer} **Default:** `0o666` - * `flag` {string} See [support of file system `flags`][] **Default:** `'w'` + * `flag` {string} See [support of file system `flags`][]. **Default:** `'w'`. * `callback` {Function} * `err` {Error} @@ -3399,7 +3321,7 @@ changes: * `options` {Object|string} * `encoding` {string|null} **Default:** `'utf8'` * `mode` {integer} **Default:** `0o666` - * `flag` {string} See [support of file system `flags`][] **Default:** `'w'` + * `flag` {string} See [support of file system `flags`][]. **Default:** `'w'`. The synchronous version of [`fs.writeFile()`][]. Returns `undefined`. @@ -3475,7 +3397,7 @@ added: REPLACEME * `options` {Object|string} * `encoding` {string|null} **Default:** `'utf8'` * `mode` {integer} **Default:** `0o666` - * `flag` {string} See [support of file system `flags`][] **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 @@ -3579,7 +3501,7 @@ added: REPLACEME --> * `options` {Object|string} * `encoding` {string|null} **Default:** `null` - * `flag` {string} See [support of file system `flags`][] **Default:** `'r'` + * `flag` {string} See [support of file system `flags`][]. **Default:** `'r'`. * Returns: {Promise} Asynchronously reads the entire contents of a file. @@ -3713,7 +3635,7 @@ added: REPLACEME * `options` {Object|string} * `encoding` {string|null} **Default:** `'utf8'` * `mode` {integer} **Default:** `0o666` - * `flag` {string} See [support of file system `flags`][] **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. @@ -3779,7 +3701,7 @@ added: REPLACEME * `options` {Object|string} * `encoding` {string|null} **Default:** `'utf8'` * `mode` {integer} **Default:** `0o666` - * `flag` {string} See [support of file system `flags`][] **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 @@ -4088,89 +4010,21 @@ added: REPLACEME --> * `path` {string|Buffer|URL} -* `flags` {string|number} See [support of file system `flags`][] +* `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)