[PATCH 0/3] man-pages: add documentation for statmount/listmount

[PATCH 0/3] man-pages: add documentation for statmount/listmount

[Josef Bacik]

Hello,

We don't have docs for statmount(2) or listmount(2) yet, so here is a first pass
at this.  I've never had to write man pages, and the `make lint` thing doesn't
work because it's looking for checkpatch, but if I put checkpatch.pl in my path
it messes up.

I was able to run make check and fix up a variety of format things, so hopefully
these are usable.

In any case I've added to the statx(2) doc for the new STATX_MNT_ID_UNIQUE that
is needed to utlize any of this.

I've added two man pages, one for statmount(2) and listmount(2).  This reflects
the current state of what is in Linus's tree, it doesn't have any of the
additions Christian and I have done recently, I will fix them up later when
those changes are merged.  Thanks,

Josef

Josef Bacik (3):
  statx.2: Document STATX_MNT_ID_UNIQUE
  statmount.2: New page describing the statmount syscall
  listmount.2: New page describing the listmount syscall

 man/man2/listmount.2 | 107 +++++++++++++++++
 man/man2/statmount.2 | 274 +++++++++++++++++++++++++++++++++++++++++++
 man/man2/statx.2     |  12 +-
 3 files changed, 391 insertions(+), 2 deletions(-)
 create mode 100644 man/man2/listmount.2
 create mode 100644 man/man2/statmount.2

-- 
2.43.0

[PATCH 1/3] statx.2: Document STATX_MNT_ID_UNIQUE

[Josef Bacik]

Linux 6.8 adds STATX_MNT_ID_UNIQUE support
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=98d2b43081972

Add the text and explanation to the statx man page.

Signed-off-by: Josef Bacik <josef@toxicpanda.com>
---
 man/man2/statx.2 | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/man/man2/statx.2 b/man/man2/statx.2
index 0dcf7e20b..3d5ecd651 100644
--- a/man/man2/statx.2
+++ b/man/man2/statx.2
@@ -234,7 +234,7 @@ .SH DESCRIPTION
 .I mask
 is an ORed combination of the following constants:
 .P
-.in +4n
+.in +1n
 .TS
 lB l.
 STATX_TYPE	Want stx_mode & S_IFMT
@@ -255,6 +255,7 @@ .SH DESCRIPTION
 STATX_MNT_ID	Want stx_mnt_id (since Linux 5.8)
 STATX_DIOALIGN	Want stx_dio_mem_align and stx_dio_offset_align
 	(since Linux 6.1; support varies by filesystem)
+STATX_MNT_ID_UNIQUE	Want unique stx_mnt_id (since Linux 6.8)
 .TE
 .in
 .P
@@ -410,11 +411,18 @@ .SH DESCRIPTION
 .TP
 .I stx_mnt_id
 .\" commit fa2fcf4f1df1559a0a4ee0f46915b496cc2ebf60
-The mount ID of the mount containing the file.
+If using STATX_MNT_ID, this is the mount ID of the mount containing the file.
 This is the same number reported by
 .BR name_to_handle_at (2)
 and corresponds to the number in the first field in one of the records in
 .IR /proc/self/mountinfo .
+.IP
+If using STATX_MNT_ID_UNIQUE, this is the unique mount ID of the mount
+containing the file.  This is the number reported by
+.BR listmount (2)
+and is the ID used to query the mount with
+.BR statmount (2) .
+It is guaranteed to not be reused while the system is running.
 .TP
 .I stx_dio_mem_align
 The alignment (in bytes) required for user memory buffers for direct I/O
-- 
2.43.0

Re: [PATCH 1/3] statx.2: Document STATX_MNT_ID_UNIQUE

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2294 bytes --]

On Tue, Jun 25, 2024 at 02:56:04PM GMT, Josef Bacik wrote:
> Linux 6.8 adds STATX_MNT_ID_UNIQUE support
> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=98d2b43081972
> 
> Add the text and explanation to the statx man page.
> 
> Signed-off-by: Josef Bacik <josef@toxicpanda.com>

Hi Josef,

Thanks for the patch.  I've applied it with some minor tweaks.  I
changed mostly the line breaks (see /Use semantic newlines/ in
man-pages(7)).

<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=080218fbb88a94db7a9b24858ee5bad2610f13d5>

Have a lovely night!
Alex

