man2: add man pages for 'new' mount API

[PATCH v2 01/11] mount_setattr.2: document glibc >= 2.36 syscall wrappers

Posted by Aleksa Sarai 1 month, 4 weeks ago

Glibc 2.36 added syscall wrappers for the entire family of fd-based
mount syscalls, including mount_setattr(2).  Thus it's no longer
necessary to instruct users to do raw syscall(2) operations.

Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
---
 man/man2/mount_setattr.2 | 45 +++++++--------------------------------------
 1 file changed, 7 insertions(+), 38 deletions(-)

diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2
index 60d9cf9de8aa..c96f0657f046 100644
--- a/man/man2/mount_setattr.2
+++ b/man/man2/mount_setattr.2
@@ -10,21 +10,12 @@ .SH LIBRARY
 .RI ( libc ,\~ \-lc )
 .SH SYNOPSIS
 .nf
-.BR "#include <linux/fcntl.h>" " /* Definition of " AT_* " constants */"
-.BR "#include <linux/mount.h>" " /* Definition of " MOUNT_ATTR_* " constants */"
-.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
-.B #include <unistd.h>
+.BR "#include <fcntl.h>" "       /* Definition of " AT_* " constants */"
+.B #include <sys/mount.h>
 .P
-.BI "int syscall(SYS_mount_setattr, int " dirfd ", const char *" path ,
-.BI "            unsigned int " flags ", struct mount_attr *" attr \
-", size_t " size );
+.BI "int mount_setattr(int " dirfd ", const char *" path ", unsigned int " flags ","
+.BI "                  struct mount_attr *" attr ", size_t " size );"
 .fi
-.P
-.IR Note :
-glibc provides no wrapper for
-.BR mount_setattr (),
-necessitating the use of
-.BR syscall (2).
 .SH DESCRIPTION
 The
 .BR mount_setattr ()
@@ -586,6 +577,7 @@ .SH HISTORY
 .\" commit 7d6beb71da3cc033649d641e1e608713b8220290
 .\" commit 2a1867219c7b27f928e2545782b86daaf9ad50bd
 .\" commit 9caccd41541a6f7d6279928d9f971f6642c361af
+glibc 2.36.
 .SH NOTES
 .SS ID-mapped mounts
 Creating an ID-mapped mount makes it possible to
@@ -914,37 +906,14 @@ .SH EXAMPLES
 #include <err.h>
 #include <fcntl.h>
 #include <getopt.h>
-#include <linux/mount.h>
-#include <linux/types.h>
+#include <sys/mount.h>
+#include <sys/types.h>
 #include <stdbool.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
-#include <sys/syscall.h>
 #include <unistd.h>
 \&
-static inline int
-mount_setattr(int dirfd, const char *path, unsigned int flags,
-              struct mount_attr *attr, size_t size)
-{
-    return syscall(SYS_mount_setattr, dirfd, path, flags,
-                   attr, size);
-}
-\&
-static inline int
-open_tree(int dirfd, const char *filename, unsigned int flags)
-{
-    return syscall(SYS_open_tree, dirfd, filename, flags);
-}
-\&
-static inline int
-move_mount(int from_dirfd, const char *from_path,
-           int to_dirfd, const char *to_path, unsigned int flags)
-{
-    return syscall(SYS_move_mount, from_dirfd, from_path,
-                   to_dirfd, to_path, flags);
-}
-\&
 static const struct option longopts[] = {
     {"map\-mount",       required_argument,  NULL,  \[aq]a\[aq]},
     {"recursive",       no_argument,        NULL,  \[aq]b\[aq]},

-- 
2.50.1

Re: [PATCH v2 01/11] mount_setattr.2: document glibc >= 2.36 syscall wrappers

Posted by Askar Safin 1 month, 3 weeks ago

When I render "mount_setattr" from this (v2) pathset, I see weird quote mark. I. e.:

$ MANWIDTH=10000 man /path/to/mount_setattr.2
...
SYNOPSIS
       #include <fcntl.h>       /* Definition of AT_* constants */
       #include <sys/mount.h>

       int mount_setattr(int dirfd, const char *path, unsigned int flags,
                         struct mount_attr *attr, size_t size);"
...

--
Askar Safin
https://types.pl/@safinaskar

Re: [PATCH v2 01/11] mount_setattr.2: document glibc >= 2.36 syscall wrappers

Posted by Aleksa Sarai 1 month, 3 weeks ago

On 2025-08-08, Askar Safin <safinaskar@zohomail.com> wrote:
> When I render "mount_setattr" from this (v2) pathset, I see weird quote mark. I. e.:
> 
> $ MANWIDTH=10000 man /path/to/mount_setattr.2
> ...
> SYNOPSIS
>        #include <fcntl.h>       /* Definition of AT_* constants */
>        #include <sys/mount.h>
> 
>        int mount_setattr(int dirfd, const char *path, unsigned int flags,
>                          struct mount_attr *attr, size_t size);"
> ...

Ah, my bad. "make -R lint-man" told me to put end quotes on the synopsis
lines, but I missed that there was a separate quote missing. This should
fix it:

diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2
index d44fafc93a20..46fcba927dd8 100644
--- a/man/man2/mount_setattr.2
+++ b/man/man2/mount_setattr.2
@@ -14,7 +14,7 @@ .SH SYNOPSIS
 .B #include <sys/mount.h>
 .P
 .BI "int mount_setattr(int " dirfd ", const char *" path ", unsigned int " flags ","
-.BI "                  struct mount_attr *" attr ", size_t " size );"
+.BI "                  struct mount_attr *" attr ", size_t " size ");"
 .fi
 .SH DESCRIPTION
 The


