Skip to contentSkip to conversation

man/man2/cachestat.2: add a man page for cachestat()

PATCH Superseded Matteo Croce 2 participants 4 messages May 30, 2025 – Jun 11, 2025 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

v3 of 4 Superseded Latest is v4 →

lore
Share & tools
lore

Matteo Croce

author
#0 lore raw

PATCH v3 1/1 man/man2/cachestat.2: add a man page for cachestat()

From: Matteo Croce <[email protected]>

Add a missing man page for cachestat().
The text was converted from the commit message:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=cf264e1329fb0307e044f7675849f9f38b44c11a

Signed-off-by Nhat Pham <[email protected]>
Signed-off-by Matteo Croce <[email protected]>
---
 man/man2/cachestat.2 | 111 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 111 insertions(+)
 create mode 100644 man/man2/cachestat.2
man/man2/cachestat.2 new file +111 -0
new file mode 100644
index 000000000..12dbd900d
@@ -0,0 +1,111 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH cachestat 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+cachestat \- query the page cache statistics of a file
+.SH SYNOPSIS
+.nf
+.B #include <sys/mman.h>
+.P
+.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 };
+.P
+.BI "int cachestat(unsigned int " fd ", struct cachestat_range *" cstat_range ","
+.BI "              struct cachestat *" cstat ", unsigned int " flags ");"
+.nf
+.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 appropriately.
+.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.
Signature · 1 line
2.49.0
maintainer
#1 lore raw

Hi Matteo,

Quoted 8 lines · Matteo Croce

From: Matteo Croce <[email protected]>

Add a missing man page for cachestat().
The text was converted from the commit message:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=cf264e1329fb0307e044f7675849f9f38b44c11a

Signed-off-by Nhat Pham <[email protected]>
Signed-off-by Matteo Croce <[email protected]>

Thanks! The patch looks good. I was going to push it, when CI reported some issues:

MANDOC .tmp/man/man2/cachestat.2.lint-man.mandoc.touch
mandoc: .tmp/man/man2/cachestat.2:60:3: ERROR: skipping unknown macro: If
mandoc: .tmp/man/man2/cachestat.2:27:2: STYLE: fill mode already disabled, skipping: nf

See comments about that below.

Quoted 28 lines
---
 man/man2/cachestat.2 | 111 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 111 insertions(+)
 create mode 100644 man/man2/cachestat.2
man/man2/cachestat.2 new file +17 -0
new file mode 100644
index 000000000..12dbd900d
@@ -0,0 +1,111 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH cachestat 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+cachestat \- query the page cache statistics of a file
+.SH SYNOPSIS
+.nf
+.B #include <sys/mman.h>
+.P
+.B struct cachestat_range {
+.B "    __u64 off;"
+.B "    __u64 len;"
+.B };
+.P
+.B struct cachestat {

man/man2/cachestat.2 line 27

Quoted 10 lines
man/man2/cachestat.2 new file +10 -0
+.B "    __u64 nr_cache;"
+.B "    __u64 nr_dirty;"
+.B "    __u64 nr_writeback;"
+.B "    __u64 nr_evicted;"
+.B "    __u64 nr_recently_evicted;"
+.B };
+.P
+.BI "int cachestat(unsigned int " fd ", struct cachestat_range *" cstat_range ","
+.BI "              struct cachestat *" cstat ", unsigned int " flags ");"
+.nf

This should be .fi (.nf is no-fill mode, while .fi ends that --it starts fill mode again--)

Quoted 23 lines
man/man2/cachestat.2 new file +23 -0
+.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

man/man2/cachestat.2 line 60

Quoted 10 lines
man/man2/cachestat.2 new file +10 -0
+The
+.I .off
+and
+.I .len
+fields must be non-negative.
+If
+.IR .len\~>\~0 ,
+the queried range is
+.RI [ .off ,\~ .off+.len ]
+. If

The '.' should go in the previous line.

Have a lovely day!
Alex

Quoted 55 lines
man/man2/cachestat.2 new file +51 -0
+.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 appropriately.
+.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.
Signature · 1 line
2.49.0
Signature · 1 line
<https://www.alejandro-colomar.es/>
author
#2 lore raw

Il giorno mer 11 giu 2025 alle ore 11:09 Alejandro Colomar <[email protected]> ha scritto:

Quoted 13 lines

Hi Matteo,

Quoted 8 lines · Matteo Croce

From: Matteo Croce <[email protected]>

