| Message ID | 2d72a44fa49f47bd7258d7efb931926b26de4004.1720549824.git.josef@toxicpanda.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | man-pages: add documentation for statmount/listmount | expand |
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 > >
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
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 >
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
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)
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