-- 
Aleksa Sarai
Senior Software Engineer (Containers)
SUSE Linux GmbH
https://www.cyphar.com/

Re: [PATCH v2 01/11] mount_setattr.2: document glibc >= 2.36 syscall wrappers

Posted by Alejandro Colomar 1 month, 3 weeks ago

Hi Aleksa, Askar,

On Fri, Aug 08, 2025 at 09:55:10PM +1000, Aleksa Sarai wrote:
> On 2025-08-08, Askar Safin <safinaskar@zohomail.com> wrote:
> > When I render "mount_setattr" from this (v2) pathset, I see weird quote mark. I. e.:
> > 
> > $ MANWIDTH=10000 man /path/to/mount_setattr.2
> > ...
> > SYNOPSIS
> >        #include <fcntl.h>       /* Definition of AT_* constants */
> >        #include <sys/mount.h>
> > 
> >        int mount_setattr(int dirfd, const char *path, unsigned int flags,
> >                          struct mount_attr *attr, size_t size);"
> > ...
> 
> Ah, my bad. "make -R lint-man" told me to put end quotes on the synopsis
> lines, but I missed that there was a separate quote missing. This should
> fix it:
> 
> diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2
> index d44fafc93a20..46fcba927dd8 100644
> --- a/man/man2/mount_setattr.2
> +++ b/man/man2/mount_setattr.2
> @@ -14,7 +14,7 @@ .SH SYNOPSIS
>  .B #include <sys/mount.h>
>  .P
>  .BI "int mount_setattr(int " dirfd ", const char *" path ", unsigned int " flags ","
> -.BI "                  struct mount_attr *" attr ", size_t " size );"
> +.BI "                  struct mount_attr *" attr ", size_t " size ");"

Actually, I'd use

.BI "                  struct mount_attr *" attr ", size_t " size );

>  .fi
>  .SH DESCRIPTION
>  The

Hmmm, thanks for the catch!  My CI server is down until I come back home
and have a chance to fix it.


Have a lovely day!
Alex

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

Re: [PATCH v2 01/11] mount_setattr.2: document glibc >= 2.36 syscall wrappers

Posted by Alejandro Colomar 1 month, 3 weeks ago

Hi Aleksa, Askar,

On Sat, Aug 09, 2025 at 12:42:58PM +0200, Alejandro Colomar wrote:
> Hi Aleksa, Askar,
> 
> On Fri, Aug 08, 2025 at 09:55:10PM +1000, Aleksa Sarai wrote:
> > On 2025-08-08, Askar Safin <safinaskar@zohomail.com> wrote:
> > > When I render "mount_setattr" from this (v2) pathset, I see weird quote mark. I. e.:
> > > 
> > > $ MANWIDTH=10000 man /path/to/mount_setattr.2
> > > ...
> > > SYNOPSIS
> > >        #include <fcntl.h>       /* Definition of AT_* constants */
> > >        #include <sys/mount.h>
> > > 
> > >        int mount_setattr(int dirfd, const char *path, unsigned int flags,
> > >                          struct mount_attr *attr, size_t size);"
> > > ...
> > 
> > Ah, my bad. "make -R lint-man" told me to put end quotes on the synopsis
> > lines, but I missed that there was a separate quote missing. This should
> > fix it:
> > 
> > diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2
> > index d44fafc93a20..46fcba927dd8 100644
> > --- a/man/man2/mount_setattr.2
> > +++ b/man/man2/mount_setattr.2
> > @@ -14,7 +14,7 @@ .SH SYNOPSIS
> >  .B #include <sys/mount.h>
> >  .P
> >  .BI "int mount_setattr(int " dirfd ", const char *" path ", unsigned int " flags ","
> > -.BI "                  struct mount_attr *" attr ", size_t " size );"
> > +.BI "                  struct mount_attr *" attr ", size_t " size ");"
> 
> Actually, I'd use
> 
> .BI "                  struct mount_attr *" attr ", size_t " size );

