[PATCH v3 22/25] linux: Add cachestat

Adhemerval Zanella adhemerval.zanella@linaro.org
Mon Nov 16 19:42:35 GMT 2026


The cachestat system call (commit
cf264e1329fb0307e044f7675849f9f38b44c11a, Linux 6.5) returns the page
cache statistics of a byte range of a file.

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

The structures are defined by <linux/mman.h>, which programs include
along with <sys/mman.h> in either order, and the kernel header does not
provide a macro to check for them.  Defining them in <sys/mman.h> would
break programs that include <linux/mman.h> afterwards, so with
_GNU_SOURCE <sys/mman.h> now includes <linux/mman.h> if it is available
(as <sys/stat.h> does with <linux/stat.h> for statx), and only defines
them if the kernel header was not included.

The <asm/mman.h> definitions have the same values as the glibc ones,
and both include orders build without warnings with -Wall -Wextra on all
supported ABIs.  With kernel headers older than Linux 6.5 the structures
are only declared.

Some projects already call it through syscall: util-linux (fincore),
stress-ng, and LTP.  Both util-linux and LTP detect a cachestat function at
configure time and then expect the declarations from <sys/mman.h>.

Checked on x86_64-linux-gnu.
---
 NEWS                                          |   4 +
 sysdeps/unix/sysv/linux/Makefile              |   1 +
 sysdeps/unix/sysv/linux/Versions              |   1 +
 sysdeps/unix/sysv/linux/aarch64/libc.abilist  |   1 +
 sysdeps/unix/sysv/linux/alpha/libc.abilist    |   1 +
 sysdeps/unix/sysv/linux/arc/libc.abilist      |   1 +
 sysdeps/unix/sysv/linux/arm/be/libc.abilist   |   1 +
 sysdeps/unix/sysv/linux/arm/le/libc.abilist   |   1 +
 sysdeps/unix/sysv/linux/bits/mman_ext.h       |  37 ++++
 sysdeps/unix/sysv/linux/csky/libc.abilist     |   1 +
 sysdeps/unix/sysv/linux/hppa/libc.abilist     |   1 +
 sysdeps/unix/sysv/linux/i386/libc.abilist     |   1 +
 .../sysv/linux/loongarch/ilp32/libc.abilist   |   1 +
 .../sysv/linux/loongarch/lp64/libc.abilist    |   1 +
 .../sysv/linux/m68k/coldfire/libc.abilist     |   1 +
 .../unix/sysv/linux/m68k/m680x0/libc.abilist  |   1 +
 .../sysv/linux/microblaze/be/libc.abilist     |   1 +
 .../sysv/linux/microblaze/le/libc.abilist     |   1 +
 .../sysv/linux/mips/mips32/fpu/libc.abilist   |   1 +
 .../sysv/linux/mips/mips32/nofpu/libc.abilist |   1 +
 .../sysv/linux/mips/mips64/n32/libc.abilist   |   1 +
 .../sysv/linux/mips/mips64/n64/libc.abilist   |   1 +
 sysdeps/unix/sysv/linux/or1k/libc.abilist     |   1 +
 .../linux/powerpc/powerpc32/fpu/libc.abilist  |   1 +
 .../powerpc/powerpc32/nofpu/libc.abilist      |   1 +
 .../linux/powerpc/powerpc64/be/libc.abilist   |   1 +
 .../linux/powerpc/powerpc64/le/libc.abilist   |   1 +
 .../unix/sysv/linux/riscv/rv32/libc.abilist   |   1 +
 .../unix/sysv/linux/riscv/rv64/libc.abilist   |   1 +
 sysdeps/unix/sysv/linux/s390/libc.abilist     |   1 +
 sysdeps/unix/sysv/linux/sh/be/libc.abilist    |   1 +
 sysdeps/unix/sysv/linux/sh/le/libc.abilist    |   1 +
 .../sysv/linux/sparc/sparc32/libc.abilist     |   1 +
 .../sysv/linux/sparc/sparc64/libc.abilist     |   1 +
 sysdeps/unix/sysv/linux/syscalls.list         |   1 +
 sysdeps/unix/sysv/linux/tst-cachestat.c       | 182 ++++++++++++++++++
 .../unix/sysv/linux/x86_64/64/libc.abilist    |   1 +
 .../unix/sysv/linux/x86_64/x32/libc.abilist   |   1 +
 38 files changed, 258 insertions(+)
 create mode 100644 sysdeps/unix/sysv/linux/tst-cachestat.c

