[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-Id: <20250807-new-mount-api-v2-10-558a27b8068c@cyphar.com>
Date: Thu, 07 Aug 2025 03:44:44 +1000
From: Aleksa Sarai <cyphar@...har.com>
To: Alejandro Colomar <alx@...nel.org>
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>,
Aleksa Sarai <cyphar@...har.com>
Subject: [PATCH v2 10/11] open_tree_attr.2, open_tree.2: document new
open_tree_attr() api
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.
Cc: Christian Brauner <brauner@...nel.org>
Signed-off-by: Aleksa Sarai <cyphar@...har.com>
---
man/man2/open_tree.2 | 74 +++++++++++++++++++++++++++++++++++++++++++++++
man/man2/open_tree_attr.2 | 1 +
2 files changed, 75 insertions(+)
diff --git a/man/man2/open_tree.2 b/man/man2/open_tree.2
index 3d38e27b5254..6e7ec4998d42 100644
--- a/man/man2/open_tree.2
+++ b/man/man2/open_tree.2
@@ -15,7 +15,19 @@ .SH SYNOPSIS
.BR "#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 *" 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 ()
@@ -222,6 +234,64 @@ .SH DESCRIPTION
and attach it to the file descriptor.
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 (),
+(before returning the resulting file descriptor)
+.BR open_tree_attr ()
+will apply the mount attributes requested in
+.I attr
+to the mount object.
+(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.)
+.P
+For the most part, the application of
+.I attr
+has identical semantics to
+.BR mount_setattr (2),
+except that it is possible to change the
+.B \%MOUNT_ATTR_IDMAP
+attribute for a mount object
+that is already configured as an ID-mapped mount.
+This is usually forbidden by
+.BR mount_setattr (2)
+and thus
+.BR open_tree_attr ()
+is currently the only permitted mechanism to change this attribute.
+Changing an ID-mapped mount is only permitted
+if a new detached mount object is being created with
+.I flags
+including
+.BR \%OPEN_TREE_CLONE .
+.P
+If
+.I flags
+contains
+.BR \%AT_RECURSIVE ,
+then the attributes are applied recursively
+(just as when
+.BR mount_setattr (2)
+is called with
+.BR \%AT_RECURSIVE ).
+This applies in addition to the
+.BR open_tree ()-specific
+behaviour regarding
+.BR \%AT_RECURSIVE .
.SH RETURN VALUE
On success, a new file descriptor is returned.
On error, \-1 is returned, and
@@ -316,9 +386,13 @@ .SH ERRORS
.SH STANDARDS
Linux.
.SH HISTORY
+.SS open_tree()
Linux 5.2.
.\" commit a07b20004793d8926f78d63eb5980559f7813404
glibc 2.36.
+.SS open_tree_attr()
+Linux 6.15.
+.\" commit c4a16820d90199409c9bf01c4f794e1e9e8d8fd8
.SH NOTES
.SS Anonymous mount namespaces
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 000000000000..e57269bbd269
--- /dev/null
+++ b/man/man2/open_tree_attr.2
@@ -0,0 +1 @@
+.so man2/open_tree.2
--
2.50.1
Powered by blists - more mailing lists