man/man2/cachestat.2: add a man page for cachestat()
PATCH 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 | 109 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 man/man2/cachestat.2
man/man2/cachestat.2 new file +109 -0
@@ -0,0 +1,109 @@ +.\" 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 +.B #include <sys/mman.h> +.PP +.B struct cachestat_range { +.br +.RS +__u64 off; +.br +__u64 len; +.RE +.B }; +.PP +.B struct cachestat { +.br +.RS +__u64 nr_cache; +.br +__u64 nr_dirty; +.br +__u64 nr_writeback; +.br +__u64 nr_evicted; +.br +__u64 nr_recently_evicted; +.RE +.B }; +.PP +.BI "int cachestat(unsigned int " fd ", struct cachestat_range *" cstat_range "," +.br +.BI " struct cachestat *" cstat ", unsigned int " flags ");" +.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. +.PP +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 +.B [off, off + len] +. If +.I 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 +.B 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 +points 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 19 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 | 109 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 man/man2/cachestat.2man/man2/cachestat.2 new file +0
-0
man/man2/cachestat.2 line 5
Quoted 5 lines
man/man2/cachestat.2 new file +5
-0@@ -0,0 +1,109 @@ +.\" Copyright, the authors of the Linux man-pages project +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH CACHESTAT 2 (date) "Linux man-pages (unreleased)"
Please use lowercase, since the API uses lowercase.
commit 4c1c52748a06141996fccbf23fb8d9e15cba11e8
Author: Alejandro Colomar <[email protected]> Date: Sun Oct 30 18:59:09 2022 +0100
Many pages: Use correct letter case in page titles (TH)
Scripted change:
$ find man* -type f \
| xargs grep -L '\.so' \
| while read f; do
P=$(basename $f);
T=$(grep '\.TH ' $f | cut -f2,3 -d' ' | sed 's/ /./'); p=$(echo $P | tr '[:upper:]' '[:lower:]'); t=$(echo $T | tr '[:upper:]' '[:lower:]'); Tn=$(echo $T | sed 's/\.[^.]\+$//') Pn=$(echo $P | sed 's/\.[^.]\+$//')
N=$(man_section $f NAME \
| sed -n '/NAME/,/ - /p' \
| sed 's/ - .*//' \
| grep -v '^NAME$' \
| tr ', ' '\n' \
| grep -i "^$Pn$" \
| head -n1)
test $P = $T \
&& test -n $N \
&& continue;
if test "x$p" != "x$t"; then
echo 1 $P $T $N;
elif test -z "$N"; then
echo 2 $P $T $N;
else
sed -i "/\.TH /s/$Tn/$N/" $f;
fi;
done;
On 10/30/22 23:00, G. Branden Robinson wrote:
> For those to whom this change is coming as an unpleasant surprise, the > forthcoming groff 1.23.0 features an option that will reverse this > change at rendering time.
>
> From groff_man(7):
>
> -rCT=1 Capitalize titles, setting the man page title (the first
> argument to .TH) in full capitals in headers and footers.
> This transformation is off by default because it discards
> case distinction information.
>
> This register can also be set in a site-local "man.local" file to force > it on for all pages. On Debian-based systems, this file is in > /etc/groff. The following line will do the trick.
>
> .nr CT 1
>
> The groff_man_style(7) man page offers further examples of such > rendering customization.
>
> /usr/local/share/groff/site-tmac/man.local
> Put site‐local changes and customizations into this file.
>
> .\" Use narrower indentation on terminals and similar.
> .if n .nr IN 4n
> .\" Put only one space after the end of a sentence.
> .ss 12 0 \" See groff(7).
> .\" Keep pages narrow even on wide terminals.
> .if n .if \n[LL]>78n .nr LL 78n
> .\" Ensure hyperlinks are enabled for terminals.
> .nr U 1
>
> On multi‐user systems, it is more considerate to users whose
> preferences may differ from the administrator’s to be less
> aggressive with such settings, or to permit their override
> with a user‐specific man.local file. This can be achieved by
> placing one or both of following requests at the end of the
> site‐local file.
> .soquiet \V[XDG_CONFIG_HOME]/man.local
> .soquiet \V[HOME]/.man.local
> However, a security‐sandboxed man(1) program may lack
> permission to open such files.
man/man2/cachestat.2 line 8
Quoted 3 lines
man/man2/cachestat.2 new file +3
-0+.SH NAME +cachestat \- query the page cache statistics of a file +.SH SYNOPSIS
You forgot to enclose most of the SYNOPSIS in '.nf'/'.fi'. Please have a look at ioctl_eventpoll(2) for a page that has both functions and structures in the SYNOPSIS.
man/man2/cachestat.2 line 17
Quoted 9 lines
man/man2/cachestat.2 new file +9
-0+.B #include <sys/mman.h> +.PP +.B struct cachestat_range { +.br +.RS +__u64 off; +.br +__u64 len; +.RE
Nah, we keep it simpler. See ioctl_eventpoll(2)
Quoted 13 lines
man/man2/cachestat.2 new file +13
-0+.B }; +.PP +.B struct cachestat { +.br +.RS +__u64 nr_cache; +.br +__u64 nr_dirty; +.br +__u64 nr_writeback; +.br +__u64 nr_evicted; +.br
man/man2/cachestat.2 line 40
Quoted 10 lines
man/man2/cachestat.2 new file +10
-0+__u64 nr_recently_evicted; +.RE +.B }; +.PP +.BI "int cachestat(unsigned int " fd ", struct cachestat_range *" cstat_range "," +.br +.BI " struct cachestat *" cstat ", unsigned int " flags ");" +.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
Please use semantic newlines. See man-pages(7):
$ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p';
Use semantic newlines
In the source of a manual page, new sentences should be started on
new lines, long sentences should be split into lines at clause
breaks (commas, semicolons, colons, and so on), and long clauses
should be split at phrase boundaries. This convention, sometimes
known as "semantic newlines", makes it easier to see the effect of
patches, which often operate at the level of individual sentences,
clauses, or phrases.We try to never (with some exceptions) go past the 80-col right margin; neither in the source code, nor in the rendered output.
man/man2/cachestat.2 line 43
Quoted 3 lines
man/man2/cachestat.2 new file +3
-0+.I off +and +.I len
Please refer to structure members as '.off' and '.len' instead of 'off' and 'len'. I'm working on a global change to do that in all of the pages. I think that will make it more readable, and obvious at first glance that they're structure members.
man/man2/cachestat.2 line 47
Quoted 4 lines
man/man2/cachestat.2 new file +4
-0+in the +.B cachestat_range +structure. +.PP
We now use .P instead of .PP (they are synonyms, but .PP generates a diagnostic in groff(1) when turning on style diagnostics, and writing one less byte per paragraph was nice). :)
Quoted 7 lines
man/man2/cachestat.2 new file +7
-0+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
man/man2/cachestat.2 line 64
Quoted 10 lines
man/man2/cachestat.2 new file +10
-0+argument. +.PP +The +.I off +and +.I len +fields must be non-negative. If +.I len > 0 +, the queried range is +.B [off, off + len]
The '[', ',', and ']' should be in roman. 'off', and 'off + len' should be in italics (just like in the rest of the page). So:
.RI [ off ,\~ off+len ]
man/man2/cachestat.2 line 66
Quoted 2 lines
man/man2/cachestat.2 new file +2
-0+. If +.I len == 0
The comma should go in this line. Otherwise, you'll see a spurious space before the comma.
.IR len\~==\~0 ,
man/man2/cachestat.2 line 75
Quoted 9 lines
man/man2/cachestat.2 new file +9
-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 +.B 0 +.
.BR 0 .
Quoted 11 lines
man/man2/cachestat.2 new file +11
-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()
man/man2/cachestat.2 line 96
Quoted 10 lines
man/man2/cachestat.2 new file +10
-0+returns 0. On error, \-1 is returned and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EFAULT +.I cstat +or +.I cstat_range +points to an invalid address.
s/points/point/
Quoted 15 lines
man/man2/cachestat.2 new file +13
-0+.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
Have a lovely day!
Alex
Signature · 1 line
<https://www.alejandro-colomar.es/>