[PATCH 23/23] linux: Add cachestat
Adhemerval Zanella Netto
adhemerval.zanella@linaro.org
Tue Nov 3 17:25:40 GMT 2026
On 03/11/26 13:16, Yury Khrustalev wrote:
> On Tue, Nov 03, 2026 at 11:32:28AM -0300, Adhemerval Zanella wrote:
>> 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 match 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.
>>
>> Somo Projects already call it through syscall: util-linux (fincore),
>> stress-ng, and LTP. The util-linux and LTP detect a cachestat function
>> at configure time and then expect the declarations from <sys/mman.h>.
>> The util-linux also builds with this change; LTP builds its cachestat
>> tests without _GNU_SOURCE, so it will need to define it.
>>
>> Checked on x86_64-linux-gnu.
>
> The new test 'misc/tst-cachestat' fails on both x86_64 and aarch64 if
> you run it in a Docker container:
>
> FAIL: misc/tst-cachestat
> original exit status 1
> error: ../sysdeps/unix/sysv/linux/tst-cachestat.c:83: cachestat (0, 16384): nr_cache 0 + nr_evicted 0 != 4
> error: ../sysdeps/unix/sysv/linux/tst-cachestat.c:83: cachestat (4096, 8192): nr_cache 0 + nr_evicted 0 != 2
> error: ../sysdeps/unix/sysv/linux/tst-cachestat.c:83: cachestat (2048, 1): nr_cache 0 + nr_evicted 0 != 1
> error: ../sysdeps/unix/sysv/linux/tst-cachestat.c:83: cachestat (2048, 4096): nr_cache 0 + nr_evicted 0 != 2
> error: ../sysdeps/unix/sysv/linux/tst-cachestat.c:83: cachestat (12288, 4096): nr_cache 0 + nr_evicted 0 != 1
> error: ../sysdeps/unix/sysv/linux/tst-cachestat.c:124: not true: cs.nr_cache + cs.nr_evicted >= npages
> ../sysdeps/unix/sysv/linux/tst-cachestat.c:131: numeric comparison failure (widths 64 and 32)
> left: 0 (0x0); from: cs.nr_cache + cs.nr_evicted
> right: 4 (0x4); from: npages
> error: 7 test failures
>
> I'm still looking into this but it would be good to fix it.
>
Thanks for the report. I had not run it under Docker, I tested only
the host and on VMs, where /tmp is tmpfs or a disk file system.
And it is an environment issue, where in a docker/podman container the
/tmp is on the container's overlayfs root, and cachestat reports the
page cache of the file it is given, while overlayfs forwards reads and
writes to the upper-layer file. The pages are cached there, the overlay
file's own page cache stays empty, and cachestat succeeds but returns
zero for every count.
For v2 I will change the test so it does not depend on the file system
behind TMPDIR:
- The range checks use a memfd_create file (tmpfs), whose page cache is
always visible.
- Only the check that no page is dirty or under writeback after fsync
uses a regular file in TMPDIR
More information about the Libc-alpha
mailing list