diff --git a/benchmark/fs/bench-stat-promise.js b/benchmark/fs/bench-stat-promise.js index 96c7058fa6218a..99a5da5799b787 100644 --- a/benchmark/fs/bench-stat-promise.js +++ b/benchmark/fs/bench-stat-promise.js @@ -9,12 +9,12 @@ const bench = common.createBenchmark(main, { }); async function run(n, statType) { - const arg = statType === 'fstat' ? - await fsPromises.open(__filename, 'r') : __filename; + const handleMode = statType === 'fstat'; + const arg = handleMode ? await fsPromises.open(__filename, 'r') : __filename; let remaining = n; bench.start(); while (remaining-- > 0) - await fsPromises[statType](arg); + await (handleMode ? arg.stat() : fsPromises[statType](arg)); bench.end(n); if (typeof arg.close === 'function') diff --git a/doc/api/fs.md b/doc/api/fs.md index af06bf91e5b5f5..bdd5c9758cc3e3 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -3800,128 +3800,6 @@ fsPromises.copyFile('source.txt', 'destination.txt', COPYFILE_EXCL) .catch(() => console.log('The file could not be copied')); ``` -### fsPromises.fchmod(filehandle, mode) - - -* `filehandle` {FileHandle} -* `mode` {integer} -* Returns: {Promise} - -Asynchronous fchmod(2). The `Promise` is resolved with no arguments upon -success. - -### fsPromises.fchown(filehandle, uid, gid) - - -* `filehandle` {FileHandle} -* `uid` {integer} -* `gid` {integer} -* Returns: {Promise} - -Changes the ownership of the file represented by `filehandle` then resolves -the `Promise` with no arguments upon success. - -### fsPromises.fdatasync(filehandle) - - -* `filehandle` {FileHandle} -* Returns: {Promise} - -Asynchronous fdatasync(2). The `Promise` is resolved with no arguments upon -success. - -### fsPromises.fstat(filehandle) - - -* `filehandle` {FileHandle} -* Returns: {Promise} - -Retrieves the [`fs.Stats`][] for the given `filehandle`. - -### fsPromises.fsync(filehandle) - - -* `filehandle` {FileHandle} -* Returns: {Promise} - -Asynchronous fsync(2). The `Promise` is resolved with no arguments upon -success. - -### fsPromises.ftruncate(filehandle[, len]) - - -* `filehandle` {FileHandle} -* `len` {integer} **Default:** `0` -* Returns: {Promise} - -Truncates the file represented by `filehandle` then resolves the `Promise` -with no arguments upon success. - -If the file referred to by the `FileHandle` was larger than `len` bytes, only -the first `len` bytes will be retained in the file. - -For example, the following program retains only the first four bytes of the -file: - -```js -console.log(fs.readFileSync('temp.txt', 'utf8')); -// Prints: Node.js - -async function doTruncate() { - const fd = await fsPromises.open('temp.txt', 'r+'); - await fsPromises.ftruncate(fd, 4); - console.log(fs.readFileSync('temp.txt', 'utf8')); // Prints: Node -} - -doTruncate().catch(console.error); -``` - -If the file previously was shorter than `len` bytes, it is extended, and the -extended part is filled with null bytes (`'\0'`). For example, - -```js -console.log(fs.readFileSync('temp.txt', 'utf8')); -// Prints: Node.js - -async function doTruncate() { - const fd = await fsPromises.open('temp.txt', 'r+'); - await fsPromises.ftruncate(fd, 10); - console.log(fs.readFileSync('temp.txt', 'utf8')); // Prints Node.js\0\0\0 -} - -doTruncate().catch(console.error); -``` - -The last three bytes are null bytes (`'\0'`), to compensate the over-truncation. - -### fsPromises.futimes(filehandle, atime, mtime) - - -* `filehandle` {FileHandle} -* `atime` {number|string|Date} -* `mtime` {number|string|Date} -* Returns: {Promise} - -Change the file system timestamps of the object referenced by the supplied -`FileHandle` then resolves the `Promise` with no arguments upon success. - -This function does not work on AIX versions before 7.1, it will resolve the -`Promise` with an error using code `UV_ENOSYS`. - ### fsPromises.lchmod(path, mode) - -* `filehandle` {FileHandle} -* `buffer` {Buffer|Uint8Array} -* `offset` {integer} -* `length` {integer} -* `position` {integer} -* Returns: {Promise} - -Read data from the file specified by `filehandle`. - -`buffer` is the buffer that the data 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. - -Following successful read, the `Promise` is resolved 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. - ### fsPromises.readdir(path[, options]) - -* `filehandle` {FileHandle} -* `buffer` {Buffer|Uint8Array} -* `offset` {integer} -* `length` {integer} -* `position` {integer} -* Returns: {Promise} - -Write `buffer` to the file specified by `filehandle`. - -The `Promise` is resolved with an object containing a `bytesWritten` property -identifying the number of bytes written, and a `buffer` property containing -a reference to the `buffer` written. - -`offset` determines the part of the buffer to be written, and `length` is -an integer specifying the number of bytes to write. - -`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). - -It is unsafe to use `fsPromises.write()` multiple times on the same file -without waiting for the `Promise` to be resolved (or rejected). For this -scenario, `fs.createWriteStream` is strongly recommended. - -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. - ### fsPromises.writeFile(file, data[, options])