Message-ID: <vc2xa2tuqqnkuoyg4hrgt6akt23ap6hxho5qs5hfcbc5nsaosv@idi6hwvyo7r5>
Date: Sun, 21 Sep 2025 11:55:56 +0200
From: Alejandro Colomar <alx@...nel.org>
To: Aleksa Sarai <cyphar@...har.com>
Cc: "Michael T. Kerrisk" <mtk.manpages@...il.com>, 
	Alexander Viro <viro@...iv.linux.org.uk>, Jan Kara <jack@...e.cz>, Askar Safin <safinaskar@...omail.com>, 
	"G. Branden Robinson" <g.branden.robinson@...il.com>, linux-man@...r.kernel.org, linux-api@...r.kernel.org, 
	linux-fsdevel@...r.kernel.org, linux-kernel@...r.kernel.org, 
	David Howells <dhowells@...hat.com>, Christian Brauner <brauner@...nel.org>
Subject: Re: [PATCH v4 09/10] man/man2/open_tree{,_attr}.2: document new
 open_tree_attr() API

Hi Aleksa,

On Fri, Sep 19, 2025 at 11:59:50AM +1000, Aleksa Sarai wrote:
> This is a new API added in Linux 6.15, and is effectively just a minor
> expansion of open_tree(2) in order to allow for MOUNT_ATTR_IDMAP to be
> changed for an existing ID-mapped mount.  glibc does not yet have a
> wrapper for this.
> 
> While working on this man-page, I discovered a bug in open_tree_attr(2)
> that accidentally permitted changing MOUNT_ATTR_IDMAP for extant
> detached ID-mapped mount objects.  This is definitely a bug, but there
> is no need to add this to BUGS because the patch to fix this has already
> been accepted (slated for 6.18, and will be backported to 6.15+).

Okay.

> 
> Cc: Christian Brauner <brauner@...nel.org>
> Signed-off-by: Aleksa Sarai <cyphar@...har.com>
> ---
>  man/man2/open_tree.2      | 140 ++++++++++++++++++++++++++++++++++++++++++++++
>  man/man2/open_tree_attr.2 |   1 +
>  2 files changed, 141 insertions(+)
> 
> diff --git a/man/man2/open_tree.2 b/man/man2/open_tree.2
> index 7f85df08b43c7b48a9d021dbbeb2c60092a2b2d4..60de4313a9d5be4ef3ff1217051f252506a2ade9 100644
> --- a/man/man2/open_tree.2
> +++ b/man/man2/open_tree.2
> @@ -15,7 +15,19 @@ .SH SYNOPSIS
>  .B #include <sys/mount.h>
>  .P
>  .BI "int open_tree(int " dirfd ", const char *" path ", unsigned int " flags );
> +.P
> +.BR "#include <sys/syscall.h>" "    /* Definition of " SYS_* " constants */"
> +.P
> +.BI "int syscall(SYS_open_tree_attr, int " dirfd ", const char *" path ,
> +.BI "            unsigned int " flags ", struct mount_attr *_Nullable " attr ", \
> +size_t " size );

Do we maybe want to move this to its own separate page?

The separate page could perfectly contain the same exact text you're
adding here; you don't need to repeat open_tree() descriptions.

In general, I feel that while this improves discoverability of related
functions, it produces more complex pages.


Cheers,
Alex