> ---
>  man/man2/statx.2 | 12 ++++++++++--
>  1 file changed, 10 insertions(+), 2 deletions(-)
> 
> diff --git a/man/man2/statx.2 b/man/man2/statx.2
> index 0dcf7e20b..3d5ecd651 100644
> --- a/man/man2/statx.2
> +++ b/man/man2/statx.2
> @@ -234,7 +234,7 @@ .SH DESCRIPTION
>  .I mask
>  is an ORed combination of the following constants:
>  .P
> -.in +4n
> +.in +1n
>  .TS
>  lB l.
>  STATX_TYPE	Want stx_mode & S_IFMT
> @@ -255,6 +255,7 @@ .SH DESCRIPTION
>  STATX_MNT_ID	Want stx_mnt_id (since Linux 5.8)
>  STATX_DIOALIGN	Want stx_dio_mem_align and stx_dio_offset_align
>  	(since Linux 6.1; support varies by filesystem)
> +STATX_MNT_ID_UNIQUE	Want unique stx_mnt_id (since Linux 6.8)
>  .TE
>  .in
>  .P
> @@ -410,11 +411,18 @@ .SH DESCRIPTION
>  .TP
>  .I stx_mnt_id
>  .\" commit fa2fcf4f1df1559a0a4ee0f46915b496cc2ebf60
> -The mount ID of the mount containing the file.
> +If using STATX_MNT_ID, this is the mount ID of the mount containing the file.
>  This is the same number reported by
>  .BR name_to_handle_at (2)
>  and corresponds to the number in the first field in one of the records in
>  .IR /proc/self/mountinfo .
> +.IP
> +If using STATX_MNT_ID_UNIQUE, this is the unique mount ID of the mount
> +containing the file.  This is the number reported by
> +.BR listmount (2)
> +and is the ID used to query the mount with
> +.BR statmount (2) .
> +It is guaranteed to not be reused while the system is running.
>  .TP
>  .I stx_dio_mem_align
>  The alignment (in bytes) required for user memory buffers for direct I/O
> -- 
> 2.43.0
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/3] statx.2: Document STATX_MNT_ID_UNIQUE

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 988 bytes --]

[trimming CC list for this formatting issue]

At 2024-06-25T14:56:04-0400, Josef Bacik wrote:
[...]
> -.in +4n
> +.in +1n
>  .TS
>  lB l.
>  STATX_TYPE	Want stx_mode & S_IFMT
> @@ -255,6 +255,7 @@ .SH DESCRIPTION
>  STATX_MNT_ID	Want stx_mnt_id (since Linux 5.8)
>  STATX_DIOALIGN	Want stx_dio_mem_align and stx_dio_offset_align
>  	(since Linux 6.1; support varies by filesystem)
> +STATX_MNT_ID_UNIQUE	Want unique stx_mnt_id (since Linux 6.8)
>  .TE

In my opinion this would have been better done by retaining the existing
indentation and changing the table to (1) expand the right-hand column
with the "x" column modifier and (2) using text blocks for lengthy items
in the right column.  tbl(1) in groff 1.23.0 covers this ground.

Alex, your acceptance of this patch isn't showing up for me yet.

$ git remote get-url origin
https://git.kernel.org/pub/scm/docs/man-pages/man-pages/

I guess it's only on your staging site so far?

Anyway, let me know if you agree.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/3] statx.2: Document STATX_MNT_ID_UNIQUE

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1420 bytes --]

Hi Branden,

On Tue, Jun 25, 2024 at 07:39:45PM GMT, G. Branden Robinson wrote:
> [trimming CC list for this formatting issue]
> 
> At 2024-06-25T14:56:04-0400, Josef Bacik wrote:
> [...]
> > -.in +4n
> > +.in +1n
> >  .TS
> >  lB l.
> >  STATX_TYPE	Want stx_mode & S_IFMT
> > @@ -255,6 +255,7 @@ .SH DESCRIPTION
> >  STATX_MNT_ID	Want stx_mnt_id (since Linux 5.8)
> >  STATX_DIOALIGN	Want stx_dio_mem_align and stx_dio_offset_align
> >  	(since Linux 6.1; support varies by filesystem)
> > +STATX_MNT_ID_UNIQUE	Want unique stx_mnt_id (since Linux 6.8)
> >  .TE
> 
> In my opinion this would have been better done by retaining the existing
> indentation and changing the table to (1) expand the right-hand column
> with the "x" column modifier and (2) using text blocks for lengthy items
> in the right column.  tbl(1) in groff 1.23.0 covers this ground.
> 
> Alex, your acceptance of this patch isn't showing up for me yet.
> 
> $ git remote get-url origin
> https://git.kernel.org/pub/scm/docs/man-pages/man-pages/
> 
> I guess it's only on your staging site so far?

