cachestat(2) — Linux manual page

NAME \| SYNOPSIS \| DESCRIPTION \| RETURN VALUE \| ERRORS \| STANDARDS \| HISTORY \| CAVEATS \| COLOPHON

cachestat(2)               System Calls Manual               cachestat(2)

NAME top

       cachestat - query the page cache statistics of a file

SYNOPSIS top

       #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 top

       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 top

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

ERRORS top

       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 top

       Linux.

HISTORY top

       Linux 6.5.

CAVEATS top

       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.

COLOPHON top

       This page is part of the man-pages (Linux kernel and C library
       user-space interface documentation) project.  Information about
       the project can be found at 
       ⟨https://www.kernel.org/doc/man-pages/⟩.  If you have a bug report
       for this manual page, see
       ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩.
       This page was obtained from the tarball man-pages-6.15.tar.gz
       fetched from
       ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on
       2025-08-11.  If you discover any rendering problems in this HTML
       version of the page, or you believe there is a better or more up-
       to-date source for the page, or you have corrections or
       improvements to the information in this COLOPHON (which is not
       part of the original manual page), send a mail to
       man-pages@man7.org

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

Pages that refer to this page: fincore(1)