man/man2/cachestat.2: add a man page for cachestat()
PATCH v4 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
--- 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
@@ -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 ");" +.fi +.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
Alejandro Colomar
maintainerHi 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=cf264e1329fb0307e044f7675849f9f38b44c11aSigned-off-by Nhat Pham <[email protected]>Signed-off-by Matteo Croce <[email protected]>
Thanks! I've applied the patch with a few amendments. I've tweaked the commit message too. See below.
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=797d642cc47ff6f1b9199e5e1d28c528409e0c14>
Quoted 24 lines
--- man/man2/cachestat.2 | 111 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 man/man2/cachestat.2man/man2/cachestat.2 new file +13
-0@@ -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;"
man/man2/cachestat.2 line 23
Quoted 10 lines
man/man2/cachestat.2 new file +10
-0+.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 };
I've wrapped the structures in EX/EE, as is done in other pages.
I've also moved them after the function prototype, to have the function stand out more.
Quoted 37 lines
man/man2/cachestat.2 new file +37
-0+.P +.BI "int cachestat(unsigned int " fd ", struct cachestat_range *" cstat_range "," +.BI " struct cachestat *" cstat ", unsigned int " flags ");" +.fi +.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
man/man2/cachestat.2 line 70
Quoted 10 lines
man/man2/cachestat.2 new file +10
-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 . +.
I've removed the line above, since it doesn't do anything.
man/man2/cachestat.2 line 82
Quoted 12 lines
man/man2/cachestat.2 new file +12
-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.
I've changed this sentence to be consistent with all other pages, which say "is set to indicate the error".
Have a lovely day!
Alex
Quoted 33 lines
man/man2/cachestat.2 new file +29
-0+.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/>
Il giorno gio 19 giu 2025 alle ore 02:16 Alejandro Colomar <[email protected]> ha scritto:
Quoted 10 lines
Hi Matteo,
Quoted 6 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
Quoted 7 lines
Quoted 2 lines
Signed-off-by Nhat Pham <[email protected]>Signed-off-by Matteo Croce <[email protected]>Thanks! I've applied the patch with a few amendments. I've tweaked the commit message too. See below.
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=797d642cc47ff6f1b9199e5e1d28c528409e0c14>
Got it, it's even better now. Thanks!
Quoted 146 lines
Quoted 24 lines
--- man/man2/cachestat.2 | 111 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 man/man2/cachestat.2man/man2/cachestat.2 new file +13
-0@@ -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;"man/man2/cachestat.2 line 23
Quoted 10 lines
man/man2/cachestat.2 new file +10
-0+.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 };I've wrapped the structures in EX/EE, as is done in other pages.
I've also moved them after the function prototype, to have the function stand out more.
Quoted 37 lines
man/man2/cachestat.2 new file +37
-0+.P +.BI "int cachestat(unsigned int " fd ", struct cachestat_range *" cstat_range "," +.BI " struct cachestat *" cstat ", unsigned int " flags ");" +.fi +.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 ]. +Ifman/man2/cachestat.2 line 70
Quoted 10 lines
man/man2/cachestat.2 new file +10
-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 . +.I've removed the line above, since it doesn't do anything.
man/man2/cachestat.2 line 82
Quoted 12 lines
man/man2/cachestat.2 new file +12
-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.I've changed this sentence to be consistent with all other pages, which say "is set to indicate the error".
Have a lovely day!
AlexQuoted 30 lines
man/man2/cachestat.2 new file +29
-1+.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. --Quoted 3 lines
2.49.0
Signature · 3 lines
Matteo Croce
perl -e 'for($t=0;;$t++){print chr($t*($t>>8|$t>>13)&255)}' |aplay