Yep; it's on my staging site.

And I agree; I dislike that +1n.  But I didn't come up with a good
solution.

> 
> Anyway, let me know if you agree.

Sure.  Do you want to send a patch against my remote?

Have a lovely night!
Alex

> 
> Regards,
> Branden



-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH 2/3] statmount.2: New page describing the statmount syscall

[Josef Bacik]

Add some documentation on the new statmount syscall.

Signed-off-by: Josef Bacik <josef@toxicpanda.com>
---
 man/man2/statmount.2 | 274 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 274 insertions(+)
 create mode 100644 man/man2/statmount.2

diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
new file mode 100644
index 000000000..6d9f505f9
--- /dev/null
+++ b/man/man2/statmount.2
@@ -0,0 +1,274 @@
+'\" t
+.\" Copyright (c) 2024 Josef Bacik <josef@toxicpanda.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH statmount 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+statmount \- get a mount status
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/mount.h>" "     /* Definition of STATMOUNT_* constants */"
+.B #include <unistd.h>
+.P
+.BI "int syscall(SYS_statmount, struct mnt_id_req * " req ,
+.BI "            struct statmount * " statmountbuf ", size_t " bufsize ,
+.BI "            unsigned long " flags " );
+.P
+.EX
+.B struct mnt_id_req {
+.BR "    __u32 size;" "    /* sizeof(struct mnt_id_req) */"
+.BR "    __u64 mnt_id;" "  /* The mnt_id being queried */"
+.BR "    __u64 param;" "   /* An ORed combination of the STATMOUNT_ constants */"
+.B };
+.EE
+.fi
+.P
+.IR Note :
+glibc provides no wrapper for
+.BR statmount (),
+necessitating the use of
+.BR syscall (2).
+.SH DESCRIPTION
+To access a mount's status, you must have CAP_SYS_ADMIN in the user namespace.
+.P
+This function returns information about a mount, storing it in the buffer
+pointed to by
+.IR buf .
+The returned buffer is a structure of the following type:
+.P
+.in +4n
+.EX
+struct statmount {
+    __u32 size;
+    __u64 mask;
+    __u32 sb_dev_major;
+    __u32 sb_dev_minor;
+    __u64 sb_magic;
+    __u32 sb_flags;
+    __u32 fs_type;
+    __u64 mnt_id;
+    __u64 mnt_parent_id;
+    __u32 mnt_id_old;
+    __u32 mnt_parent_id_old;
+    __u64 mnt_attr;
+    __u64 mnt_propagation;
+    __u64 mnt_peer_group;
+    __u64 mnt_master;
+    __u64 propagate_from;
+    __u32 mnt_root;
+    __u32 mnt_point;
+    char str[];
+};
+.EE
+.in
+.P
+(Note that reserved space and padding is omitted.)
+.SS The mnt_id_req structure
+.I req.size
+is used by the kernel to determine which struct
+.I mnt_id_req
+is being passed in, it should always be set to sizeof(struct mnt_id req).
+.P
+.I req.mnt_id
+can be obtained from either
+.BR statx (2)
+using
+.B STATX_MNT_ID_UNIQUE
+or from
+.BR listmount (2)
+and is used as the identifier to query the status of the desired mount point.
+.P
+.I req.param
+is used to tell the kernel which fields the caller is interested in.  It is an
+ORed combination of the following constants
+.P
+.in +4n
+.TS
+lBl.
+STATMOUNT_SB_BASIC	/* Want/got sb_... */
+STATMOUNT_MNT_BASIC	/* Want/got mnt_... */
+STATMOUNT_PROPAGATE_FROM	/* Want/got propagate_from */
+STATMOUNT_MNT_ROOT	/* Want/got mnt_root  */
+STATMOUNT_MNT_POINT	/* Want/got mnt_point */
+STATMOUNT_FS_TYPE	/* Want/got fs_type */
+.TE
+.in
+.P
+Note that, in general, the kernel does
+.I not
+reject values in
+.I req.param
+other than the above.
+(For an exception, see
+.B EINVAL
+in errors.)
+Instead, it simply informs the caller which values are supported
+by this kernel and filesystem via the
+.I statmount.mask
+field.
+Therefore,
+.I "do not"
+simply set
+.I req.param
+to
+.B UINT_MAX
+(all bits set),
+as one or more bits may, in the future, be used to specify an
+extension to the buffer.
+.SS
+The returned information
+The status information for the target mount is returned in the
+.I statmount
+structure pointed to by
+.IR statmountbuf .
+Included in this is
+.I size
+which indicates the size of the
+.I statmountbuf
+that was filled in, including any strings.
+.I mask
+which indicates what information in the structure has been filled in.
+.P
+It should be noted that the kernel may return fileds that weren't requested and
+may fail to return fields that were requested, depending on what the backing
+file system and kernel supports.
+In either case,
+.I req.param
+will not be equal to
+.IR mask .
+.P
+Apart from
+.I mask
+(which is described above), the fields in the
+.I statmount
+structure are:
+.TP
+.I size
+The size of the returned
+.I statmountbuf
+structure.
+.TP
+.IR sb_dev_major " and " sb_dev_minor
+The device that is mounted at this mount point.
+.TP
+.I sb_magic
+The file system specific super block magic.
+.TP
+.I sb_flags
+The flags that are set on the super block, an ORed combination of
+.BR SB_RDONLY ,
+.BR SB_SYNCHRONOUS ,
+.BR SB_DIRSYNC ,
+.BR SB_LAZYTIME .
+.TP
+.I fs_type
+The offset to the location in the
+.I statmount.str
+buffer that contains the string representation of the mounted file system. It is
+a NULL terminated string.
+.TP
+.I mnt_id
+The unique mount ID of the mount.
+.TP
+.I mnt_parent_id
+The unique mount ID of the parent mount point of this mount.  If this is the
+root mount point then
+.B mnt_id
+==
+.BR parent_mount_id .
+.TP
+.I mnt_id_old
+This corresponds to the mount ID that is exported by /proc/$PID/mountinfo.
+.TP
+.I mnt_parent_id_old
+This corresponds to the parent mount ID that is exported by
+/proc/$PID/mountinfo.
+.TP
+.I mnt_attr
+The
+.B MOUNT_ATTR_
+flags set on this mount point.
+.TP
+.I mnt_propagation
+The mount propagation flags, which can be one of
+.BR MS_SHARED ,
+.BR MS_SLAVE ,
+.BR MS_PRIVATE ,
+.BR MS_UNBINDABLE .
+.TP
+.I mnt_peer_group
+The ID of the shared peer group.
+.TP
+.I mnt_master
+The mount point receives its propagation from this mount ID.
+.TP
+.I propagate_from
+The ID from the namespace we propagated from.
+.TP
+.I mnt_root
+The offset to the location in the
+.I statmount.str
+buffer that contains the string representation of the mount relative to the root
+of the file system. It is a NULL terminated string.
+.TP
+.I mnt_point
+The offset to the location in the
+.I statmount.str
+buffer that contains the string representation of the mount relative to the
+current root (ie if you are in a
+.BR chroot ).
+It is a NULL terminated string.
+.SH RETURN VALUE
+On success, zero is returned.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EPERM
+Permission is denied for accessing this mount.
+.TP
+.B EFAULT
+.I req
+or
+.I statmountbuf
+is NULL or points to a location outside the process's
+accessible address space.
+.TP
+.B EINVAL
+Invalid flag specified in
+.IR flags .
+.TP
+.B EINVAL
+.I req
+is of insufficient size to be utilized.
+.B E2BIG
+.I req
+is too large, the limit is the architectures page size.
+.TP
+.B EOVERFLOW
+The size of
+.I statmountbuf
+is too small to contain either the
+.IR statmountbuf.fs_type ,
+.IR statmountbuf.mnt_root ,
+or
+.IR statmountbuf.mnt_point .
+Allocate a larger buffer and retry the call.
+.TP
+.B ENOENT
+The specified
+.I req.mnt_id
+doesn't exist.
+.TP
+.B ENOMEM
+Out of memory (i.e., kernel memory).
+.SH STANDARDS
+Linux.
+.SH SEE ALSO
+.BR listmount (2),
+.BR statx (2)
-- 
2.43.0

