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

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

[Josef Bacik]

V5: https://lore.kernel.org/linux-fsdevel/cover.1720545710.git.josef@toxicpanda.com/
V4: https://lore.kernel.org/linux-fsdevel/cover.1719840964.git.josef@toxicpanda.com/
V3: https://lore.kernel.org/linux-fsdevel/cover.1719425922.git.josef@toxicpanda.com/
V2: https://lore.kernel.org/linux-fsdevel/cover.1719417184.git.josef@toxicpanda.com/
V1: https://lore.kernel.org/linux-fsdevel/cover.1719341580.git.josef@toxicpanda.com/

v5->v6:
- Reworked all of the NULL related comments.
- Addressed the other review comments.

v4->v5:
- Described bufsize.
- Moved the general description of some of the fields to under the field labels
  themselves, and generally reworked everything to be more specific.
- Addressed the various formatting/wording review comments.

v3->v4:
- Addressed review comments.

v2->v3:
- Removed a spurious \t comment in listmount.2 (took me a while to figure out
  why it was needed in statmount.2 but not listmount.2, it's because it lets you
  know that there's a TS in the manpage).
- Fixed some unbalanced " in both pages
- Removed a EE in the nf section which is apparently not needed

v1->v2:
- Dropped the statx patch as Alejandro already took it (thanks!)
- Reworked everything to use semantic newlines
- Addressed all of the comments on the statmount.2 man page

Josef

Josef Bacik (2):
  statmount.2: New page describing the statmount syscall
  listmount.2: New page describing the listmount syscall

 man/man2/listmount.2 | 112 +++++++++++++++++
 man/man2/statmount.2 | 281 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 393 insertions(+)
 create mode 100644 man/man2/listmount.2
 create mode 100644 man/man2/statmount.2

-- 
2.43.0

[PATCH v6 1/2] 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 | 281 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 281 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..2ae1f1bc3
--- /dev/null
+++ b/man/man2/statmount.2
@@ -0,0 +1,281 @@
+'\" 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 * " smbuf ", size_t " bufsize ,
+.BI "            unsigned long " flags );
+.P
+.B #include <linux/mount.h>
+.P
+.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 };
+.P
+.B struct statmount {
+.B "    __u32 size;"
+.B "    __u64 mask;"
+.B "    __u32 sb_dev_major;"
+.B "    __u32 sb_dev_minor;"
+.B "    __u64 sb_magic;"
+.B "    __u32 sb_flags;"
+.B "    __u32 fs_type;"
+.B "    __u64 mnt_id;"
+.B "    __u64 mnt_parent_id;"
+.B "    __u32 mnt_id_old;"
+.B "    __u32 mnt_parent_id_old;"
+.B "    __u64 mnt_attr;"
+.B "    __u64 mnt_propagation;"
+.B "    __u64 mnt_peer_group;"
+.B "    __u64 mnt_master;"
+.B "    __u64 propagate_from;"
+.B "    __u32 mnt_root;"
+.B "    __u32 mnt_point;"
+.B "    char  str[];"
+.B };
+.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,
+the caller 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 smbuf .
+The returned buffer is a
+.I struct statmount
+which is of size
+.I bufsize
+with the fields filled in as described below.
+.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
+.I struct\~mnt_id_req
+is being passed in;
+it should always be set to
+.IR 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
+lB l.
+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
+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 smbuf .
+.P
+The fields in the
+.I statmount
+structure are:
+.TP
+.I smbuf.size
+The size of the returned
+.I smbuf
+structure,
+including any of the strings fields that were filled.
+.TP
+.I smbuf.mask
+The ORed combination of
+.BI STATMOUNT_ *
+flags indicating which fields were filled in and thus valid.
+The kernel may return fields 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 .
+.TP
+.I smbuf.sb_dev_major
+.TQ
+.I smbuf.sb_dev_minor
+The device that is mounted at this mount point.
+.TP
+.I smbuf.sb_magic
+The file system specific super block magic.
+.TP
+.I smbuf.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 smbuf.fs_type
+The offset to the location in the
+.I smbuf.str
+buffer that contains the string representation of the mounted file system.
+It is a null-terminated string.
+.TP
+.I smbuf.mnt_id
+The unique mount ID of the mount.
+.TP
+.I smbuf.mnt_parent_id
+The unique mount ID of the parent mount point of this mount.
+If this is the root mount point then
+.IR smbuf.mnt_id\~==\~smbuf.parent_mount_id .
+.TP
+.I smbuf.mnt_id_old
+This corresponds to the mount ID that is exported by
+.IR /proc/ pid /mountinfo .
+.TP
+.I smbuf.mnt_parent_id_old
+This corresponds to the parent mount ID that is exported by
+.IR /proc/ pid /mountinfo .
+.TP
+.I smbuf.mnt_attr
+The
+.BI MOUNT_ATTR_ *
+flags set on this mount point.
+.TP
+.I smbuf.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 smbuf.mnt_peer_group
+The ID of the shared peer group.
+.TP
+.I smbuf.mnt_master
+The mount point receives its propagation from this mount ID.
+.TP
+.I smbuf.propagate_from
+The ID from the namespace we propagated from.
+.TP
+.I smbuf.mnt_root
+The offset to the location in the
+.I smbuf.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 smbuf.mnt_point
+The offset to the location in the
+.I smbuf.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 smbuf
+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.
+.TP
+.B E2BIG
+.I req
+is too large.
+.TP
+.B EOVERFLOW
+The size of
+.I smbuf
+is too small to contain either the
+.IR smbuf.fs_type ,
+.IR smbuf.mnt_root ,
+or
+.IR smbuf.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 v6 1/2] statmount.2: New page describing the statmount syscall

