diff --git a/doc/api/fs.md b/doc/api/fs.md index 6fc7075d182..a80a5efcb42 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,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: - -* `'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 @@ -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]) * `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)