Re: [PATCH 2/3] statmount.2: New page describing the statmount syscall

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 12057 bytes --]

On Tue, Jun 25, 2024 at 02:56:05PM GMT, Josef Bacik wrote:
> Add some documentation on the new statmount syscall.
> 
> Signed-off-by: Josef Bacik <josef@toxicpanda.com>

Hi Josef,

I get a few warnings:

$ make lint build check
MANDOC		.tmp/man/man2/statmount.2.lint-man.mandoc.touch
mandoc: .tmp/man/man2/statmount.2:19:40: STYLE: unterminated quoted argument
mandoc: .tmp/man/man2/statmount.2:21:2: STYLE: fill mode already disabled, skipping: EX
mandoc: .tmp/man/man2/statmount.2:28:2: STYLE: fill mode already enabled, skipping: fi
make: *** [/home/alx/src/linux/man-pages/man-pages/contrib/share/mk/lint/man/mandoc.mk:36: .tmp/man/man2/statmount.2.lint-man.mandoc.touch] Error 1

> ---
>  man/man2/statmount.2 | 274 +++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 274 insertions(+)
>  create mode 100644 man/man2/statmount.2
> 
> diff --git a/man/man2/statmount.2 b/man/man2/statmount.2
> new file mode 100644
> index 000000000..6d9f505f9
> --- /dev/null
> +++ b/man/man2/statmount.2
> @@ -0,0 +1,274 @@
> +'\" t
> +.\" Copyright (c) 2024 Josef Bacik <josef@toxicpanda.com>
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH statmount 2 (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +statmount \- get a mount status
> +.SH LIBRARY
> +Standard C library
> +.RI ( libc ", " \-lc )
> +.SH SYNOPSIS
> +.nf
> +.BR "#include <linux/mount.h>" "     /* Definition of STATMOUNT_* constants */"

Please use only 2 spaces before /*.

> +.B #include <unistd.h>
> +.P
> +.BI "int syscall(SYS_statmount, struct mnt_id_req * " req ,
> +.BI "            struct statmount * " statmountbuf ", size_t " bufsize ,
> +.BI "            unsigned long " flags " );

Please add here

	.P
	.B #include <linux/mount.h>

This documents which header provides the type.

> +.P

.fi

> +.EX
> +.B struct mnt_id_req {
> +.BR "    __u32 size;" "    /* sizeof(struct mnt_id_req) */"
> +.BR "    __u64 mnt_id;" "  /* The mnt_id being queried */"
> +.BR "    __u64 param;" "   /* An ORed combination of the STATMOUNT_ constants */"
> +.B };
> +.EE
> +.fi

