From 6a5c4c52c02b87698aa8057da6a14995542715d9 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Sun, 31 Jan 2021 23:51:48 -0800 Subject: [PATCH] doc: refactor fs docs structure * Convert examples to esm to help promote that pattern with users * Make Promises APIs more prominent to help promite that pattern * Separate callback/sync apis into distinct sections to make those more consistent with the Promises api * Improve other bits and pieces Signed-off-by: James M Snell PR-URL: https://github.com/nodejs/node/pull/37170 Reviewed-By: Benjamin Gruenbaum Reviewed-By: Matteo Collina --- doc/api/fs.md | 6312 ++++++++++++++++++++++++++----------------------- 1 file changed, 3295 insertions(+), 3017 deletions(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index 13a51cdc8add33..34cb626dfad797 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -11,60 +11,57 @@ The `fs` module enables interacting with the file system in a way modeled on standard POSIX functions. -To use this module: +To use the promise-based APIs: -```js -const fs = require('fs'); +```js esm +// Using ESM Module syntax: +import * as fs from 'fs/promises'; ``` -All file system operations have synchronous, callback, and promise-based -forms. +```js cjs +// Using CommonJS syntax: +const fs = require('fs/promises'); +``` -## Synchronous example +To use the callback and sync APIs: -The synchronous form blocks the Node.js event loop and further JavaScript -execution until the operation is complete. Exceptions are thrown immediately -and can be handled using `try…catch`, or can be allowed to bubble up. +```js esm +// Using ESM Module syntax: +import * as fs from 'fs'; +``` -```js +```js cjs +// Using CommonJS syntax: const fs = require('fs'); - -try { - fs.unlinkSync('/tmp/hello'); - console.log('successfully deleted /tmp/hello'); -} catch (err) { - // handle the error -} ``` -## Callback example +All file system operations have synchronous, callback, and promise-based +forms, and are accessible using both CommonJS syntax and ES6 Modules (ESM). -The callback form takes a completion callback function as its last -argument and invokes the operation asynchronously. The arguments passed to -the completion callback depend on the method, but the first argument is always -reserved for an exception. If the operation is completed successfully, then -the first argument is `null` or `undefined`. +## Promise example -```js -const fs = require('fs'); +Promise-based operations return a promise that is fulfilled when the +asynchronous operation is complete. -fs.unlink('/tmp/hello', (err) => { - if (err) throw err; +```js esm +// Using ESM Module syntax: +import { unlink } from 'fs/promises'; + +try { + await unlink('/tmp/hello'); console.log('successfully deleted /tmp/hello'); -}); +} catch (error) { + console.error('there was an error:', error.message); +} ``` -## Promise example - -Promise-based operations return a `Promise` that is fulfilled when the -asynchronous operation is complete. - -```js -const fs = require('fs/promises'); +```js cjs +// Using CommonJS syntax +const { unlink } = require('fs/promises'); (async function(path) { try { - await fs.unlink(path); + await unlink(path); console.log(`successfully deleted ${path}`); } catch (error) { console.error('there was an error:', error.message); @@ -72,1102 +69,1204 @@ const fs = require('fs/promises'); })('/tmp/hello'); ``` -## Ordering of callback and promise-based operations +## Callback example -There is no guaranteed ordering when using either the callback or -promise-based methods. For example, the following is prone to error -because the `fs.stat()` operation might complete before the `fs.rename()` -operation: +The callback form takes a completion callback function as its last +argument and invokes the operation asynchronously. The arguments passed to +the completion callback depend on the method, but the first argument is always +reserved for an exception. If the operation is completed successfully, then +the first argument is `null` or `undefined`. -```js -fs.rename('/tmp/hello', '/tmp/world', (err) => { - if (err) throw err; - console.log('renamed complete'); -}); -fs.stat('/tmp/world', (err, stats) => { +```js esm +// Using ESM syntax +import { unlink } from 'fs'; + +unlink('/tmp/hello', (err) => { if (err) throw err; - console.log(`stats: ${JSON.stringify(stats)}`); + console.log('successfully deleted /tmp/hello'); }); ``` -To correctly order the operations, move the `fs.stat()` call into the callback -of the `fs.rename()` operation: +```js cjs +// Using CommonJS syntax +const { unlink } = require('fs'); -```js -fs.rename('/tmp/hello', '/tmp/world', (err) => { +unlink('/tmp/hello', (err) => { if (err) throw err; - fs.stat('/tmp/world', (err, stats) => { - if (err) throw err; - console.log(`stats: ${JSON.stringify(stats)}`); - }); + console.log('successfully deleted /tmp/hello'); }); ``` -Or, use the promise-based API: - -```js -const fs = require('fs/promises'); - -(async function(from, to) { - try { - await fs.rename(from, to); - const stats = await fs.stat(to); - console.log(`stats: ${JSON.stringify(stats)}`); - } catch (error) { - console.error('there was an error:', error.message); - } -})('/tmp/hello', '/tmp/world'); -``` - -## File paths - -Most `fs` operations accept filepaths that may be specified in the form of -a string, a [`Buffer`][], or a [`URL`][] object using the `file:` protocol. - -String form paths are interpreted as UTF-8 character sequences identifying -the absolute or relative filename. Relative paths will be resolved relative -to the current working directory as determined by calling `process.cwd()`. - -Example using an absolute path on POSIX: +The callback-based versions of the `fs` module APIs are preferable over +the use of the promise APIs when maximal performance (both in terms of +execution time and memory allocation are required). -```js -const fs = require('fs'); +## Synchronous example -fs.open('/open/some/file.txt', 'r', (err, fd) => { - if (err) throw err; - fs.close(fd, (err) => { - if (err) throw err; - }); -}); -``` +The synchronous APIs block the Node.js event loop and further JavaScript +execution until the operation is complete. Exceptions are thrown immediately +and can be handled using `try…catch`, or can be allowed to bubble up. -Example using a relative path on POSIX (relative to `process.cwd()`): +```js esm +// Using ESM syntax +import { unlinkSync } from 'fs'; -```js -fs.open('file.txt', 'r', (err, fd) => { - if (err) throw err; - fs.close(fd, (err) => { - if (err) throw err; - }); -}); +try { + unlinkSync('/tmp/hello'); + console.log('successfully deleted /tmp/hello'); +} catch (err) { + // handle the error +} ``` -Paths specified using a [`Buffer`][] are useful primarily on certain POSIX -operating systems that treat file paths as opaque byte sequences. On such -systems, it is possible for a single file path to contain sub-sequences that -use multiple character encodings. As with string paths, `Buffer` paths may -be relative or absolute: - -Example using an absolute path on POSIX: +```js cjs +// Using CommonJS syntax +const { unlinkSync } = require('fs'); -```js -fs.open(Buffer.from('/open/some/file.txt'), 'r', (err, fd) => { - if (err) throw err; - fs.close(fd, (err) => { - if (err) throw err; - }); -}); +try { + unlinkSync('/tmp/hello'); + console.log('successfully deleted /tmp/hello'); +} catch (err) { + // handle the error +} ``` -On Windows, Node.js follows the concept of per-drive working directory. This -behavior can be observed when using a drive path without a backslash. For -example `fs.readdirSync('C:\\')` can potentially return a different result than -`fs.readdirSync('C:')`. For more information, see -[this MSDN page][MSDN-Rel-Path]. - -### URL object support +## Promises API -For most `fs` module functions, the `path` or `filename` argument may be passed -as a WHATWG [`URL`][] object. Only [`URL`][] objects using the `file:` protocol -are supported. -```js -const fs = require('fs'); -const fileUrl = new URL('file:///tmp/hello'); +The `fs/promises` API provides asynchronous file system methods that return +promises. -fs.readFileSync(fileUrl); -``` +The promise APIs use the underlying Node.js threadpool to perform file +system operations off the event loop thread. These operations are not +synchronized or threadsafe. Care must be taken when performing multiple +concurrent modifications on the same file or data corruption may occur. -`file:` URLs are always absolute paths. +### Class: `FileHandle` + -Using WHATWG [`URL`][] objects might introduce platform-specific behaviors. +A {FileHandle} object is an object wrapper for a numeric file descriptor. -On Windows, `file:` URLs with a host name convert to UNC paths, while `file:` -URLs with drive letters convert to local absolute paths. `file:` URLs without a -host name nor a drive letter will result in a throw: +Instances of the {FileHandle} object are created by the `fsPromises.open()` +method. -```js -// On Windows : +All {FileHandle} objects are {EventEmitter}s. -// - WHATWG file URLs with hostname convert to UNC path -// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file -fs.readFileSync(new URL('file://hostname/p/a/t/h/file')); +If a {FileHandle} is not closed using the `filehandle.close()` method, it will +try to automatically close the file descriptor and emit a process warning, +helping to prevent memory leaks. Please do not rely on this behavior because +it can be unreliable and the file may not be closed. Instead, always explicitly +close {FileHandle}s. Node.js may change this behavior in the future. -// - WHATWG file URLs with drive letters convert to absolute path -// file:///C:/tmp/hello => C:\tmp\hello -fs.readFileSync(new URL('file:///C:/tmp/hello')); +#### Event: `'close'` + -// - WHATWG file URLs without hostname must have a drive letters -fs.readFileSync(new URL('file:///notdriveletter/p/a/t/h/file')); -fs.readFileSync(new URL('file:///c/p/a/t/h/file')); -// TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must be absolute -``` +The `'close'` event is emitted when the {FileHandle} has been closed and can no +longer be used. -`file:` URLs with drive letters must use `:` as a separator just after -the drive letter. Using another separator will result in a throw. +#### `filehandle.appendFile(data[, options])` + -On all other platforms, `file:` URLs with a host name are unsupported and will -result in a throw: +* `data` {string|Buffer|TypedArray|DataView} +* `options` {Object|string} + * `encoding` {string|null} **Default:** `'utf8'` +* Returns: {Promise} Fulfills with `undefined` upon success. -```js -// On other platforms: +Alias of [`filehandle.writeFile()`][]. -// - WHATWG file URLs with hostname are unsupported -// file://hostname/p/a/t/h/file => throw! -fs.readFileSync(new URL('file://hostname/p/a/t/h/file')); -// TypeError [ERR_INVALID_FILE_URL_PATH]: must be absolute +When operating on file handles, the mode cannot be changed from what it was set +to with [`fsPromises.open()`][]. Therefore, this is equivalent to +[`filehandle.writeFile()`][]. -// - WHATWG file URLs convert to absolute path -// file:///tmp/hello => /tmp/hello -fs.readFileSync(new URL('file:///tmp/hello')); -``` +#### `filehandle.chmod(mode)` + -A `file:` URL having encoded slash characters will result in a throw on all -platforms: +* `mode` {integer} the file mode bit mask. +* Returns: {Promise} Fulfills with `undefined` upon success. -```js -// On Windows -fs.readFileSync(new URL('file:///C:/p/a/t/h/%2F')); -fs.readFileSync(new URL('file:///C:/p/a/t/h/%2f')); -/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded -\ or / characters */ +Modifies the permissions on the file. See chmod(2). -// On POSIX -fs.readFileSync(new URL('file:///p/a/t/h/%2F')); -fs.readFileSync(new URL('file:///p/a/t/h/%2f')); -/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded -/ characters */ -``` +#### `filehandle.chown(uid, gid)` + -On Windows, `file:` URLs having encoded backslash will result in a throw: +* `uid` {integer} The file's new owner's user id. +* `gid` {integer} The file's new group's group id. +* Returns: {Promise} Fulfills with `undefined` upon success. -```js -// On Windows -fs.readFileSync(new URL('file:///C:/path/%5C')); -fs.readFileSync(new URL('file:///C:/path/%5c')); -/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded -\ or / characters */ -``` +Changes the ownership of the file. A wrapper for chown(2). -## File descriptors +#### `filehandle.close()` + -On POSIX systems, for every process, the kernel maintains a table of currently -open files and resources. Each open file is assigned a simple numeric -identifier called a *file descriptor*. At the system-level, all file system -operations use these file descriptors to identify and track each specific -file. Windows systems use a different but conceptually similar mechanism for -tracking resources. To simplify things for users, Node.js abstracts away the -specific differences between operating systems and assigns all open files a -numeric file descriptor. +* Returns: {Promise} Fulfills with `undefined` upon success. -The `fs.open()` method is used to allocate a new file descriptor. Once -allocated, the file descriptor may be used to read data from, write data to, -or request information about the file. +Closes the file handle after waiting for any pending operation on the handle to +complete. -```js -fs.open('/open/some/file.txt', 'r', (err, fd) => { - if (err) throw err; - fs.fstat(fd, (err, stat) => { - if (err) throw err; - // use stat +```js esm +import { open } from 'fs/promises'; - // always close the file descriptor! - fs.close(fd, (err) => { - if (err) throw err; - }); - }); -}); +let filehandle; +try { + filehandle = await open('thefile.txt', 'r'); +} finally { + await filehandle?.close(); +} ``` -Most operating systems limit the number of file descriptors that may be open -at any given time so it is critical to close the descriptor when operations -are completed. Failure to do so will result in a memory leak that will -eventually cause an application to crash. - -## Threadpool usage - -All file system APIs except `fs.FSWatcher()` and those that are 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.Dir` +#### `filehandle.datasync()` -A class representing a directory stream. - -Created by [`fs.opendir()`][], [`fs.opendirSync()`][], or -[`fsPromises.opendir()`][]. +* Returns: {Promise} Fulfills with `undefined` upon success. -```js -const fs = require('fs'); +Forces all currently queued I/O operations associated with the file to the +operating system's synchronized I/O completion state. Refer to the POSIX +fdatasync(2) documentation for details. -async function print(path) { - const dir = await fs.promises.opendir(path); - for await (const dirent of dir) { - console.log(dirent.name); - } -} -print('./').catch(console.error); -``` +Unlike `filehandle.sync` this method does not flush modified metadata. -### `dir.close()` +#### `filehandle.fd` -* Returns: {Promise} - -Asynchronously close the directory's underlying resource handle. -Subsequent reads will result in errors. - -A `Promise` is returned that will be fulfilled after the resource has been -closed. +* {number} The numeric file descriptor managed by the {FileHandle} object. -### `dir.close(callback)` +#### `filehandle.read(buffer, offset, length, position)` -* `callback` {Function} - * `err` {Error} +* `buffer` {Buffer|Uint8Array} A buffer that will be filled with the file + data read. +* `offset` {integer} The location in the buffer at which to start filling. + **Default:** `0` +* `length` {integer} The number of bytes to read. **Default:** `buffer.length` +* `position` {integer} The location where to begin reading data from the + file. If `null`, data will be read from the current file position, and + the position will be updated. If `position` is an integer, the current + file position will remain unchanged. +* Returns: {Promise} Fulfills upon success with an object with two properties: + * `bytesRead` {integer} The number of bytes read + * `buffer` {Buffer|Uint8Array} A reference to the passed in `buffer` argument. -Asynchronously close the directory's underlying resource handle. -Subsequent reads will result in errors. +Reads data from the file and stores that in the given buffer. -The `callback` will be called after the resource handle has been closed. +If the file is not modified concurrently, the end-of-file is reached when the +number of bytes read is zero. -### `dir.closeSync()` +#### `filehandle.read(options)` +* `options` {Object} + * `buffer` {Buffer|Uint8Array} A buffer that will be filled with the file + data read. **Default:** `Buffer.alloc(16384)` + * `offset` {integer} The location in the buffer at which to start filling. + **Default:** `0` + * `length` {integer} The number of bytes to read. **Default:** `buffer.length` + * `position` {integer} The location where to begin reading data from the + file. If `null`, data will be read from the current file position, and + the position will be updated. If `position` is an integer, the current + file position will remain unchanged. **Default:**: `null` +* Returns: {Promise} Fulfills upon success with an object with two properties: + * `bytesRead` {integer} The number of bytes read + * `buffer` {Buffer|Uint8Array} A reference to the passed in `buffer` + argument. + +Reads data from the file and stores that in the given buffer. -Synchronously close the directory's underlying resource handle. -Subsequent reads will result in errors. +If the file is not modified concurrently, the end-of-file is reached when the +number of bytes read is zero. -### `dir.path` +#### `filehandle.readFile(options)` -* {string} - -The read-only path of this directory as was provided to [`fs.opendir()`][], -[`fs.opendirSync()`][], or [`fsPromises.opendir()`][]. - -### `dir.read()` - +* `options` {Object|string} + * `encoding` {string|null} **Default:** `null` + * `signal` {AbortSignal} allows aborting an in-progress readFile +* Returns: {Promise} Fulfills upon a successful read with the contents of the + file. If no encoding is specified (using `options.encoding`), the data is + returned as a {Buffer} object. Otherwise, the data will be a string. -* Returns: {Promise} containing {fs.Dirent|null} +Asynchronously reads the entire contents of a file. -Asynchronously read the next directory entry via readdir(3) as an -[`fs.Dirent`][]. +If `options` is a string, then it specifies the `encoding`. -After the read is completed, a `Promise` is returned that will be fulfilled -with an [`fs.Dirent`][], or `null` if there are no more directory entries to -read. +The {FileHandle} has to support reading. -Directory entries returned by this function are in no particular order as -provided by the operating system's underlying directory mechanisms. -Entries added or removed while iterating over the directory might not be -included in the iteration results. +If one or more `filehandle.read()` calls are made on a file handle and then a +`filehandle.readFile()` call is made, the data will be read from the current +position till the end of the file. It doesn't always read from the beginning +of the file. -### `dir.read(callback)` +#### `filehandle.readv(buffers[, position])` -* `callback` {Function} - * `err` {Error} - * `dirent` {fs.Dirent|null} - -Asynchronously read the next directory entry via readdir(3) as an -[`fs.Dirent`][]. - -After the read is completed, the `callback` will be called with an -[`fs.Dirent`][], or `null` if there are no more directory entries to read. +* `buffers` {Buffer[]|TypedArray[]|DataView[]} +* `position` {integer} The offset from the beginning of the file where the data + should be read from. If `position` is not a `number`, the data will be read + from the current position. +* Returns: {Promise} Fulfills upon success an object containing two properties: + * `bytesRead` {integer} the number of bytes read + * `buffers` {Buffer[]|TypedArray[]|DataView[]} property containing + a reference to the `buffers` input. -Directory entries returned by this function are in no particular order as -provided by the operating system's underlying directory mechanisms. -Entries added or removed while iterating over the directory might not be -included in the iteration results. +Read from a file and write to an array of {ArrayBufferView}s -### `dir.readSync()` +#### `filehandle.stat([options])` -* Returns: {fs.Dirent|null} +* `options` {Object} + * `bigint` {boolean} Whether the numeric values in the returned + {fs.Stats} object should be `bigint`. **Default:** `false`. +* Returns: {Promise} Fulfills with an {fs.Stats} for the file. -Synchronously read the next directory entry via readdir(3) as an -[`fs.Dirent`][]. +#### `filehandle.sync()` + -If there are no more directory entries to read, `null` will be returned. +* Returns: {Promise} Fufills with `undefined` upon success. -Directory entries returned by this function are in no particular order as -provided by the operating system's underlying directory mechanisms. -Entries added or removed while iterating over the directory might not be -included in the iteration results. +Request that all data for the open file descriptor is flushed to the storage +device. The specific implementation is operating system and device specific. +Refer to the POSIX fsync(2) documentation for more detail. -### `dir[Symbol.asyncIterator]()` +#### `filehandle.truncate(len)` -* Returns: {AsyncIterator} of {fs.Dirent} - -Asynchronously iterates over the directory via readdir(3) until all entries have -been read. +* `len` {integer} **Default:** `0` +* Returns: {Promise} Fulfills with `undefined` upo nsuccess. -Entries returned by the async iterator are always an [`fs.Dirent`][]. -The `null` case from `dir.read()` is handled internally. +Truncates the file. -See [`fs.Dir`][] for an example. +If the file was larger than `len` bytes, only the first `len` bytes will be +retained in the file. -Directory entries returned by this iterator are in no particular order as -provided by the operating system's underlying directory mechanisms. -Entries added or removed while iterating over the directory might not be -included in the iteration results. +The following example retains only the first four bytes of the file: -## Class: `fs.Dirent` - +```js esm +import { open } from 'fs/promises'; -A representation of a directory entry, which can be a file or a subdirectory -within the directory, as returned by reading from an [`fs.Dir`][]. The -directory entry is a combination of the file name and file type pairs. +let filehandle = null; +try { + filehandle = await open('temp.txt', 'r+'); + await filehandle.truncate(4); +} finally { + filehandle?.close(); +} +``` -Additionally, when [`fs.readdir()`][] or [`fs.readdirSync()`][] is called with -the `withFileTypes` option set to `true`, the resulting array is filled with -`fs.Dirent` objects, rather than strings or `Buffers`. +If the file previously was shorter than `len` bytes, it is extended, and the +extended part is filled with null bytes (`'\0'`): -### `dirent.isBlockDevice()` +#### `filehandle.utimes(atime, mtime)` -* Returns: {boolean} +* `atime` {number|string|Date} +* `mtime` {number|string|Date} +* Returns: {Promise} + +Change the file system timestamps of the object referenced by the {FileHandle} +then resolves the promise with no arguments upon success. -Returns `true` if the `fs.Dirent` object describes a block device. +This function does not work on AIX versions before 7.1, it will reject the +promise with an error using code `UV_ENOSYS`. -### `dirent.isCharacterDevice()` +#### `filehandle.write(buffer[, offset[, length[, position]]])` -* Returns: {boolean} +* `buffer` {Buffer|Uint8Array|string|Object} +* `offset` {integer} The start position from within `buffer` where the data + to write begins. +* `length` {integer} The number of bytes from `buffer` to write. +* `position` {integer} The offset from the beginning of the file where the + data from `buffer` should be written. If `position` is not a `number`, + the data will be written at the current position. See the POSIX pwrite(2) + documentation for more detail. +* Returns: {Promise} -Returns `true` if the `fs.Dirent` object describes a character device. +Write `buffer` to the file. -### `dirent.isDirectory()` - +The promise is resolved with an object containing two properties: -* Returns: {boolean} +* `bytesWritten` {integer} the number of bytes written +* `buffer` {Buffer|Uint8Array|string|Object} a reference to the `buffer` + written. -Returns `true` if the `fs.Dirent` object describes a file system -directory. +It is unsafe to use `filehandle.write()` multiple times on the same file +without waiting for the promise to be resolved (or rejected). For this +scenario, use [`fs.createWriteStream()`][]. + +On Linux, positional writes do not 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. -### `dirent.isFIFO()` +#### `filehandle.write(string[, position[, encoding]])` -* Returns: {boolean} +* `string` {string|Object} +* `position` {integer} The offset from the beginning of the file where the + data from `string` should be written. If `position` is not a `number` the + data will be written at the current position. See the POSIX pwrite(2) + documentation for more detail. +* `encoding` {string} The expected string encoding. **Default:** `'utf8'` +* Returns: {Promise} -Returns `true` if the `fs.Dirent` object describes a first-in-first-out -(FIFO) pipe. +Write `string` to the file. If `string` is not a string, or an object with an +own `toString` function property, the promise is rejected with an error. -### `dirent.isFile()` - +The promise is resolved with an object containing two properties: -* Returns: {boolean} +* `bytesWritten` {integer} the number of bytes written +* `buffer` {string|Object} a reference to the `string` written. -Returns `true` if the `fs.Dirent` object describes a regular file. +It is unsafe to use `filehandle.write()` multiple times on the same file +without waiting for the promise to be resolved (or rejected). For this +scenario, use [`fs.createWriteStream()`][]. + +On Linux, positional writes do not 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. -### `dirent.isSocket()` +#### `filehandle.writeFile(data, options)` -* Returns: {boolean} +* `data` {string|Buffer|Uint8Array|Object} +* `options` {Object|string} + * `encoding` {string|null} The expected character encoding when `data` is a + string. **Default:** `'utf8'` +* Returns: {Promise} -Returns `true` if the `fs.Dirent` object describes a socket. +Asynchronously writes data to a file, replacing the file if it already exists. +`data` can be a string, a buffer, or an object with an own `toString` function +property. The promise is resolved with no arguments upon success. -### `dirent.isSymbolicLink()` - +If `options` is a string, then it specifies the `encoding`. -* Returns: {boolean} +The {FileHandle} has to support writing. -Returns `true` if the `fs.Dirent` object describes a symbolic link. +It is unsafe to use `filehandle.writeFile()` multiple times on the same file +without waiting for the promise to be resolved (or rejected). + +If one or more `filehandle.write()` calls are made on a file handle and then a +`filehandle.writeFile()` call is made, the data will be written from the +current position till the end of the file. It doesn't always write from the +beginning of the file. -### `dirent.name` +#### `filehandle.writev(buffers[, position])` -* {string|Buffer} +* `buffers` {Buffer[]|TypedArray[]|DataView[]} +* `position` {integer} The offset from the beginning of the file where the + data from `buffers` should be written. If `position` is not a `number`, + the data will be written at the current position. +* Returns: {Promise} -The file name that this `fs.Dirent` object refers to. The type of this -value is determined by the `options.encoding` passed to [`fs.readdir()`][] or -[`fs.readdirSync()`][]. +Write an array of {ArrayBufferView}s to the file. -## Class: `fs.FSWatcher` - +The promise is resolved with an object containing a two properties: -* Extends {EventEmitter} +* `bytesWritten` {integer} the number of bytes written +* `buffers` {Buffer[]|TypedArray[]|DataView[]} a reference to the `buffers` + input. -A successful call to [`fs.watch()`][] method will return a new `fs.FSWatcher` -object. +It is unsafe to call `writev()` multiple times on the same file without waiting +for the promise to be resolved (or rejected). -All `fs.FSWatcher` objects emit a `'change'` event whenever a specific watched -file is modified. +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. -### Event: `'change'` +### `fsPromises.access(path[, mode])` -* `eventType` {string} The type of change event that has occurred -* `filename` {string|Buffer} The filename that changed (if relevant/available) +* `path` {string|Buffer|URL} +* `mode` {integer} **Default:** `fs.constants.F_OK` +* Returns: {Promise} Fulfills with `undefined` upon success. -Emitted when something changes in a watched directory or file. -See more details in [`fs.watch()`][]. +Tests a user's permissions for the file or directory specified by `path`. +The `mode` argument is an optional integer that specifies the accessibility +checks to be performed. Check [File access constants][] for possible values +of `mode`. It is possible to create a mask consisting of the bitwise OR of +two or more values (e.g. `fs.constants.W_OK | fs.constants.R_OK`). -The `filename` argument may not be provided depending on operating system -support. If `filename` is provided, it will be provided as a `Buffer` if -`fs.watch()` is called with its `encoding` option set to `'buffer'`, otherwise -`filename` will be a UTF-8 string. +If the accessibility check is successful, the promise is resolved with no +value. If any of the accessibility checks fail, the promise is rejected +with an {Error} object. The following example checks if the file +`/etc/passwd` can be read and written by the current process. -```js -// Example when handled through fs.watch() listener -fs.watch('./tmp', { encoding: 'buffer' }, (eventType, filename) => { - if (filename) { - console.log(filename); - // Prints: - } -}); +```js esm +import { access } from 'fs/promises'; +import { constants } from 'fs'; + +try { + await access('/etc/passwd', constants.R_OK | constants.W_OK); + console.log('can access'); +} catch { + console.error('cannot access'); +} ``` -### Event: `'close'` +Using `fsPromises.access()` to check for the accessibility of a file before +calling `fsPromises.open()` is not recommended. Doing so introduces a race +condition, since other processes may change the file's state between the two +calls. Instead, user code should open/read/write the file directly and handle +the error raised if the file is not accessible. + +### `fsPromises.appendFile(path, data[, options])` -Emitted when the watcher stops watching for changes. The closed -`fs.FSWatcher` object is no longer usable in the event handler. +* `path` {string|Buffer|URL|FileHandle} filename or {FileHandle} +* `data` {string|Buffer} +* `options` {Object|string} + * `encoding` {string|null} **Default:** `'utf8'` + * `mode` {integer} **Default:** `0o666` + * `flag` {string} See [support of file system `flags`][]. **Default:** `'a'`. +* Returns: {Promise} Fulfills with `undefined` upon success. -### Event: `'error'` - +Asynchronously append data to a file, creating the file if it does not yet +exist. `data` can be a string or a {Buffer}. -* `error` {Error} +If `options` is a string, then it specifies the `encoding`. -Emitted when an error occurs while watching the file. The errored -`fs.FSWatcher` object is no longer usable in the event handler. +The `path` may be specified as a {FileHandle} that has been opened +for appending (using `fsPromises.open()`). -### `watcher.close()` +### `fsPromises.chmod(path, mode)` - -Stop watching for changes on the given `fs.FSWatcher`. Once stopped, the -`fs.FSWatcher` object is no longer usable. - -### `watcher.ref()` - -* Returns: {fs.FSWatcher} - -When called, requests that the Node.js event loop *not* exit so long as the -`FSWatcher` is active. Calling `watcher.ref()` multiple times will have -no effect. +* `path` {string|Buffer|URL} +* `mode` {string|integer} +* Returns: {Promise} Fulfills with `undefined` upon success. -By default, all `FSWatcher` objects are "ref'ed", making it normally -unnecessary to call `watcher.ref()` unless `watcher.unref()` had been -called previously. +Changes the permissions of a file. -### `watcher.unref()` +### `fsPromises.chown(path, uid, gid)` -* Returns: {fs.FSWatcher} +* `path` {string|Buffer|URL} +* `uid` {integer} +* `gid` {integer} +* Returns: {Promise} Fulfills with `undefined` upon success. -When called, the active `FSWatcher` object will not require the Node.js -event loop to remain active. If there is no other activity keeping the -event loop running, the process may exit before the `FSWatcher` object's -callback is invoked. Calling `watcher.unref()` multiple times will have -no effect. +Changes the ownership of a file. -## Class: `fs.StatWatcher` +### `fsPromises.copyFile(src, dest[, mode])` -* Extends {EventEmitter} +* `src` {string|Buffer|URL} source filename to copy +* `dest` {string|Buffer|URL} destination filename of the copy operation +* `mode` {integer} Optional modifiers that specify the behavior of the copy + operation. It is possible to create a mask consisting of the bitwise OR of + two or more values (e.g. + `fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE`) + **Default:** `0`. + * `fs.constants.COPYFILE_EXCL`: The copy operation will fail if `dest` + already exists. + * `fs.constants.COPYFILE_FICLONE`: The copy operation will attempt to create + a copy-on-write reflink. If the platform does not support copy-on-write, + then a fallback copy mechanism is used. + * `fs.constants.COPYFILE_FICLONE_FORCE`: The copy operation will attempt to + create a copy-on-write reflink. If the platform does not support + copy-on-write, then the operation will fail. +* Returns: {Promise} Fulfills with `undefined` upon success. -A successful call to `fs.watchFile()` method will return a new `fs.StatWatcher` -object. +Asynchronously copies `src` to `dest`. By default, `dest` is overwritten if it +already exists. -### `watcher.ref()` - +No guarantees are made about the atomicity of the copy operation. If an +error occurs after the destination file has been opened for writing, an attempt +will be made to remove the destination. -* Returns: {fs.StatWatcher} +```js esm +import { constants } from 'fs'; +import { copyFile } from 'fs/promises'; -When called, requests that the Node.js event loop *not* exit so long as the -`StatWatcher` is active. Calling `watcher.ref()` multiple times will have -no effect. +try { + await copyFile('source.txt', 'destination.txt'); + console.log('source.txt was copied to destination.txt'); +} catch { + console.log('The file could not be copied'); +} -By default, all `StatWatcher` objects are "ref'ed", making it normally -unnecessary to call `watcher.ref()` unless `watcher.unref()` had been -called previously. +// By using COPYFILE_EXCL, the operation will fail if destination.txt exists. +try { + await copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL); + console.log('source.txt was copied to destination.txt'); +} catch { + console.log('The file could not be copied'); +} +``` -### `watcher.unref()` +### `fsPromises.lchmod(path, mode)` -* Returns: {fs.StatWatcher} +* `path` {string|Buffer|URL} +* `mode` {integer} +* Returns: {Promise} Fulfills with `undefined` upon success. -When called, the active `StatWatcher` object will not require the Node.js -event loop to remain active. If there is no other activity keeping the -event loop running, the process may exit before the `StatWatcher` object's -callback is invoked. Calling `watcher.unref()` multiple times will have -no effect. +Changes the permissions on a symbolic link. + +This method is only implemented on macOS. -## Class: `fs.ReadStream` +### `fsPromises.lchown(path, uid, gid)` -* Extends: {stream.Readable} +* `path` {string|Buffer|URL} +* `uid` {integer} +* `gid` {integer} +* Returns: {Promise} Fulfills with `undefined` upon success. -Instances of `fs.ReadStream` are created and returned using the -[`fs.createReadStream()`][] function. +Changes the ownership on a symbolic link. -### Event: `'close'` +### `fsPromises.lutimes(path, atime, mtime)` -Emitted when the `fs.ReadStream`'s underlying file descriptor has been closed. +* `path` {string|Buffer|URL} +* `atime` {number|string|Date} +* `mtime` {number|string|Date} +* Returns: {Promise} Fulfills with `undefined` upon success. + +Changes the access and modification times of a file in the same way as +[`fsPromises.utimes()`][], with the difference that if the path refers to a +symbolic link, then the link is not dereferenced: instead, the timestamps of +the symbolic link itself are changed. -### Event: `'open'` +### `fsPromises.link(existingPath, newPath)` -* `fd` {integer} Integer file descriptor used by the `ReadStream`. +* `existingPath` {string|Buffer|URL} +* `newPath` {string|Buffer|URL} +* Returns: {Promise} Fulfills with `undefined` upon success. -Emitted when the `fs.ReadStream`'s file descriptor has been opened. +Creates a new link from the `existingPath` to the `newPath`. See the POSIX +link(2) documentation for more detail. -### Event: `'ready'` +### `fsPromises.lstat(path[, options])` -Emitted when the `fs.ReadStream` is ready to be used. +* `path` {string|Buffer|URL} +* `options` {Object} + * `bigint` {boolean} Whether the numeric values in the returned + {fs.Stats} object should be `bigint`. **Default:** `false`. +* Returns: {Promise} Fulfills with the {fs.Stats} object for the given + symbolic link `path`. -Fires immediately after `'open'`. +Equivalent to `fsPromises.stats()` when `path` refers to a symbolic link. +Refer to the POSIX lstat(2) document for more detail. -### `readStream.bytesRead` +### `fsPromises.mkdir(path[, options])` -* {number} +* `path` {string|Buffer|URL} +* `options` {Object|integer} + * `recursive` {boolean} **Default:** `false` + * `mode` {string|integer} Not supported on Windows. **Default:** `0o777`. +* Returns: {Promise} Upon success, fulfills with `undefined` if `recursive` + is `false`, or the first directory path created if `recursive` is `true`. -The number of bytes that have been read so far. +Asynchronously creates a directory. + +The optional `options` argument can be an integer specifying `mode` (permission +and sticky bits), or an object with a `mode` property and a `recursive` +property indicating whether parent directories should be created. Calling +`fsPromises.mkdir()` when `path` is a directory that exists results in a +rejection only when `recursive` is false. -### `readStream.path` +### `fsPromises.mkdtemp(prefix[, options])` -* {string|Buffer} +* `prefix` {string} +* `options` {string|Object} + * `encoding` {string} **Default:** `'utf8'` +* Returns: {Promise} Fulfills with a string containing the filesystem path + of the newly created temporary directory. -The path to the file the stream is reading from as specified in the first -argument to `fs.createReadStream()`. If `path` is passed as a string, then -`readStream.path` will be a string. If `path` is passed as a `Buffer`, then -`readStream.path` will be a `Buffer`. +Creates a unique temporary directory. A unique directory name is generated by +appending six random characters to the end of the provided `prefix`. Due to +platform inconsistencies, avoid trailing `X` characters in `prefix`. Some +platforms, notably the BSDs, can return more than six random characters, and +replace trailing `X` characters in `prefix` with random characters. -### `readStream.pending` - +The optional `options` argument can be a string specifying an encoding, or an +object with an `encoding` property specifying the character encoding to use. -* {boolean} +```js esm +import { mkdtemp } from 'fs/promises'; -This property is `true` if the underlying file has not been opened yet, -i.e. before the `'ready'` event is emitted. +try { + await mkdtemp(path.join(os.tmpdir(), 'foo-')); +} catch (err) { + console.error(err); +} +``` + +The `fsPromises.mkdtemp()` method will append the six randomly selected +characters directly to the `prefix` string. For instance, given a directory +`/tmp`, if the intention is to create a temporary directory *within* `/tmp`, the +`prefix` must end with a trailing platform-specific path separator +(`require('path').sep`). -## Class: `fs.Stats` +### `fsPromises.open(path, flags[, mode])` -A `fs.Stats` object provides information about a file. - -Objects returned from [`fs.stat()`][], [`fs.lstat()`][] and [`fs.fstat()`][] and -their synchronous counterparts are of this type. -If `bigint` in the `options` passed to those methods is true, the numeric values -will be `bigint` instead of `number`, and the object will contain additional -nanosecond-precision properties suffixed with `Ns`. +* `path` {string|Buffer|URL} +* `flags` {string|number} See [support of file system `flags`][]. + **Default:** `'r'`. +* `mode` {string|integer} Sets the file mode (permission and sticky bits) + if the file is created. **Default:** `0o666` (readable and writable) +* Returns: {Promise} Fullfils with a {FileHandle} object. -```console -Stats { - dev: 2114, - ino: 48064969, - mode: 33188, - nlink: 1, - uid: 85, - gid: 100, - rdev: 0, - size: 527, - blksize: 4096, - blocks: 8, - atimeMs: 1318289051000.1, - mtimeMs: 1318289051000.1, - ctimeMs: 1318289051000.1, - birthtimeMs: 1318289051000.1, - atime: Mon, 10 Oct 2011 23:24:11 GMT, - mtime: Mon, 10 Oct 2011 23:24:11 GMT, - ctime: Mon, 10 Oct 2011 23:24:11 GMT, - birthtime: Mon, 10 Oct 2011 23:24:11 GMT } -``` +Opens a {FileHandle}. -`bigint` version: +Refer to the POSIX open(2) documentation for more detail. -```console -BigIntStats { - dev: 2114n, - ino: 48064969n, - mode: 33188n, - nlink: 1n, - uid: 85n, - gid: 100n, - rdev: 0n, - size: 527n, - blksize: 4096n, - blocks: 8n, - atimeMs: 1318289051000n, - mtimeMs: 1318289051000n, - ctimeMs: 1318289051000n, - birthtimeMs: 1318289051000n, - atimeNs: 1318289051000000000n, - mtimeNs: 1318289051000000000n, - ctimeNs: 1318289051000000000n, - birthtimeNs: 1318289051000000000n, - atime: Mon, 10 Oct 2011 23:24:11 GMT, - mtime: Mon, 10 Oct 2011 23:24:11 GMT, - ctime: Mon, 10 Oct 2011 23:24:11 GMT, - birthtime: Mon, 10 Oct 2011 23:24:11 GMT } -``` +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]. -### `stats.isBlockDevice()` +### `fsPromises.opendir(path[, options])` -* Returns: {boolean} +* `path` {string|Buffer|URL} +* `options` {Object} + * `encoding` {string|null} **Default:** `'utf8'` + * `bufferSize` {number} Number of directory entries that are buffered + internally when reading from the directory. Higher values lead to better + performance but higher memory usage. **Default:** `32` +* Returns: {Promise} Fulfills with an {fs.Dir}. -Returns `true` if the `fs.Stats` object describes a block device. +Asynchronously open a directory for iterative scanning. See the POSIX +opendir(3) documentation for more detail. -### `stats.isCharacterDevice()` - +Creates an {fs.Dir}, which contains all further functions for reading from +and cleaning up the directory. -* Returns: {boolean} +The `encoding` option sets the encoding for the `path` while opening the +directory and subsequent read operations. -Returns `true` if the `fs.Stats` object describes a character device. +Example using async iteration: -### `stats.isDirectory()` - - -* Returns: {boolean} - -Returns `true` if the `fs.Stats` object describes a file system directory. +```js esm +import { opendir } from 'fs/promises'; -If the `fs.Stats` object was obtained from [`fs.lstat()`][], this method will -always return `false`. This is because [`fs.lstat()`][] returns information -about a symbolic link itself and not the path it resolves to. +try { + const dir = await opendir('./'); + for await (const dirent of dir) + console.log(dirent.name); +} catch (err) { + console.error(err); +} +``` -### `stats.isFIFO()` +### `fsPromises.readdir(path[, options])` -* Returns: {boolean} - -Returns `true` if the `fs.Stats` object describes a first-in-first-out (FIFO) -pipe. - -### `stats.isFile()` - +* `path` {string|Buffer|URL} +* `options` {string|Object} + * `encoding` {string} **Default:** `'utf8'` + * `withFileTypes` {boolean} **Default:** `false` +* Returns: {Promise} Fulfills with an array of the names of the files in + the directory excluding `'.'` and `'..'`. -* Returns: {boolean} +Reads the contents of a directory. -Returns `true` if the `fs.Stats` object describes a regular file. +The optional `options` argument can be a string specifying an encoding, or an +object with an `encoding` property specifying the character encoding to use for +the filenames. If the `encoding` is set to `'buffer'`, the filenames returned +will be passed as {Buffer} objects. -### `stats.isSocket()` - +If `options.withFileTypes` is set to `true`, the resolved array will contain +{fs.Dirent} objects. -* Returns: {boolean} +```js esm +import { readdir } from 'fs/promises'; -Returns `true` if the `fs.Stats` object describes a socket. +try { + const files = await readdir(path); + for await (const file of files) + console.log(file); +} catch (err) { + console.error(err); +} +``` -### `stats.isSymbolicLink()` +### `fsPromises.readFile(path[, options])` -* Returns: {boolean} - -Returns `true` if the `fs.Stats` object describes a symbolic link. - -This method is only valid when using [`fs.lstat()`][]. - -### `stats.dev` - -* {number|bigint} +* `path` {string|Buffer|URL|FileHandle} filename or `FileHandle` +* `options` {Object|string} + * `encoding` {string|null} **Default:** `null` + * `flag` {string} See [support of file system `flags`][]. **Default:** `'r'`. + * `signal` {AbortSignal} allows aborting an in-progress readFile +* Returns: {Promise} Fulfills with the contents of the file. -The numeric identifier of the device containing the file. +Asynchronously reads the entire contents of a file. -### `stats.ino` +If no encoding is specified (using `options.encoding`), the data is returned +as a {Buffer} object. Otherwise, the data will be a string. -* {number|bigint} +If `options` is a string, then it specifies the encoding. -The file system specific "Inode" number for the file. +When the `path` is a directory, the behavior of `fsPromises.readFile()` is +platform-specific. On macOS, Linux, and Windows, the promise will be rejected +with an error. On FreeBSD, a representation of the directory's contents will be +returned. -### `stats.mode` +It is possible to abort an ongoing `readFile` using an {AbortSignal}. If a +request is aborted the promise returned is rejected with an `AbortError`: -* {number|bigint} +```js esm +import { readFile } from 'fs/promises'; -A bit-field describing the file type and mode. +try { + const controller = new AbortController(); + const signal = controller.signal; + readFile(fileName, { signal }); -### `stats.nlink` + // Abort the request + controller.abort(); +} catch (err) { + console.error(err); +} +``` -* {number|bigint} +Aborting an ongoing request does not abort individual operating +system requests but rather the internal buffering `fs.readFile` performs. -The number of hard-links that exist for the file. +Any specified {FileHandle} has to support reading. -### `stats.uid` +### `fsPromises.readlink(path[, options])` + -* {number|bigint} +* `path` {string|Buffer|URL} +* `options` {string|Object} + * `encoding` {string} **Default:** `'utf8'` +* Returns: {Promise} Fulfills with the `linkString` upon success. -The numeric user identifier of the user that owns the file (POSIX). +Reads the contents of the symbolic link refered to by `path`. See the POSIX +readlink(2) documentation for more etail. The promise is resolved with the +`linkString` upon success. -### `stats.gid` +The optional `options` argument can be a string specifying an encoding, or an +object with an `encoding` property specifying the character encoding to use for +the link path returned. If the `encoding` is set to `'buffer'`, the link path +returned will be passed as a {Buffer} object. -* {number|bigint} +### `fsPromises.realpath(path[, options])` + -The numeric group identifier of the group that owns the file (POSIX). +* `path` {string|Buffer|URL} +* `options` {string|Object} + * `encoding` {string} **Default:** `'utf8'` +* Returns: {Promise} Fulfills with the resolved path upon success. -### `stats.rdev` +Determines the actual location of `path` using the same semantics as the +`fs.realpath.native()` function. -* {number|bigint} +Only paths that can be converted to UTF8 strings are supported. -A numeric device identifier if the file represents a device. +The optional `options` argument can be a string specifying an encoding, or an +object with an `encoding` property specifying the character encoding to use for +the path. If the `encoding` is set to `'buffer'`, the path returned will be +passed as a {Buffer} object. -### `stats.size` +On Linux, when Node.js is linked against musl libc, the procfs file system must +be mounted on `/proc` in order for this function to work. Glibc does not have +this restriction. -* {number|bigint} +### `fsPromises.rename(oldPath, newPath)` + -The size of the file in bytes. +* `oldPath` {string|Buffer|URL} +* `newPath` {string|Buffer|URL} +* Returns: {Promise} Fulfills with `undefined` upon success. -### `stats.blksize` +Renames `oldPath` to `newPath`. -* {number|bigint} +### `fsPromises.rmdir(path[, options])` + -The file system block size for i/o operations. +* `path` {string|Buffer|URL} +* `options` {Object} + * `maxRetries` {integer} If an `EBUSY`, `EMFILE`, `ENFILE`, `ENOTEMPTY`, or + `EPERM` error is encountered, Node.js retries the operation with a linear + backoff wait of `retryDelay` milliseconds longer on each try. This option + represents the number of retries. This option is ignored if the `recursive` + option is not `true`. **Default:** `0`. + * `recursive` {boolean} If `true`, perform a recursive directory removal. In + recursive mode, errors are not reported if `path` does not exist, and + operations are retried on failure. **Default:** `false`. + * `retryDelay` {integer} The amount of time in milliseconds to wait between + retries. This option is ignored if the `recursive` option is not `true`. + **Default:** `100`. +* Returns: {Promise} Fulfills with `undefined` upon success. -### `stats.blocks` +Removes the directory identified by `path`. -* {number|bigint} +Using `fsPromises.rmdir()` on a file (not a directory) results in the +promise being rejected with an `ENOENT` error on Windows and an `ENOTDIR` +error on POSIX. -The number of blocks allocated for this file. +Setting `recursive` to `true` results in behavior similar to the Unix command +`rm -rf`: an error will not be raised for paths that do not exist, and paths +that represent files will be deleted. The permissive behavior of the +`recursive` option is deprecated, `ENOTDIR` and `ENOENT` will be thrown in +the future. -### `stats.atimeMs` +### `fsPromises.rm(path[, options])` -* {number|bigint} +* `path` {string|Buffer|URL} +* `options` {Object} + * `force` {boolean} When `true`, exceptions will be ignored if `path` does + not exist. **Default:** `false`. + * `maxRetries` {integer} If an `EBUSY`, `EMFILE`, `ENFILE`, `ENOTEMPTY`, or + `EPERM` error is encountered, Node.js will retry the operation with a linear + backoff wait of `retryDelay` milliseconds longer on each try. This option + represents the number of retries. This option is ignored if the `recursive` + option is not `true`. **Default:** `0`. + * `recursive` {boolean} If `true`, perform a recursive directory removal. In + recursive mode operations are retried on failure. **Default:** `false`. + * `retryDelay` {integer} The amount of time in milliseconds to wait between + retries. This option is ignored if the `recursive` option is not `true`. + **Default:** `100`. +* Returns: {Promise} Fulfills with `undefined` upon success. -The timestamp indicating the last time this file was accessed expressed in -milliseconds since the POSIX Epoch. +Removes files and directories (modeled on the standard POSIX `rm` utility). -### `stats.mtimeMs` +### `fsPromises.stat(path[, options])` -* {number|bigint} - -The timestamp indicating the last time this file was modified expressed in -milliseconds since the POSIX Epoch. +* `path` {string|Buffer|URL} +* `options` {Object} + * `bigint` {boolean} Whether the numeric values in the returned + {fs.Stats} object should be `bigint`. **Default:** `false`. +* Returns: {Promise} Fulfills with the {fs.Stats} object for the + given `path`. -### `stats.ctimeMs` +### `fsPromises.symlink(target, path[, type])` -* {number|bigint} - -The timestamp indicating the last time the file status was changed expressed -in milliseconds since the POSIX Epoch. - -### `stats.birthtimeMs` - +* `target` {string|Buffer|URL} +* `path` {string|Buffer|URL} +* `type` {string} **Default:** `'file'` +* Returns: {Promise} Fulfills with `undefined` upon success. -* {number|bigint} +Creates a symbolic link. -The timestamp indicating the creation time of this file expressed in -milliseconds since the POSIX Epoch. +The `type` argument is only used on Windows platforms and can be one of `'dir'`, +`'file'`, or `'junction'`. Windows junction points require the destination path +to be absolute. When using `'junction'`, the `target` argument will +automatically be normalized to absolute path. -### `stats.atimeNs` +### `fsPromises.truncate(path[, len])` -* {bigint} +* `path` {string|Buffer|URL} +* `len` {integer} **Default:** `0` +* Returns: {Promise} Fulfills with `undefined` upon success. -Only present when `bigint: true` is passed into the method that generates -the object. -The timestamp indicating the last time this file was accessed expressed in -nanoseconds since the POSIX Epoch. +Truncates (shortens or extends the length) of the content at `path` to `len` +bytes. -### `stats.mtimeNs` +### `fsPromises.unlink(path)` -* {bigint} +* `path` {string|Buffer|URL} +* Returns: {Promise} Fulfills with `undefined` upon success. -Only present when `bigint: true` is passed into the method that generates -the object. -The timestamp indicating the last time this file was modified expressed in -nanoseconds since the POSIX Epoch. +If `path` refers to a symbolic link, then the link is removed without affecting +the file or directory to which that link refers. If the `path` refers to a file +path that is not a symbolic link, the file is deleted. See the POSIX unlink(2) +documentation for more detail. -### `stats.ctimeNs` +### `fsPromises.utimes(path, atime, mtime)` -* {bigint} +* `path` {string|Buffer|URL} +* `atime` {number|string|Date} +* `mtime` {number|string|Date} +* Returns: {Promise} Fulfills with `undefined` upon success. -Only present when `bigint: true` is passed into the method that generates -the object. -The timestamp indicating the last time the file status was changed expressed -in nanoseconds since the POSIX Epoch. +Change the file system timestamps of the object referenced by `path`. -### `stats.birthtimeNs` - +The `atime` and `mtime` arguments follow these rules: -* {bigint} - -Only present when `bigint: true` is passed into the method that generates -the object. -The timestamp indicating the creation time of this file expressed in -nanoseconds since the POSIX Epoch. - -### `stats.atime` - - -* {Date} - -The timestamp indicating the last time this file was accessed. - -### `stats.mtime` - - -* {Date} - -The timestamp indicating the last time this file was modified. - -### `stats.ctime` - - -* {Date} - -The timestamp indicating the last time the file status was changed. - -### `stats.birthtime` - - -* {Date} - -The timestamp indicating the creation time of this file. - -### Stat time values - -The `atimeMs`, `mtimeMs`, `ctimeMs`, `birthtimeMs` properties are -numeric values that hold the corresponding times in milliseconds. Their -precision is platform specific. When `bigint: true` is passed into the -method that generates the object, the properties will be [bigints][], -otherwise they will be [numbers][MDN-Number]. - -The `atimeNs`, `mtimeNs`, `ctimeNs`, `birthtimeNs` properties are -[bigints][] that hold the corresponding times in nanoseconds. They are -only present when `bigint: true` is passed into the method that generates -the object. Their precision is platform specific. - -`atime`, `mtime`, `ctime`, and `birthtime` are -[`Date`][MDN-Date] object alternate representations of the various times. The -`Date` and number values are not connected. Assigning a new number value, or -mutating the `Date` value, will not be reflected in the corresponding alternate -representation. - -The times in the stat object have the following semantics: - -* `atime` "Access Time": Time when file data last accessed. Changed - by the mknod(2), utimes(2), and read(2) system calls. -* `mtime` "Modified Time": Time when file data last modified. - Changed by the mknod(2), utimes(2), and write(2) system calls. -* `ctime` "Change Time": Time when file status was last changed - (inode data modification). Changed by the chmod(2), chown(2), - link(2), mknod(2), rename(2), unlink(2), utimes(2), - read(2), and write(2) system calls. -* `birthtime` "Birth Time": Time of file creation. Set once when the - file is created. On filesystems where birthtime is not available, - this field may instead hold either the `ctime` or - `1970-01-01T00:00Z` (ie, Unix epoch timestamp `0`). This value may be greater - than `atime` or `mtime` in this case. On Darwin and other FreeBSD variants, - also set if the `atime` is explicitly set to an earlier value than the current - `birthtime` using the utimes(2) system call. - -Prior to Node.js 0.12, the `ctime` held the `birthtime` on Windows systems. As -of 0.12, `ctime` is not "creation time", and on Unix systems, it never was. - -## Class: `fs.WriteStream` - - -* Extends {stream.Writable} - -Instances of `fs.WriteStream` are created and returned using the -[`fs.createWriteStream()`][] function. +* Values can be either numbers representing Unix epoch time, `Date`s, or a + numeric string like `'123456789.0'`. +* If the value can not be converted to a number, or is `NaN`, `Infinity` or + `-Infinity`, an `Error` will be thrown. -### Event: `'close'` +### `fsPromises.writeFile(file, data[, options])` -Emitted when the `WriteStream`'s underlying file descriptor has been closed. +* `file` {string|Buffer|URL|FileHandle} filename or `FileHandle` +* `data` {string|Buffer|Uint8Array|Object} +* `options` {Object|string} + * `encoding` {string|null} **Default:** `'utf8'` + * `mode` {integer} **Default:** `0o666` + * `flag` {string} See [support of file system `flags`][]. **Default:** `'w'`. + * `signal` {AbortSignal} allows aborting an in-progress writeFile +* Returns: {Promise} Fulfills with `undefined` upon success. -### Event: `'open'` - +Asynchronously writes data to a file, replacing the file if it already exists. +`data` can be a string, a {Buffer}, or an object with an own `toString` function +property. -* `fd` {integer} Integer file descriptor used by the `WriteStream`. +The `encoding` option is ignored if `data` is a buffer. -Emitted when the `WriteStream`'s file is opened. +If `options` is a string, then it specifies the encoding. -### Event: `'ready'` - +Any specified {FileHandle} has to support writing. -Emitted when the `fs.WriteStream` is ready to be used. +It is unsafe to use `fsPromises.writeFile()` multiple times on the same file +without waiting for the promise to be settled. -Fires immediately after `'open'`. +Similarly to `fsPromises.readFile` - `fsPromises.writeFile` is a convenience +method that performs multiple `write` calls internally to write the buffer +passed to it. For performance sensitive code consider using +[`fs.createWriteStream()`][]. -### `writeStream.bytesWritten` - +It is possible to use an {AbortSignal} to cancel an `fsPromises.writeFile()`. +Cancelation is "best effort", and some amount of data is likely still +to be written. -The number of bytes written so far. Does not include data that is still queued -for writing. +```js esm +import { writeFile } from 'fs/promises'; -### `writeStream.path` - +try { + const controller = new AbortController(); + const { signal } = controller; + const data = new Uint8Array(Buffer.from('Hello Node.js')); + writeFile('message.txt', data, { signal }); + controller.abort(); +} catch (err) { + // When a request is aborted - err is an AbortError + console.error(err); +} +``` -The path to the file the stream is writing to as specified in the first -argument to [`fs.createWriteStream()`][]. If `path` is passed as a string, then -`writeStream.path` will be a string. If `path` is passed as a `Buffer`, then -`writeStream.path` will be a `Buffer`. +Aborting an ongoing request does not abort individual operating +system requests but rather the internal buffering `fs.writeFile` performs. -### `writeStream.pending` - +## Callback API -* {boolean} +The callback APIs perform all operations asynchronously, without blocking the +event loop, then invoke a callback function upon completion or error. -This property is `true` if the underlying file has not been opened yet, -i.e. before the `'ready'` event is emitted. +The callback APIs use the underlying Node.js threadpool to perform file +system operations off the event loop thread. These operations are not +synchronized or threadsafe. Care must be taken when performing multiple +concurrent modifications on the same file or data corruption may occur. -## `fs.access(path[, mode], callback)` +### `fs.access(path[, mode], callback)` - -* `path` {string|Buffer|URL} -* `mode` {integer} **Default:** `fs.constants.F_OK` - -Synchronously tests a user's permissions for the file or directory specified -by `path`. The `mode` argument is an optional integer that specifies the -accessibility checks to be performed. Check [File access constants][] for -possible values of `mode`. It is possible to create a mask consisting of -the bitwise OR of two or more values -(e.g. `fs.constants.W_OK | fs.constants.R_OK`). - -If any of the accessibility checks fail, an `Error` will be thrown. Otherwise, -the method will return `undefined`. - -```js -try { - fs.accessSync('etc/passwd', fs.constants.R_OK | fs.constants.W_OK); - console.log('can read/write'); -} catch (err) { - console.error('no access!'); -} -``` - -## `fs.appendFile(path, data[, options], callback)` +### `fs.appendFile(path, data[, options], callback)` -* `path` {string|Buffer|URL|number} filename or file descriptor -* `data` {string|Buffer} -* `options` {Object|string} - * `encoding` {string|null} **Default:** `'utf8'` - * `mode` {integer} **Default:** `0o666` - * `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`][]. - -```js -try { - fs.appendFileSync('message.txt', 'data to append'); - console.log('The "data to append" was appended to file!'); -} catch (err) { - /* Handle the error */ -} -``` - -If `options` is a string, then it specifies the encoding: - -```js -fs.appendFileSync('message.txt', 'data to append', 'utf8'); -``` - -The `path` may be specified as a numeric file descriptor that has been opened -for appending (using `fs.open()` or `fs.openSync()`). The file descriptor will -not be closed automatically. - -```js -let fd; - -try { - fd = fs.openSync('message.txt', 'a'); - fs.appendFileSync(fd, 'data to append', 'utf8'); -} catch (err) { - /* Handle the error */ -} finally { - if (fd !== undefined) - fs.closeSync(fd); -} -``` - -## `fs.chmod(path, mode, callback)` - - -* `path` {string|Buffer|URL} -* `mode` {string|integer} -* `callback` {Function} - * `err` {Error} +* `path` {string|Buffer|URL} +* `mode` {string|integer} +* `callback` {Function} + * `err` {Error} Asynchronously changes the permissions of a file. No arguments other than a possible exception are given to the completion callback. -See also: chmod(2). +See the POSIX chmod(2) documentation for more detail. -```js -fs.chmod('my_file.txt', 0o775, (err) => { +```js esm +import { chmod } from 'fs'; + +chmod('my_file.txt', 0o775, (err) => { if (err) throw err; console.log('The permissions for file "my_file.txt" have been changed!'); }); ``` -### File modes +#### File modes The `mode` argument used in both the `fs.chmod()` and `fs.chmodSync()` methods is a numeric bitmask created using a logical OR of the following @@ -1552,25 +1617,7 @@ Caveats: on Windows only the write permission can be changed, and the distinction among the permissions of group, owner or others is not implemented. -## `fs.chmodSync(path, mode)` - - -* `path` {string|Buffer|URL} -* `mode` {string|integer} - -For detailed information, see the documentation of the asynchronous version of -this API: [`fs.chmod()`][]. - -See also: chmod(2). - -## `fs.chown(path, uid, gid, callback)` +### `fs.chown(path, uid, gid, callback)` - -* `path` {string|Buffer|URL} -* `uid` {integer} -* `gid` {integer} - -Synchronously changes owner and group of a file. Returns `undefined`. -This is the synchronous version of [`fs.chown()`][]. - -See also: chown(2). +See the POSIX chown(2) documentation for more detail. -## `fs.close(fd[, callback])` +### `fs.close(fd[, callback])` - -* `fd` {integer} - -Synchronous close(2). Returns `undefined`. - -Calling `fs.closeSync()` on any file descriptor (`fd`) that is currently in use -through any other `fs` operation may lead to undefined behavior. - -## `fs.constants` - -* {Object} - -Returns an object containing commonly used constants for file system -operations. The specific constants currently defined are described in -[FS constants][]. +See the POSIX close(2) documentation for more detail. -## `fs.copyFile(src, dest[, mode], callback)` +### `fs.copyFile(src, dest[, mode], callback)` - -* `src` {string|Buffer|URL} source filename to copy -* `dest` {string|Buffer|URL} destination filename of the copy operation -* `mode` {integer} modifiers for copy operation. **Default:** `0`. - -Synchronously copies `src` to `dest`. By default, `dest` is overwritten if it -already exists. Returns `undefined`. Node.js makes no guarantees about the -atomicity of the copy operation. If an error occurs after the destination file -has been opened for writing, Node.js will attempt to remove the destination. - -`mode` is an optional integer that specifies the behavior -of the copy operation. It is possible to create a mask consisting of the bitwise -OR of two or more values (e.g. -`fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE`). - -* `fs.constants.COPYFILE_EXCL`: The copy operation will fail if `dest` already - exists. -* `fs.constants.COPYFILE_FICLONE`: The copy operation will attempt to create a - copy-on-write reflink. If the platform does not support copy-on-write, then a - fallback copy mechanism is used. -* `fs.constants.COPYFILE_FICLONE_FORCE`: The copy operation will attempt to - create a copy-on-write reflink. If the platform does not support - copy-on-write, then the operation will fail. - -```js -const fs = require('fs'); -const { COPYFILE_EXCL } = fs.constants; - -// destination.txt will be created or overwritten by default. -fs.copyFileSync('source.txt', 'destination.txt'); -console.log('source.txt was copied to destination.txt'); +copyFile('source.txt', 'destination.txt', callback); // By using COPYFILE_EXCL, the operation will fail if destination.txt exists. -fs.copyFileSync('source.txt', 'destination.txt', COPYFILE_EXCL); +copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL, callback); ``` -## `fs.createReadStream(path[, options])` +### `fs.createReadStream(path[, options])` - -* `path` {string|Buffer|URL} -* Returns: {boolean} - -Returns `true` if the path exists, `false` otherwise. - -For detailed information, see the documentation of the asynchronous version of -this API: [`fs.exists()`][]. - -`fs.exists()` is deprecated, but `fs.existsSync()` is not. The `callback` -parameter to `fs.exists()` accepts parameters that are inconsistent with other -Node.js callbacks. `fs.existsSync()` does not use a callback. - -```js -if (fs.existsSync('/etc/passwd')) { - console.log('The path exists.'); -} -``` - -## `fs.fchmod(fd, mode, callback)` +### `fs.fchmod(fd, mode, callback)` - -* `fd` {integer} -* `mode` {string|integer} - -Synchronous fchmod(2). Returns `undefined`. +See the POSIX fchmod(2) documentation for more detail. -## `fs.fchown(fd, uid, gid, callback)` +### `fs.fchown(fd, uid, gid, callback)` - -* `fd` {integer} -* `uid` {integer} -* `gid` {integer} +Sets the owner of the file. No arguments other than a possible exception are +given to the completion callback. -Synchronous fchown(2). Returns `undefined`. +See the POSIX fchown(2) documentation for more detail. -## `fs.fdatasync(fd, callback)` +### `fs.fdatasync(fd, callback)` - -* `fd` {integer} - -Synchronous fdatasync(2). Returns `undefined`. +Forces all currently queued I/O operations associated with the file to the +operating system's synchronized I/O completion state. Refer to the POSIX +fdatasync(2) documentation for details. No arguments other than a possible +exception are given to the completion callback. -## `fs.fstat(fd[, options], callback)` +### `fs.fstat(fd[, options], callback)` - -* `fd` {integer} -* `options` {Object} - * `bigint` {boolean} Whether the numeric values in the returned - [`fs.Stats`][] object should be `bigint`. **Default:** `false`. -* Returns: {fs.Stats} +Invokes the callback with the {fs.Stats} for the file descriptor. -Synchronous fstat(2). +See the POSIX fstat(2) documentation for more detail. -## `fs.fsync(fd, callback)` +### `fs.fsync(fd, callback)` - -* `fd` {integer} - -Synchronous fsync(2). Returns `undefined`. +Request that all data for the open file descriptor is flushed to the storage +device. The specific implementation is operating system and device specific. +Refer to the POSIX fsync(2) documentation for more detail. No arguments other +than a possible exception are given to the completion callback. -## `fs.ftruncate(fd[, len], callback)` +### `fs.ftruncate(fd[, len], callback)` - -* `fd` {integer} -* `len` {integer} **Default:** `0` - -Returns `undefined`. - -For detailed information, see the documentation of the asynchronous version of -this API: [`fs.ftruncate()`][]. +If the file previously was shorter than `len` bytes, it is extended, and the +extended part is filled with null bytes (`'\0'`): -## `fs.futimes(fd, atime, mtime, callback)` +### `fs.futimes(fd, atime, mtime, callback)` - -* `fd` {integer} -* `atime` {number|string|Date} -* `mtime` {number|string|Date} - -Synchronous version of [`fs.futimes()`][]. Returns `undefined`. - -## `fs.lchmod(path, mode, callback)` +### `fs.lchmod(path, mode, callback)` +Changes the permissions on a symbolic link. No arguments other than a possible +exception are given to the completion callback. -* `path` {string|Buffer|URL} -* `mode` {integer} +This method is only implemented on macOS. -Synchronous lchmod(2). Returns `undefined`. +See the POSIX lchmod(2) documentation for more detail. -## `fs.lchown(path, uid, gid, callback)` +### `fs.lchown(path, uid, gid, callback)` - -* `path` {string|Buffer|URL} -* `uid` {integer} -* `gid` {integer} +Set the owner of the symbolic link. No arguments other than a possible +exception are given to the completion callback. -Synchronous lchown(2). Returns `undefined`. +See the POSIX lchown(2) documentation for more detail. -## `fs.lutimes(path, atime, mtime, callback)` +### `fs.lutimes(path, atime, mtime, callback)` - -* `path` {string|Buffer|URL} -* `atime` {number|string|Date} -* `mtime` {number|string|Date} - -Change the file system timestamps of the symbolic link referenced by `path`. -Returns `undefined`, or throws an exception when parameters are incorrect or -the operation fails. This is the synchronous version of [`fs.lutimes()`][]. - -## `fs.link(existingPath, newPath, callback)` +### `fs.link(existingPath, newPath, callback)` - -* `existingPath` {string|Buffer|URL} -* `newPath` {string|Buffer|URL} - -Synchronous link(2). Returns `undefined`. +Creates a new link from the `existingPath` to the `newPath`. See the POSIX +link(2) documentation for more detail. No arguments other than a possible +exception are given to the completion callback. -## `fs.lstat(path[, options], callback)` +### `fs.lstat(path[, options], callback)` - -* `path` {string|Buffer|URL} -* `options` {Object} - * `bigint` {boolean} Whether the numeric values in the returned - [`fs.Stats`][] object should be `bigint`. **Default:** `false`. - * `throwIfNoEntry` {boolean} Whether an exception will be thrown - if no file system entry exists, rather than returning `undefined`. - **Default:** `true`. -* Returns: {fs.Stats} +Retrieves the {fs.Stats} for the symbolic link refered to by the path. +The callback gets two arguments `(err, stats)` where `stats` is a {`fs.Stats} +object. `lstat()` is identical to `stat()`, except that if `path` is a symbolic +link, then the link itself is stat-ed, not the file that it refers to. -Synchronous lstat(2). +See the POSIX lstat(2) documentation for more details. -## `fs.mkdir(path[, options], callback)` +### `fs.mkdir(path[, options], callback)` - -* `path` {string|Buffer|URL} -* `options` {Object|integer} - * `recursive` {boolean} **Default:** `false` - * `mode` {string|integer} Not supported on Windows. **Default:** `0o777`. -* Returns: {string|undefined} - -Synchronously creates a directory. Returns `undefined`, or if `recursive` is -`true`, the first directory path created. -This is the synchronous version of [`fs.mkdir()`][]. - -See also: mkdir(2). +See the POSIX mkdir(2) documentation for more details. -## `fs.mkdtemp(prefix[, options], callback)` +### `fs.mkdtemp(prefix[, options], callback)` - -* `prefix` {string} -* `options` {string|Object} - * `encoding` {string} **Default:** `'utf8'` -* Returns: {string} - -Returns the created directory path. - -For detailed information, see the documentation of the asynchronous version of -this API: [`fs.mkdtemp()`][]. - -The optional `options` argument can be a string specifying an encoding, or an -object with an `encoding` property specifying the character encoding to use. - -## `fs.open(path[, flags[, mode]], callback)` +### `fs.open(path[, flags[, mode]], callback)` - -* `path` {string|Buffer|URL} -* `options` {Object} - * `encoding` {string|null} **Default:** `'utf8'` - * `bufferSize` {number} Number of directory entries that are buffered - internally when reading from the directory. Higher values lead to better - performance but higher memory usage. **Default:** `32` -* Returns: {fs.Dir} - -Synchronously open a directory. See opendir(3). +Asynchronously open a directory. See the POSIX opendir(3) documentation for +more details. -Creates an [`fs.Dir`][], which contains all further functions for reading from +Creates an {fs.Dir}, which contains all further functions for reading from and cleaning up the directory. The `encoding` option sets the encoding for the `path` while opening the directory and subsequent read operations. -## `fs.openSync(path[, flags, mode])` - - -* `path` {string|Buffer|URL} -* `flags` {string|number} **Default:** `'r'`. - See [support of file system `flags`][]. -* `mode` {string|integer} **Default:** `0o666` -* Returns: {number} - -Returns an integer representing the file descriptor. - -For detailed information, see the documentation of the asynchronous version of -this API: [`fs.open()`][]. - -## `fs.read(fd, buffer, offset, length, position, callback)` +### `fs.read(fd, buffer, offset, length, position, callback)` * `fd` {integer} -* `buffer` {Buffer|TypedArray|DataView} -* `offset` {integer} -* `length` {integer} -* `position` {integer|bigint} +* `buffer` {Buffer|TypedArray|DataView} The buffer that the data will be + written to. +* `offset` {integer} The position in `buffer` to write the data to. +* `length` {integer} The number of bytes to read. +* `position` {integer|bigint} Specifies where to begin reading from in the + file. If `position` is `null` or `-1 `, data will be read from the current + file position, and the file position will be updated. If `position` is an + integer, the file position will be unchanged. * `callback` {Function} * `err` {Error} * `bytesRead` {integer} @@ -2952,26 +2670,15 @@ changes: Read data from the file specified by `fd`. -`buffer` is the buffer that the data (read from the fd) will be written to. - -`offset` is the offset in the buffer to start writing at. - -`length` is an integer specifying the number of bytes to read. - -`position` is an argument specifying where to begin reading from in the file. -If `position` is `null`, data will be read from the current file position, -and the file position will be updated. -If `position` is an integer, the file position will remain unchanged. - The callback is given the three arguments, `(err, bytesRead, buffer)`. If the file is not modified concurrently, the end-of-file is reached when the number of bytes read is zero. If this method is invoked as its [`util.promisify()`][]ed version, it returns -a `Promise` for an `Object` with `bytesRead` and `buffer` properties. +a promise for an `Object` with `bytesRead` and `buffer` properties. -## `fs.read(fd, [options,] callback)` +### `fs.read(fd, [options,] callback)` - -* `path` {string|Buffer|URL} -* `options` {string|Object} - * `encoding` {string} **Default:** `'utf8'` - * `withFileTypes` {boolean} **Default:** `false` -* Returns: {string[]|Buffer[]|fs.Dirent[]} - -Synchronous readdir(3). - -The optional `options` argument can be a string specifying an encoding, or an -object with an `encoding` property specifying the character encoding to use for -the filenames returned. If the `encoding` is set to `'buffer'`, -the filenames returned will be passed as `Buffer` objects. - -If `options.withFileTypes` is set to `true`, the result will contain -[`fs.Dirent`][] objects. - -## `fs.readFile(path[, options], callback)` - * `path` {string|Buffer|URL|integer} filename or file descriptor @@ -3111,8 +2792,10 @@ changes: Asynchronously reads the entire contents of a file. -```js -fs.readFile('/etc/passwd', (err, data) => { +```js esm +import { readFile } from 'fs'; + +readFile('/etc/passwd', (err, data) => { if (err) throw err; console.log(data); }); @@ -3125,8 +2808,10 @@ If no encoding is specified, then the raw buffer is returned. If `options` is a string, then it specifies the encoding: -```js -fs.readFile('/etc/passwd', 'utf8', callback); +```js esm +import { readFile } from 'fs'; + +readFile('/etc/passwd', 'utf8', callback); ``` When the path is a directory, the behavior of `fs.readFile()` and @@ -3134,14 +2819,16 @@ When the path is a directory, the behavior of `fs.readFile()` and error will be returned. On FreeBSD, a representation of the directory's contents will be returned. -```js +```js esm +import { readFile } from 'fs'; + // macOS, Linux, and Windows -fs.readFile('', (err, data) => { +readFile('', (err, data) => { // => [Error: EISDIR: illegal operation on a directory, read ] }); // FreeBSD -fs.readFile('', (err, data) => { +readFile('', (err, data) => { // => null, }); ``` @@ -3149,10 +2836,12 @@ fs.readFile('', (err, data) => { It is possible to abort an ongoing request using an `AbortSignal`. If a request is aborted the callback is called with an `AbortError`: -```js +```js esm +import { readFile } from 'fs'; + const controller = new AbortController(); const signal = controller.signal; -fs.readFile(fileInfo[0].name, { signal }, (err, buf) => { +readFile(fileInfo[0].name, { signal }, (err, buf) => { // ... }); // When you want to abort the request @@ -3165,7 +2854,7 @@ when possible prefer streaming via `fs.createReadStream()`. Aborting an ongoing request does not abort individual operating system requests but rather the internal buffering `fs.readFile` performs. -### File descriptors +#### File descriptors 1. Any specified file descriptor has to support reading. 2. If a file descriptor is specified as the `path`, it will not be closed @@ -3175,7 +2864,7 @@ system requests but rather the internal buffering `fs.readFile` performs. the call to `fs.readFile()` with the same file descriptor, would give `'World'`, rather than `'Hello World'`. -### Performance Considerations +#### Performance Considerations The `fs.readFile()` method asynchronously reads the contents of a file into memory one chunk at a time, allowing the event loop to turn between each chunk. @@ -3197,46 +2886,7 @@ The Node.js GitHub issue [#25741][] provides more information and a detailed analysis on the performance of `fs.readFile()` for multiple file sizes in different Node.js versions. -## `fs.readFileSync(path[, options])` - - -* `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'`. -* Returns: {string|Buffer} - -Returns the contents of the `path`. - -For detailed information, see the documentation of the asynchronous version of -this API: [`fs.readFile()`][]. - -If the `encoding` option is specified then this function returns a -string. Otherwise it returns a buffer. - -Similar to [`fs.readFile()`][], when the path is a directory, the behavior of -`fs.readFileSync()` is platform-specific. - -```js -// macOS, Linux, and Windows -fs.readFileSync(''); -// => [Error: EISDIR: illegal operation on a directory, read ] - -// FreeBSD -fs.readFileSync(''); // => -``` - -## `fs.readlink(path[, options], callback)` +### `fs.readlink(path[, options], callback)` - -* `path` {string|Buffer|URL} -* `options` {string|Object} - * `encoding` {string} **Default:** `'utf8'` -* Returns: {string|Buffer} +Reads the contents of the symbolic link refered to by `path`. The callback gets +two arguments `(err, linkString)`. -Synchronous readlink(2). Returns the symbolic link's string value. +See the POSIX readlink(2) documentation for more details. The optional `options` argument can be a string specifying an encoding, or an object with an `encoding` property specifying the character encoding to use for -the link path returned. If the `encoding` is set to `'buffer'`, -the link path returned will be passed as a `Buffer` object. - -## `fs.readSync(fd, buffer, offset, length, position)` - - -* `fd` {integer} -* `buffer` {Buffer|TypedArray|DataView} -* `offset` {integer} -* `length` {integer} -* `position` {integer|bigint} -* Returns: {number} - -Returns the number of `bytesRead`. - -For detailed information, see the documentation of the asynchronous version of -this API: [`fs.read()`][]. - -## `fs.readSync(fd, buffer, [options])` - - -* `fd` {integer} -* `buffer` {Buffer|TypedArray|DataView} -* `options` {Object} - * `offset` {integer} **Default:** `0` - * `length` {integer} **Default:** `buffer.length` - * `position` {integer|bigint} **Default:** `null` -* Returns: {number} - -Returns the number of `bytesRead`. - -Similar to the above `fs.readSync` function, this version takes an optional `options` object. -If no `options` object is specified, it will default with the above values. - -For detailed information, see the documentation of the asynchronous version of -this API: [`fs.read()`][]. +the link path passed to the callback. If the `encoding` is set to `'buffer'`, +the link path returned will be passed as a {Buffer} object. -## `fs.readv(fd, buffers[, position], callback)` +### `fs.readv(fd, buffers[, position], callback)` - -* `fd` {integer} -* `buffers` {ArrayBufferView[]} -* `position` {integer} -* Returns: {number} The number of bytes read. - -For detailed information, see the documentation of the asynchronous version of -this API: [`fs.readv()`][]. +a promise for an `Object` with `bytesRead` and `buffers` properties. -## `fs.realpath(path[, options], callback)` +### `fs.realpath(path[, options], callback)` @@ -3471,66 +3031,13 @@ Only paths that can be converted to UTF8 strings are supported. The optional `options` argument can be a string specifying an encoding, or an object with an `encoding` property specifying the character encoding to use for the path passed to the callback. If the `encoding` is set to `'buffer'`, -the path returned will be passed as a `Buffer` object. - -On Linux, when Node.js is linked against musl libc, the procfs file system must -be mounted on `/proc` in order for this function to work. Glibc does not have -this restriction. - -## `fs.realpathSync(path[, options])` - - -* `path` {string|Buffer|URL} -* `options` {string|Object} - * `encoding` {string} **Default:** `'utf8'` -* Returns: {string|Buffer} - -Returns the resolved pathname. - -For detailed information, see the documentation of the asynchronous version of -this API: [`fs.realpath()`][]. - -## `fs.realpathSync.native(path[, options])` - - -* `path` {string|Buffer|URL} -* `options` {string|Object} - * `encoding` {string} **Default:** `'utf8'` -* Returns: {string|Buffer} - -Synchronous realpath(3). - -Only paths that can be converted to UTF8 strings are supported. - -The optional `options` argument can be a string specifying an encoding, or an -object with an `encoding` property specifying the character encoding to use for -the path returned. If the `encoding` is set to `'buffer'`, -the path returned will be passed as a `Buffer` object. +the path returned will be passed as a {Buffer} object. On Linux, when Node.js is linked against musl libc, the procfs file system must be mounted on `/proc` in order for this function to work. Glibc does not have this restriction. -## `fs.rename(oldPath, newPath, callback)` +### `fs.rename(oldPath, newPath, callback)` - -* `oldPath` {string|Buffer|URL} -* `newPath` {string|Buffer|URL} - -Synchronous rename(2). Returns `undefined`. - -## `fs.rmdir(path[, options], callback)` +### `fs.rmdir(path[, options], callback)` - -* `path` {string|Buffer|URL} -* `options` {Object} - * `maxRetries` {integer} If an `EBUSY`, `EMFILE`, `ENFILE`, `ENOTEMPTY`, or - `EPERM` error is encountered, Node.js retries the operation with a linear - backoff wait of `retryDelay` milliseconds longer on each try. This option - represents the number of retries. This option is ignored if the `recursive` - option is not `true`. **Default:** `0`. - * `recursive` {boolean} If `true`, perform a recursive directory removal. In - recursive mode, errors are not reported if `path` does not exist, and - operations are retried on failure. **Default:** `false`. - * `retryDelay` {integer} The amount of time in milliseconds to wait between - retries. This option is ignored if the `recursive` option is not `true`. - **Default:** `100`. - -Synchronous rmdir(2). Returns `undefined`. - -Using `fs.rmdirSync()` on a file (not a directory) results in an `ENOENT` error -on Windows and an `ENOTDIR` error on POSIX. - -Setting `recursive` to `true` results in behavior similar to the Unix command -`rm -rf`: an error will not be raised for paths that do not exist, and paths -that represent files will be deleted. The permissive behavior of the -`recursive` option is deprecated, `ENOTDIR` and `ENOENT` will be thrown in -the future. - -## `fs.rm(path[, options], callback)` +### `fs.rm(path[, options], callback)` @@ -3718,30 +3163,7 @@ Asynchronously removes files and directories (modeled on the standard POSIX `rm` utility). No arguments other than a possible exception are given to the completion callback. -## `fs.rmSync(path[, options])` - - -* `path` {string|Buffer|URL} -* `options` {Object} - * `force` {boolean} When `true`, exceptions will be ignored if `path` does - not exist. **Default:** `false`. - * `maxRetries` {integer} If an `EBUSY`, `EMFILE`, `ENFILE`, `ENOTEMPTY`, or - `EPERM` error is encountered, Node.js will retry the operation with a linear - backoff wait of `retryDelay` milliseconds longer on each try. This option - represents the number of retries. This option is ignored if the `recursive` - option is not `true`. **Default:** `0`. - * `recursive` {boolean} If `true`, perform a recursive directory removal. In - recursive mode operations are retried on failure. **Default:** `false`. - * `retryDelay` {integer} The amount of time in milliseconds to wait between - retries. This option is ignored if the `recursive` option is not `true`. - **Default:** `100`. - -Synchronously removes files and directories (modeled on the standard POSIX `rm` -utility). Returns `undefined`. - -## `fs.stat(path[, options], callback)` +### `fs.stat(path[, options], callback)` - -* `path` {string|Buffer|URL} -* `options` {Object} - * `bigint` {boolean} Whether the numeric values in the returned - [`fs.Stats`][] object should be `bigint`. **Default:** `false`. - * `throwIfNoEntry` {boolean} Whether an exception will be thrown - if no file system entry exists, rather than returning `undefined`. - **Default:** `true`. -* Returns: {fs.Stats} - -Synchronous stat(2). - -## `fs.symlink(target, path[, type], callback)` +### `fs.symlink(target, path[, type], callback)` - -* `target` {string|Buffer|URL} -* `path` {string|Buffer|URL} -* `type` {string} - -Returns `undefined`. - -For detailed information, see the documentation of the asynchronous version of -this API: [`fs.symlink()`][]. - -## `fs.truncate(path[, len], callback)` +### `fs.truncate(path[, len], callback)` - -* `path` {string|Buffer|URL} -* `len` {integer} **Default:** `0` - -Synchronous truncate(2). Returns `undefined`. A file descriptor can also be -passed as the first argument. In this case, `fs.ftruncateSync()` is called. +See the POSIX truncate(2) documentation for more details. -Passing a file descriptor is deprecated and may result in an error being thrown -in the future. - -## `fs.unlink(path, callback)` +### `fs.unlink(path, callback)` - -* `path` {string|Buffer|URL} - -Synchronous unlink(2). Returns `undefined`. +See the POSIX unlink(2) documentation for more details. -## `fs.unwatchFile(filename[, listener])` +### `fs.unwatchFile(filename[, listener])` @@ -4067,7 +3414,7 @@ Using [`fs.watch()`][] is more efficient than `fs.watchFile()` and `fs.unwatchFile()`. `fs.watch()` should be used instead of `fs.watchFile()` and `fs.unwatchFile()` when possible. -## `fs.utimes(path, atime, mtime, callback)` +### `fs.utimes(path, atime, mtime, callback)` - -* `path` {string|Buffer|URL} -* `atime` {number|string|Date} -* `mtime` {number|string|Date} - -Returns `undefined`. - -For detailed information, see the documentation of the asynchronous version of -this API: [`fs.utimes()`][]. - -## `fs.watch(filename[, options][, listener])` +### `fs.watch(filename[, options][, listener])` @@ -4201,7 +3521,7 @@ when the option is used on a platform that does not support it. On Windows, no events will be emitted if the watched directory is moved or renamed. An `EPERM` error is reported when the watched directory is deleted. -#### Availability +##### Availability @@ -4226,7 +3546,7 @@ when using virtualization software such as Vagrant or Docker. It is still possible to use `fs.watchFile()`, which uses stat polling, but this method is slower and less reliable. -#### Inodes +##### Inodes @@ -4240,7 +3560,7 @@ AIX files retain the same inode for the lifetime of a file. Saving and closing a watched file on AIX will result in two notifications (one for adding new content, and one for truncation). -#### Filename argument +##### Filename argument @@ -4249,8 +3569,9 @@ macOS, Windows, and AIX. Even on supported platforms, `filename` is not always guaranteed to be provided. Therefore, don't assume that `filename` argument is always provided in the callback, and have some fallback logic if it is `null`. -```js -fs.watch('somedir', (eventType, filename) => { +```js esm +import { watch } from 'fs'; +watch('somedir', (eventType, filename) => { console.log(`event type is: ${eventType}`); if (filename) { console.log(`filename provided: ${filename}`); @@ -4260,7 +3581,7 @@ fs.watch('somedir', (eventType, filename) => { }); ``` -## `fs.watchFile(filename[, options], listener)` +### `fs.watchFile(filename[, options], listener)` -* `file` {string|Buffer|URL|integer} filename or file descriptor -* `data` {string|Buffer|TypedArray|DataView|Object} -* `options` {Object|string} - * `encoding` {string|null} **Default:** `'utf8'` - * `mode` {integer} **Default:** `0o666` - * `flag` {string} See [support of file system `flags`][]. **Default:** `'w'`. +* `fd` {integer} +* `buffers` {ArrayBufferView[]} +* `position` {integer} +* `callback` {Function} + * `err` {Error} + * `bytesWritten` {integer} + * `buffers` {ArrayBufferView[]} -Returns `undefined`. +Write an array of `ArrayBufferView`s to the file specified by `fd` using +`writev()`. -For detailed information, see the documentation of the asynchronous version of -this API: [`fs.writeFile()`][]. +`position` is the offset from the beginning of the file where this data +should be written. If `typeof position !== 'number'`, the data will be written +at the current position. -## `fs.writeSync(fd, buffer[, offset[, length[, position]]])` - +The callback will be given three arguments: `err`, `bytesWritten`, and +`buffers`. `bytesWritten` is how many bytes were written from `buffers`. -* `fd` {integer} -* `buffer` {Buffer|TypedArray|DataView|string|Object} -* `offset` {integer} -* `length` {integer} -* `position` {integer} -* Returns: {number} The number of bytes written. +If this method is [`util.promisify()`][]ed, it returns a promise for an +`Object` with `bytesWritten` and `buffers` properties. -For detailed information, see the documentation of the asynchronous version of -this API: [`fs.write(fd, buffer...)`][]. +It is unsafe to use `fs.writev()` multiple times on the same file without +waiting for the callback. For this scenario, use [`fs.createWriteStream()`][]. + +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. + +## Synchronous API -## `fs.writeSync(fd, string[, position[, encoding]])` +The synchronous APIs perform all operations synchronously, blocking the +event loop until the operation completes or fails. + +### `fs.accessSync(path[, mode])` -* `fd` {integer} -* `string` {string|Object} -* `position` {integer} -* `encoding` {string} -* Returns: {number} The number of bytes written. +* `path` {string|Buffer|URL} +* `mode` {integer} **Default:** `fs.constants.F_OK` -For detailed information, see the documentation of the asynchronous version of -this API: [`fs.write(fd, string...)`][]. +Synchronously tests a user's permissions for the file or directory specified +by `path`. The `mode` argument is an optional integer that specifies the +accessibility checks to be performed. Check [File access constants][] for +possible values of `mode`. It is possible to create a mask consisting of +the bitwise OR of two or more values +(e.g. `fs.constants.W_OK | fs.constants.R_OK`). + +If any of the accessibility checks fail, an `Error` will be thrown. Otherwise, +the method will return `undefined`. -## `fs.writev(fd, buffers[, position], callback)` +```js esm +import { accessSync, constants } from 'fs'; + +try { + accessSync('etc/passwd', constants.R_OK | constants.W_OK); + console.log('can read/write'); +} catch (err) { + console.error('no access!'); +} +``` + +### `fs.appendFileSync(path, data[, options])` -* `fd` {integer} -* `buffers` {ArrayBufferView[]} -* `position` {integer} -* `callback` {Function} - * `err` {Error} - * `bytesWritten` {integer} - * `buffers` {ArrayBufferView[]} +* `path` {string|Buffer|URL|number} filename or file descriptor +* `data` {string|Buffer} +* `options` {Object|string} + * `encoding` {string|null} **Default:** `'utf8'` + * `mode` {integer} **Default:** `0o666` + * `flag` {string} See [support of file system `flags`][]. **Default:** `'a'`. -Write an array of `ArrayBufferView`s to the file specified by `fd` using -`writev()`. +Synchronously append data to a file, creating the file if it does not yet +exist. `data` can be a string or a {Buffer}. -`position` is the offset from the beginning of the file where this data -should be written. If `typeof position !== 'number'`, the data will be written -at the current position. +```js esm +import { appendFileSync } from 'fs'; -The callback will be given three arguments: `err`, `bytesWritten`, and -`buffers`. `bytesWritten` is how many bytes were written from `buffers`. +try { + appendFileSync('message.txt', 'data to append'); + console.log('The "data to append" was appended to file!'); +} catch (err) { + /* Handle the error */ +} +``` -If this method is [`util.promisify()`][]ed, it returns a `Promise` for an -`Object` with `bytesWritten` and `buffers` properties. +If `options` is a string, then it specifies the encoding: -It is unsafe to use `fs.writev()` multiple times on the same file without -waiting for the callback. For this scenario, use [`fs.createWriteStream()`][]. +```js esm +import { appendFileSync } from 'fs'; -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. +appendFileSync('message.txt', 'data to append', 'utf8'); +``` + +The `path` may be specified as a numeric file descriptor that has been opened +for appending (using `fs.open()` or `fs.openSync()`). The file descriptor will +not be closed automatically. + +```js esm +import { openSync, closeSync, appendFileSync } from 'fs'; + +let fd; + +try { + fd = openSync('message.txt', 'a'); + appendFileSync(fd, 'data to append', 'utf8'); +} catch (err) { + /* Handle the error */ +} finally { + if (fd !== undefined) + closeSync(fd); +} +``` -## `fs.writevSync(fd, buffers[, position])` +### `fs.chmodSync(path, mode)` -* `fd` {integer} -* `buffers` {ArrayBufferView[]} -* `position` {integer} -* Returns: {number} The number of bytes written. +* `path` {string|Buffer|URL} +* `mode` {string|integer} For detailed information, see the documentation of the asynchronous version of -this API: [`fs.writev()`][]. +this API: [`fs.chmod()`][]. -## `fs` Promises API +See the POSIX chmod(2) documentation for more detail. + +### `fs.chownSync(path, uid, gid)` -The `fs.promises` API provides an alternative set of asynchronous file system -methods that return `Promise` objects rather than using callbacks. The -API is accessible via `require('fs').promises` or `require('fs/promises')`. +* `path` {string|Buffer|URL} +* `uid` {integer} +* `gid` {integer} -### Class: `FileHandle` +Synchronously changes owner and group of a file. Returns `undefined`. +This is the synchronous version of [`fs.chown()`][]. + +See the POSIX chown(2) documentation for more detail. + +### `fs.closeSync(fd)` -A `FileHandle` object is a wrapper for a numeric file descriptor. -Instances of `FileHandle` are distinct from numeric file descriptors -in that they provide an object oriented API for working with files. +* `fd` {integer} -If a `FileHandle` is not closed using the -`filehandle.close()` method, it might automatically close the file descriptor -and will emit a process warning, thereby helping to prevent memory leaks. -Please do not rely on this behavior because it is unreliable and -the file may not be closed. Instead, always explicitly close `FileHandle`s. -Node.js may change this behavior in the future. +Closes the file descriptor. Returns `undefined`. -Instances of the `FileHandle` object are created internally by the -`fsPromises.open()` method. +Calling `fs.closeSync()` on any file descriptor (`fd`) that is currently in use +through any other `fs` operation may lead to undefined behavior. -Unlike the callback-based API (`fs.fstat()`, `fs.fchown()`, `fs.fchmod()`, and -so on), a numeric file descriptor is not used by the promise-based API. Instead, -the promise-based API uses the `FileHandle` class in order to help avoid -accidental leaking of unclosed file descriptors after a `Promise` is fulfilled -or rejected. +See the POSIX close(2) documentation for more detail. -#### Event: `'close'` +### `fs.copyFileSync(src, dest[, mode])` -The `'close'` event is emitted when the `FileHandle` and any of its underlying -resources (a file descriptor, for example) have been closed. - -#### `filehandle.appendFile(data, options)` - +* `src` {string|Buffer|URL} source filename to copy +* `dest` {string|Buffer|URL} destination filename of the copy operation +* `mode` {integer} modifiers for copy operation. **Default:** `0`. -* `data` {string|Buffer} -* `options` {Object|string} - * `encoding` {string|null} **Default:** `'utf8'` -* Returns: {Promise} +Synchronously copies `src` to `dest`. By default, `dest` is overwritten if it +already exists. Returns `undefined`. Node.js makes no guarantees about the +atomicity of the copy operation. If an error occurs after the destination file +has been opened for writing, Node.js will attempt to remove the destination. -Alias of [`filehandle.writeFile()`][]. +`mode` is an optional integer that specifies the behavior +of the copy operation. It is possible to create a mask consisting of the bitwise +OR of two or more values (e.g. +`fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE`). -When operating on file handles, the mode cannot be changed from what it was set -to with [`fsPromises.open()`][]. Therefore, this is equivalent to -[`filehandle.writeFile()`][]. +* `fs.constants.COPYFILE_EXCL`: The copy operation will fail if `dest` already + exists. +* `fs.constants.COPYFILE_FICLONE`: The copy operation will attempt to create a + copy-on-write reflink. If the platform does not support copy-on-write, then a + fallback copy mechanism is used. +* `fs.constants.COPYFILE_FICLONE_FORCE`: The copy operation will attempt to + create a copy-on-write reflink. If the platform does not support + copy-on-write, then the operation will fail. -#### `filehandle.chmod(mode)` - +```js esm +import { copyFileSync, constants } from 'fs'; -* `mode` {integer} -* Returns: {Promise} +// destination.txt will be created or overwritten by default. +copyFileSync('source.txt', 'destination.txt'); +console.log('source.txt was copied to destination.txt'); -Modifies the permissions on the file. The `Promise` is fulfilled with no -arguments upon success. +// By using COPYFILE_EXCL, the operation will fail if destination.txt exists. +copyFileSync('source.txt', 'destination.txt', constants.COPYFILE_EXCL); +``` -#### `filehandle.chown(uid, gid)` +### `fs.existsSync(path)` -* `uid` {integer} -* `gid` {integer} -* Returns: {Promise} +* `path` {string|Buffer|URL} +* Returns: {boolean} -Changes the ownership of the file then fulfills the `Promise` with no arguments -upon success. +Returns `true` if the path exists, `false` otherwise. -#### `filehandle.close()` - +For detailed information, see the documentation of the asynchronous version of +this API: [`fs.exists()`][]. -* Returns: {Promise} A `Promise` that will be fulfilled once the underlying - file descriptor is closed, or will be rejected if an error occurs while - closing. +`fs.exists()` is deprecated, but `fs.existsSync()` is not. The `callback` +parameter to `fs.exists()` accepts parameters that are inconsistent with other +Node.js callbacks. `fs.existsSync()` does not use a callback. -Closes the file handle after waiting for any pending operation on the handle to -complete. +```js esm +import { existsSync } from 'fs'; -```js -const fsPromises = require('fs').promises; -async function openAndClose() { - let filehandle; - try { - filehandle = await fsPromises.open('thefile.txt', 'r'); - } finally { - if (filehandle !== undefined) - await filehandle.close(); - } -} +if (existsSync('/etc/passwd')) + console.log('The path exists.'); ``` -#### `filehandle.datasync()` +### `fs.fchmodSync(fd, mode)` -* Returns: {Promise} - -Asynchronous fdatasync(2). The `Promise` is fulfilled with no arguments upon -success. +* `fd` {integer} +* `mode` {string|integer} -#### `filehandle.fd` - +Sets the permissions on the file. Returns `undefined`. -* {number} The numeric file descriptor managed by the `FileHandle` object. +See the POSIX fchmod(2) documentation for more detail. -#### `filehandle.read(buffer, offset, length, position)` +### `fs.fchownSync(fd, uid, gid)` -* `buffer` {Buffer|Uint8Array} -* `offset` {integer} -* `length` {integer} -* `position` {integer} -* Returns: {Promise} - -Read data from the file. - -`buffer` is the buffer that the data will be written to. +* `fd` {integer} +* `uid` {integer} The file's new owner's user id. +* `gid` {integer} The file's new group's group id. -`offset` is the offset in the buffer to start writing at. +Sets the owner of the file. Returns `undefined`. -`length` is an integer specifying the number of bytes to read. +See the POSIX fchown(2) documentation for more detail. -`position` is an argument specifying where to begin reading from in the file. -If `position` is `null`, data will be read from the current file position, -and the file position will be updated. -If `position` is an integer, the file position will remain unchanged. +### `fs.fdatasyncSync(fd)` + -Following successful read, the `Promise` is fulfilled with an object with a -`bytesRead` property specifying the number of bytes read, and a `buffer` -property that is a reference to the passed in `buffer` argument. +* `fd` {integer} -If the file is not modified concurrently, the end-of-file is reached when the -number of bytes read is zero. +Forces all currently queued I/O operations associated with the file to the +operating system's synchronized I/O completion state. Refer to the POSIX +fdatasync(2) documentation for details. Returns `undefined`. -#### `filehandle.read(options)` +### `fs.fstatSync(fd[, options])` -* `options` {Object} - * `buffer` {Buffer|Uint8Array} **Default:** `Buffer.alloc(16384)` - * `offset` {integer} **Default:** `0` - * `length` {integer} **Default:** `buffer.length` - * `position` {integer} **Default:** `null` -* Returns: {Promise} - -#### `filehandle.readFile(options)` - - -* `options` {Object|string} - * `encoding` {string|null} **Default:** `null` - * `signal` {AbortSignal} allows aborting an in-progress readFile -* Returns: {Promise} - -Asynchronously reads the entire contents of a file. - -The `Promise` is fulfilled with the contents of the file. If no encoding is -specified (using `options.encoding`), the data is returned as a `Buffer` -object. Otherwise, the data will be a string. - -If `options` is a string, then it specifies the encoding. - -The `FileHandle` has to support reading. - -If one or more `filehandle.read()` calls are made on a file handle and then a -`filehandle.readFile()` call is made, the data will be read from the current -position till the end of the file. It doesn't always read from the beginning -of the file. - -#### `filehandle.readv(buffers[, position])` - - -* `buffers` {ArrayBufferView[]} -* `position` {integer} -* Returns: {Promise} - -Read from a file and write to an array of `ArrayBufferView`s - -The `Promise` is fulfilled with an object containing a `bytesRead` property -identifying the number of bytes read, and a `buffers` property containing -a reference to the `buffers` input. - -`position` is the offset from the beginning of the file where this data -should be read from. If `typeof position !== 'number'`, the data will be read -from the current position. - -#### `filehandle.stat([options])` - +* `fd` {integer} * `options` {Object} * `bigint` {boolean} Whether the numeric values in the returned - [`fs.Stats`][] object should be `bigint`. **Default:** `false`. -* Returns: {Promise} + {fs.Stats} object should be `bigint`. **Default:** `false`. +* Returns: {fs.Stats} -Retrieves the [`fs.Stats`][] for the file. +Retrieves the {fs.Stats} for the file descriptor. -#### `filehandle.sync()` +See the POSIX fstat(2) documentation for more detail. + +### `fs.fsyncSync(fd)` -* Returns: {Promise} +* `fd` {integer} -Asynchronous fsync(2). The `Promise` is fulflled with no arguments upon -success. +Request that all data for the open file descriptor is flushed to the storage +device. The specific implementation is operating system and device specific. +Refer to the POSIX fsync(2) documentation for more detail. Returns `undefined`. -#### `filehandle.truncate(len)` +### `fs.ftruncateSync(fd[, len])` +* `fd` {integer} * `len` {integer} **Default:** `0` -* Returns: {Promise} -Truncates the file then fulfills the `Promise` with no arguments upon success. +Truncates the file descriptor. Returns `undefined`. -If the file was larger than `len` bytes, only the first `len` bytes will be -retained in the file. +For detailed information, see the documentation of the asynchronous version of +this API: [`fs.ftruncate()`][]. -For example, the following program retains only the first four bytes of the -file: +### `fs.futimesSync(fd, atime, mtime)` + -```js -const fs = require('fs'); -const fsPromises = fs.promises; +* `fd` {integer} +* `atime` {number|string|Date} +* `mtime` {number|string|Date} -console.log(fs.readFileSync('temp.txt', 'utf8')); -// Prints: Node.js +Synchronous version of [`fs.futimes()`][]. Returns `undefined`. -async function doTruncate() { - let filehandle = null; - try { - filehandle = await fsPromises.open('temp.txt', 'r+'); - await filehandle.truncate(4); - } finally { - if (filehandle) { - // Close the file if it is opened. - await filehandle.close(); - } - } - console.log(fs.readFileSync('temp.txt', 'utf8')); // Prints: Node -} +### `fs.lchmodSync(path, mode)` + -doTruncate().catch(console.error); -``` +* `path` {string|Buffer|URL} +* `mode` {integer} -If the file previously was shorter than `len` bytes, it is extended, and the -extended part is filled with null bytes (`'\0'`): +Changes the permissions on a symbolic link. Returns `undefined`. -```js -const fs = require('fs'); -const fsPromises = fs.promises; +This method is only implemented on macOS. -console.log(fs.readFileSync('temp.txt', 'utf8')); -// Prints: Node.js +See the POSIX lchmod(2) documentation for more detail. -async function doTruncate() { - let filehandle = null; - try { - filehandle = await fsPromises.open('temp.txt', 'r+'); - await filehandle.truncate(10); - } finally { - if (filehandle) { - // Close the file if it is opened. - await filehandle.close(); - } - } - console.log(fs.readFileSync('temp.txt', 'utf8')); // Prints Node.js\0\0\0 -} +### `fs.lchownSync(path, uid, gid)` + -doTruncate().catch(console.error); -``` +* `path` {string|Buffer|URL} +* `uid` {integer} The file's new owner's user id. +* `gid` {integer} The file's new group's group id. -The last three bytes are null bytes (`'\0'`), to compensate the over-truncation. +Set the owner for the path. Returns `undefined`. -#### `filehandle.utimes(atime, mtime)` +See the POSIX lchown(2) documentation for more details. + +### `fs.lutimesSync(path, atime, mtime)` +* `path` {string|Buffer|URL} * `atime` {number|string|Date} * `mtime` {number|string|Date} -* Returns: {Promise} - -Change the file system timestamps of the object referenced by the `FileHandle` -then fulfills the `Promise` with no arguments upon success. -This function does not work on AIX versions before 7.1, it will reject the -`Promise` with an error using code `UV_ENOSYS`. +Change the file system timestamps of the symbolic link referenced by `path`. +Returns `undefined`, or throws an exception when parameters are incorrect or +the operation fails. This is the synchronous version of [`fs.lutimes()`][]. -#### `filehandle.write(buffer[, offset[, length[, position]]])` +### `fs.linkSync(existingPath, newPath)` -* `buffer` {Buffer|Uint8Array|string|Object} -* `offset` {integer} -* `length` {integer} -* `position` {integer} -* Returns: {Promise} - -Write `buffer` to the file. +* `existingPath` {string|Buffer|URL} +* `newPath` {string|Buffer|URL} -The `Promise` is fulfilled with an object containing a `bytesWritten` property -identifying the number of bytes written, and a `buffer` property containing -a reference to the `buffer` written. +Creates a new link from the `existingPath` to the `newPath`. See the POSIX +link(2) documentation for more detail. Returns `undefined`. -`offset` determines the part of the buffer to be written, and `length` is -an integer specifying the number of bytes to write. +### `fs.lstatSync(path[, options])` + -`position` refers to the offset from the beginning of the file where this data -should be written. If `typeof position !== 'number'`, the data will be written -at the current position. See pwrite(2). +* `path` {string|Buffer|URL} +* `options` {Object} + * `bigint` {boolean} Whether the numeric values in the returned + {fs.Stats} object should be `bigint`. **Default:** `false`. + * `throwIfNoEntry` {boolean} Whether an exception will be thrown + if no file system entry exists, rather than returning `undefined`. + **Default:** `true`. +* Returns: {fs.Stats} -It is unsafe to use `filehandle.write()` multiple times on the same file -without waiting for the `Promise` to be fulfilled (or rejected). For this -scenario, use [`fs.createWriteStream()`][]. +Retrieves the {fs.Stats} for the symbolic link refered to by `path`. -On Linux, positional writes do not 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. +See the POSIX lstat(2) documentation for more details. -#### `filehandle.write(string[, position[, encoding]])` +### `fs.mkdirSync(path[, options])` -* `string` {string|Object} -* `position` {integer} -* `encoding` {string} **Default:** `'utf8'` -* Returns: {Promise} +* `path` {string|Buffer|URL} +* `options` {Object|integer} + * `recursive` {boolean} **Default:** `false` + * `mode` {string|integer} Not supported on Windows. **Default:** `0o777`. +* Returns: {string|undefined} -Write `string` to the file. If `string` is not a string, or an -object with an own `toString` function property, then an exception is thrown. +Synchronously creates a directory. Returns `undefined`, or if `recursive` is +`true`, the first directory path created. +This is the synchronous version of [`fs.mkdir()`][]. -The `Promise` is fulfilled with an object containing a `bytesWritten` property -identifying the number of bytes written, and a `buffer` property containing -a reference to the `string` written. +See the POSIX mkdir(2) documentation for more details. -`position` refers to the offset from the beginning of the file where this data -should be written. If the type of `position` is not a `number` the data -will be written at the current position. See pwrite(2). +### `fs.mkdtempSync(prefix[, options])` + -`encoding` is the expected string encoding. +* `prefix` {string} +* `options` {string|Object} + * `encoding` {string} **Default:** `'utf8'` +* Returns: {string} -It is unsafe to use `filehandle.write()` multiple times on the same file -without waiting for the `Promise` to be fulfilled (or rejected). For this -scenario, use [`fs.createWriteStream()`][]. +Returns the created directory path. -On Linux, positional writes do not 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. +For detailed information, see the documentation of the asynchronous version of +this API: [`fs.mkdtemp()`][]. -#### `filehandle.writeFile(data, options)` +The optional `options` argument can be a string specifying an encoding, or an +object with an `encoding` property specifying the character encoding to use. + +### `fs.opendirSync(path[, options])` -* `data` {string|Buffer|Uint8Array|Object} -* `options` {Object|string} +* `path` {string|Buffer|URL} +* `options` {Object} * `encoding` {string|null} **Default:** `'utf8'` -* Returns: {Promise} + * `bufferSize` {number} Number of directory entries that are buffered + internally when reading from the directory. Higher values lead to better + performance but higher memory usage. **Default:** `32` +* Returns: {fs.Dir} -Asynchronously writes data to a file, replacing the file if it already exists. -`data` can be a string, a buffer, or an object with an own `toString` function -property. The `Promise` is fulfilled with no arguments upon success. +Synchronously open a directory. See opendir(3). -The `encoding` option is ignored if `data` is a buffer. +Creates an {fs.Dir}, which contains all further functions for reading from +and cleaning up the directory. -If `options` is a string, then it specifies the encoding. +The `encoding` option sets the encoding for the `path` while opening the +directory and subsequent read operations. -The `FileHandle` has to support writing. +### `fs.openSync(path[, flags, mode])` + -It is unsafe to use `filehandle.writeFile()` multiple times on the same file -without waiting for the `Promise` to be fulfilled (or rejected). +* `path` {string|Buffer|URL} +* `flags` {string|number} **Default:** `'r'`. + See [support of file system `flags`][]. +* `mode` {string|integer} **Default:** `0o666` +* Returns: {number} -If one or more `filehandle.write()` calls are made on a file handle and then a -`filehandle.writeFile()` call is made, the data will be written from the -current position till the end of the file. It doesn't always write from the -beginning of the file. +Returns an integer representing the file descriptor. -#### `filehandle.writev(buffers[, position])` +For detailed information, see the documentation of the asynchronous version of +this API: [`fs.open()`][]. + +### `fs.readdirSync(path[, options])` -* `buffers` {ArrayBufferView[]} -* `position` {integer} -* Returns: {Promise} +* `path` {string|Buffer|URL} +* `options` {string|Object} + * `encoding` {string} **Default:** `'utf8'` + * `withFileTypes` {boolean} **Default:** `false` +* Returns: {string[]|Buffer[]|fs.Dirent[]} -Write an array of `ArrayBufferView`s to the file. +Reads the contents of the director. -The `Promise` is fulfilled with an object containing a `bytesWritten` property -identifying the number of bytes written, and a `buffers` property containing -a reference to the `buffers` input. +See the POSIX readdir(3) documentation for more details. -`position` is the offset from the beginning of the file where this data -should be written. If `typeof position !== 'number'`, the data will be written -at the current position. +The optional `options` argument can be a string specifying an encoding, or an +object with an `encoding` property specifying the character encoding to use for +the filenames returned. If the `encoding` is set to `'buffer'`, +the filenames returned will be passed as {Buffer} objects. -It is unsafe to call `writev()` multiple times on the same file without waiting -for the previous operation to complete. +If `options.withFileTypes` is set to `true`, the result will contain +{fs.Dirent} objects. -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. +### `fs.readFileSync(path[, options])` + -### `fsPromises.access(path[, mode])` +* `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'`. +* Returns: {string|Buffer} + +Returns the contents of the `path`. + +For detailed information, see the documentation of the asynchronous version of +this API: [`fs.readFile()`][]. + +If the `encoding` option is specified then this function returns a +string. Otherwise it returns a buffer. + +Similar to [`fs.readFile()`][], when the path is a directory, the behavior of +`fs.readFileSync()` is platform-specific. + +```js esm +import { readFileSync } from 'fs'; + +// macOS, Linux, and Windows +readFileSync(''); +// => [Error: EISDIR: illegal operation on a directory, read ] + +// FreeBSD +readFileSync(''); // => +``` + +### `fs.readlinkSync(path[, options])` * `path` {string|Buffer|URL} -* `mode` {integer} **Default:** `fs.constants.F_OK` -* Returns: {Promise} +* `options` {string|Object} + * `encoding` {string} **Default:** `'utf8'` +* Returns: {string|Buffer} -Tests a user's permissions for the file or directory specified by `path`. -The `mode` argument is an optional integer that specifies the accessibility -checks to be performed. Check [File access constants][] for possible values -of `mode`. It is possible to create a mask consisting of the bitwise OR of -two or more values (e.g. `fs.constants.W_OK | fs.constants.R_OK`). +Returns the symbolic link's string value. -If the accessibility check is successful, the `Promise` is fulfilled with no -value. If any of the accessibility checks fail, the `Promise` is rejected -with an `Error` object. The following example checks if the file -`/etc/passwd` can be read and written by the current process. +See the POSIX readlink(2) documentation for more details. -```js -const fs = require('fs'); -const fsPromises = fs.promises; +The optional `options` argument can be a string specifying an encoding, or an +object with an `encoding` property specifying the character encoding to use for +the link path returned. If the `encoding` is set to `'buffer'`, +the link path returned will be passed as a {Buffer} object. -fsPromises.access('/etc/passwd', fs.constants.R_OK | fs.constants.W_OK) - .then(() => console.log('can access')) - .catch(() => console.error('cannot access')); -``` +### `fs.readSync(fd, buffer, offset, length, position)` + -Using `fsPromises.access()` to check for the accessibility of a file before -calling `fsPromises.open()` is not recommended. Doing so introduces a race -condition, since other processes may change the file's state between the two -calls. Instead, user code should open/read/write the file directly and handle -the error raised if the file is not accessible. +* `fd` {integer} +* `buffer` {Buffer|TypedArray|DataView} +* `offset` {integer} +* `length` {integer} +* `position` {integer|bigint} +* Returns: {number} -### `fsPromises.appendFile(path, data[, options])` +Returns the number of `bytesRead`. + +For detailed information, see the documentation of the asynchronous version of +this API: [`fs.read()`][]. + +### `fs.readSync(fd, buffer, [options])` -* `path` {string|Buffer|URL|FileHandle} filename or `FileHandle` -* `data` {string|Buffer} -* `options` {Object|string} - * `encoding` {string|null} **Default:** `'utf8'` - * `mode` {integer} **Default:** `0o666` - * `flag` {string} See [support of file system `flags`][]. **Default:** `'a'`. -* Returns: {Promise} +* `fd` {integer} +* `buffer` {Buffer|TypedArray|DataView} +* `options` {Object} + * `offset` {integer} **Default:** `0` + * `length` {integer} **Default:** `buffer.length` + * `position` {integer|bigint} **Default:** `null` +* Returns: {number} -Asynchronously append data to a file, creating the file if it does not yet -exist. `data` can be a string or a [`Buffer`][]. The `Promise` will be -fulfilled with no arguments upon success. +Returns the number of `bytesRead`. -If `options` is a string, then it specifies the encoding. +Similar to the above `fs.readSync` function, this version takes an optional `options` object. +If no `options` object is specified, it will default with the above values. -The `path` may be specified as a `FileHandle` that has been opened -for appending (using `fsPromises.open()`). +For detailed information, see the documentation of the asynchronous version of +this API: [`fs.read()`][]. + +### `fs.readvSync(fd, buffers[, position])` + + +* `fd` {integer} +* `buffers` {ArrayBufferView[]} +* `position` {integer} +* Returns: {number} The number of bytes read. + +For detailed information, see the documentation of the asynchronous version of +this API: [`fs.readv()`][]. + +### `fs.realpathSync(path[, options])` + + +* `path` {string|Buffer|URL} +* `options` {string|Object} + * `encoding` {string} **Default:** `'utf8'` +* Returns: {string|Buffer} + +Returns the resolved pathname. + +For detailed information, see the documentation of the asynchronous version of +this API: [`fs.realpath()`][]. + +### `fs.realpathSync.native(path[, options])` + + +* `path` {string|Buffer|URL} +* `options` {string|Object} + * `encoding` {string} **Default:** `'utf8'` +* Returns: {string|Buffer} + +Synchronous realpath(3). + +Only paths that can be converted to UTF8 strings are supported. + +The optional `options` argument can be a string specifying an encoding, or an +object with an `encoding` property specifying the character encoding to use for +the path returned. If the `encoding` is set to `'buffer'`, +the path returned will be passed as a {Buffer} object. + +On Linux, when Node.js is linked against musl libc, the procfs file system must +be mounted on `/proc` in order for this function to work. Glibc does not have +this restriction. + +### `fs.renameSync(oldPath, newPath)` + + +* `oldPath` {string|Buffer|URL} +* `newPath` {string|Buffer|URL} + +Renames the file from `oldPath` to `newPath`. Returns `undefined`. + +See the POSIX rename(2) documentation for more details. + +### `fs.rmdirSync(path[, options])` + + +* `path` {string|Buffer|URL} +* `options` {Object} + * `maxRetries` {integer} If an `EBUSY`, `EMFILE`, `ENFILE`, `ENOTEMPTY`, or + `EPERM` error is encountered, Node.js retries the operation with a linear + backoff wait of `retryDelay` milliseconds longer on each try. This option + represents the number of retries. This option is ignored if the `recursive` + option is not `true`. **Default:** `0`. + * `recursive` {boolean} If `true`, perform a recursive directory removal. In + recursive mode, errors are not reported if `path` does not exist, and + operations are retried on failure. **Default:** `false`. + * `retryDelay` {integer} The amount of time in milliseconds to wait between + retries. This option is ignored if the `recursive` option is not `true`. + **Default:** `100`. + +Synchronous rmdir(2). Returns `undefined`. + +Using `fs.rmdirSync()` on a file (not a directory) results in an `ENOENT` error +on Windows and an `ENOTDIR` error on POSIX. + +Setting `recursive` to `true` results in behavior similar to the Unix command +`rm -rf`: an error will not be raised for paths that do not exist, and paths +that represent files will be deleted. The permissive behavior of the +`recursive` option is deprecated, `ENOTDIR` and `ENOENT` will be thrown in +the future. + +### `fs.rmSync(path[, options])` + + +* `path` {string|Buffer|URL} +* `options` {Object} + * `force` {boolean} When `true`, exceptions will be ignored if `path` does + not exist. **Default:** `false`. + * `maxRetries` {integer} If an `EBUSY`, `EMFILE`, `ENFILE`, `ENOTEMPTY`, or + `EPERM` error is encountered, Node.js will retry the operation with a linear + backoff wait of `retryDelay` milliseconds longer on each try. This option + represents the number of retries. This option is ignored if the `recursive` + option is not `true`. **Default:** `0`. + * `recursive` {boolean} If `true`, perform a recursive directory removal. In + recursive mode operations are retried on failure. **Default:** `false`. + * `retryDelay` {integer} The amount of time in milliseconds to wait between + retries. This option is ignored if the `recursive` option is not `true`. + **Default:** `100`. + +Synchronously removes files and directories (modeled on the standard POSIX `rm` +utility). Returns `undefined`. + +### `fs.statSync(path[, options])` + + +* `path` {string|Buffer|URL} +* `options` {Object} + * `bigint` {boolean} Whether the numeric values in the returned + {fs.Stats} object should be `bigint`. **Default:** `false`. + * `throwIfNoEntry` {boolean} Whether an exception will be thrown + if no file system entry exists, rather than returning `undefined`. + **Default:** `true`. +* Returns: {fs.Stats} + +Retrieves the {fs.Stats} for the path. + +### `fs.symlinkSync(target, path[, type])` + + +* `target` {string|Buffer|URL} +* `path` {string|Buffer|URL} +* `type` {string} + +Returns `undefined`. + +For detailed information, see the documentation of the asynchronous version of +this API: [`fs.symlink()`][]. + +### `fs.truncateSync(path[, len])` + + +* `path` {string|Buffer|URL} +* `len` {integer} **Default:** `0` + +Truncates the file. Returns `undefined`. A file descriptor can also be +passed as the first argument. In this case, `fs.ftruncateSync()` is called. + +Passing a file descriptor is deprecated and may result in an error being thrown +in the future. + +### `fs.unlinkSync(path)` + + +* `path` {string|Buffer|URL} + +Synchronous unlink(2). Returns `undefined`. + +### `fs.utimesSync(path, atime, mtime)` + + +* `path` {string|Buffer|URL} +* `atime` {number|string|Date} +* `mtime` {number|string|Date} + +Returns `undefined`. + +For detailed information, see the documentation of the asynchronous version of +this API: [`fs.utimes()`][]. + +### `fs.writeFileSync(file, data[, options])` + + +* `file` {string|Buffer|URL|integer} filename or file descriptor +* `data` {string|Buffer|TypedArray|DataView|Object} +* `options` {Object|string} + * `encoding` {string|null} **Default:** `'utf8'` + * `mode` {integer} **Default:** `0o666` + * `flag` {string} See [support of file system `flags`][]. **Default:** `'w'`. + +Returns `undefined`. + +For detailed information, see the documentation of the asynchronous version of +this API: [`fs.writeFile()`][]. + +### `fs.writeSync(fd, buffer[, offset[, length[, position]]])` + + +* `fd` {integer} +* `buffer` {Buffer|TypedArray|DataView|string|Object} +* `offset` {integer} +* `length` {integer} +* `position` {integer} +* Returns: {number} The number of bytes written. + +For detailed information, see the documentation of the asynchronous version of +this API: [`fs.write(fd, buffer...)`][]. + +### `fs.writeSync(fd, string[, position[, encoding]])` + + +* `fd` {integer} +* `string` {string|Object} +* `position` {integer} +* `encoding` {string} +* Returns: {number} The number of bytes written. + +For detailed information, see the documentation of the asynchronous version of +this API: [`fs.write(fd, string...)`][]. + +### `fs.writevSync(fd, buffers[, position])` + + +* `fd` {integer} +* `buffers` {ArrayBufferView[]} +* `position` {integer} +* Returns: {number} The number of bytes written. + +For detailed information, see the documentation of the asynchronous version of +this API: [`fs.writev()`][]. + +## Common Objects + +The common objects are shared by all of the file system API variants +(promise, callback, and synchronous). + +### Class: `fs.Dir` + + +A class representing a directory stream. + +Created by [`fs.opendir()`][], [`fs.opendirSync()`][], or +[`fsPromises.opendir()`][]. + +```js esm +import { opendir } from 'fs/promises'; + +try { + const dir = await opendir('./'); + for await (const dirent of dir) + console.log(dirent.name); +} catch (err) { + console.error(err); +} +``` + +#### `dir.close()` + + +* Returns: {Promise} + +Asynchronously close the directory's underlying resource handle. +Subsequent reads will result in errors. + +A promise is returned that will be resolved after the resource has been +closed. + +#### `dir.close(callback)` + + +* `callback` {Function} + * `err` {Error} + +Asynchronously close the directory's underlying resource handle. +Subsequent reads will result in errors. + +The `callback` will be called after the resource handle has been closed. + +#### `dir.closeSync()` + + +Synchronously close the directory's underlying resource handle. +Subsequent reads will result in errors. + +#### `dir.path` + + +* {string} + +The read-only path of this directory as was provided to [`fs.opendir()`][], +[`fs.opendirSync()`][], or [`fsPromises.opendir()`][]. + +#### `dir.read()` + + +* Returns: {Promise} containing {fs.Dirent|null} + +Asynchronously read the next directory entry via readdir(3) as an +{fs.Dirent}. + +A promise is returned that will be resolved with an {fs.Dirent}, or `null` +if there are no more directory entries to read. + +Directory entries returned by this function are in no particular order as +provided by the operating system's underlying directory mechanisms. +Entries added or removed while iterating over the directory might not be +included in the iteration results. + +#### `dir.read(callback)` + + +* `callback` {Function} + * `err` {Error} + * `dirent` {fs.Dirent|null} + +Asynchronously read the next directory entry via readdir(3) as an +{fs.Dirent}. + +After the read is completed, the `callback` will be called with an +{fs.Dirent}, or `null` if there are no more directory entries to read. + +Directory entries returned by this function are in no particular order as +provided by the operating system's underlying directory mechanisms. +Entries added or removed while iterating over the directory might not be +included in the iteration results. + +#### `dir.readSync()` + + +* Returns: {fs.Dirent|null} + +Synchronously read the next directory entry as an {fs.Dirent}. See the +POSIX readdir(3) documentation for more detail. + +If there are no more directory entries to read, `null` will be returned. + +Directory entries returned by this function are in no particular order as +provided by the operating system's underlying directory mechanisms. +Entries added or removed while iterating over the directory might not be +included in the iteration results. + +#### `dir[Symbol.asyncIterator]()` + + +* Returns: {AsyncIterator} of {fs.Dirent} + +Asynchronously iterates over the directory until all entries have +been read. Refer to the POSIX readdir(3) documentation for more detail. + +Entries returned by the async iterator are always an {fs.Dirent}. +The `null` case from `dir.read()` is handled internally. + +See {fs.Dir} for an example. + +Directory entries returned by this iterator are in no particular order as +provided by the operating system's underlying directory mechanisms. +Entries added or removed while iterating over the directory might not be +included in the iteration results. + +### Class: `fs.Dirent` + + +A representation of a directory entry, which can be a file or a subdirectory +within the directory, as returned by reading from an {fs.Dir}. The +directory entry is a combination of the file name and file type pairs. + +Additionally, when [`fs.readdir()`][] or [`fs.readdirSync()`][] is called with +the `withFileTypes` option set to `true`, the resulting array is filled with +{fs.Dirent} objects, rather than strings or {Buffer}s. + +#### `dirent.isBlockDevice()` + + +* Returns: {boolean} + +Returns `true` if the {fs.Dirent} object describes a block device. + +#### `dirent.isCharacterDevice()` + + +* Returns: {boolean} + +Returns `true` if the {fs.Dirent} object describes a character device. + +#### `dirent.isDirectory()` + + +* Returns: {boolean} + +Returns `true` if the {fs.Dirent} object describes a file system +directory. + +#### `dirent.isFIFO()` + + +* Returns: {boolean} + +Returns `true` if the {fs.Dirent} object describes a first-in-first-out +(FIFO) pipe. + +#### `dirent.isFile()` + + +* Returns: {boolean} + +Returns `true` if the {fs.Dirent} object describes a regular file. + +#### `dirent.isSocket()` + + +* Returns: {boolean} + +Returns `true` if the {fs.Dirent} object describes a socket. + +#### `dirent.isSymbolicLink()` + + +* Returns: {boolean} + +Returns `true` if the {fs.Dirent} object describes a symbolic link. + +#### `dirent.name` + + +* {string|Buffer} + +The file name that this {fs.Dirent} object refers to. The type of this +value is determined by the `options.encoding` passed to [`fs.readdir()`][] or +[`fs.readdirSync()`][]. + +### Class: `fs.FSWatcher` + + +* Extends {EventEmitter} + +A successful call to [`fs.watch()`][] method will return a new {fs.FSWatcher} +object. + +All {fs.FSWatcher} objects emit a `'change'` event whenever a specific watched +file is modified. + +#### Event: `'change'` + + +* `eventType` {string} The type of change event that has occurred +* `filename` {string|Buffer} The filename that changed (if relevant/available) + +Emitted when something changes in a watched directory or file. +See more details in [`fs.watch()`][]. + +The `filename` argument may not be provided depending on operating system +support. If `filename` is provided, it will be provided as a {Buffer} if +`fs.watch()` is called with its `encoding` option set to `'buffer'`, otherwise +`filename` will be a UTF-8 string. + +```js esm +import { watch } from 'fs'; +// Example when handled through fs.watch() listener +watch('./tmp', { encoding: 'buffer' }, (eventType, filename) => { + if (filename) { + console.log(filename); + // Prints: + } +}); +``` + +#### Event: `'close'` + + +Emitted when the watcher stops watching for changes. The closed +{fs.FSWatcher} object is no longer usable in the event handler. + +#### Event: `'error'` + + +* `error` {Error} + +Emitted when an error occurs while watching the file. The errored +{fs.FSWatcher} object is no longer usable in the event handler. + +#### `watcher.close()` + + +Stop watching for changes on the given {fs.FSWatcher}. Once stopped, the +{fs.FSWatcher} object is no longer usable. + +#### `watcher.ref()` + + +* Returns: {fs.FSWatcher} + +When called, requests that the Node.js event loop *not* exit so long as the +{fs.FSWatcher} is active. Calling `watcher.ref()` multiple times will have +no effect. + +By default, all {fs.FSWatcher} objects are "ref'ed", making it normally +unnecessary to call `watcher.ref()` unless `watcher.unref()` had been +called previously. + +#### `watcher.unref()` + + +* Returns: {fs.FSWatcher} + +When called, the active {fs.FSWatcher} object will not require the Node.js +event loop to remain active. If there is no other activity keeping the +event loop running, the process may exit before the {fs.FSWatcher} object's +callback is invoked. Calling `watcher.unref()` multiple times will have +no effect. + +### Class: `fs.StatWatcher` + + +* Extends {EventEmitter} + +A successful call to `fs.watchFile()` method will return a new {fs.StatWatcher} +object. + +#### `watcher.ref()` + + +* Returns: {fs.StatWatcher} + +When called, requests that the Node.js event loop *not* exit so long as the +{fs.StatWatcher} is active. Calling `watcher.ref()` multiple times will have +no effect. + +By default, all {fs.StatWatcher} objects are "ref'ed", making it normally +unnecessary to call `watcher.ref()` unless `watcher.unref()` had been +called previously. + +#### `watcher.unref()` + + +* Returns: {fs.StatWatcher} + +When called, the active {fs.StatWatcher} object will not require the Node.js +event loop to remain active. If there is no other activity keeping the +event loop running, the process may exit before the {fs.StatWatcher} object's +callback is invoked. Calling `watcher.unref()` multiple times will have +no effect. + +### Class: `fs.ReadStream` + + +* Extends: {stream.Readable} + +Instances of {fs.ReadStream} are created and returned using the +[`fs.createReadStream()`][] function. + +#### Event: `'close'` + + +Emitted when the {fs.ReadStream}'s underlying file descriptor has been closed. + +#### Event: `'open'` + + +* `fd` {integer} Integer file descriptor used by the {fs.ReadStream}. + +Emitted when the {fs.ReadStream}'s file descriptor has been opened. + +#### Event: `'ready'` + + +Emitted when the {fs.ReadStream} is ready to be used. + +Fires immediately after `'open'`. + +#### `readStream.bytesRead` + + +* {number} + +The number of bytes that have been read so far. + +#### `readStream.path` + + +* {string|Buffer} + +The path to the file the stream is reading from as specified in the first +argument to `fs.createReadStream()`. If `path` is passed as a string, then +`readStream.path` will be a string. If `path` is passed as a {Buffer}, then +`readStream.path` will be a {Buffer}. + +#### `readStream.pending` + + +* {boolean} + +This property is `true` if the underlying file has not been opened yet, +i.e. before the `'ready'` event is emitted. + +### Class: `fs.Stats` + + +A {fs.Stats} object provides information about a file. + +Objects returned from [`fs.stat()`][], [`fs.lstat()`][] and [`fs.fstat()`][] and +their synchronous counterparts are of this type. +If `bigint` in the `options` passed to those methods is true, the numeric values +will be `bigint` instead of `number`, and the object will contain additional +nanosecond-precision properties suffixed with `Ns`. + +```console +Stats { + dev: 2114, + ino: 48064969, + mode: 33188, + nlink: 1, + uid: 85, + gid: 100, + rdev: 0, + size: 527, + blksize: 4096, + blocks: 8, + atimeMs: 1318289051000.1, + mtimeMs: 1318289051000.1, + ctimeMs: 1318289051000.1, + birthtimeMs: 1318289051000.1, + atime: Mon, 10 Oct 2011 23:24:11 GMT, + mtime: Mon, 10 Oct 2011 23:24:11 GMT, + ctime: Mon, 10 Oct 2011 23:24:11 GMT, + birthtime: Mon, 10 Oct 2011 23:24:11 GMT } +``` + +`bigint` version: + +```console +BigIntStats { + dev: 2114n, + ino: 48064969n, + mode: 33188n, + nlink: 1n, + uid: 85n, + gid: 100n, + rdev: 0n, + size: 527n, + blksize: 4096n, + blocks: 8n, + atimeMs: 1318289051000n, + mtimeMs: 1318289051000n, + ctimeMs: 1318289051000n, + birthtimeMs: 1318289051000n, + atimeNs: 1318289051000000000n, + mtimeNs: 1318289051000000000n, + ctimeNs: 1318289051000000000n, + birthtimeNs: 1318289051000000000n, + atime: Mon, 10 Oct 2011 23:24:11 GMT, + mtime: Mon, 10 Oct 2011 23:24:11 GMT, + ctime: Mon, 10 Oct 2011 23:24:11 GMT, + birthtime: Mon, 10 Oct 2011 23:24:11 GMT } +``` -### `fsPromises.chmod(path, mode)` +#### `stats.isBlockDevice()` -* `path` {string|Buffer|URL} -* `mode` {string|integer} -* Returns: {Promise} +* Returns: {boolean} -Changes the permissions of a file then fulfills the `Promise` with no -arguments upon succces. +Returns `true` if the {fs.Stats} object describes a block device. -### `fsPromises.chown(path, uid, gid)` +#### `stats.isCharacterDevice()` -* `path` {string|Buffer|URL} -* `uid` {integer} -* `gid` {integer} -* Returns: {Promise} +* Returns: {boolean} -Changes the ownership of a file then fulfills the `Promise` with no arguments -upon success. +Returns `true` if the {fs.Stats} object describes a character device. -### `fsPromises.copyFile(src, dest[, mode])` +#### `stats.isDirectory()` -* `src` {string|Buffer|URL} source filename to copy -* `dest` {string|Buffer|URL} destination filename of the copy operation -* `mode` {integer} modifiers for copy operation. **Default:** `0`. -* Returns: {Promise} - -Asynchronously copies `src` to `dest`. By default, `dest` is overwritten if it -already exists. The `Promise` will be fulfilled with no arguments upon success. - -Node.js makes no guarantees about the atomicity of the copy operation. If an -error occurs after the destination file has been opened for writing, Node.js -will attempt to remove the destination. - -`mode` is an optional integer that specifies the behavior -of the copy operation. It is possible to create a mask consisting of the bitwise -OR of two or more values (e.g. -`fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE`). - -* `fs.constants.COPYFILE_EXCL`: The copy operation will fail if `dest` already - exists. -* `fs.constants.COPYFILE_FICLONE`: The copy operation will attempt to create a - copy-on-write reflink. If the platform does not support copy-on-write, then a - fallback copy mechanism is used. -* `fs.constants.COPYFILE_FICLONE_FORCE`: The copy operation will attempt to - create a copy-on-write reflink. If the platform does not support - copy-on-write, then the operation will fail. - -```js -const { - promises: fsPromises, - constants: { - COPYFILE_EXCL - } -} = require('fs'); +* Returns: {boolean} -// destination.txt will be created or overwritten by default. -fsPromises.copyFile('source.txt', 'destination.txt') - .then(() => console.log('source.txt was copied to destination.txt')) - .catch(() => console.log('The file could not be copied')); +Returns `true` if the {fs.Stats} object describes a file system directory. -// By using COPYFILE_EXCL, the operation will fail if destination.txt exists. -fsPromises.copyFile('source.txt', 'destination.txt', COPYFILE_EXCL) - .then(() => console.log('source.txt was copied to destination.txt')) - .catch(() => console.log('The file could not be copied')); -``` +If the {fs.Stats} object was obtained from [`fs.lstat()`][], this method will +always return `false`. This is because [`fs.lstat()`][] returns information +about a symbolic link itself and not the path it resolves to. -### `fsPromises.lchmod(path, mode)` +#### `stats.isFIFO()` -* `path` {string|Buffer|URL} -* `mode` {integer} -* Returns: {Promise} +* Returns: {boolean} -Changes the permissions on a symbolic link then fulfills the `Promise` with -no arguments upon success. This method is only implemented on macOS. +Returns `true` if the {fs.Stats} object describes a first-in-first-out (FIFO) +pipe. -### `fsPromises.lchown(path, uid, gid)` +#### `stats.isFile()` -* `path` {string|Buffer|URL} -* `uid` {integer} -* `gid` {integer} -* Returns: {Promise} +* Returns: {boolean} -Changes the ownership on a symbolic link then fulfills the `Promise` with -no arguments upon success. +Returns `true` if the {fs.Stats} object describes a regular file. -### `fsPromises.lutimes(path, atime, mtime)` +#### `stats.isSocket()` -* `path` {string|Buffer|URL} -* `atime` {number|string|Date} -* `mtime` {number|string|Date} -* Returns: {Promise} - -Changes the access and modification times of a file in the same way as -[`fsPromises.utimes()`][], with the difference that if the path refers to a -symbolic link, then the link is not dereferenced: instead, the timestamps of -the symbolic link itself are changed. +* Returns: {boolean} -Upon success, the `Promise` is fulfilled without arguments. +Returns `true` if the {fs.Stats} object describes a socket. -### `fsPromises.link(existingPath, newPath)` +#### `stats.isSymbolicLink()` -* `existingPath` {string|Buffer|URL} -* `newPath` {string|Buffer|URL} -* Returns: {Promise} - -Asynchronous link(2). The `Promise` is fulfilled with no arguments upon success. - -### `fsPromises.lstat(path[, options])` - +* Returns: {boolean} -* `path` {string|Buffer|URL} -* `options` {Object} - * `bigint` {boolean} Whether the numeric values in the returned - [`fs.Stats`][] object should be `bigint`. **Default:** `false`. -* Returns: {Promise} +Returns `true` if the {fs.Stats} object describes a symbolic link. -Asynchronous lstat(2). The `Promise` is fulfilled with the [`fs.Stats`][] -object for the given symbolic link `path`. +This method is only valid when using [`fs.lstat()`][]. -### `fsPromises.mkdir(path[, options])` - +#### `stats.dev` -* `path` {string|Buffer|URL} -* `options` {Object|integer} - * `recursive` {boolean} **Default:** `false` - * `mode` {string|integer} Not supported on Windows. **Default:** `0o777`. -* Returns: {Promise} +* {number|bigint} -Asynchronously creates a directory then fulfills the `Promise` with either no -arguments, or the first directory path created if `recursive` is `true`. +The numeric identifier of the device containing the file. -The optional `options` argument can be an integer specifying `mode` (permission -and sticky bits), or an object with a `mode` property and a `recursive` -property indicating whether parent directories should be created. Calling -`fsPromises.mkdir()` when `path` is a directory that exists results in a -rejection only when `recursive` is false. +#### `stats.ino` -### `fsPromises.mkdtemp(prefix[, options])` - +* {number|bigint} -* `prefix` {string} -* `options` {string|Object} - * `encoding` {string} **Default:** `'utf8'` -* Returns: {Promise} +The file system specific "Inode" number for the file. -Creates a unique temporary directory and fulfills the `Promise` with the -created directory path. A unique directory name is generated by appending six -random characters to the end of the provided `prefix`. Due to platform -inconsistencies, avoid trailing `X` characters in `prefix`. Some platforms, -notably the BSDs, can return more than six random characters, and replace -trailing `X` characters in `prefix` with random characters. +#### `stats.mode` -The optional `options` argument can be a string specifying an encoding, or an -object with an `encoding` property specifying the character encoding to use. +* {number|bigint} -```js -fsPromises.mkdtemp(path.join(os.tmpdir(), 'foo-')) - .catch(console.error); -``` +A bit-field describing the file type and mode. -The `fsPromises.mkdtemp()` method will append the six randomly selected -characters directly to the `prefix` string. For instance, given a directory -`/tmp`, if the intention is to create a temporary directory *within* `/tmp`, the -`prefix` must end with a trailing platform-specific path separator -(`require('path').sep`). +#### `stats.nlink` -### `fsPromises.open(path, flags[, mode])` - +* {number|bigint} -* `path` {string|Buffer|URL} -* `flags` {string|number} See [support of file system `flags`][]. - **Default:** `'r'`. -* `mode` {string|integer} **Default:** `0o666` (readable and writable) -* Returns: {Promise} +The number of hard-links that exist for the file. -Asynchronous file open that returns a `Promise` that, when fulfilled, yields a -`FileHandle` object. See open(2). +#### `stats.uid` -`mode` sets the file mode (permission and sticky bits), but only if the file was -created. +* {number|bigint} -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]. +The numeric user identifier of the user that owns the file (POSIX). -### `fsPromises.opendir(path[, options])` - +#### `stats.gid` -* `path` {string|Buffer|URL} -* `options` {Object} - * `encoding` {string|null} **Default:** `'utf8'` - * `bufferSize` {number} Number of directory entries that are buffered - internally when reading from the directory. Higher values lead to better - performance but higher memory usage. **Default:** `32` -* Returns: {Promise} containing {fs.Dir} +* {number|bigint} -Asynchronously open a directory. See opendir(3). +The numeric group identifier of the group that owns the file (POSIX). -Creates an [`fs.Dir`][], which contains all further functions for reading from -and cleaning up the directory. +#### `stats.rdev` -The `encoding` option sets the encoding for the `path` while opening the -directory and subsequent read operations. +* {number|bigint} -Example using async iteration: +A numeric device identifier if the file represents a device. -```js -const fs = require('fs'); +#### `stats.size` -async function print(path) { - const dir = await fs.promises.opendir(path); - for await (const dirent of dir) { - console.log(dirent.name); - } -} -print('./').catch(console.error); -``` +* {number|bigint} -### `fsPromises.readdir(path[, options])` - +The size of the file in bytes. -* `path` {string|Buffer|URL} -* `options` {string|Object} - * `encoding` {string} **Default:** `'utf8'` - * `withFileTypes` {boolean} **Default:** `false` -* Returns: {Promise} +#### `stats.blksize` -Reads the contents of a directory then fulfills the `Promise` with an array -of the names of the files in the directory excluding `'.'` and `'..'`. +* {number|bigint} -The optional `options` argument can be a string specifying an encoding, or an -object with an `encoding` property specifying the character encoding to use for -the filenames. If the `encoding` is set to `'buffer'`, the filenames returned -will be passed as `Buffer` objects. +The file system block size for i/o operations. -If `options.withFileTypes` is set to `true`, the array will contain -[`fs.Dirent`][] objects. +#### `stats.blocks` -```js -const fs = require('fs'); +* {number|bigint} -async function print(path) { - const files = await fs.promises.readdir(path); - for (const file of files) { - console.log(file); - } -} -print('./').catch(console.error); -``` +The number of blocks allocated for this file. -### `fsPromises.readFile(path[, options])` +#### `stats.atimeMs` -* `path` {string|Buffer|URL|FileHandle} filename or `FileHandle` -* `options` {Object|string} - * `encoding` {string|null} **Default:** `null` - * `flag` {string} See [support of file system `flags`][]. **Default:** `'r'`. - * `signal` {AbortSignal} allows aborting an in-progress readFile -* Returns: {Promise} - -Asynchronously reads the entire contents of a file. +* {number|bigint} -The `Promise` is fulfilled with the contents of the file. If no encoding is -specified (using `options.encoding`), the data is returned as a `Buffer` -object. Otherwise, the data will be a string. +The timestamp indicating the last time this file was accessed expressed in +milliseconds since the POSIX Epoch. -If `options` is a string, then it specifies the encoding. +#### `stats.mtimeMs` + -When the `path` is a directory, the behavior of `fsPromises.readFile()` is -platform-specific. On macOS, Linux, and Windows, the promise will be rejected -with an error. On FreeBSD, a representation of the directory's contents will be -returned. +* {number|bigint} -It is possible to abort an ongoing `readFile` using an `AbortSignal`. If a -request is aborted the promise returned is rejected with an `AbortError`: +The timestamp indicating the last time this file was modified expressed in +milliseconds since the POSIX Epoch. -```js -const controller = new AbortController(); -const signal = controller.signal; -readFile(fileName, { signal }).then((file) => { /* ... */ }); -// Abort the request -controller.abort(); -``` +#### `stats.ctimeMs` + -Aborting an ongoing request does not abort individual operating -system requests but rather the internal buffering `fs.readFile` performs. +* {number|bigint} -Any specified `FileHandle` has to support reading. +The timestamp indicating the last time the file status was changed expressed +in milliseconds since the POSIX Epoch. -### `fsPromises.readlink(path[, options])` +#### `stats.birthtimeMs` -* `path` {string|Buffer|URL} -* `options` {string|Object} - * `encoding` {string} **Default:** `'utf8'` -* Returns: {Promise} - -Asynchronous readlink(2). The `Promise` is fulfilled with the `linkString` upon -success. +* {number|bigint} -The optional `options` argument can be a string specifying an encoding, or an -object with an `encoding` property specifying the character encoding to use for -the link path returned. If the `encoding` is set to `'buffer'`, the link path -returned will be passed as a `Buffer` object. +The timestamp indicating the creation time of this file expressed in +milliseconds since the POSIX Epoch. -### `fsPromises.realpath(path[, options])` +#### `stats.atimeNs` -* `path` {string|Buffer|URL} -* `options` {string|Object} - * `encoding` {string} **Default:** `'utf8'` -* Returns: {Promise} +* {bigint} -Determines the actual location of `path` using the same semantics as the -`fs.realpath.native()` function then fulfills the `Promise` with the resolved -path. +Only present when `bigint: true` is passed into the method that generates +the object. +The timestamp indicating the last time this file was accessed expressed in +nanoseconds since the POSIX Epoch. -Only paths that can be converted to UTF8 strings are supported. +#### `stats.mtimeNs` + -The optional `options` argument can be a string specifying an encoding, or an -object with an `encoding` property specifying the character encoding to use for -the path. If the `encoding` is set to `'buffer'`, the path returned will be -passed as a `Buffer` object. +* {bigint} -On Linux, when Node.js is linked against musl libc, the procfs file system must -be mounted on `/proc` in order for this function to work. Glibc does not have -this restriction. +Only present when `bigint: true` is passed into the method that generates +the object. +The timestamp indicating the last time this file was modified expressed in +nanoseconds since the POSIX Epoch. -### `fsPromises.rename(oldPath, newPath)` +#### `stats.ctimeNs` -* `oldPath` {string|Buffer|URL} -* `newPath` {string|Buffer|URL} -* Returns: {Promise} +* {bigint} -Renames `oldPath` to `newPath` and fulfills the `Promise` with no arguments -upon success. +Only present when `bigint: true` is passed into the method that generates +the object. +The timestamp indicating the last time the file status was changed expressed +in nanoseconds since the POSIX Epoch. -### `fsPromises.rmdir(path[, options])` +#### `stats.birthtimeNs` -* `path` {string|Buffer|URL} -* `options` {Object} - * `maxRetries` {integer} If an `EBUSY`, `EMFILE`, `ENFILE`, `ENOTEMPTY`, or - `EPERM` error is encountered, Node.js retries the operation with a linear - backoff wait of `retryDelay` milliseconds longer on each try. This option - represents the number of retries. This option is ignored if the `recursive` - option is not `true`. **Default:** `0`. - * `recursive` {boolean} If `true`, perform a recursive directory removal. In - recursive mode, errors are not reported if `path` does not exist, and - operations are retried on failure. **Default:** `false`. - * `retryDelay` {integer} The amount of time in milliseconds to wait between - retries. This option is ignored if the `recursive` option is not `true`. - **Default:** `100`. -* Returns: {Promise} +* {bigint} -Removes the directory identified by `path` then fulfills the `Promise` with -no arguments upon success. +Only present when `bigint: true` is passed into the method that generates +the object. +The timestamp indicating the creation time of this file expressed in +nanoseconds since the POSIX Epoch. -Using `fsPromises.rmdir()` on a file (not a directory) results in the -`Promise` being rejected with an `ENOENT` error on Windows and an `ENOTDIR` -error on POSIX. +#### `stats.atime` + -Setting `recursive` to `true` results in behavior similar to the Unix command -`rm -rf`: an error will not be raised for paths that do not exist, and paths -that represent files will be deleted. The permissive behavior of the -`recursive` option is deprecated, `ENOTDIR` and `ENOENT` will be thrown in -the future. +* {Date} -### `fsPromises.rm(path[, options])` +The timestamp indicating the last time this file was accessed. + +#### `stats.mtime` -* `path` {string|Buffer|URL} -* `options` {Object} - * `force` {boolean} When `true`, exceptions will be ignored if `path` does - not exist. **Default:** `false`. - * `maxRetries` {integer} If an `EBUSY`, `EMFILE`, `ENFILE`, `ENOTEMPTY`, or - `EPERM` error is encountered, Node.js will retry the operation with a linear - backoff wait of `retryDelay` milliseconds longer on each try. This option - represents the number of retries. This option is ignored if the `recursive` - option is not `true`. **Default:** `0`. - * `recursive` {boolean} If `true`, perform a recursive directory removal. In - recursive mode operations are retried on failure. **Default:** `false`. - * `retryDelay` {integer} The amount of time in milliseconds to wait between - retries. This option is ignored if the `recursive` option is not `true`. - **Default:** `100`. +* {Date} -Removes files and directories (modeled on the standard POSIX `rm` utility). -Fulfills the `Promise` with no arguments on success. +The timestamp indicating the last time this file was modified. -### `fsPromises.stat(path[, options])` +#### `stats.ctime` -* `path` {string|Buffer|URL} -* `options` {Object} - * `bigint` {boolean} Whether the numeric values in the returned - [`fs.Stats`][] object should be `bigint`. **Default:** `false`. -* Returns: {Promise} +* {Date} -The `Promise` is fulfilled with the [`fs.Stats`][] object for the given `path`. +The timestamp indicating the last time the file status was changed. -### `fsPromises.symlink(target, path[, type])` +#### `stats.birthtime` -* `target` {string|Buffer|URL} -* `path` {string|Buffer|URL} -* `type` {string} **Default:** `'file'` -* Returns: {Promise} +* {Date} -Creates a symbolic link then fulfills the `Promise` with no arguments upon -success. +The timestamp indicating the creation time of this file. -The `type` argument is only used on Windows platforms and can be one of `'dir'`, -`'file'`, or `'junction'`. Windows junction points require the destination path -to be absolute. When using `'junction'`, the `target` argument will -automatically be normalized to absolute path. +#### Stat time values -### `fsPromises.truncate(path[, len])` - +The `atimeMs`, `mtimeMs`, `ctimeMs`, `birthtimeMs` properties are +numeric values that hold the corresponding times in milliseconds. Their +precision is platform specific. When `bigint: true` is passed into the +method that generates the object, the properties will be [bigints][], +otherwise they will be [numbers][MDN-Number]. -* `path` {string|Buffer|URL} -* `len` {integer} **Default:** `0` -* Returns: {Promise} +The `atimeNs`, `mtimeNs`, `ctimeNs`, `birthtimeNs` properties are +[bigints][] that hold the corresponding times in nanoseconds. They are +only present when `bigint: true` is passed into the method that generates +the object. Their precision is platform specific. -Truncates the `path` then fulfills the `Promise` with no arguments upon -success. The `path` *must* be a string or `Buffer`. +`atime`, `mtime`, `ctime`, and `birthtime` are +[`Date`][MDN-Date] object alternate representations of the various times. The +`Date` and number values are not connected. Assigning a new number value, or +mutating the `Date` value, will not be reflected in the corresponding alternate +representation. -### `fsPromises.unlink(path)` - +The times in the stat object have the following semantics: -* `path` {string|Buffer|URL} -* Returns: {Promise} +* `atime` "Access Time": Time when file data last accessed. Changed + by the mknod(2), utimes(2), and read(2) system calls. +* `mtime` "Modified Time": Time when file data last modified. + Changed by the mknod(2), utimes(2), and write(2) system calls. +* `ctime` "Change Time": Time when file status was last changed + (inode data modification). Changed by the chmod(2), chown(2), + link(2), mknod(2), rename(2), unlink(2), utimes(2), + read(2), and write(2) system calls. +* `birthtime` "Birth Time": Time of file creation. Set once when the + file is created. On filesystems where birthtime is not available, + this field may instead hold either the `ctime` or + `1970-01-01T00:00Z` (ie, Unix epoch timestamp `0`). This value may be greater + than `atime` or `mtime` in this case. On Darwin and other FreeBSD variants, + also set if the `atime` is explicitly set to an earlier value than the current + `birthtime` using the utimes(2) system call. -Asynchronous unlink(2). The `Promise` is fulfilled with no arguments upon -success. +Prior to Node.js 0.12, the `ctime` held the `birthtime` on Windows systems. As +of 0.12, `ctime` is not "creation time", and on Unix systems, it never was. -### `fsPromises.utimes(path, atime, mtime)` +### Class: `fs.WriteStream` -* `path` {string|Buffer|URL} -* `atime` {number|string|Date} -* `mtime` {number|string|Date} -* Returns: {Promise} +* Extends {stream.Writable} -Change the file system timestamps of the object referenced by `path` then -fulfills the `Promise` with no arguments upon success. +Instances of {fs.WriteStream} are created and returned using the +[`fs.createWriteStream()`][] function. -The `atime` and `mtime` arguments follow these rules: +#### Event: `'close'` + -* Values can be either numbers representing Unix epoch time, `Date`s, or a - numeric string like `'123456789.0'`. -* If the value can not be converted to a number, or is `NaN`, `Infinity` or - `-Infinity`, an `Error` will be thrown. +Emitted when the {fs.WriteStream}'s underlying file descriptor has been closed. -### `fsPromises.writeFile(file, data[, options])` +#### Event: `'open'` -* `file` {string|Buffer|URL|FileHandle} filename or `FileHandle` -* `data` {string|Buffer|Uint8Array|Object} -* `options` {Object|string} - * `encoding` {string|null} **Default:** `'utf8'` - * `mode` {integer} **Default:** `0o666` - * `flag` {string} See [support of file system `flags`][]. **Default:** `'w'`. - * `signal` {AbortSignal} allows aborting an in-progress writeFile -* Returns: {Promise} +* `fd` {integer} Integer file descriptor used by the {fs.WriteStream}. -Asynchronously writes data to a file, replacing the file if it already exists. -`data` can be a string, a buffer, or an object with an own `toString` function -property. The `Promise` is fulfilled with no arguments upon success. +Emitted when the {fs.WriteStream}'s file is opened. -The `encoding` option is ignored if `data` is a buffer. +#### Event: `'ready'` + -If `options` is a string, then it specifies the encoding. +Emitted when the {fs.WriteStream} is ready to be used. -Any specified `FileHandle` has to support writing. +Fires immediately after `'open'`. -It is unsafe to use `fsPromises.writeFile()` multiple times on the same file -without waiting for the `Promise` to be fulfilled (or rejected). +#### `writeStream.bytesWritten` + -Similarly to `fsPromises.readFile` - `fsPromises.writeFile` is a convenience -method that performs multiple `write` calls internally to write the buffer -passed to it. For performance sensitive code consider using -[`fs.createWriteStream()`][]. +The number of bytes written so far. Does not include data that is still queued +for writing. -It is possible to use an {AbortSignal} to cancel an `fsPromises.writeFile()`. -Cancelation is "best effort", and some amount of data is likely still -to be written. +#### `writeStream.path` + -```js -const controller = new AbortController(); -const { signal } = controller; -const data = new Uint8Array(Buffer.from('Hello Node.js')); -(async () => { - try { - await fs.writeFile('message.txt', data, { signal }); - } catch (err) { - // When a request is aborted - err is an AbortError - } -})(); -// When the request should be aborted -controller.abort(); -``` +The path to the file the stream is writing to as specified in the first +argument to [`fs.createWriteStream()`][]. If `path` is passed as a string, then +`writeStream.path` will be a string. If `path` is passed as a {Buffer}, then +`writeStream.path` will be a {Buffer}. -Aborting an ongoing request does not abort individual operating -system requests but rather the internal buffering `fs.writeFile` performs. +#### `writeStream.pending` + + +* {boolean} + +This property is `true` if the underlying file has not been opened yet, +i.e. before the `'ready'` event is emitted. -## FS constants +### `fs.constants` + +* {Object} + +Returns an object containing commonly used constants for file system +operations. + +#### FS constants The following constants are exported by `fs.constants`. @@ -5899,21 +5872,21 @@ To use more than one constant, use the bitwise OR `|` operator. Example: -```js -const fs = require('fs'); +```js esm +import { open, constants } from 'fs'; const { O_RDWR, O_CREAT, O_EXCL -} = fs.constants; +} = constants; -fs.open('/path/to/my/file', O_RDWR | O_CREAT | O_EXCL, (err, fd) => { +open('/path/to/my/file', O_RDWR | O_CREAT | O_EXCL, (err, fd) => { // ... }); ``` -### File access constants +##### File access constants The following constants are meant for use with [`fs.access()`][]. @@ -5945,7 +5918,7 @@ The following constants are meant for use with [`fs.access()`][]. -### File copy constants +##### File copy constants The following constants are meant for use with [`fs.copyFile()`][]. @@ -5973,7 +5946,7 @@ The following constants are meant for use with [`fs.copyFile()`][]. -### File open constants +##### File open constants The following constants are meant for use with `fs.open()`. @@ -6067,9 +6040,9 @@ The following constants are meant for use with `fs.open()`. -### File type constants +##### File type constants -The following constants are meant for use with the [`fs.Stats`][] object's +The following constants are meant for use with the {fs.Stats} object's `mode` property for determining a file's type. @@ -6111,9 +6084,9 @@ The following constants are meant for use with the [`fs.Stats`][] object's
-### File mode constants +##### File mode constants -The following constants are meant for use with the [`fs.Stats`][] object's +The following constants are meant for use with the {fs.Stats} object's `mode` property for determining the access permissions for a file. @@ -6171,7 +6144,323 @@ The following constants are meant for use with the [`fs.Stats`][] object's
-## File system flags +## Notes + +### Ordering of callback and promise-based operations + +Because they are executed asynchronously by the underlying thread pool, +there is no guaranteed ordering when using either the callback or +promise-based methods. + +For example, the following is prone to error because the `fs.stat()` +operation might complete before the `fs.rename()` operation: + +```js +fs.rename('/tmp/hello', '/tmp/world', (err) => { + if (err) throw err; + console.log('renamed complete'); +}); +fs.stat('/tmp/world', (err, stats) => { + if (err) throw err; + console.log(`stats: ${JSON.stringify(stats)}`); +}); +``` + +It is important to correctly order the operations by awaiting the results +of one before invoking the other: + +```js esm +// Using ESM syntax +import { rename, stat } from 'fs/promises'; + +const from = '/tmp/hello'; +const to = '/tmp/world'; + +try { + await rename(from, to); + const stats = await stat(to); + console.log(`stats: ${JSON.stringify(stats)}`); +} catch (error) { + console.error('there was an error:', error.message); +} +``` + +```js cjs +// Using CommonJS syntax +const { rename, stat } = require('fs/promises'); + +(async function(from, to) { + try { + await rename(from, to); + const stats = await stat(to); + console.log(`stats: ${JSON.stringify(stats)}`); + } catch (error) { + console.error('there was an error:', error.message); + } +})('/tmp/hello', '/tmp/world'); +``` + +Or, when using the callback APIs, move the `fs.stat()` call into the callback +of the `fs.rename()` operation: + +```js esm +import { rename, stat } from 'fs'; + +rename('/tmp/hello', '/tmp/world', (err) => { + if (err) throw err; + stat('/tmp/world', (err, stats) => { + if (err) throw err; + console.log(`stats: ${JSON.stringify(stats)}`); + }); +}); +``` + +```js cjs +const { rename, stat } = require('fs/promises'); + +rename('/tmp/hello', '/tmp/world', (err) => { + if (err) throw err; + stat('/tmp/world', (err, stats) => { + if (err) throw err; + console.log(`stats: ${JSON.stringify(stats)}`); + }); +}); +``` + +### File paths + +Most `fs` operations accept file paths that may be specified in the form of +a string, a {Buffer}, or a {URL} object using the `file:` protocol. + +#### String paths + +String form paths are interpreted as UTF-8 character sequences identifying +the absolute or relative filename. Relative paths will be resolved relative +to the current working directory as determined by calling `process.cwd()`. + +Example using an absolute path on POSIX: + +```js esm +import { open } from 'fs/promises'; + +let fd; +try { + fd = await open('/open/some/file.txt', 'r'); + // Do something with the file +} finally { + await fd.close(); +} +``` + +Example using a relative path on POSIX (relative to `process.cwd()`): + +```js esm +import { open } from 'fs/promises'; + +let fd; +try { + fd = await open('file.txt', 'r'); + // Do something with the file +} finally { + await fd.close(); +} +``` + +#### File URL paths + +For most `fs` module functions, the `path` or `filename` argument may be passed +as a {URL} object using the `file:` protocol. + +```js esm +import { readFileSync } from 'fs'; + +readFileSync(new URL('file:///tmp/hello')); +``` + +`file:` URLs are always absolute paths. + +##### Platform-specific considerations + +On Windows, `file:` {URL}s with a host name convert to UNC paths, while `file:` +{URL}s with drive letters convert to local absolute paths. `file:` {URL}s +without a host name nor a drive letter will result in an error: + +```js esm +import { readFileSync } from 'fs'; +// On Windows : + +// - WHATWG file URLs with hostname convert to UNC path +// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file +readFileSync(new URL('file://hostname/p/a/t/h/file')); + +// - WHATWG file URLs with drive letters convert to absolute path +// file:///C:/tmp/hello => C:\tmp\hello +readFileSync(new URL('file:///C:/tmp/hello')); + +// - WHATWG file URLs without hostname must have a drive letters +readFileSync(new URL('file:///notdriveletter/p/a/t/h/file')); +readFileSync(new URL('file:///c/p/a/t/h/file')); +// TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must be absolute +``` + +`file:` {URL}s with drive letters must use `:` as a separator just after +the drive letter. Using another separator will result in an error. + +On all other platforms, `file:` {URL}s with a host name are unsupported and +will result in an error: + +```js esm +import { readFileSync } from 'fs'; +// On other platforms: + +// - WHATWG file URLs with hostname are unsupported +// file://hostname/p/a/t/h/file => throw! +readFileSync(new URL('file://hostname/p/a/t/h/file')); +// TypeError [ERR_INVALID_FILE_URL_PATH]: must be absolute + +// - WHATWG file URLs convert to absolute path +// file:///tmp/hello => /tmp/hello +readFileSync(new URL('file:///tmp/hello')); +``` + +A `file:` {URL} having encoded slash characters will result in an error on all +platforms: + +```js esm +import { readFileSync } from 'fs'; + +// On Windows +readFileSync(new URL('file:///C:/p/a/t/h/%2F')); +readFileSync(new URL('file:///C:/p/a/t/h/%2f')); +/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded +\ or / characters */ + +// On POSIX +readFileSync(new URL('file:///p/a/t/h/%2F')); +readFileSync(new URL('file:///p/a/t/h/%2f')); +/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded +/ characters */ +``` + +On Windows, `file:` {URL}s having encoded backslash will result in an error: + +```js esm +import { readFileSync } from 'fs'; + +// On Windows +readFileSync(new URL('file:///C:/path/%5C')); +readFileSync(new URL('file:///C:/path/%5c')); +/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded +\ or / characters */ +``` + +#### Buffer paths + +Paths specified using a {Buffer} are useful primarily on certain POSIX +operating systems that treat file paths as opaque byte sequences. On such +systems, it is possible for a single file path to contain sub-sequences that +use multiple character encodings. As with string paths, {Buffer} paths may +be relative or absolute: + +Example using an absolute path on POSIX: + +```js esm +import { open } from 'fs/promises'; + +let fd; +try { + fd = await open(Buffer.from('/open/some/file.txt'), 'r'); + // Do something with the file +} finally { + await fd.close(); +} +``` + +#### Per-drive working directories on Windows + +On Windows, Node.js follows the concept of per-drive working directory. This +behavior can be observed when using a drive path without a backslash. For +example `fs.readdirSync('C:\\')` can potentially return a different result than +`fs.readdirSync('C:')`. For more information, see +[this MSDN page][MSDN-Rel-Path]. + +### File descriptors + +On POSIX systems, for every process, the kernel maintains a table of currently +open files and resources. Each open file is assigned a simple numeric +identifier called a *file descriptor*. At the system-level, all file system +operations use these file descriptors to identify and track each specific +file. Windows systems use a different but conceptually similar mechanism for +tracking resources. To simplify things for users, Node.js abstracts away the +differences between operating systems and assigns all open files a numeric file +descriptor. + +The callback-based `fs.open()`, and synchronous `fs.openSync()` methods open a +file and allocate a new file descriptor. Once allocated, the file descriptor may +be used to read data from, write data to, or request information about the file. + +Operating systems limit the number of file descriptors that may be open +at any given time so it is critical to close the descriptor when operations +are completed. Failure to do so will result in a memory leak that will +eventually cause an application to crash. + +```js esm +import { open, close, fstat } from 'fs'; + +function closeFd(fd) { + close(fd, (err) => { + if (err) throw err; + }); +} + +open('/open/some/file.txt', 'r', (err, fd) => { + if (err) throw err; + try { + fstat(fd, (err, stat) => { + if (err) { + closeFd(fd); + throw err; + } + + // use stat + + closeFd(fd); + }); + } catch (err) { + closeFd(fd); + throw err; + } +}); +``` + +The promise-based APIs use a {FileHandle} object in place of the numeric +file descriptor. These objects are better managed by the system to ensure +that resources are not leaked. However, it is still required that they are +closed when operations are completed: + +```js esm +import { open } from 'fs/promises'; + +let file; +try { + file = await open('/open/some/file.txt', 'r'); + const stat = await file.stat(); + // use stat +} finally { + await file.close(); +} +``` + +### Threadpool usage + +All callback and promise-based file system APIs ( with the exception of +`fs.FSWatcher()`) use libuv's threadpool. This can have surprising and negative +performance implications for some applications. See the +[`UV_THREADPOOL_SIZE`][] documentation for more information. + +### File system flags The following flags are available wherever the `flag` option takes a string. @@ -6263,7 +6552,6 @@ the file contents. [#25741]: https://github.com/nodejs/node/issues/25741 [Caveats]: #fs_caveats [Common System Errors]: errors.md#errors_common_system_errors -[FS constants]: #fs_fs_constants_1 [File access constants]: #fs_file_access_constants [MDN-Date]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date [MDN-Number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type @@ -6274,20 +6562,12 @@ the file contents. [Writable Stream]: stream.md#stream_class_stream_writable [`AHAFS`]: https://www.ibm.com/developerworks/aix/library/au-aix_event_infrastructure/ [`Buffer.byteLength`]: buffer.md#buffer_static_method_buffer_bytelength_string_encoding -[`Buffer`]: buffer.md#buffer_buffer [`FSEvents`]: https://developer.apple.com/documentation/coreservices/file_system_events [`Number.MAX_SAFE_INTEGER`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER [`ReadDirectoryChangesW`]: https://docs.microsoft.com/en-us/windows/desktop/api/winbase/nf-winbase-readdirectorychangesw -[`ReadStream`]: #fs_class_fs_readstream -[`URL`]: url.md#url_the_whatwg_url_api [`UV_THREADPOOL_SIZE`]: cli.md#cli_uv_threadpool_size_size -[`WriteStream`]: #fs_class_fs_writestream [`event ports`]: https://illumos.org/man/port_create [`filehandle.writeFile()`]: #fs_filehandle_writefile_data_options -[`fs.Dir`]: #fs_class_fs_dir -[`fs.Dirent`]: #fs_class_fs_dirent -[`fs.FSWatcher`]: #fs_class_fs_fswatcher -[`fs.Stats`]: #fs_class_fs_stats [`fs.access()`]: #fs_fs_access_path_mode_callback [`fs.chmod()`]: #fs_fs_chmod_path_mode_callback [`fs.chown()`]: #fs_fs_chown_path_uid_gid_callback @@ -6326,8 +6606,6 @@ the file contents. [`fsPromises.utimes()`]: #fs_fspromises_utimes_path_atime_mtime [`inotify(7)`]: https://man7.org/linux/man-pages/man7/inotify.7.html [`kqueue(2)`]: https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2 -[`net.Socket`]: net.md#net_class_net_socket -[`stat()`]: fs.md#fs_fs_stat_path_options_callback [`util.promisify()`]: util.md#util_util_promisify_original [bigints]: https://tc39.github.io/proposal-bigint [chcp]: https://ss64.com/nt/chcp.html