fsync(2)

💖 fsync(2) — the bestie cut 💖

okay so this is a page from the System Calls Manual, and today's main characters are fsync and fdatasync — they sync a file's in-core state with the storage device. no cap, that's the whole vibe. 🦋

---

🌸 NAME 🌸

fsync, fdatasync — synchronize a file's in-core state with storage device ✨

📚 LIBRARY 📚

Standard C library (libc, -lc) 💅

✨ SYNOPSIS ✨

#include <unistd.h>

int fsync(int fd);

int fdatasync(int fd);

🎀 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

fsync():

• glibc 2.16 and later: no feature test macros need be defined 💖
• glibc up to and including 2.15:

_BSD_SOURCE || _XOPEN_SOURCE
    || /* Since glibc 2.8: */ _POSIX_C_SOURCE >= 200112L

fdatasync():

_POSIX_C_SOURCE >= 199309L || _XOPEN_SOURCE >= 500

---

💜 DESCRIPTION 💜

okay bestie, listen. fsync() transfers — like, literally "flushes" — all the modified in-core data of the file referred to by the file descriptor fd (that's the modified buffer cache pages, for the record) to the disk device, or whatever other permanent storage device you've got going on, so that every single changed bit of information can be retrieved even if the system crashes or gets rebooted. 😭

And yes, this includes writing through or flushing a disk cache if there is one. the way that this call just blocks until the device reports the transfer has completed?? main character behavior, honestly. 👑

As well as flushing the file data, fsync() also flushes the metadata information associated with the file (peep inode(7)).

⚠️ heads up though — calling fsync() does not necessarily ensure that the entry in the directory containing the file has also reached disk. for that, you need an explicit fsync() on a file descriptor for the directory too. two separate calls, bestie, don't skip the second one. 💀

fdatasync() is similar to fsync(), but it does not flush modified metadata unless that metadata is needed in order to allow a subsequent data retrieval to be correctly handled. so like — changes to st_atime or st_mtime (that's time of last access and time of last modification, respectively; see inode(7)) don't require flushing, because they're not necessary for a subsequent data read to be handled correctly. 🍓

but on the other hand?? a change to the file size (st_size, as made by, say, ftruncate(2)) would require a metadata flush. so it's giving "it depends". 💅

The aim of fdatasync() is to reduce disk activity for applications that don't require all metadata to be synchronized with the disk. efficiency queen. ✨

---

🫶 RETURN VALUE 🫶

On success, these system calls return zero. 🎉

On error, -1 is returned, and errno is set to indicate the error. 🙈

💀 ERRORS 💀

• EBADF — fd is not a valid open file descriptor. not a vibe.
• EINTR — The function was interrupted by a signal; see signal(7). 😤
• EIO — An error occurred during synchronization. This error may relate to data written to some other file descriptor on the same file. Since Linux 4.13, errors from write-back will be reported to all file descriptors that might have written the data which triggered the error. Some filesystems (e.g., NFS) keep close track of which data came through which file descriptor, and give more precise reporting. Other filesystems (e.g., most local filesystems) will report errors to all file descriptors that were open on the file when the error was recorded. so it's giving "who did this" and sometimes the answer is "everyone". 💀
• ENOSPC — Disk space was exhausted while synchronizing.
• EROFS — (listed with no description attached, just vibes)
• EINVAL — fd is bound to a special file (e.g., a pipe, FIFO, or socket) which does not support synchronization.
• ENOSPC — (yeah it's listed again, and again with no description — we don't question the ancestors)
• EDQUOT — fd is bound to a file on NFS or another filesystem which does not allocate space at the time of a write(2) system call, and some previous write failed due to insufficient storage space.

---

🌈 VERSIONS 🌈

On POSIX systems on which fdatasync() is available, _POSIX_SYNCHRONIZED_IO is defined in <unistd.h> to a value greater than 0. (See also sysconf(3).) ⭐

⭐ STANDARDS ⭐

POSIX.1-2024. iconic, certified, ratified. 👑

📜 HISTORY 📜

fsync()

• 4.2BSD, SUSv1, POSIX.1-1996.

fdatasync()

• POSIX.1-1996.

In Linux 2.2 and earlier, fdatasync() is equivalent to fsync(), and so has no performance advantage. so if you're time-traveling, don't bother. 🕰️

The fsync() implementations in older kernels and lesser used filesystems do not know how to flush disk caches. In these cases disk caches need to be disabled using hdparm(8) or sdparm(8) to guarantee safe operation. ⚠️

Under AT&T UNIX System V Release 4 fd needs to be opened for writing. This is by itself incompatible with the original BSD interface and forbidden by POSIX, but nevertheless survives in HP-UX and AIX. the way that this is just still around?? heritage. 🙈

👑 SEE ALSO 👑

sync(1), bdflush(2), open(2), posix_fadvise(2), pwritev(2), sync(2), sync_file_range(2), fflush(3), fileno(3), hdparm(8), mount(8)

---

and that's the whole page, bestie!! 🌈💖✨ this one came from Linux man-pages 6.20, dated 2026-02-08 — screenshot it, cite it, tell your friends. now go flush something. 💅🦋🎀