---
name: "cachestat"
section: "2"
platform: "linux"
package: "man-pages"
version: "6.19-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/cachestat"
---

# cachestat(2)

query the page cache statistics of a file

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