diff --git a/NEWS b/NEWS
index 54bc8c5a01b..0556121e030 100644
--- a/NEWS
+++ b/NEWS
@@ -57,6 +57,10 @@ Major new features:
   allowed to see, optionally only those of some types or owned by a user
   namespace.
 
+* On Linux, the cachestat function has been added to <sys/mman.h>.  It
+  returns the page cache statistics of a range of a file: the number of
+  cached, dirty, under writeback, and evicted pages.
+
 Deprecated and removed features, and other changes affecting compatibility:
 
 * The posix_spawn_file_actions_addchdir and posix_spawn_file_actions_addfchdir
diff --git a/sysdeps/unix/sysv/linux/Makefile b/sysdeps/unix/sysv/linux/Makefile
index db48ffdb76d..8295b0e60df 100644
--- a/sysdeps/unix/sysv/linux/Makefile
+++ b/sysdeps/unix/sysv/linux/Makefile
@@ -202,6 +202,7 @@ sysdep_headers += \
 tests += \
   test-errno-linux \
   tst-adjtimex \
+  tst-cachestat \
   tst-clock_adjtime \
   tst-clone \
   tst-clone2 \
diff --git a/sysdeps/unix/sysv/linux/Versions b/sysdeps/unix/sysv/linux/Versions
index 0e1fd4d16c7..f1d699f204a 100644
--- a/sysdeps/unix/sysv/linux/Versions
+++ b/sysdeps/unix/sysv/linux/Versions
@@ -344,6 +344,7 @@ libc {
     openat2;
   }
   GLIBC_2.45 {
+    cachestat;
     fchroot;
     file_getattr;
     file_setattr;
diff --git a/sysdeps/unix/sysv/linux/aarch64/libc.abilist b/sysdeps/unix/sysv/linux/aarch64/libc.abilist
index b24d0613ef7..f6bb2db6dea 100644
--- a/sysdeps/unix/sysv/linux/aarch64/libc.abilist
+++ b/sysdeps/unix/sysv/linux/aarch64/libc.abilist
@@ -2775,6 +2775,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/alpha/libc.abilist b/sysdeps/unix/sysv/linux/alpha/libc.abilist
index d89e3870bbf..c4ac9f87687 100644
--- a/sysdeps/unix/sysv/linux/alpha/libc.abilist
+++ b/sysdeps/unix/sysv/linux/alpha/libc.abilist
@@ -3122,6 +3122,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/arc/libc.abilist b/sysdeps/unix/sysv/linux/arc/libc.abilist
index 1868d4a7cbc..26e2030a075 100644
--- a/sysdeps/unix/sysv/linux/arc/libc.abilist
+++ b/sysdeps/unix/sysv/linux/arc/libc.abilist
@@ -2536,6 +2536,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/arm/be/libc.abilist b/sysdeps/unix/sysv/linux/arm/be/libc.abilist
index 0fbc2f5947f..6fe71045cf2 100644
--- a/sysdeps/unix/sysv/linux/arm/be/libc.abilist
+++ b/sysdeps/unix/sysv/linux/arm/be/libc.abilist
@@ -2828,6 +2828,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/arm/le/libc.abilist b/sysdeps/unix/sysv/linux/arm/le/libc.abilist
index 12d9e1ae9ae..802ace37133 100644
--- a/sysdeps/unix/sysv/linux/arm/le/libc.abilist
+++ b/sysdeps/unix/sysv/linux/arm/le/libc.abilist
@@ -2825,6 +2825,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/bits/mman_ext.h b/sysdeps/unix/sysv/linux/bits/mman_ext.h
index 19b09e00dd4..a373fd4d681 100644
--- a/sysdeps/unix/sysv/linux/bits/mman_ext.h
+++ b/sysdeps/unix/sysv/linux/bits/mman_ext.h
@@ -29,4 +29,41 @@ extern __ssize_t process_madvise (int __pid_fd, const struct iovec *__iov,
 
 extern int process_mrelease (int pidfd, unsigned int flags) __THROW;
 
+# ifdef __has_include
+#  if __has_include ("linux/mman.h")
+#   include "linux/mman.h"
+#  endif
+# endif
+
+# ifndef _LINUX_MMAN_H
+/* Byte range of the file queried by cachestat.  A zero LEN means up to
+   the end of the file.  */
+struct cachestat_range
+{
+  __uint64_t off;
+  __uint64_t len;
+};
+
+/* Page cache statistics returned by cachestat, in number of pages.  */
+struct cachestat
+{
+  __uint64_t nr_cache;
+  __uint64_t nr_dirty;
+  __uint64_t nr_writeback;
+  __uint64_t nr_evicted;
+  __uint64_t nr_recently_evicted;
+};
+# endif
+
+/* Kernel headers older than Linux 6.5 do not define them.  */
+struct cachestat_range;
+struct cachestat;
+
+/* Store in *CSTAT the page cache statistics of the file FD in the byte
+   range *CSTAT_RANGE.  FLAGS must be zero.  Return 0 on success, or -1
+   and set errno on failure.  */
+extern int cachestat (int __fd, const struct cachestat_range *__cstat_range,
+		      struct cachestat *__cstat, unsigned int __flags)
+  __THROW;
+
 #endif /* __USE_GNU  */
diff --git a/sysdeps/unix/sysv/linux/csky/libc.abilist b/sysdeps/unix/sysv/linux/csky/libc.abilist
index 8ca9a0f1132..65a7844fc4e 100644
--- a/sysdeps/unix/sysv/linux/csky/libc.abilist
+++ b/sysdeps/unix/sysv/linux/csky/libc.abilist
@@ -2812,6 +2812,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/hppa/libc.abilist b/sysdeps/unix/sysv/linux/hppa/libc.abilist
index d8457291774..3c386896d77 100644
--- a/sysdeps/unix/sysv/linux/hppa/libc.abilist
+++ b/sysdeps/unix/sysv/linux/hppa/libc.abilist
@@ -2849,6 +2849,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/i386/libc.abilist b/sysdeps/unix/sysv/linux/i386/libc.abilist
index 3c85600cd5a..023d56f2546 100644
--- a/sysdeps/unix/sysv/linux/i386/libc.abilist
+++ b/sysdeps/unix/sysv/linux/i386/libc.abilist
@@ -3032,6 +3032,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/loongarch/ilp32/libc.abilist b/sysdeps/unix/sysv/linux/loongarch/ilp32/libc.abilist
index 3bd72753155..961dd2332af 100644
--- a/sysdeps/unix/sysv/linux/loongarch/ilp32/libc.abilist
+++ b/sysdeps/unix/sysv/linux/loongarch/ilp32/libc.abilist
@@ -2287,6 +2287,7 @@ GLIBC_2.44 wprintf F
 GLIBC_2.44 write F
 GLIBC_2.44 writev F
 GLIBC_2.44 wscanf F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/loongarch/lp64/libc.abilist b/sysdeps/unix/sysv/linux/loongarch/lp64/libc.abilist
index 8f425dc776c..bf5345e128f 100644
--- a/sysdeps/unix/sysv/linux/loongarch/lp64/libc.abilist
+++ b/sysdeps/unix/sysv/linux/loongarch/lp64/libc.abilist
@@ -2296,6 +2296,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/m68k/coldfire/libc.abilist b/sysdeps/unix/sysv/linux/m68k/coldfire/libc.abilist
index 548aaf05fac..5798f01a8f2 100644
--- a/sysdeps/unix/sysv/linux/m68k/coldfire/libc.abilist
+++ b/sysdeps/unix/sysv/linux/m68k/coldfire/libc.abilist
@@ -2808,6 +2808,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/m68k/m680x0/libc.abilist b/sysdeps/unix/sysv/linux/m68k/m680x0/libc.abilist
index b01516c3172..f8d8070bde5 100644
--- a/sysdeps/unix/sysv/linux/m68k/m680x0/libc.abilist
+++ b/sysdeps/unix/sysv/linux/m68k/m680x0/libc.abilist
@@ -2975,6 +2975,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/microblaze/be/libc.abilist b/sysdeps/unix/sysv/linux/microblaze/be/libc.abilist
index 26c306f74e3..fc30a78f18f 100644
--- a/sysdeps/unix/sysv/linux/microblaze/be/libc.abilist
+++ b/sysdeps/unix/sysv/linux/microblaze/be/libc.abilist
@@ -2861,6 +2861,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/microblaze/le/libc.abilist b/sysdeps/unix/sysv/linux/microblaze/le/libc.abilist
index eb9ad7c22cc..fe40f063df7 100644
--- a/sysdeps/unix/sysv/linux/microblaze/le/libc.abilist
+++ b/sysdeps/unix/sysv/linux/microblaze/le/libc.abilist
@@ -2858,6 +2858,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/mips/mips32/fpu/libc.abilist b/sysdeps/unix/sysv/linux/mips/mips32/fpu/libc.abilist
index 6510e0ec3c8..791ccb7cba5 100644
--- a/sysdeps/unix/sysv/linux/mips/mips32/fpu/libc.abilist
+++ b/sysdeps/unix/sysv/linux/mips/mips32/fpu/libc.abilist
@@ -2938,6 +2938,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/mips/mips32/nofpu/libc.abilist b/sysdeps/unix/sysv/linux/mips/mips32/nofpu/libc.abilist
index 8f694cff7e8..a129cd34903 100644
--- a/sysdeps/unix/sysv/linux/mips/mips32/nofpu/libc.abilist
+++ b/sysdeps/unix/sysv/linux/mips/mips32/nofpu/libc.abilist
@@ -2936,6 +2936,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/mips/mips64/n32/libc.abilist b/sysdeps/unix/sysv/linux/mips/mips64/n32/libc.abilist
index 4d15b429237..849335380e3 100644
--- a/sysdeps/unix/sysv/linux/mips/mips64/n32/libc.abilist
+++ b/sysdeps/unix/sysv/linux/mips/mips64/n32/libc.abilist
@@ -2944,6 +2944,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/mips/mips64/n64/libc.abilist b/sysdeps/unix/sysv/linux/mips/mips64/n64/libc.abilist
index 7309f1b3b82..9c94334b8b8 100644
--- a/sysdeps/unix/sysv/linux/mips/mips64/n64/libc.abilist
+++ b/sysdeps/unix/sysv/linux/mips/mips64/n64/libc.abilist
@@ -2846,6 +2846,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/or1k/libc.abilist b/sysdeps/unix/sysv/linux/or1k/libc.abilist
index cb44a37e1af..41642a5f0c1 100644
--- a/sysdeps/unix/sysv/linux/or1k/libc.abilist
+++ b/sysdeps/unix/sysv/linux/or1k/libc.abilist
@@ -2286,6 +2286,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/powerpc/powerpc32/fpu/libc.abilist b/sysdeps/unix/sysv/linux/powerpc/powerpc32/fpu/libc.abilist
index 87fd6d55098..3bcc7fab64b 100644
--- a/sysdeps/unix/sysv/linux/powerpc/powerpc32/fpu/libc.abilist
+++ b/sysdeps/unix/sysv/linux/powerpc/powerpc32/fpu/libc.abilist
@@ -3165,6 +3165,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/powerpc/powerpc32/nofpu/libc.abilist b/sysdeps/unix/sysv/linux/powerpc/powerpc32/nofpu/libc.abilist
index bf7443d41b9..4e94beb0612 100644
--- a/sysdeps/unix/sysv/linux/powerpc/powerpc32/nofpu/libc.abilist
+++ b/sysdeps/unix/sysv/linux/powerpc/powerpc32/nofpu/libc.abilist
@@ -3210,6 +3210,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/powerpc/powerpc64/be/libc.abilist b/sysdeps/unix/sysv/linux/powerpc/powerpc64/be/libc.abilist
index cbc540442aa..537ecc3a553 100644
--- a/sysdeps/unix/sysv/linux/powerpc/powerpc64/be/libc.abilist
+++ b/sysdeps/unix/sysv/linux/powerpc/powerpc64/be/libc.abilist
@@ -2919,6 +2919,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/powerpc/powerpc64/le/libc.abilist b/sysdeps/unix/sysv/linux/powerpc/powerpc64/le/libc.abilist
index 6d9e4ef7249..da8d6956164 100644
--- a/sysdeps/unix/sysv/linux/powerpc/powerpc64/le/libc.abilist
+++ b/sysdeps/unix/sysv/linux/powerpc/powerpc64/le/libc.abilist
@@ -2995,6 +2995,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/riscv/rv32/libc.abilist b/sysdeps/unix/sysv/linux/riscv/rv32/libc.abilist
index ec6455b0942..24ed335847f 100644
--- a/sysdeps/unix/sysv/linux/riscv/rv32/libc.abilist
+++ b/sysdeps/unix/sysv/linux/riscv/rv32/libc.abilist
@@ -2539,6 +2539,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/riscv/rv64/libc.abilist b/sysdeps/unix/sysv/linux/riscv/rv64/libc.abilist
index 64275f17de5..5f3ee0e7139 100644
--- a/sysdeps/unix/sysv/linux/riscv/rv64/libc.abilist
+++ b/sysdeps/unix/sysv/linux/riscv/rv64/libc.abilist
@@ -2739,6 +2739,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/s390/libc.abilist b/sysdeps/unix/sysv/linux/s390/libc.abilist
index edc843e3211..027ae39cbe8 100644
--- a/sysdeps/unix/sysv/linux/s390/libc.abilist
+++ b/sysdeps/unix/sysv/linux/s390/libc.abilist
@@ -2956,6 +2956,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/sh/be/libc.abilist b/sysdeps/unix/sysv/linux/sh/be/libc.abilist
index 21d387470a7..fbdfab376e7 100644
--- a/sysdeps/unix/sysv/linux/sh/be/libc.abilist
+++ b/sysdeps/unix/sysv/linux/sh/be/libc.abilist
@@ -2855,6 +2855,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/sh/le/libc.abilist b/sysdeps/unix/sysv/linux/sh/le/libc.abilist
index 0055e4fedba..b611a3013c0 100644
--- a/sysdeps/unix/sysv/linux/sh/le/libc.abilist
+++ b/sysdeps/unix/sysv/linux/sh/le/libc.abilist
@@ -2852,6 +2852,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/sparc/sparc32/libc.abilist b/sysdeps/unix/sysv/linux/sparc/sparc32/libc.abilist
index 7a9fc0289d5..cd31adb4cdd 100644
--- a/sysdeps/unix/sysv/linux/sparc/sparc32/libc.abilist
+++ b/sysdeps/unix/sysv/linux/sparc/sparc32/libc.abilist
@@ -3186,6 +3186,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/sparc/sparc64/libc.abilist b/sysdeps/unix/sysv/linux/sparc/sparc64/libc.abilist
index af2203dbf84..45c553203f8 100644
--- a/sysdeps/unix/sysv/linux/sparc/sparc64/libc.abilist
+++ b/sysdeps/unix/sysv/linux/sparc/sparc64/libc.abilist
@@ -2822,6 +2822,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/syscalls.list b/sysdeps/unix/sysv/linux/syscalls.list
index 0fd789efec7..a234837f6e0 100644
--- a/sysdeps/unix/sysv/linux/syscalls.list
+++ b/sysdeps/unix/sysv/linux/syscalls.list
@@ -2,6 +2,7 @@
 
 alarm		-	alarm		i:i	alarm
 bdflush		EXTRA	bdflush		i:ii	__compat_bdflush	bdflush@GLIBC_2.0:GLIBC_2.23
+cachestat	EXTRA	cachestat	i:ippU	cachestat
 capget		EXTRA	capget		i:pp	capget
 capset		EXTRA	capset		i:pp	capset
 create_module	EXTRA	create_module	3	__compat_create_module	create_module@GLIBC_2.0:GLIBC_2.23
diff --git a/sysdeps/unix/sysv/linux/tst-cachestat.c b/sysdeps/unix/sysv/linux/tst-cachestat.c
new file mode 100644
index 00000000000..3656dec42de
--- /dev/null
+++ b/sysdeps/unix/sysv/linux/tst-cachestat.c
@@ -0,0 +1,182 @@
+/* Basic tests for Linux cachestat.
+   Copyright (C) 2026 Free Software Foundation, Inc.
+   This file is part of the GNU C Library.
+
+   The GNU C Library is free software; you can redistribute it and/or
+   modify it under the terms of the GNU Lesser General Public
+   License as published by the Free Software Foundation; either
+   version 2.1 of the License, or (at your option) any later version.
+
+   The GNU C Library is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+   Lesser General Public License for more details.
+
+   You should have received a copy of the GNU Lesser General Public
+   License along with the GNU C Library; if not, see
+   <https://www.gnu.org/licenses/>.  */
+
+#include <errno.h>
+#include <inttypes.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/mman.h>
+#include <sys/syscall.h>
+#include <unistd.h>
+#include <support/check.h>
+#include <support/support.h>
+#include <support/temp_file.h>
+#include <support/xunistd.h>
+
+/* Kernel headers older than Linux 6.5 provide <linux/mman.h> without the
+   cachestat structures, which <sys/mman.h> then only declares.  They were
+   added along with the system call, so complete the types in that case.  */
+#if defined _LINUX_MMAN_H && !defined __NR_cachestat
+struct cachestat_range
+{
+  uint64_t off;
+  uint64_t len;
+};
+
+struct cachestat
+{
+  uint64_t nr_cache;
+  uint64_t nr_dirty;
+  uint64_t nr_writeback;
+  uint64_t nr_evicted;
+  uint64_t nr_recently_evicted;
+};
+#endif
+
+/* Number of pages written to the files.  */
+enum { npages = 4 };
+
+static long int page_size;
+
+static struct cachestat
+query (int fd, uint64_t off, uint64_t len)
+{
+  struct cachestat_range range = { .off = off, .len = len };
+  struct cachestat cs;
+  /* Check that all the fields are written.  */
+  memset (&cs, 0xff, sizeof (cs));
+  if (cachestat (fd, &range, &cs, 0) != 0)
+    FAIL_EXIT1 ("cachestat (%" PRIu64 ", %" PRIu64 "): %m", off, len);
+  TEST_VERIFY (cs.nr_dirty <= cs.nr_cache);
+  TEST_VERIFY (cs.nr_writeback <= cs.nr_cache);
+  TEST_VERIFY (cs.nr_recently_evicted <= cs.nr_evicted);
+  return cs;
+}
+
+static void
+check_range (int fd, uint64_t off, uint64_t len, uint64_t expected)
+{
+  struct cachestat cs = query (fd, off, len);
+  if (cs.nr_cache + cs.nr_evicted != expected)
+    FAIL ("cachestat (%" PRIu64 ", %" PRIu64 "): nr_cache %llu"
+	  " + nr_evicted %llu != %" PRIu64, off, len,
+	  (unsigned long long int) cs.nr_cache,
+	  (unsigned long long int) cs.nr_evicted, expected);
+}
+
+/* Write NPAGES pages to FD.  */
+static void
+write_pages (int fd)
+{
+  size_t size = npages * page_size;
+  char *buf = xmalloc (size);
+  memset (buf, 0x55, size);
+  xwrite (fd, buf, size);
+  free (buf);
+}
+
+static int
+do_test (void)
+{
+  page_size = sysconf (_SC_PAGESIZE);
+  size_t size = npages * page_size;
+
+  /* The cachestat reports the page cache of the file itself, so the counts
+     depend on the file system.  A memfd file is on tmpfs, which keeps its
+     pages there (or in swap, reported as evicted).  On overlayfs, for
+     instance, the data is cached by the underlying file and cachestat reports
+     no page.  */
+  int fd = memfd_create ("tst-cachestat", MFD_CLOEXEC);
+  if (fd == -1)
+    FAIL_EXIT1 ("memfd_create: %m");
+
+  struct cachestat_range range = { 0 };
+  struct cachestat cs;
+  if (cachestat (fd, &range, &cs, 0) != 0)
+    {
+      if (errno == ENOSYS)
+	FAIL_UNSUPPORTED ("cachestat is not supported by the kernel");
+      /* The kernel only fails with EPERM for files the caller cannot write
+	 to, which is not the case of FD, so it comes from a seccomp filter
+	 (such as the default podman one).  */
+      if (errno == EPERM)
+	FAIL_UNSUPPORTED ("cachestat is not permitted: %m");
+      FAIL_EXIT1 ("cachestat: %m");
+    }
+  TEST_COMPARE (cs.nr_cache, 0);
+  TEST_COMPARE (cs.nr_evicted, 0);
+
+  write_pages (fd);
+
+  /* The byte range is rounded to whole pages.  */
+  check_range (fd, 0, size, npages);
+  check_range (fd, page_size, 2 * page_size, 2);
+  check_range (fd, page_size / 2, 1, 1);
+  check_range (fd, page_size / 2, page_size, 2);
+  check_range (fd, (npages - 1) * page_size, page_size, 1);
+
+  /* A zero length means up to the end of the file, but a large folio may
+     extend past it.  */
+  cs = query (fd, 0, 0);
+  TEST_VERIFY (cs.nr_cache + cs.nr_evicted >= npages);
+
+  /* FLAGS must be zero.  */
+  range.len = size;
+  TEST_COMPARE (cachestat (fd, &range, &cs, 1), -1);
+  TEST_COMPARE (errno, EINVAL);
+
+  TEST_COMPARE (cachestat (-1, &range, &cs, 0), -1);
+  TEST_COMPARE (errno, EBADF);
+
+  xclose (fd);
+
+  /* No page is dirty or under writeback after fsync.  fsync does not
+     write back tmpfs pages, so use a file in TMPDIR.  */
+  fd = create_temp_file ("tst-cachestat", NULL);
+  TEST_VERIFY_EXIT (fd != -1);
+  write_pages (fd);
+  TEST_COMPARE (fsync (fd), 0);
+  cs = query (fd, 0, size);
+  if (cs.nr_cache + cs.nr_evicted == 0)
+    printf ("info: no page is reported for a file in TMPDIR (overlayfs?),"
+	    " skipping fsync check\n");
+  else
+    {
+      TEST_COMPARE (cs.nr_dirty, 0);
+      TEST_COMPARE (cs.nr_writeback, 0);
+      TEST_COMPARE (cs.nr_cache + cs.nr_evicted, npages);
+    }
+  xclose (fd);
+
+  /* hugetlbfs is not supported.  */
+  int hfd = memfd_create ("tst-cachestat", MFD_CLOEXEC | MFD_HUGETLB);
+  if (hfd == -1)
+    printf ("info: cannot create hugetlbfs file: %m\n");
+  else
+    {
+      TEST_COMPARE (cachestat (hfd, &range, &cs, 0), -1);
+      TEST_COMPARE (errno, EOPNOTSUPP);
+      xclose (hfd);
+    }
+
+  return 0;
+}
+
+#include <support/test-driver.c>
diff --git a/sysdeps/unix/sysv/linux/x86_64/64/libc.abilist b/sysdeps/unix/sysv/linux/x86_64/64/libc.abilist
index b44e5aefed3..551e36268a0 100644
--- a/sysdeps/unix/sysv/linux/x86_64/64/libc.abilist
+++ b/sysdeps/unix/sysv/linux/x86_64/64/libc.abilist
@@ -2771,6 +2771,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
diff --git a/sysdeps/unix/sysv/linux/x86_64/x32/libc.abilist b/sysdeps/unix/sysv/linux/x86_64/x32/libc.abilist
index 047be7f401a..b8cba8cf81b 100644
--- a/sysdeps/unix/sysv/linux/x86_64/x32/libc.abilist
+++ b/sysdeps/unix/sysv/linux/x86_64/x32/libc.abilist
@@ -2790,6 +2790,7 @@ GLIBC_2.43 memset_explicit F
 GLIBC_2.43 mseal F
 GLIBC_2.43 openat2 F
 GLIBC_2.43 umaxabs F
+GLIBC_2.45 cachestat F
 GLIBC_2.45 fchroot F
 GLIBC_2.45 file_getattr F
 GLIBC_2.45 file_setattr F
-- 
2.53.0



More information about the Libc-alpha mailing list