This .fi moved to above.  I guess you started working on these pages
before 2024-06-17 when I fixed that warning.  Sorry.  :)

	commit a911df9e88dedc801bed50eb92c26002729af9c0
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   Mon Jun 17 01:18:39 2024 +0200

	    man/, share/mk/: Fix nested EX/EE within nf/fi
	    
	    EX/EE can't be nested within nf/ni.  The mandoc(1) reports weren't
	    spurious.
	    
	    Re-enable the mandoc(1) warnings, and fix the code.
	    
	    Fixes: 31203a0c8dbf ("share/mk/: Globally disable two spurious mandoc(1) warnings")
	    Link: <https://lists.gnu.org/archive/html/groff/2024-06/msg00019.html>
	    Reported-by: Douglas McIlroy <douglas.mcilroy@dartmouth.edu>
	    Cc: "G. Branden Robinson" <branden@debian.org>
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

> +.P
> +.IR Note :
> +glibc provides no wrapper for
> +.BR statmount (),
> +necessitating the use of
> +.BR syscall (2).
> +.SH DESCRIPTION
> +To access a mount's status, you must have CAP_SYS_ADMIN in the user namespace.
> +.P
> +This function returns information about a mount, storing it in the buffer

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.

> +pointed to by
> +.IR buf .
> +The returned buffer is a structure of the following type:
> +.P
> +.in +4n
> +.EX
> +struct statmount {
> +    __u32 size;
> +    __u64 mask;
> +    __u32 sb_dev_major;
> +    __u32 sb_dev_minor;
> +    __u64 sb_magic;
> +    __u32 sb_flags;
> +    __u32 fs_type;
> +    __u64 mnt_id;
> +    __u64 mnt_parent_id;
> +    __u32 mnt_id_old;
> +    __u32 mnt_parent_id_old;
> +    __u64 mnt_attr;
> +    __u64 mnt_propagation;
> +    __u64 mnt_peer_group;
> +    __u64 mnt_master;
> +    __u64 propagate_from;
> +    __u32 mnt_root;
> +    __u32 mnt_point;
> +    char str[];
> +};

