FSYNC(2)

💾 FSYNC(2) — the system calls manual, bestie edition ✨

okay so picture this: you're in section 2 of the manual, the System Calls Manual zone, and we're talking about two little functions that are lowkey the reason your files don't just evaporate. they're fdatasync and fsync. iconic behavior. let's get into it 🫶

---

🌸 NAME 🌸

fdatasync, fsync — synchronise changes to a file 💅

---

📚 LIBRARY 📚

Standard C Library (libc, -lc). yeah bestie, you know the one.

---

✨ SYNOPSIS ✨

#include <unistd.h>

int
fdatasync(int fd);

int
fsync(int fd);

---

🦋 DESCRIPTION 🦋

so. the fsync() system call is the main character here. what it does is it takes all modified data and attributes of the file that your file descriptor fd points at, and it moves them to a permanent storage device. no cap. normally that means every single in-core modified copy of buffers for that file gets written out to a disk. all of them. periodt. 🔥

then we have fdatasync(), which is like fsync()'s chiller cousin. it causes all modified data of fd to be moved to a permanent storage device too — but here's the tea — unlike fsync(), it does not guarantee that the file attributes or metadata you need to access the file are actually committed to that permanent storage. so it's data only, no metadata promises. 🎀

now, when should you reach for which one?

• use fsync() if your program needs a file to be in a known state — for example, when you're building a simple transaction facility. that's the vibe.
• if the file metadata has already been committed, then using fdatasync() can be more efficient than fsync(). efficiency queen 💅

one more thing, and this matters: both fdatasync() and fsync() calls are cancellation points. iykyk.

---

💖 RETURN VALUES 💖

the fsync() function returns the value 0 if it's successful 🎉

otherwise it returns the value -1, and the global variable errno gets set to indicate the error. sad girl hours 😭

---

💀 ERRORS 💀

the fsync() and fdatasync() calls fail if:

• [EBADF] — the fd argument is not a valid descriptor. bestie that's not a real fd 🙈
• [EINVAL] — the fd argument refers to a socket, not to a file. wrong vibe entirely.
• [EIO] — an I/O error occurred while reading from or writing to the file system. oof.
• [EINTEGRITY] — corrupted data was detected while reading from the file system. genuinely tragic 💀

---

👑 SEE ALSO 👑

fsync(1), sync(2), syncer(4), sync(8)

go read those too, they're all part of the same friend group 🫶

---

🌈 HISTORY 🌈

• the fsync() system call appeared in 4.2BSD. a legend from day one ⭐
• the fdatasync() system call appeared in FreeBSD 11.1. the newer sibling, still slaying.

---

🍓 BUGS 🍓

⚠️ okay so real talk: the fdatasync() system call currently does not guarantee that enqueued aio(4) requests for the file referenced by fd are completed before the syscall returns. so like... don't assume. noted. 💀

---

and that's the whole page, bestie 💖 this was the Debian build, dated March 30, 2020, and it lives under the title FSYNC(2) in the System Calls Manual. now go flush your buffers. literally. 🧚✨