I've pushed this as a fix.  As a sanity check:

	$ diffman-git HEAD
	--- HEAD^:man/man2/mount_setattr.2
	+++ HEAD:man/man2/mount_setattr.2
	@@ -11,7 +11,7 @@
		#include <sys/mount.h>
	 
		int mount_setattr(int dirfd, const char *path, unsigned int flags,
	-                         struct mount_attr *attr, size_t size);"
	+                         struct mount_attr *attr, size_t size);
	 
	 DESCRIPTION
		The mount_setattr() system call changes the mount properties of a mount


Have a lovely day!
Alex

> 
> >  .fi
> >  .SH DESCRIPTION
> >  The
> 
> Hmmm, thanks for the catch!  My CI server is down until I come back home
> and have a chance to fix it.
> 
> 
> Have a lovely day!
> Alex
> 
> -- 
> <https://www.alejandro-colomar.es/>



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

Re: [PATCH v2 01/11] mount_setattr.2: document glibc >= 2.36 syscall wrappers

Posted by Alejandro Colomar 1 month, 4 weeks ago

Hi Aleksa,

On Thu, Aug 07, 2025 at 03:44:35AM +1000, Aleksa Sarai wrote:
> Glibc 2.36 added syscall wrappers for the entire family of fd-based
> mount syscalls, including mount_setattr(2).  Thus it's no longer
> necessary to instruct users to do raw syscall(2) operations.
> 
> Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>

Thanks!  I've applied and pushed the patch.


Have a lovely day!
Alex

> ---
>  man/man2/mount_setattr.2 | 45 +++++++--------------------------------------
>  1 file changed, 7 insertions(+), 38 deletions(-)
> 
> diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2
> index 60d9cf9de8aa..c96f0657f046 100644
> --- a/man/man2/mount_setattr.2
> +++ b/man/man2/mount_setattr.2
> @@ -10,21 +10,12 @@ .SH LIBRARY
>  .RI ( libc ,\~ \-lc )
>  .SH SYNOPSIS
>  .nf
> -.BR "#include <linux/fcntl.h>" " /* Definition of " AT_* " constants */"
> -.BR "#include <linux/mount.h>" " /* Definition of " MOUNT_ATTR_* " constants */"
> -.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
> -.B #include <unistd.h>
> +.BR "#include <fcntl.h>" "       /* Definition of " AT_* " constants */"
> +.B #include <sys/mount.h>
>  .P
> -.BI "int syscall(SYS_mount_setattr, int " dirfd ", const char *" path ,
> -.BI "            unsigned int " flags ", struct mount_attr *" attr \
> -", size_t " size );
> +.BI "int mount_setattr(int " dirfd ", const char *" path ", unsigned int " flags ","
> +.BI "                  struct mount_attr *" attr ", size_t " size );"
>  .fi
> -.P
> -.IR Note :
> -glibc provides no wrapper for
> -.BR mount_setattr (),
> -necessitating the use of
> -.BR syscall (2).
>  .SH DESCRIPTION
>  The
>  .BR mount_setattr ()
> @@ -586,6 +577,7 @@ .SH HISTORY
>  .\" commit 7d6beb71da3cc033649d641e1e608713b8220290
>  .\" commit 2a1867219c7b27f928e2545782b86daaf9ad50bd
>  .\" commit 9caccd41541a6f7d6279928d9f971f6642c361af
> +glibc 2.36.
>  .SH NOTES
>  .SS ID-mapped mounts
>  Creating an ID-mapped mount makes it possible to
> @@ -914,37 +906,14 @@ .SH EXAMPLES
>  #include <err.h>
>  #include <fcntl.h>
>  #include <getopt.h>
> -#include <linux/mount.h>
> -#include <linux/types.h>
> +#include <sys/mount.h>
> +#include <sys/types.h>
>  #include <stdbool.h>
>  #include <stdio.h>
>  #include <stdlib.h>
>  #include <string.h>
> -#include <sys/syscall.h>
>  #include <unistd.h>
>  \&
> -static inline int
> -mount_setattr(int dirfd, const char *path, unsigned int flags,
> -              struct mount_attr *attr, size_t size)
> -{
> -    return syscall(SYS_mount_setattr, dirfd, path, flags,
> -                   attr, size);
> -}
> -\&
> -static inline int
> -open_tree(int dirfd, const char *filename, unsigned int flags)
> -{
> -    return syscall(SYS_open_tree, dirfd, filename, flags);
> -}
> -\&
> -static inline int
> -move_mount(int from_dirfd, const char *from_path,
> -           int to_dirfd, const char *to_path, unsigned int flags)
> -{
> -    return syscall(SYS_move_mount, from_dirfd, from_path,
> -                   to_dirfd, to_path, flags);
> -}
> -\&
>  static const struct option longopts[] = {
>      {"map\-mount",       required_argument,  NULL,  \[aq]a\[aq]},
>      {"recursive",       no_argument,        NULL,  \[aq]b\[aq]},
> 
> -- 
> 2.50.1
> 
> 

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