* Re: [PATCH] man/man2/cachestat.2: add a man page for cachestat()
2025-05-22 21:21 [PATCH] man/man2/cachestat.2: add a man page for cachestat() Matteo Croce
@ 2025-05-24 18:21 ` Alejandro Colomar
0 siblings, 0 replies; 2+ messages in thread
From: Alejandro Colomar @ 2025-05-24 18:21 UTC (permalink / raw)
To: Matteo Croce; +Cc: linux-man, Nhat Pham, Johannes Weiner, Matteo Croce
[-- Attachment #1: Type: text/plain, Size: 8859 bytes --]
Hi Matteo,
On Thu, May 22, 2025 at 05:21:49PM -0400, Matteo Croce wrote:
> From: Matteo Croce <teknoraver@meta.com>
>
> 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 <nphamcs@gmail.com>
> Signed-off-by: Matteo Croce <teknoraver@meta.com>
> ---
> man/man2/cachestat.2 | 109 +++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 109 insertions(+)
> create mode 100644 man/man2/cachestat.2
>
> diff --git a/man/man2/cachestat.2 b/man/man2/cachestat.2
> new file mode 100644
> index 000000000..f741e3695
> --- /dev/null
> +++ b/man/man2/cachestat.2
> @@ -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.
See:
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=4c1c52748a06141996fccbf23fb8d9e15cba11e8>
commit 4c1c52748a06141996fccbf23fb8d9e15cba11e8
Author: Alejandro Colomar <alx@kernel.org>
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.
Cc: Ingo Schwarze <schwarze@openbsd.org>
Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
> +.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.
> +.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)
> +.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
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.
> +.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.
> +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). :)
> +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]
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 ]
> +. If
> +.I len == 0
The comma should go in this line. Otherwise, you'll see a spurious
space before the comma.
.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
> +.B 0
> +.
.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
> +points to an invalid address.
s/points/point/
> +.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.
> --
> 2.49.0
Have a lovely day!
Alex
--
<https://www.alejandro-colomar.es/>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 2+ messages in thread