Debian Codegraph @

upstream/debian-unstable/man2/cachestat.2

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH cachestat 2 2025-06-28 "Linux man-pages 6.18"
6 .SH NAME
7 cachestat \- query the page cache statistics of a file
8 .SH SYNOPSIS
9 .nf
10 .B #include <sys/mman.h>
11 .P
12 .BI "int cachestat(unsigned int " fd ", struct cachestat_range *" cstat_range ,
13 .BI " struct cachestat *" cstat ", unsigned int " flags );
14 .fi
15 .P
16 .EX
17 .B struct cachestat_range {
18 .B " __u64 off;"
19 .B " __u64 len;"
20 .B };
21 .P
22 .B struct cachestat {
23 .B " __u64 nr_cache;"
24 .B " __u64 nr_dirty;"
25 .B " __u64 nr_writeback;"
26 .B " __u64 nr_evicted;"
27 .B " __u64 nr_recently_evicted;"
28 .B };
29 .EE
30 .SH DESCRIPTION
31 .B cachestat()
32 queries the number of cached pages, dirty pages,
33 pages marked for writeback, evicted pages,
34 and recently evicted pages in the byte range specified by
35 .I .off
36 and
37 .I .len
38 in the
39 .B cachestat_range
40 structure.
41 .P
42 An evicted page is one that was previously in the page cache
43 but has since been evicted.
44 A page is considered recently evicted if its reentry into the cache
45 would indicate active usage under memory pressure.
46 .P
47 The results are returned in a
48 .B cachestat
49 structure, pointed to by the
50 .I cstat
51 argument.
52 .P
53 The
54 .I .off
55 and
56 .I .len
57 fields must be non-negative.
58 If
59 .IR .len\~>\~0 ,
60 the queried range is
61 .RI [ .off ,\~ .off+.len ].
62 If
63 .IR len\~==\~0 ,
64 the range is from
65 .I .off
66 to the end of the file.
67 .P
68 The
69 .I flags
70 argument is reserved for future use and must be set to
71 .BR 0 .
72 .P
73 Currently,
74 .B hugetlbfs
75 files are not supported.
76 .SH RETURN VALUE
77 On success,
78 .B cachestat()
79 returns 0.
80 On error, \-1 is returned,
81 and
82 .I errno
83 is set to indicate the error.
84 .SH ERRORS
85 .TP
86 .B EFAULT
87 .I cstat
88 or
89 .I cstat_range
90 point to an invalid address.
91 .TP
92 .B EINVAL
93 Invalid
94 .I flags
95 value.
96 .TP
97 .B EBADF
98 Invalid file descriptor.
99 .TP
100 .B EOPNOTSUPP
101 The file descriptor refers to a
102 .B hugetlbfs
103 file, which is unsupported.
104 .SH STANDARDS
105 Linux.
106 .SH HISTORY
107 Linux 6.5.
108 .SH CAVEATS
109 Note that the status of a page may change after
110 .B cachestat()
111 retrieves it but before the values are returned to the application;
112 thus, the values may be slightly outdated.