>  .fi
> +.P
> +.IR Note :
> +glibc provides no wrapper for
> +.BR open_tree_attr (),
> +necessitating the use of
> +.BR syscall (2).
>  .SH DESCRIPTION
>  The
>  .BR open_tree ()
> @@ -246,6 +258,129 @@ .SH DESCRIPTION
>  as a detached mount object.
>  This flag is only permitted in conjunction with
>  .BR \%OPEN_TREE_CLONE .
> +.SS open_tree_attr()
> +The
> +.BR open_tree_attr ()
> +system call operates in exactly the same way as
> +.BR open_tree (),
> +except for the differences described here.
> +.P
> +After performing the same operation as with
> +.BR open_tree (),
> +.BR open_tree_attr ()
> +will apply the mount attribute changes described in
> +.I attr
> +to the file descriptor before it is returned.
> +(See
> +.BR mount_attr (2type)
> +for a description of the
> +.I mount_attr
> +structure.
> +As described in
> +.BR mount_setattr (2),
> +.I size
> +must be set to
> +.I sizeof(struct mount_attr)
> +in order to support future extensions.)
> +If
> +.I attr
> +is NULL,
> +or has
> +.IR attr.attr_clr ,
> +.IR attr.attr_set ,
> +and
> +.I attr.propagation
> +all set to zero,
> +then
> +.BR open_tree_attr ()
> +has identical behaviour to
> +.BR open_tree ().
> +.P
> +The application of
> +.I attr
> +to the resultant file descriptor
> +has identical semantics to
> +.BR mount_setattr (2),
> +except for the following extensions and general caveats:
> +.IP \[bu] 3
> +Unlike
> +.BR mount_setattr (2)
> +called with a regular
> +.B OPEN_TREE_CLONE
> +detached mount object from
> +.BR open_tree (),
> +.BR open_tree_attr ()
> +can specify a different setting for
> +.B \%MOUNT_ATTR_IDMAP
> +to the original mount object cloned with
> +.BR OPEN_TREE_CLONE .
> +.IP
> +Adding
> +.B \%MOUNT_ATTR_IDMAP
> +to
> +.I attr.attr_clr
> +will disable ID-mapping for the new mount object;
> +adding
> +.B \%MOUNT_ATTR_IDMAP
> +to
> +.I attr.attr_set
> +will configure the mount object to have the ID-mapping defined by
> +the user namespace referenced by the file descriptor
> +.IR attr.userns_fd .
> +(The semantics of which are identical to when
> +.BR mount_setattr (2)
> +is used to configure
> +.BR \%MOUNT_ATTR_IDMAP .)
> +.IP
> +Changing or removing the mapping
> +of an ID-mapped mount is only permitted
> +if a new detached mount object is being created with
> +.I flags
> +including
> +.BR \%OPEN_TREE_CLONE .
> +.\" Aleksa Sarai
> +.\"  At time of writing, this is not actually true because of a bug where
> +.\"  open_tree_attr() would accidentally permit changing MOUNT_ATTR_IDMAP for
> +.\"  existing detached mount objects without setting OPEN_TREE_CLONE, but a
> +.\"  patch to fix it has been slated for 6.18 and will be backported to 6.15+.
> +.\"  <https://lore.kernel.org/r/20250808-open_tree_attr-bugfix-idmap-v1-0-0ec7bc05646c@cyphar.com/>
> +.IP \[bu]
> +If
> +.I flags
> +contains
> +.BR \%AT_RECURSIVE ,
> +then the attributes described in
> +.I attr
> +are applied recursively
> +(just as when
> +.BR mount_setattr (2)
> +is called with
> +.BR \%AT_RECURSIVE ).
> +However, this applies in addition to the
> +.BR open_tree ()-specific
> +behaviour regarding
> +.BR \%AT_RECURSIVE ,
> +and thus
> +.I flags
> +must also contain
> +.BR \%OPEN_TREE_CLONE .
> +.P
> +Note that if
> +.I flags
> +does not contain
> +.BR \%OPEN_TREE_CLONE ,
> +.BR open_tree_attr ()
> +will attempt to modify the mount attributes of
> +the mount object attached at
> +the path described by
> +.I dirfd
> +and
> +.IR path .
> +As with
> +.BR mount_setattr (2),
> +if said path is not a mount point,
> +.BR open_tree_attr ()
> +will return an error.
>  .SH RETURN VALUE
>  On success, a new file descriptor is returned.
>  On error, \-1 is returned, and
> @@ -339,10 +474,15 @@ .SH ERRORS
>  .SH STANDARDS
>  Linux.
>  .SH HISTORY
> +.SS open_tree()
>  Linux 5.2.
>  .\" commit a07b20004793d8926f78d63eb5980559f7813404
>  .\" commit 400913252d09f9cfb8cce33daee43167921fc343
>  glibc 2.36.
> +.SS open_tree_attr()
> +Linux 6.15.
> +.\" commit c4a16820d90199409c9bf01c4f794e1e9e8d8fd8
> +.\" commit 7a54947e727b6df840780a66c970395ed9734ebe
>  .SH NOTES
>  .SS Mount propagation
>  The bind-mount mount objects created by
> diff --git a/man/man2/open_tree_attr.2 b/man/man2/open_tree_attr.2
> new file mode 100644
> index 0000000000000000000000000000000000000000..e57269bbd269bcce0b0a974425644ba75e379f2f
> --- /dev/null
> +++ b/man/man2/open_tree_attr.2
> @@ -0,0 +1 @@
> +.so man2/open_tree.2
> 
> -- 
> 2.51.0
> 
> 

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

Download attachment "signature.asc" of type "application/pgp-signature" (834 bytes)

Powered by blists - more mailing lists