Node.js Reference ยท fs and fs/promises
Node.js fs.fsync() and fdatasync() methods
Reference for fs.fsync() and fs.fdatasync() in Node.js: force a file's data onto storage, the callback, sync and promise forms, and durable write patterns.
fs.fsync(fd, callback) asks the operating system to push everything it has buffered for an open file down to the storage device. After it completes, the data (and the file's metadata) should survive a power cut. fs.fdatasync() does the same for the file contents, but it may skip metadata that is not needed to read the data back, such as the modification time. That can make it a little faster.
A normal write call only hands bytes to the operating system's cache. If the machine crashes a moment later, the bytes can be lost even though your program saw success. You need fsync only when losing a recent write would be a real problem: a database journal, a lock file, a config file that must never be half-written.
import fs from "node:fs"; const fd = fs.openSync("data.bin", "w"); fs.writeSync(fd, "important"); fs.fsyncSync(fd); fs.closeSync(fd);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
fs.fsync(fd, callback) fs.fsyncSync(fd): undefined fs.fdatasync(fd, callback) fs.fdatasyncSync(fd): undefined // fs/promises: methods of a FileHandle filehandle.sync(): Promise<undefined> filehandle.datasync(): Promise<undefined>
| Name | Description |
|---|---|
fd |
An integer file descriptor from fs.open() or fs.openSync(). |
callback |
Called as callback(err). |
Returns: undefined (the promise versions resolve with undefined).
Errors: EBADF if the descriptor is closed or invalid, EIO if the device reports a failure while flushing, and ERR_INVALID_ARG_TYPE if fd is not an integer. fs/promises has no top-level fsync(fd); use the FileHandle methods.
Usage notes
- Flush before you close, not after.
closedoes not imply a flush, and the descriptor is gone once it returns. - Durable replace pattern: write a temporary file,
fsyncit,renameit over the target, thenfsyncthe containing directory. Without the last step the rename itself may be lost. On Linux you can open a directory read-only withfs.openSync(dir, "r")and callfsyncSyncon it; Windows does not support this. - It is slow on purpose. A sync can take milliseconds on an SSD and far longer on a busy disk. Do not call it after every small write in a loop; batch writes and sync once.
fsyncSyncblocks the event loop for the whole wait. In a server, prefer the callback or promise form.- Hardware caches: the operating system and drive decide how honest a "flushed" answer is. Node cannot promise more than the platform does.
- Streams:
fs.createWriteStream()has no sync option. End the stream, then open the file and sync, or write through aFileHandle. - Not needed for reads. Calling it on a read-only descriptor is allowed on most systems but does nothing useful.