1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: add flags section to document all flags

Browse Source 
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>
This commit is contained in:
Indranil Dasgupta 2018-04-15 03:50:48 +02:00 committed by Trivikram Kamat
parent d718d53996
commit 53822f605d
1 changed files with 109 additions and 164 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

273
doc/api/fs.md
View File

@ -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('<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