You could move this structure definition to the SYNOPSIS too.

> +.EE
> +.in
> +.P
> +(Note that reserved space and padding is omitted.)
> +.SS The mnt_id_req structure
> +.I req.size
> +is used by the kernel to determine which struct
> +.I mnt_id_req
> +is being passed in, it should always be set to sizeof(struct mnt_id req).
> +.P
> +.I req.mnt_id
> +can be obtained from either
> +.BR statx (2)
> +using
> +.B STATX_MNT_ID_UNIQUE
> +or from
> +.BR listmount (2)
> +and is used as the identifier to query the status of the desired mount point.
> +.P
> +.I req.param
> +is used to tell the kernel which fields the caller is interested in.  It is an
> +ORed combination of the following constants
> +.P
> +.in +4n
> +.TS
> +lBl.
> +STATMOUNT_SB_BASIC	/* Want/got sb_... */
> +STATMOUNT_MNT_BASIC	/* Want/got mnt_... */
> +STATMOUNT_PROPAGATE_FROM	/* Want/got propagate_from */
> +STATMOUNT_MNT_ROOT	/* Want/got mnt_root  */
> +STATMOUNT_MNT_POINT	/* Want/got mnt_point */
> +STATMOUNT_FS_TYPE	/* Want/got fs_type */
> +.TE
> +.in
> +.P
> +Note that, in general, the kernel does
> +.I not
> +reject values in
> +.I req.param
> +other than the above.
> +(For an exception, see
> +.B EINVAL
> +in errors.)
> +Instead, it simply informs the caller which values are supported
> +by this kernel and filesystem via the
> +.I statmount.mask
> +field.
> +Therefore,
> +.I "do not"
> +simply set
> +.I req.param
> +to
> +.B UINT_MAX
> +(all bits set),
> +as one or more bits may, in the future, be used to specify an
> +extension to the buffer.
> +.SS
> +The returned information

Please put the sub-section title in the same SS line.  I've fixed this
in statx.2:

<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=c2ee1116f7663c98d06a6b64c842260099f64fd2>

> +The status information for the target mount is returned in the
> +.I statmount
> +structure pointed to by
> +.IR statmountbuf .
> +Included in this is
> +.I size
> +which indicates the size of the
> +.I statmountbuf
> +that was filled in, including any strings.
> +.I mask
> +which indicates what information in the structure has been filled in.
> +.P
> +It should be noted that the kernel may return fileds that weren't requested and
> +may fail to return fields that were requested, depending on what the backing
> +file system and kernel supports.
> +In either case,
> +.I req.param
> +will not be equal to
> +.IR mask .
> +.P
> +Apart from
> +.I mask
> +(which is described above), the fields in the
> +.I statmount
> +structure are:
> +.TP
> +.I size
> +The size of the returned
> +.I statmountbuf
> +structure.
> +.TP
> +.IR sb_dev_major " and " sb_dev_minor

Hmmm, please check
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=b1b482c6ad353906adc4d796d4794fc7649cfea9>

.TP
.I sb_dev_major
.TQ
.I sb_dev_minor

> +The device that is mounted at this mount point.
> +.TP
> +.I sb_magic
> +The file system specific super block magic.
> +.TP
> +.I sb_flags
> +The flags that are set on the super block, an ORed combination of
> +.BR SB_RDONLY ,
> +.BR SB_SYNCHRONOUS ,
> +.BR SB_DIRSYNC ,
> +.BR SB_LAZYTIME .
> +.TP
> +.I fs_type
> +The offset to the location in the
> +.I statmount.str
> +buffer that contains the string representation of the mounted file system. It is
> +a NULL terminated string.

null-terminated

> +.TP
> +.I mnt_id
> +The unique mount ID of the mount.
> +.TP
> +.I mnt_parent_id
> +The unique mount ID of the parent mount point of this mount.  If this is the
> +root mount point then
> +.B mnt_id
> +==
> +.BR parent_mount_id .

.IR mnt_id\~==\~parent_mount_id .

> +.TP
> +.I mnt_id_old
> +This corresponds to the mount ID that is exported by /proc/$PID/mountinfo.
> +.TP
> +.I mnt_parent_id_old
> +This corresponds to the parent mount ID that is exported by
> +/proc/$PID/mountinfo.

