cachestat(2)

💅 cachestat — bestie, let's read the page cache

okay so this one lives in section 2 of the manual (the System Calls Manual, if you're keeping score), and it's called cachestat. Yes girl, it's a syscall. Come sit with me. 🫶

✨ NAME ✨

cachestat — query the page cache statistics of a file

🌸 SYNOPSIS 🌸

lowkey the whole shape of it, no notes:

#include <sys/mman.h>

int cachestat(unsigned int fd, struct cachestat_range *cstat_range,
              struct cachestat *cstat, unsigned int flags);

struct cachestat_range {
    __u64 off;
    __u64 len;
};

struct cachestat {
    __u64 nr_cache;
    __u64 nr_dirty;
    __u64 nr_writeback;
    __u64 nr_evicted;
    __u64 nr_recently_evicted;
};

like. look at those structs. they're giving "I know exactly what I'm about". 👑

🦋 DESCRIPTION 🦋

so cachestat() is literally the gossip channel for your page cache. you ask it about a byte range, and it tells you, for that range:

• how many pages are cached
• how many are dirty
• how many are marked for writeback
• how many got evicted
• and how many got recently evicted

and which range are we talking about? the one you set in the cachestat_range struct, using .off and .len. that's it. that's the vibe check. 💖

now let's define terms because not everyone's fluent yet:

an evicted page is one that was previously in the page cache but has since been evicted. rude of the kernel honestly.

a page counts as recently evicted if its reentry into the cache would indicate active usage under memory pressure. iykyk — that's the kernel saying "if you come back for this, you were actually using it."

and where do the numbers go? into a cachestat structure, which you point at with the cstat argument. hand it a pointer, get your stats. simple. ✨

the rules for the range, bestie, listen carefully:

• The .off and .len fields must be non-negative. no negatives, periodt.
• If .len > 0, the queried range is [.off, .off+.len].
• If len == 0, the range is from .off to the end of the file. (yes, len, not .len — that's how it's written, don't come for me 🙈)

about that flags argument: it is reserved for future use and must be set to 0. it's the "we'll deal with you later" field. put a zero in it. 🎀

and nn, one small thing: currently, hugetlbfs files are not supported. not me being dramatic, it's just true. 💀

🌈 RETURN VALUE 🌈

• success? cachestat() returns 0. slay.
• error? it returns -1, and errno is set to tell you which error. that's your diagnosis, read it. 🩺

💜 ERRORS 💜

• EFAULT — cstat or cstat_range point to an invalid address. your pointer is lost, babe. 😭
• EINVAL — Invalid flags value. you put something in the reserved field, didn't you.
• EBADF — Invalid file descriptor.
• EOPNOTSUPP — the file descriptor refers to a hugetlbfs file, which is unsupported. yeah. that one. 🙈

⭐ STANDARDS ⭐

Linux. that's it, that's the whole list. 🇱

🎀 HISTORY 🎀

Linux 6.5. so it's a newer-era icon. not vintage, not brand new — just right. ✨

👑 CAVEATS 👑

heads up: the status of a page may change after cachestat() retrieves it but before the values are returned to your application. so yes, the values may be slightly outdated. it's not a bug, it's just the passage of time. the kernel is fast, you're fast, pages move. 💅

---

and that's the whole page, bestie. you ate. 🍓

sign-off corner: this was from Linux man-pages 6.20, dated 2025-06-28, and it's the cachestat(2) page — go forth and stat your cache. 🦋💖