[Alejandro Colomar]

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

Hi Josef,

On Tue, Jul 09, 2024 at 02:31:22PM GMT, Josef Bacik wrote:
> Add some documentation on the new statmount syscall.
> 
> Signed-off-by: Josef Bacik <josef@toxicpanda.com>

I've applied the patch, with some tweaks.
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=1e607c20633d839d9241da50071d508ef617f878>

Have a lovely day!
Alex


diff --git i/man/man2/statmount.2 w/man/man2/statmount.2
index 2ae1f1bc3..4b54a6c85 100644
--- i/man/man2/statmount.2
+++ w/man/man2/statmount.2
@@ -14,40 +14,42 @@ .SH SYNOPSIS
 .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 * " smbuf ", size_t " bufsize ,
+.BI "int syscall(SYS_statmount, struct mnt_id_req *" req ,
+.BI "            struct statmount *" smbuf ", size_t " bufsize ,
 .BI "            unsigned long " flags );
 .P
 .B #include <linux/mount.h>
+.fi
 .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 */"
+.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 };
 .P
 .B struct statmount {
-.B "    __u32 size;"
-.B "    __u64 mask;"
-.B "    __u32 sb_dev_major;"
-.B "    __u32 sb_dev_minor;"
-.B "    __u64 sb_magic;"
-.B "    __u32 sb_flags;"
-.B "    __u32 fs_type;"
-.B "    __u64 mnt_id;"
-.B "    __u64 mnt_parent_id;"
-.B "    __u32 mnt_id_old;"
-.B "    __u32 mnt_parent_id_old;"
-.B "    __u64 mnt_attr;"
-.B "    __u64 mnt_propagation;"
-.B "    __u64 mnt_peer_group;"
-.B "    __u64 mnt_master;"
-.B "    __u64 propagate_from;"
-.B "    __u32 mnt_root;"
-.B "    __u32 mnt_point;"
-.B "    char  str[];"
+.B "    __u32  size;"
+.B "    __u64  mask;"
+.B "    __u32  sb_dev_major;"
+.B "    __u32  sb_dev_minor;"
+.B "    __u64  sb_magic;"
+.B "    __u32  sb_flags;"
+.B "    __u32  fs_type;"
+.B "    __u64  mnt_id;"
+.B "    __u64  mnt_parent_id;"
+.B "    __u32  mnt_id_old;"
+.B "    __u32  mnt_parent_id_old;"
+.B "    __u64  mnt_attr;"
+.B "    __u64  mnt_propagation;"
+.B "    __u64  mnt_peer_group;"
+.B "    __u64  mnt_master;"
+.B "    __u64  propagate_from;"
+.B "    __u32  mnt_root;"
+.B "    __u32  mnt_point;"
+.B "    char   str[];"
 .B };
