NAME

       cachestat - query the page cache statistics of a file

SYNOPSIS

       #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;
       };

DESCRIPTION

       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 .off and .len in the cachestat_range structure.

       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.

       The results are returned in a cachestat structure, pointed to by the cstat argument.

       The .off and .len fields must be non-negative.  If .len > 0, the queried range is [.off, .off+.len].   If
       len == 0, the range is from .off to the end of the file.

       The flags argument is reserved for future use and must be set to 0.

       Currently, hugetlbfs files are not supported.

RETURN VALUE

       On success, cachestat() returns 0.  On error, -1 is returned, and errno is set to indicate the error.

ERRORS

       EFAULT cstat or cstat_range point to an invalid address.

       EINVAL Invalid flags value.

       EBADF  Invalid file descriptor.

       EOPNOTSUPP
              The file descriptor refers to a hugetlbfs file, which is unsupported.

STANDARDS

       Linux.

HISTORY

       Linux 6.5.

CAVEATS

       Note  that  the  status  of  a  page  may change after cachestat() retrieves it but before the values are
       returned to the application; thus, the values may be slightly outdated.

Linux man-pages 6.15                               2025-06-28                                       cachestat(2)