.IR /proc/ pid /mountinfo .

See groff_man_style(7):

     .I [text]
            Set  text  in an italic or oblique face.  If no argument is
            given, the macro plants a one‐line input trap; text on  the
            next  line, which can be further formatted with a macro, is
            set in an italic or oblique face.

            Use italics for file and path names, for environment  vari‐
            ables,  for  C  data types, for enumeration or preprocessor
            constants in C, for variant (user‐replaceable) portions  of
            syntax synopses, for the first occurrence (only) of a tech‐
            nical  concept  being introduced, for names of journals and
            of literary works longer than an article,  and  anywhere  a
            parameter requiring replacement by the user is encountered.
            An  exception  involves  variant  text in a context already
            typeset in italics, such as file or  path  names  with  re‐
            placeable  components; in such cases, follow the convention
            of mathematical typography: set the file or  path  name  in
            italics  as  usual  but use roman for the variant part (see
            .IR and .RI below), and italics again in running roman text
            when referring to the variant material.

Have a lovely night!
Alex

> +.TP
> +.I mnt_attr
> +The
> +.B MOUNT_ATTR_
> +flags set on this mount point.
> +.TP
> +.I mnt_propagation
> +The mount propagation flags, which can be one of
> +.BR MS_SHARED ,
> +.BR MS_SLAVE ,
> +.BR MS_PRIVATE ,
> +.BR MS_UNBINDABLE .
> +.TP
> +.I mnt_peer_group
> +The ID of the shared peer group.
> +.TP
> +.I mnt_master
> +The mount point receives its propagation from this mount ID.
> +.TP
> +.I propagate_from
> +The ID from the namespace we propagated from.
> +.TP
> +.I mnt_root
> +The offset to the location in the
> +.I statmount.str
> +buffer that contains the string representation of the mount relative to the root
> +of the file system. It is a NULL terminated string.
> +.TP
> +.I mnt_point
> +The offset to the location in the
> +.I statmount.str
> +buffer that contains the string representation of the mount relative to the
> +current root (ie if you are in a
> +.BR chroot ).
> +It is a NULL terminated string.
> +.SH RETURN VALUE
> +On success, zero is returned.
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.SH ERRORS
> +.TP
> +.B EPERM
> +Permission is denied for accessing this mount.
> +.TP
> +.B EFAULT
> +.I req
> +or
> +.I statmountbuf
> +is NULL or points to a location outside the process's
> +accessible address space.
> +.TP
> +.B EINVAL
> +Invalid flag specified in
> +.IR flags .
> +.TP
> +.B EINVAL
> +.I req
> +is of insufficient size to be utilized.
> +.B E2BIG
> +.I req
> +is too large, the limit is the architectures page size.
> +.TP
> +.B EOVERFLOW
> +The size of
> +.I statmountbuf
> +is too small to contain either the
> +.IR statmountbuf.fs_type ,
> +.IR statmountbuf.mnt_root ,
> +or
> +.IR statmountbuf.mnt_point .
> +Allocate a larger buffer and retry the call.
> +.TP
> +.B ENOENT
> +The specified
> +.I req.mnt_id
> +doesn't exist.
> +.TP
> +.B ENOMEM
> +Out of memory (i.e., kernel memory).
> +.SH STANDARDS
> +Linux.
> +.SH SEE ALSO
> +.BR listmount (2),
> +.BR statx (2)
> -- 
> 2.43.0
> 
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH 3/3] listmount.2: New page describing the listmount syscall

[Josef Bacik]

Add some documentation for the new listmount syscall.

Signed-off-by: Josef Bacik <josef@toxicpanda.com>
---
 man/man2/listmount.2 | 107 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)
 create mode 100644 man/man2/listmount.2

