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@xxxxxxxxxxxxxx>
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@xxxxxxxxxxxxxx>
> +.\"
> +.\" 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:
signature.asc
Description: PGP signature