Add a missing man page for cachestat().
The text was converted from the commit message:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=cf264e1329fb0307e044f7675849f9f38b44c11a

Signed-off-by Nhat Pham <[email protected]>
Signed-off-by Matteo Croce <[email protected]>
Quoted 7 lines

Thanks! The patch looks good. I was going to push it, when CI reported some issues:

MANDOC .tmp/man/man2/cachestat.2.lint-man.mandoc.touch
mandoc: .tmp/man/man2/cachestat.2:60:3: ERROR: skipping unknown macro: If
mandoc: .tmp/man/man2/cachestat.2:27:2: STYLE: fill mode already disabled, skipping: nf

Oh nice, didn't know about mandoc. I'm using it to validate the man page with:

mandoc -W base,stop man/man2/cachestat.2

thanks!

Quoted 81 lines

See comments about that below.

Quoted 28 lines
---
 man/man2/cachestat.2 | 111 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 111 insertions(+)
 create mode 100644 man/man2/cachestat.2
man/man2/cachestat.2 new file +17 -0
new file mode 100644
index 000000000..12dbd900d
@@ -0,0 +1,111 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH cachestat 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+cachestat \- query the page cache statistics of a file
+.SH SYNOPSIS
+.nf
+.B #include <sys/mman.h>
+.P
+.B struct cachestat_range {
+.B "    __u64 off;"
+.B "    __u64 len;"
+.B };
+.P
+.B struct cachestat {

man/man2/cachestat.2 line 27

Quoted 10 lines
man/man2/cachestat.2 new file +10 -0
+.B "    __u64 nr_cache;"
+.B "    __u64 nr_dirty;"
+.B "    __u64 nr_writeback;"
+.B "    __u64 nr_evicted;"
+.B "    __u64 nr_recently_evicted;"
+.B };
+.P
+.BI "int cachestat(unsigned int " fd ", struct cachestat_range *" cstat_range ","
+.BI "              struct cachestat *" cstat ", unsigned int " flags ");"
+.nf

This should be .fi (.nf is no-fill mode, while .fi ends that --it starts fill mode again--)

Quoted 23 lines
man/man2/cachestat.2 new file +23 -0
+.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

man/man2/cachestat.2 line 60

Quoted 10 lines
man/man2/cachestat.2 new file +10 -0
+The
+.I .off
+and
+.I .len
+fields must be non-negative.
+If
+.IR .len\~>\~0 ,
+the queried range is
+.RI [ .off ,\~ .off+.len ]
+. If

The '.' should go in the previous line.

Quoted 3 lines

Have a lovely day!
Alex

I'm fixing these errors now, have a lovely day too!

Signature · 3 lines
Matteo Croce

perl -e 'for($t=0;;$t++){print chr($t*($t>>8|$t>>13)&255)}' |aplay
maintainer
#3 lore raw

Hi Matteo,

Quoted 8 lines · Matteo Croce
Quoted 4 lines

MANDOC .tmp/man/man2/cachestat.2.lint-man.mandoc.touch
mandoc: .tmp/man/man2/cachestat.2:60:3: ERROR: skipping unknown macro: If
mandoc: .tmp/man/man2/cachestat.2:27:2: STYLE: fill mode already disabled, skipping: nf

Oh nice, didn't know about mandoc. I'm using it to validate the man page with:

mandoc -W base,stop man/man2/cachestat.2

I use mandoc -Tlint man/man2/cachestat.2 (except that I ignore a few of those warnings). Here's the exact command that runs in the build system (and thus in my CI):

	$ make lint-man-mandoc -R --debug=print |& head -n8
	make: warning: undefined variable 'GNUMAKEFLAGS'
	MANDOC		.tmp/man/man2/ioctl_fs.2.lint-man.mandoc.touch
	! (mandoc -Tlint  .tmp/man/man2/ioctl_fs.2 2>&1 \
	   | grep -v -f '/srv/alx/src/linux/man-pages/man-pages/master/share/mk/lint/man/mandoc.ignore.grep' \
	   || true; \
	) \
	| grep ^ >&2
	touch .tmp/man/man2/ioctl_fs.2.lint-man.mandoc.touch

You can run make -R -j4 lint-man-mandoc to lint it with the usual exceptions that I configured. Or make -R -j4 lint build-all check to run even more checks. Help about those is under CONTRIBUTING.d/ and with make -R help.

Quoted 1 line

I'm fixing these errors now, have a lovely day too!

:-)

Cheers,
Alex

Signature · 1 line
<https://www.alejandro-colomar.es/>