sync_file_range(2)

✨ sync_file_range — bestie edition ✨

okay so this is sync_file_range(2) from the System Calls Manual, and it's a whole situation 💅

---

🎀 NAME 🎀

sync_file_range — sync a file segment with disk. that's it, that's the vibe, we're syncing a segment of a file to disk 🦋

📚 LIBRARY 📚

Standard C library (libc, -lc). the classic. the blueprint. no cap 💖

🌸 SYNOPSIS 🌸

#define _GNU_SOURCE         /* See feature_test_macros(7) */
#define _FILE_OFFSET_BITS 64
#include <fcntl.h>

int sync_file_range(int fd, off_t offset, off_t nbytes,
                    unsigned int flags);

like, bestie, you need those defines up top. _GNU_SOURCE is giving main character energy (peep feature_test_macros(7) for the lore), and _FILE_OFFSET_BITS 64 is there so your offsets don't get humbled on 32-bit platforms 🫶

💖 DESCRIPTION 💖

sync_file_range() lets you have fine control when synchronizing the open file that the file descriptor fd points to, with disk. it's giving precision. it's giving artistry. ✨

offset is the starting byte of the file range you wanna synchronize.

nbytes is how long that range is, in bytes — and here's the spicy part: if nbytes is zero, then literally every byte from offset all the way to the end of file gets synchronized. 🌈

and the units?? synchronization happens in units of the system page size, so:

• offset gets rounded down to a page boundary
• (offset+nbytes-1) gets rounded up to a page boundary

periodt. math is math. 🧚

The flags bit-mask argument can include any of these values:

• SYNC_FILE_RANGE_WAIT_BEFORE — wait for write-out of every page in the specified range that's already been submitted to the device driver for write-out, before you do any writing at all. like waiting your turn, but for pages. 💅
• SYNC_FILE_RANGE_WRITE — kick off write-out of all the dirty pages in the specified range that aren't currently submitted for write-out. ngl, even this one may block if you try to write more than the request queue size 😭
• SYNC_FILE_RANGE_WAIT_AFTER — wait for write-out of all the pages in the range after you've done any writing.

Specifying flags as 0 is permitted — it's a no-op. literally just vibes, zero consequences 💀

⚠️ Warning ⚠️

okay bestie, sit down for this one because it's serious:

This system call is extremely dangerous and should not be used in portable programs.

none of these operations writes out the file's metadata. so unless your application is strictly performing overwrites of already-instantiated disk blocks, there are no guarantees your data will survive a crash. 😭 there's no user interface to tell you whether a write is purely an overwrite. and on filesystems using copy-on-write semantics (e.g. btrfs), an overwrite of existing allocated blocks is impossible. when writing into preallocated space, lots of filesystems also need calls into the block allocator — and this system call does not sync that out to disk. and this system call does not flush disk write caches, so it provides no data integrity on systems with volatile disk write caches.

tl;dr: iconic? maybe. safe? absolutely not. 🙈

🔍 Some details 🔍

SYNC_FILE_RANGE_WAIT_BEFORE and SYNC_FILE_RANGE_WAIT_AFTER will detect any I/O errors or ENOSPC conditions and return them to the caller. so they're the snitches of the flag world and honestly? we respect it 🫶

useful combinations of the flag bits are:

• SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE — makes sure that all pages in the specified range which were dirty when sync_file_range() was called get placed under write-out. this is a start-write-for-data-integrity operation. ✨
• SYNC_FILE_RANGE_WRITE — starts write-out of all dirty pages in the specified range that aren't presently under write-out. this is an asynchronous flush-to-disk operation. and it is not suitable for data integrity operations. 🚩
• SYNC_FILE_RANGE_WAIT_BEFORE (or SYNC_FILE_RANGE_WAIT_AFTER) — waits for completion of write-out of all pages in the specified range. you can use this after an earlier SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE operation to wait for that op to finish and collect its result. it's giving follow-up text energy 📱
• SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE | SYNC_FILE_RANGE_WAIT_AFTER — this is a write-for-data-integrity operation that ensures all pages in the specified range which were dirty when sync_file_range() was called get committed to disk. the full ensemble. the whole girl group is on stage. 👑

💫 RETURN VALUE 💫

slay: on success, sync_file_range() returns 0.

on failure, -1 is returned and errno is set to indicate the error. not slay, but informative. 💀

🚨 ERRORS 🚨

• EBADF — fd is not a valid file descriptor. bestie that's not a file 🫠
• EINVAL — flags specifies an invalid bit; or offset or nbytes is invalid. read the room (and the arguments) 😤
• EIO — I/O error. the disk said no 💔
• ENOMEM — out of memory. she's full 😭
• ENOSPC — out of disk space. she's also full 😭😭
• ESPIPE — fd refers to something other than a regular file, a block device, or a directory. like... what even is that 🍓

🌟 VERSIONS 🌟

sync_file_range2()

some architectures (e.g. PowerPC, ARM) need 64-bit arguments aligned in a suitable pair of registers. on those architectures, the call signature of sync_file_range() shown in the SYNOPSIS would force a register to be wasted as padding between the fd and offset arguments. (peep syscall(2) for the details.) so these architectures define a different system call that orders the arguments suitably:

int sync_file_range2(int fd, unsigned int flags,
                     off_t offset, off_t nbytes);

the behavior of this system call is otherwise exactly the same as sync_file_range(). same girl, different outfit change. 💅✨

📜 STANDARDS 📜

Linux. that's the standard. we're Linux-pilled. 🐧

🕰️ HISTORY 🕰️

Linux 2.6.17. she's been around a minute and she's still iconic 👑

sync_file_range2()

a system call with this signature first appeared on the ARM architecture in Linux 2.6.20, under the name arm_sync_file_range(). it got renamed in Linux 2.6.22, when the analogous system call was added for PowerPC. on architectures where glibc support is provided, glibc transparently wraps sync_file_range2() under the name sync_file_range(). sneaky. elegant. we love a glow-up 🌈

📝 NOTES 📝

_FILE_OFFSET_BITS should be defined to be 64 in code that takes the address of sync_file_range, if that code is meant to be portable to traditional 32-bit x86 and ARM platforms where off_t's width defaults to 32 bits. protect your offsets, babe 🫶

👀 SEE ALSO 👀

fdatasync(2), fsync(2), msync(2), sync(2) — go read the whole friend group, they're all valid 💜

---

and that's the page, bestie!! 🎀 this was pulled straight from Linux man-pages 6.20, dated 2026-02-08 — so if you're reading this and the date's gone stale, that's a you-and-your-distro problem, not mine 💖✨🦋