-.fi
+.EE
 .P
 .IR Note :
 glibc provides no wrapper for
@@ -117,7 +119,7 @@ .SS The mnt_id_req structure
 .I statmount.mask
 field.
 Therefore,
-.I "do not"
+.I do not
 simply set
 .I req.param
 to



> ---
>  man/man2/statmount.2 | 281 +++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 281 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..2ae1f1bc3
> --- /dev/null
> +++ b/man/man2/statmount.2
> @@ -0,0 +1,281 @@
> +'\" 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 * " smbuf ", size_t " bufsize ,
> +.BI "            unsigned long " flags );
> +.P
> +.B #include <linux/mount.h>
> +.P
> +.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 };
> +.P
> +.B struct statmount {
> +.B "    __u32 size;"
> +.B "    __u64 mask;"
> +.B "    __u32 sb_dev_major;"
> +.B "    __u32 sb_dev_minor;"
> +.B "    __u64 sb_magic;"
> +.B "    __u32 sb_flags;"
> +.B "    __u32 fs_type;"
> +.B "    __u64 mnt_id;"
> +.B "    __u64 mnt_parent_id;"
> +.B "    __u32 mnt_id_old;"
> +.B "    __u32 mnt_parent_id_old;"
> +.B "    __u64 mnt_attr;"
> +.B "    __u64 mnt_propagation;"
> +.B "    __u64 mnt_peer_group;"
> +.B "    __u64 mnt_master;"
> +.B "    __u64 propagate_from;"
> +.B "    __u32 mnt_root;"
> +.B "    __u32 mnt_point;"
> +.B "    char  str[];"
> +.B };
> +.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,
> +the caller 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 smbuf .
> +The returned buffer is a
> +.I struct statmount
> +which is of size
> +.I bufsize
> +with the fields filled in as described below.
> +.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
> +.I struct\~mnt_id_req
> +is being passed in;
> +it should always be set to
> +.IR 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
> +lB l.
> +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
> +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 smbuf .
> +.P
> +The fields in the
> +.I statmount
> +structure are:
> +.TP
> +.I smbuf.size
> +The size of the returned
> +.I smbuf
> +structure,
> +including any of the strings fields that were filled.
> +.TP
> +.I smbuf.mask
> +The ORed combination of
> +.BI STATMOUNT_ *
> +flags indicating which fields were filled in and thus valid.
> +The kernel may return fields 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 .
> +.TP
> +.I smbuf.sb_dev_major
> +.TQ
> +.I smbuf.sb_dev_minor
> +The device that is mounted at this mount point.
> +.TP
> +.I smbuf.sb_magic
> +The file system specific super block magic.
> +.TP
> +.I smbuf.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 smbuf.fs_type
> +The offset to the location in the
> +.I smbuf.str
> +buffer that contains the string representation of the mounted file system.
> +It is a null-terminated string.
> +.TP
> +.I smbuf.mnt_id
> +The unique mount ID of the mount.
> +.TP
> +.I smbuf.mnt_parent_id
> +The unique mount ID of the parent mount point of this mount.
> +If this is the root mount point then
> +.IR smbuf.mnt_id\~==\~smbuf.parent_mount_id .
> +.TP
> +.I smbuf.mnt_id_old
> +This corresponds to the mount ID that is exported by
> +.IR /proc/ pid /mountinfo .
> +.TP
> +.I smbuf.mnt_parent_id_old
> +This corresponds to the parent mount ID that is exported by
> +.IR /proc/ pid /mountinfo .
> +.TP
> +.I smbuf.mnt_attr
> +The
> +.BI MOUNT_ATTR_ *
> +flags set on this mount point.
> +.TP
> +.I smbuf.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 smbuf.mnt_peer_group
> +The ID of the shared peer group.
> +.TP
> +.I smbuf.mnt_master
> +The mount point receives its propagation from this mount ID.
> +.TP
> +.I smbuf.propagate_from
> +The ID from the namespace we propagated from.
> +.TP
> +.I smbuf.mnt_root
> +The offset to the location in the
> +.I smbuf.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 smbuf.mnt_point
> +The offset to the location in the
> +.I smbuf.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 smbuf
> +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.
> +.TP
> +.B E2BIG
> +.I req
> +is too large.
> +.TP
> +.B EOVERFLOW
> +The size of
> +.I smbuf
> +is too small to contain either the
> +.IR smbuf.fs_type ,
> +.IR smbuf.mnt_root ,
> +or
> +.IR smbuf.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 v6 2/2] 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 | 112 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 112 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..212929fb6
--- /dev/null
+++ b/man/man2/listmount.2
@@ -0,0 +1,112 @@
+.\" 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
+.B #include <linux/mount.h>
+.P
+.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 };
+.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
+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.
+.TP
+.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 v6 2/2] listmount.2: New page describing the listmount syscall

