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+).
Cc: Christian Brauner <brauner@kernel.org>
Signed-off-by: Aleksa Sarai <cyphar@cyphar.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 );
.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.0Hi 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@kernel.org> > Signed-off-by: Aleksa Sarai <cyphar@cyphar.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/>).
On 2025-09-21, Alejandro Colomar <alx@kernel.org> wrote: > On Fri, Sep 19, 2025 at 11:59:50AM +1000, Aleksa Sarai wrote: > > 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. I tried it and I don't think it is a better experience as a reader when split into two pages because of the huge overlap between the two syscalls. -- Aleksa Sarai Senior Software Engineer (Containers) SUSE Linux GmbH https://www.cyphar.com/
Hi Aleksa, On Wed, Sep 24, 2025 at 04:31:15PM +1000, Aleksa Sarai wrote: > On 2025-09-21, Alejandro Colomar <alx@kernel.org> wrote: > > On Fri, Sep 19, 2025 at 11:59:50AM +1000, Aleksa Sarai wrote: > > > 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. > > I tried it and I don't think it is a better experience as a reader when > split into two pages because of the huge overlap between the two > syscalls. Okay. Thanks! Have a lovely day! Alex -- <https://www.alejandro-colomar.es> Use port 80 (that is, <...:80/>).
© 2016 - 2025 Red Hat, Inc.