diff --git a/doc/api/fs.md b/doc/api/fs.md index f2430b0da09a78..1f9f210bc10ec7 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -291,6 +291,44 @@ explicitly synchronous use libuv's threadpool, which can have surprising and negative performance implications for some applications, see the [`UV_THREADPOOL_SIZE`][] documentation for more information. +## class: fs.FileHandle + + +A `fs.FileHandle` object is a wrapper for a numeric file descriptor. Instances +of `fs.FileHandle` are distinct from numeric file descriptors in that, if the +`fs.FileHandle` is not explicitly closed using the `fd.close()` method, they +will automatically close the file descriptor and will emit a process warning, +thereby helping to prevent memory leaks. + +Instances of the `fs.FileHandle` object are created internally by the +`fs.openFileHandle()` and `fs.openFileHandleSync()` methods. + +### filehandle.close() + + +* Returns: {Promise} A `Promise` that will be resolved once the underlying + file descriptor is closed, or will reject if an error occurs while closing. + +Closes the file descriptor. + +```js +const filehandle = fs.openFileHandleSync('thefile.txt', 'r'); +filehandle.close() + .then(() => console.log('ok')) + .catch(() => console.log('not ok')); +``` + +### filehandle.fd + + +Value: {number} The numeric file descriptor managed by the `FileHandle` object. + ## Class: fs.FSWatcher + +* `path` {string|Buffer|URL} +* `flags` {string|number} +* `mode` {integer} **Default:** `0o666` +* `callback` {Function} + * `err` {Error} + * `fd` {[fs.FileHandle][#fs_class_fs_filehandle]} + +Asynchronous file open that returns a `fs.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 doesn't turn `fs.openFileHAndle()` into a synchronous blocking + call. If synchronous operation is desired `fs.openFileHandleSync()` 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. + +* `'a+'` - Open file for reading and appending. +The file is created if it does not exist. + +* `'ax+'` - Like `'a+'` but fails if `path` exists. + +`mode` sets the file mode (permission and sticky bits), but only if the file was +created. It defaults to `0o666` (readable and writable). + +The callback gets two arguments `(err, filehandle)`. + +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. + +*Note*: The behavior of `fs.openFileHandle()` 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.openFileHandle('', 'a+', (err, filehandle) => { + // => [Error: EISDIR: illegal operation on a directory, open ] +}); + +// Windows and FreeBSD +fs.openFileHandle('', 'a+', (err, filehandle) => { + // => 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 +[this MSDN page][MSDN-Using-Streams]. + +*Note:* On Windows, opening an existing hidden file using the `w` flag (e.g. +using `fs.openFileHandle()`) 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.openFileHandleSync(path, flags[, mode]) + + +* `path` {string|Buffer|URL} +* `flags` {string|number} +* `mode` {integer} **Default:** `0o666` +* Returns: {[fs.FileHandle][#fs_class_fs_filehandle]} + +Synchronous version of [`fs.openFileHandle()`][]. Returns a `fs.FileHandle` +object representing the file descriptor. + ## fs.openSync(path, flags[, mode])