[Alejandro Colomar]

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

Hi Josef,

On Tue, Jul 09, 2024 at 02:31:23PM GMT, Josef Bacik wrote:
> Add some documentation for the new listmount syscall.
> 
> Signed-off-by: Josef Bacik <josef@toxicpanda.com>

Thanks!  I've applied the patch with some minor tweaks:

	diff --git i/man/man2/listmount.2 w/man/man2/listmount.2
	index 212929fb6..8f7c7afaa 100644
	--- i/man/man2/listmount.2
	+++ w/man/man2/listmount.2
	@@ -4,7 +4,9 @@
	 .\"
	 .TH listmount 2 (date) "Linux man-pages (unreleased)"
	 .SH NAME
	-listmount \- get a list of mount ID's
	+listmount
	+\-
	+get a list of mount ID's
	 .SH LIBRARY
	 Standard C library
	 .RI ( libc ", " \-lc )
	@@ -14,15 +16,15 @@ .SH SYNOPSIS
	 .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 "            uint64_t * " mnt_ids ", size_t " nr_mnt_ids ,
	 .BI "            unsigned long " flags );
	 .P
	 .B #include <linux/mount.h>
	 .P
	 .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 */"
	+.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 };
	 .fi
	 .P
	@@ -45,7 +47,8 @@ .SS The mnt_id_req structure
	 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).
	+it should always be set to
	+.IR \%sizeof(struct\~mnt_id_req) .
	 .P
	 .I req.mnt_id
	 is the parent mnt_id that we will list from,
	@@ -69,7 +72,8 @@ .SS The mnt_id_req structure
	 .SH RETURN VALUE
	 On success, the number of entries filled into
	 .I mnt_ids
	-is returned, 0 if there are no more mounts left.
	+is returned;
	+0 if there are no more mounts left.
	 On error, \-1 is returned, and
	 .I errno
	 is set to indicate the error.

Would you mind adding an example program in a new patch?

Have a lovely night!
Alex

> ---
>  man/man2/listmount.2 | 112 +++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 112 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..212929fb6
> --- /dev/null
> +++ b/man/man2/listmount.2
> @@ -0,0 +1,112 @@
> +.\" 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
> +.B #include <linux/mount.h>
> +.P
> +.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 };
> +.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
> +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.
> +.TP
> +.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
> 
> 

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

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

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

[Josef Bacik]

