MSYNC(2)

💾 MSYNC(2) — the manual page, bestie edition 💾

okay so this is msync, a system call from the System Calls Manual, and it's literally the "hey file system, catch up bestie" button. let's get into it 🫶

---

✨ NAME ✨

msync — synchronize a mapped region

no cap, that's the whole job description.

---

📚 LIBRARY 📚

Standard C Library (libc, -lc)

---

🌸 SYNOPSIS 🌸

#include <sys/mman.h>

int
msync(void *addr, size_t len, int flags);

---

💅 DESCRIPTION 💅

The msync() system call writes any modified pages back to the file system and updates the file modification time. it's giving "flushed and timestamped, mwah" 💖

now here's the tea about len:

• if len is 0, all modified pages within the region containing addr will be flushed.
• if len is non-zero, only those pages containing addr and len-1 succeeding locations will be examined.

The flags argument may be specified as follows:

• MS_ASYNC — Return immediately (girl said "I'll deal with it later, bye" 💨)
• MS_SYNC — Perform synchronous writes (she stays. she waits. she's committed 💪)
• MS_INVALIDATE — Invalidate all cached data (yanking the cache out of existence, iconic behavior)

---

🎀 RETURN VALUES 🎀

The msync() function returns the value 0 if successful. otherwise, the value -1 is returned and the global variable errno is set to indicate the error. so basically 0 = slay, -1 = check errno, bestie 😭

---

🔥 ERRORS 🔥

The msync() system call will fail if:

• [EBUSY] — Some or all of the pages in the specified region are locked and MS_INVALIDATE is specified. (you asked to nuke the cache but the pages are literally holding on. rude.)
• [EINVAL] — The addr argument is not a multiple of the hardware page size. (alignment check said no 💀)
• [ENOMEM] — The addresses in the range starting at addr and continuing for len bytes are outside the range allowed for the address space of a process, or specify one or more pages that are not mapped. (that address is not in your house, ma'am 🙈)
• [EINVAL] — The flags argument was both MS_ASYNC and MS_INVALIDATE. Only one of these flags is allowed. (pick a lane, babe. you cannot be both.)
• [EIO] — An error occurred while writing at least one of the pages in the specified region. (the write itself fumbled. not your fault. probably.)

---

🦋 SEE ALSO 🦋

madvise(2), mincore(2), mlock(2), mprotect(2), munmap(2)

the whole mmap friend group, honestly. go read them too, iykyk ✨

---

👑 HISTORY 👑

The msync() system call first appeared in 4.4BSD. a true vintage queen, older than basically everyone reading this 🌈

---

💀 BUGS 💀

The msync() system call is usually not needed, since BSD implements a coherent file system buffer cache. so like, she's a little extra sometimes. 🙈

However, it may be used to associate dirty VM pages with file system buffers and thus cause them to be flushed to physical media sooner rather than later. so when you do need her, she's the one making sure your stuff actually hits the disk before the lights go out. main character energy tbh.

---

and that's the page, bestie!! 💖 this version came from the Debian distro's man pages, dated March 18, 2012, and it's page MSYNC(2) — go forth and flush responsibly 🫶✨