.\" Copyright, the authors of the Linux man-pages project
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH cachestat 2 2025-06-28 "Linux man-pages 6.15"
.SH NAME
cachestat \- query the page cache statistics of a file
.SH SYNOPSIS
.nf
.B #include <sys/mman.h>
.P
.BI "int cachestat(unsigned int " fd ", struct cachestat_range *" cstat_range ,
.BI "              struct cachestat *" cstat ", unsigned int " flags );
.fi
.P
.EX
.B struct cachestat_range {
.B "    __u64 off;"
.B "    __u64 len;"
.B };
.P
.B struct cachestat {
.B "    __u64 nr_cache;"
.B "    __u64 nr_dirty;"
.B "    __u64 nr_writeback;"
.B "    __u64 nr_evicted;"
.B "    __u64 nr_recently_evicted;"
.B };
.EE
.SH DESCRIPTION
.B cachestat()
queries the number of cached pages, dirty pages,
pages marked for writeback, evicted pages,
and recently evicted pages in the byte range specified by
.I .off
and
.I .len
in the
.B cachestat_range
structure.
.P
An evicted page is one that was previously in the page cache
but has since been evicted.
A page is considered recently evicted if its reentry into the cache
would indicate active usage under memory pressure.
.P
The results are returned in a
.B cachestat
structure, pointed to by the
.I cstat
argument.
.P
The
.I .off
and
.I .len
fields must be non-negative.
If
.IR .len\~>\~0 ,
the queried range is
.RI [ .off ,\~ .off+.len ].
If
.IR len\~==\~0 ,
the range is from
.I .off
to the end of the file.
.P
The
.I flags
argument is reserved for future use and must be set to
.BR 0 .
.P
Currently,
.B hugetlbfs
files are not supported.
.SH RETURN VALUE
On success,
.B cachestat()
returns 0.
On error, \-1 is returned,
and
.I errno
is set to indicate the error.
.SH ERRORS
.TP
.B EFAULT
.I cstat
or
.I cstat_range
point to an invalid address.
.TP
.B EINVAL
Invalid
.I flags
value.
.TP
.B EBADF
Invalid file descriptor.
.TP
.B EOPNOTSUPP
The file descriptor refers to a
.B hugetlbfs
file, which is unsupported.
.SH STANDARDS
Linux.
.SH HISTORY
Linux 6.5.
.SH CAVEATS
Note that the status of a page may change after
.B cachestat()
retrieves it but before the values are returned to the application;
thus, the values may be slightly outdated.