On Mon, Jul 22, 2024 at 10:27:23PM +0200, Alejandro Colomar wrote:
> Hi Josef,
> 
> On Tue, Jul 09, 2024 at 02:31:23PM GMT, Josef Bacik wrote:
> > Add some documentation for the new listmount syscall.
> > 
> > Signed-off-by: Josef Bacik <josef@toxicpanda.com>
> 
> Thanks!  I've applied the patch with some minor tweaks:
> 
> 	diff --git i/man/man2/listmount.2 w/man/man2/listmount.2
> 	index 212929fb6..8f7c7afaa 100644
> 	--- i/man/man2/listmount.2
> 	+++ w/man/man2/listmount.2
> 	@@ -4,7 +4,9 @@
> 	 .\"
> 	 .TH listmount 2 (date) "Linux man-pages (unreleased)"
> 	 .SH NAME
> 	-listmount \- get a list of mount ID's
> 	+listmount
> 	+\-
> 	+get a list of mount ID's
> 	 .SH LIBRARY
> 	 Standard C library
> 	 .RI ( libc ", " \-lc )
> 	@@ -14,15 +16,15 @@ .SH SYNOPSIS
> 	 .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 "            uint64_t * " mnt_ids ", size_t " nr_mnt_ids ,
> 	 .BI "            unsigned long " flags );
> 	 .P
> 	 .B #include <linux/mount.h>
> 	 .P
> 	 .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 */"
> 	+.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 };
> 	 .fi
> 	 .P
> 	@@ -45,7 +47,8 @@ .SS The mnt_id_req structure
> 	 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).
> 	+it should always be set to
> 	+.IR \%sizeof(struct\~mnt_id_req) .
> 	 .P
> 	 .I req.mnt_id
> 	 is the parent mnt_id that we will list from,
> 	@@ -69,7 +72,8 @@ .SS The mnt_id_req structure
> 	 .SH RETURN VALUE
> 	 On success, the number of entries filled into
> 	 .I mnt_ids
> 	-is returned, 0 if there are no more mounts left.
> 	+is returned;
> 	+0 if there are no more mounts left.
> 	 On error, \-1 is returned, and
> 	 .I errno
> 	 is set to indicate the error.
> 
> Would you mind adding an example program in a new patch?

Yup I can do that, I was going to follow-up with a patch for the new extensions
that have landed in this merge window, after the final release has been cut.  Is
it cool if I wait until then, or would you like something sooner?  Thanks,

Josef

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

[Alejandro Colomar]

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

Hi Josef,

On Mon, Jul 22, 2024 at 04:44:16PM GMT, Josef Bacik wrote:
> > Would you mind adding an example program in a new patch?
> 
> Yup I can do that, I was going to follow-up with a patch for the new extensions
> that have landed in this merge window, after the final release has been cut.  Is
> it cool if I wait until then, or would you like something sooner?  Thanks,

Thanks!  And sure; you can wait as much as necessary.  :-)

Have a lovely night!
Alex

> 
> Josef
> 

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

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

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

[Miklos Szeredi]

Thanks, Josef for doing the man pages.

On Tue, 9 Jul 2024 at 20:32, Josef Bacik <josef@toxicpanda.com> wrote:
> +.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

The "+ 1" is done by the kernel, so this should be just set to the
last returned mount ID.   Also maybe explicitly mention that a value
of zero is used to start from the beginning of the list (zero is a
reserved mount ID value).

Thanks,
Miklos

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

[Jeff Layton]

On Tue, 2024-07-09 at 14:31 -0400, Josef Bacik wrote:
> Add some documentation for the new listmount syscall.
> 
> Signed-off-by: Josef Bacik <josef@toxicpanda.com>
> ---
>  man/man2/listmount.2 | 112 +++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 112 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..212929fb6
> --- /dev/null
> +++ b/man/man2/listmount.2
> @@ -0,0 +1,112 @@
> +.\" 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
> +.B #include <linux/mount.h>
> +.P
> +.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 };
> +.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.

The above does not seem to be correct. I can access the mounts in my
own namespace just fine. What I can't do is access mounts in other
namespaces without CAP_SYS_ADMIN, right?

Maybe this?

"To access mounts outside your own 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) .

The above is a little vague. It's not clear whether the list is just
immediate child mounts or if you get all mounts below that point. The
implementation in the kernel is the latter. You get a list of any
descendent mount of the given mnt_id.

Should we make that more clear?

> +.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
> +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.
> +.TP
> +.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)

-- 
Jeff Layton <jlayton@kernel.org>