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@xxxxxxxxxx> Signed-off-by: Aleksa Sarai <cyphar@xxxxxxxxxx> --- man/man2/open_tree.2 | 122 ++++++++++++++++++++++++++++++++++++++++++++++ man/man2/open_tree_attr.2 | 1 + 2 files changed, 123 insertions(+) diff --git a/man/man2/open_tree.2 b/man/man2/open_tree.2 index 07aac7616107d16d05cc71ba7db6aee35f3a9cc6..f671c401b1f1e2926f7948d6fe5041b7848125ac 100644 --- a/man/man2/open_tree.2 +++ b/man/man2/open_tree.2 @@ -14,7 +14,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 *" 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 () @@ -228,6 +240,111 @@ .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 (), +(before returning the resulting file descriptor) +.BR open_tree_attr () +will apply the mount attribute changes described in +.I attr +to the returned file descriptor. +(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 +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 . +.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 @@ -321,10 +438,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 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 0000000000000000000000000000000000000000..e57269bbd269bcce0b0a974425644ba75e379f2f --- /dev/null +++ b/man/man2/open_tree_attr.2 @@ -0,0 +1 @@ +.so man2/open_tree.2 -- 2.50.1