diff --git a/man/man2/listmount.2 b/man/man2/listmount.2
new file mode 100644
index 000000000..442125a5c
--- /dev/null
+++ b/man/man2/listmount.2
@@ -0,0 +1,107 @@
+'\" t
+.\" Copyright (c) 2024 Josef Bacik <josef@toxicpanda.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH listmount 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+listmount \- get a list of mount ID's
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/mount.h>" "  /* Definition of struct mnt_id_req constants */"
+.B #include <unistd.h>
+.P
+.BI "int syscall(SYS_listmount, struct mnt_id_req * " req ,
+.BI "            u64 * " mnt_ids ", size_t " nr_mnt_ids ,
+.BI "            unsigned long " flags " );
+.P
+.EX
+.B struct mnt_id_req {
+.BR "    __u32 size;" "    /* sizeof(struct mnt_id_req) */"
+.BR "    __u64 mnt_id;" "  /* The parent mnt_id being searched */"
+.BR "    __u64 param;" "   /* The next mnt_id we want to find */"
+.B };
+.EE
+.fi
+.P
+.IR Note :
+glibc provides no wrapper for
+.BR listmount (),
+necessitating the use of
+.BR syscall (2).
+.SH DESCRIPTION
+To access the mounts in your namespace , you must have CAP_SYS_ADMIN in the user
+namespace.
+.P
+This function returns a list of mount IDs under the
+.BR req.mnt_id .
+This is meant to be used in conjuction with
+.BR statmount (2)
+in order to provide a way to iterate and discover mounted file systems.
+.SS The mnt_id_req structure
+.I req.size
+is used by the kernel to determine which struct
+.I mnt_id_req
+is being passed in, it should always be set to sizeof(struct mnt_id req).
+.P
+.I req.mnt_id
+is the parent mnt_id that we will list from, which can either be
+.B LSMT_ROOT
+which means the root mount of the current mount namespace, or a mount ID
+obtained from either
+.BR statx (2)
+using
+.B STATX_MNT_ID_UNIQUE
+or from
+.BR listmount (2) .
+.P
+.I req.param
+is used to tell the kernel what mount ID to start the list from.  This is
+useful if multiple calls to
+.BR listmount (2)
+are required. This can be set to the last mount ID returned + 1 in order to
+resume from a previous spot in the list.
+.SH RETURN VALUE
+On success, the number of entries filled into
+.I mnt_ids
+is returned, 0 if there are no more mounts left.  On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EPERM
+Permission is denied for accessing this mount.
+.TP
+.B EFAULT
+.I req
+or
+.I mnt_ids
+is NULL or points to a location outside the process's
+accessible address space.
+.TP
+.B EINVAL
+Invalid flag specified in
+.IR flags .
+.TP
+.B EINVAL
+.I req
+is of insufficient size to be utilized.
+.B E2BIG
+.I req
+is too large, the limit is the architectures page size.
+.TP
+.B ENOENT
+The specified
+.I req.mnt_id
+doesn't exist.
+.TP
+.B ENOMEM
+Out of memory (i.e., kernel memory).
+.SH STANDARDS
+Linux.
+.SH SEE ALSO
+.BR statmount (2),
+.BR statx (2)
-- 
2.43.0

Re: [PATCH 0/3] man-pages: add documentation for statmount/listmount

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1594 bytes --]

On Tue, Jun 25, 2024 at 02:56:03PM GMT, Josef Bacik wrote:
> Hello,

Hi Josef,

> We don't have docs for statmount(2) or listmount(2) yet, so here is a first pass
> at this.  I've never had to write man pages, and the `make lint` thing doesn't
> work because it's looking for checkpatch, but if I put checkpatch.pl in my path
> it messes up.

You should be able to `make -t lint-c-checkpatch` to skip those.

> I was able to run make check and fix up a variety of format things, so hopefully
> these are usable.

Great.  I'll help if there are any problems.

> 
> In any case I've added to the statx(2) doc for the new STATX_MNT_ID_UNIQUE that
> is needed to utlize any of this.
> 
> I've added two man pages, one for statmount(2) and listmount(2).  This reflects
> the current state of what is in Linus's tree, it doesn't have any of the
> additions Christian and I have done recently, I will fix them up later when
> those changes are merged.  Thanks,
> 
> Josef

Thanks!

Have a lovely day!
Alex

> 
> Josef Bacik (3):
>   statx.2: Document STATX_MNT_ID_UNIQUE
>   statmount.2: New page describing the statmount syscall
>   listmount.2: New page describing the listmount syscall
> 
>  man/man2/listmount.2 | 107 +++++++++++++++++
>  man/man2/statmount.2 | 274 +++++++++++++++++++++++++++++++++++++++++++
>  man/man2/statx.2     |  12 +-
>  3 files changed, 391 insertions(+), 2 deletions(-)
>  create mode 100644 man/man2/listmount.2
>  create mode 100644 man/man2/statmount.2
> 
> -- 
> 2.43.0
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]