Skip to content
Tutorials Center
My learning

Topics

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.

NODE
import fs from "node:fs";

const fd = fs.openSync("data.bin", "w");
fs.writeSync(fd, "important");
fs.fsyncSync(fd);
fs.closeSync(fd);

Try it

Node.js Writing, syncing and closing

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.

Node.js The promise form on a FileHandle

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

NODE
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. close does not imply a flush, and the descriptor is gone once it returns.
  • Durable replace pattern: write a temporary file, fsync it, rename it over the target, then fsync the containing directory. Without the last step the rename itself may be lost. On Linux you can open a directory read-only with fs.openSync(dir, "r") and call fsyncSync on 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.
  • fsyncSync blocks 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 a FileHandle.
  • Not needed for reads. Calling it on a read-only descriptor is allowed on most systems but does nothing useful.