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

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

[Matteo Croce]

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)"
+.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.
-- 
2.49.0

Re: [PATCH] man/man2/cachestat.2: add a man page for cachestat()

[Alejandro Colomar]

[-- 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 --]