hesela.devcachestat
cachestat is a Linux system call that samples cached, dirty, writeback and eviction-related page counts for a file range.
Available since Linux 6.5, the interface takes a file descriptor, byte offset and length, and flags set to zero. Its counts can become stale before return; hugetlbfs is unsupported. [1]
Cached, dirty and writeback are overlapping categories. Linux v6.16 increments nr_cache before independently inspecting dirty and writeback marks. Eviction counters sample retained metadata rather than a lifetime total; recently evicted uses a working-set test, not a fixed number of elapsed seconds. [2]
For positive, non-overflowing lengths, the v6.8 implementation selects pages through floor((off + len - 1) / page_size). A zero length selects the suffix, not an empty range. Five two-page, memory-locked trials on Linux 6.8.0-146-generic observed one cached page for offset 4095 and length 1, but two for length 2, with 4096-byte pages. These are bounded API observations, not cache-hit ratios or a workload benchmark. [3] [4]
Linux v6.16 permits disclosure for a writable descriptor, inode ownership or relevant capability, or a successful file write-permission check; otherwise it returns EPERM. The existing mincore interface can instead mask information with all-one bytes. [2] [5]
The NDSS 2026 study Eviction Notice reports that cachestat disclosure was restricted in February 2025 (CVE-2025-21691); its artifact appendix says the mitigated syscall no longer supports the paper's cross-user scenario. Check distribution backports, not only the kernel release label. The self-owned-file observations above do not assess cross-user exposure. [6]
Relations
- related
- Page cache, mincore, Process I/O accounting, fsync, Working set
Advantages
- Reports file-range dirty and writeback counts without first creating a user-space mapping. [2]
Limitations
- Zero dirty pages do not certify an application's persistence protocol or replace checking synchronization errors.
- A sample cannot establish which process accessed a shared file or how many accesses hit its cached pages.
Citations
- Linux man-pages 6.19: cachestat(2), API, history and snapshot caveat
- Linux v6.16 mm/filemap.c: filemap_cachestat and cachestat syscall
- Linux v6.8 mm/filemap.c: cachestat range calculation and independent counter increments
- Hesela: five self-owned, locked-file cachestat trials with source hashes and environment
- Linux v6.16 mm/mincore.c: can_do_mincore and all-one masking
- Neela et al. Eviction Notice: Reviving and Advancing Page Cache Attacks. NDSS 2026; artifact appendix. DOI: 10.14722/ndss.2026.240006
Sources & caveats
- API manual and version-pinned v6.8/v6.16 implementations reviewed 2026-11-06; the manual's inclusive-looking range notation differs from the actual len - 1 endpoint.
- Native experiment uses fresh two-page files and mlock; all five trials and error controls are preserved. Filesystem magic 0xef53 does not identify an ext-family version.
- No permission-bypass, side-channel, eviction, race, performance or power-loss experiment. Current permission behavior is sourced to v6.16, not inferred from the older test kernel.