man/man2/cachestat.2: add a man page for cachestat()
PATCH v2 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 | 106 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 man/man2/cachestat.2
man/man2/cachestat.2 new file +106 -0
@@ -0,0 +1,106 @@ +.\" 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> +.PP +.B struct cachestat_range { +.BR " __u64 off;" +.BR " __u64 len;" +.RE +.B }; +.PP +.B struct cachestat { +.BR " __u64 nr_cache;" +.BR " __u64 nr_dirty;" +.BR " __u64 nr_writeback;" +.BR " __u64 nr_evicted;" +.BR " __u64 nr_recently_evicted;" +.B }; +.PP +.BI "int cachestat(unsigned int " fd ", struct cachestat_range *" cstat_range "," +.br +.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. +.PP +The results are returned in a +.B cachestat +structure, pointed to by the +.I cstat +argument. +.PP +The +.I .off +and +.I .len +fields must be non-negative. If +.I .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. +.PP +The +.I flags +argument is reserved for future use and must be set to +.BR 0 . +. +.PP +Currently, +.B hugetlbfs +files are not supported. +.PP +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. +.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.
Signature · 1 line
2.49.0
Alejandro Colomar
maintainerHi Matteo,
Quoted 20 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]>--- man/man2/cachestat.2 | 106 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 man/man2/cachestat.2man/man2/cachestat.2 new file +1
-0@@ -0,0 +1,106 @@ +.\" Copyright, the authors of the Linux man-pages project
man/man2/cachestat.2 line 11
Quoted 10 lines
man/man2/cachestat.2 new file +10
-0+.\" +.\" 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> +.PP
s/PP/P/g
man/man2/cachestat.2 line 13
Quoted 2 lines
man/man2/cachestat.2 new file +2
-0+.B struct cachestat_range { +.BR " __u64 off;"
Since these lines only have 1 argument, s/BR/B/g.
See groff_man(7):
.B [text]
Set text in bold. If no argument is given, a one‐line in‐ put trap is planted; text on the next line, which can be further formatted with a macro, is set in bold.
.BR bold‐text roman‐text ...
Set each argument in bold and roman, alternately.
man/man2/cachestat.2 line 15
Quoted 2 lines
man/man2/cachestat.2 new file +2
-0+.BR " __u64 len;" +.RE
This RE is spurious.
man/man2/cachestat.2 line 27
Quoted 12 lines
man/man2/cachestat.2 new file +12
-0+.B }; +.PP +.B struct cachestat { +.BR " __u64 nr_cache;" +.BR " __u64 nr_dirty;" +.BR " __u64 nr_writeback;" +.BR " __u64 nr_evicted;" +.BR " __u64 nr_recently_evicted;" +.B }; +.PP +.BI "int cachestat(unsigned int " fd ", struct cachestat_range *" cstat_range "," +.br
This br is spurious.
Quoted 20 lines
man/man2/cachestat.2 new file +20
-0+.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. +.PP +The results are returned in a
man/man2/cachestat.2 line 57
Quoted 10 lines
man/man2/cachestat.2 new file +10
-0+.B cachestat +structure, pointed to by the +.I cstat +argument. +.PP +The +.I .off +and +.I .len +fields must be non-negative. If
s/\. /.\n/
man/man2/cachestat.2 line 59
Quoted 2 lines
man/man2/cachestat.2 new file +2
-0+.I .len > 0 +, the queried range is
The comma should go in the previous line. Otherwise, it creates a spurious space.
.IR .len\~>\~0 ,
Quoted 11 lines
man/man2/cachestat.2 new file +11
-0+.RI [ .off ,\~ .off+.len ] +. If +.IR len\~==\~0 , +the range is from +.I .off +to the end of the file. +.PP +The +.I flags +argument is reserved for future use and must be set to +.BR 0 .
man/man2/cachestat.2 line 80
Quoted 10 lines
man/man2/cachestat.2 new file +10
-0+. +.PP +Currently, +.B hugetlbfs +files are not supported. +.PP +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.
I'd move the paragraph from above to a CAVEATS section (see man-pages(7)).
man/man2/cachestat.2 line 84
Quoted 4 lines
man/man2/cachestat.2 new file +4
-0+.SH RETURN VALUE +On success, +.B cachestat() +returns 0. On error, \-1 is returned and
s/\. /.\n/
s/ and/,\nand/
Quoted 12 lines
man/man2/cachestat.2 new file +12
-0+.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
man/man2/cachestat.2 line 106
Quoted 10 lines
man/man2/cachestat.2 new file +10
-0+.I flags +value. +.TP +.B EBADF +Invalid file descriptor. +.TP +.B EOPNOTSUPP +The file descriptor refers to a +.B hugetlbfs +file, which is unsupported.
Please add STANDARDS and HISTORY sections. You can have a look at membarrier(2) for this:
$ man -w membarrier | xargs mansect '(STANDARDS|HISTORY)' | tail -n+3; .SH STANDARDS Linux. .SH HISTORY Linux 4.3. .P Before Linux 5.10, the prototype was: .P .in +4n .EX .BI "int membarrier(int " cmd ", int " flags ); .EE .in
Quoted 2 lines
Signature · 1 line
2.49.0
Have a lovely day!
Alex
Signature · 1 line
<https://www.alejandro-colomar.es/>