Message-ID: <3kewugw6bh6y6ghw44ksqqir6r37wnyckwx7st66ydtdaxbtgk@ibg57jop5mn7>
Date: Fri, 26 Sep 2025 14:51:48 +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 v5 4/8] man/man2/fsmount.2: document "new" mount API

Hi Aleksa,

On Thu, Sep 25, 2025 at 01:31:26AM +1000, Aleksa Sarai wrote:
> This is loosely based on the original documentation written by David
> Howells and later maintained by Christian Brauner, but has been
> rewritten to be more from a user perspective (as well as fixing a few
> critical mistakes).
> 
> Co-authored-by: David Howells <dhowells@...hat.com>
> Signed-off-by: David Howells <dhowells@...hat.com>
> Co-authored-by: Christian Brauner <brauner@...nel.org>
> Signed-off-by: Christian Brauner <brauner@...nel.org>
> Signed-off-by: Aleksa Sarai <cyphar@...har.com>

Thanks!  I've applied this patch.
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=24243cc66e191fd917c9c13a01b7ac037ce0972e>


Cheers,
Alex

> ---
>  man/man2/fsmount.2 | 231 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 231 insertions(+)
> 
> diff --git a/man/man2/fsmount.2 b/man/man2/fsmount.2
> new file mode 100644
> index 0000000000000000000000000000000000000000..b62850a68443bb8f6178389eb6cb1a5f9029ab30
> --- /dev/null
> +++ b/man/man2/fsmount.2
> @@ -0,0 +1,231 @@
> +.\" Copyright, the authors of the Linux man-pages project
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH fsmount 2 (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +fsmount \- instantiate mount object from filesystem context
> +.SH LIBRARY
> +Standard C library
> +.RI ( libc ,\~ \-lc )
> +.SH SYNOPSIS
> +.nf
> +.B #include <sys/mount.h>
> +.P
> +.BI "int fsmount(int " fsfd ", unsigned int " flags \
> +", unsigned int " attr_flags );
> +.fi
> +.SH DESCRIPTION
> +The
> +.BR fsmount ()
> +system call is part of
> +the suite of file-descriptor-based mount facilities in Linux.
> +.P
> +.BR fsmount ()
> +creates a new detached mount object
> +for the root of the new filesystem instance
> +referenced by the filesystem context file descriptor
> +.IR fsfd .
> +A new file descriptor
> +associated with the detached mount object
> +is then returned.
> +In order to create a mount object with
> +.BR fsmount (),
> +the calling process must have the
> +.B \%CAP_SYS_ADMIN
> +capability.
> +.P
> +The filesystem context must have been created with a call to
> +.BR fsopen (2)
> +and then had a filesystem instance instantiated with a call to
> +.BR fsconfig (2)
> +with
> +.B \%FSCONFIG_CMD_CREATE
> +or
> +.B \%FSCONFIG_CMD_CREATE_EXCL
> +in order to be in the correct state
> +for this operation
> +(the "awaiting-mount" mode in kernel-developer parlance).
> +.\" FS_CONTEXT_AWAITING_MOUNT is the term the kernel uses for this.
> +Unlike
> +.BR open_tree (2)
> +with
> +.BR \%OPEN_TREE_CLONE ,
> +.BR fsmount ()
> +can only be called once
> +in the lifetime of a filesystem context
> +to produce a mount object.
> +.P
> +As with file descriptors returned from
> +.BR open_tree (2)
> +called with
> +.BR OPEN_TREE_CLONE ,
> +the returned file descriptor
> +can then be used with
> +.BR move_mount (2),
> +.BR mount_setattr (2),
> +or other such system calls to do further mount operations.
> +This mount object will be unmounted and destroyed
> +when the file descriptor is closed
> +if it was not otherwise attached to a mount point
> +by calling
> +.BR move_mount (2).
> +(Note that the unmount operation on
> +.BR close (2)
> +is lazy\[em]akin to calling
> +.BR umount2 (2)
> +with
> +.BR MNT_DETACH ;
> +any existing open references to files
> +from the mount object
> +will continue to work,
> +and the mount object will only be completely destroyed
> +once it ceases to be busy.)
> +The returned file descriptor
> +also acts the same as one produced by
> +.BR open (2)
> +with
> +.BR O_PATH ,
> +meaning it can also be used as a
> +.I dirfd
> +argument
> +to "*at()" system calls.
> +.P
> +.I flags
> +controls the creation of the returned file descriptor.
> +A value for
> +.I flags
> +is constructed by bitwise ORing
> +zero or more of the following constants:
> +.RS
> +.TP
> +.B FSMOUNT_CLOEXEC
> +Set the close-on-exec
> +.RB ( FD_CLOEXEC )
> +flag on the new file descriptor.
> +See the description of the
> +.B O_CLOEXEC
> +flag in
> +.BR open (2)
> +for reasons why this may be useful.
> +.RE
> +.P
> +.I attr_flags
> +specifies mount attributes
> +which will be applied to the created mount object,
> +in the form of
> +.BI \%MOUNT_ATTR_ *
> +flags.
> +The flags are interpreted as though
> +.BR mount_setattr (2)
> +was called with
> +.I attr.attr_set
> +set to the same value as
> +.IR attr_flags .
> +.BI \%MOUNT_ATTR_ *
> +flags which would require
> +specifying additional fields in
> +.BR mount_attr (2type)
> +(such as
> +.BR \%MOUNT_ATTR_IDMAP )
> +are not valid flag values for
> +.IR attr_flags .
> +.P
> +If the
> +.BR fsmount ()
> +operation is successful,
> +the filesystem context
> +associated with the file descriptor
> +.I fsfd
> +is reset
> +and placed into reconfiguration mode,
> +as if it were just returned by
> +.BR fspick (2).
> +You may continue to use
> +.BR fsconfig (2)
> +with the now-reset filesystem context,
> +including issuing the
> +.B \%FSCONFIG_CMD_RECONFIGURE
> +command
> +to reconfigure the filesystem instance.
> +.SH RETURN VALUE
> +On success, a new file descriptor is returned.
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.SH ERRORS
> +.TP
> +.B EBUSY
> +The filesystem context associated with
> +.I fsfd
> +is not in the right state
> +to be used by
> +.BR fsmount ().
> +.TP
> +.B EINVAL
> +.I flags
> +had an invalid flag set.
> +.TP
> +.B EINVAL
> +.I attr_flags
> +had an invalid
> +.BI MOUNT_ATTR_ *
> +flag set.
> +.TP
> +.B EMFILE
> +The calling process has too many open files to create more.
> +.TP
> +.B ENFILE
> +The system has too many open files to create more.
> +.TP
> +.B ENOSPC
> +The "anonymous" mount namespace
> +necessary to contain the new mount object
> +could not be allocated,
> +as doing so would exceed
> +the configured per-user limit on
> +the number of mount namespaces in the current user namespace.
> +(See also
> +.BR namespaces (7).)
> +.TP
> +.B ENOMEM
> +The kernel could not allocate sufficient memory to complete the operation.
> +.TP
> +.B EPERM
> +The calling process does not have the required
> +.B CAP_SYS_ADMIN
> +capability.
> +.SH STANDARDS
> +Linux.
> +.SH HISTORY
> +Linux 5.2.
> +.\" commit 93766fbd2696c2c4453dd8e1070977e9cd4e6b6d
> +.\" commit 400913252d09f9cfb8cce33daee43167921fc343
> +glibc 2.36.
> +.SH EXAMPLES
> +.in +4n
> +.EX
> +int fsfd, mntfd, tmpfd;
> +\&
> +fsfd = fsopen("tmpfs", FSOPEN_CLOEXEC);
> +fsconfig(fsfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
> +mntfd = fsmount(fsfd, FSMOUNT_CLOEXEC,
> +                MOUNT_ATTR_NODEV | MOUNT_ATTR_NOEXEC);
> +\&
> +/* Create a new file without attaching the mount object */
> +tmpfd = openat(mntfd, "tmpfile", O_CREAT | O_EXCL | O_RDWR, 0600);
> +unlinkat(mntfd, "tmpfile", 0);
> +\&
> +/* Attach the mount object to "/tmp" */
> +move_mount(mntfd, "", AT_FDCWD, "/tmp", MOVE_MOUNT_F_EMPTY_PATH);
> +.EE
> +.in
> +.SH SEE ALSO
> +.BR fsconfig (2),
> +.BR fsopen (2),
> +.BR fspick (2),
> +.BR mount (2),
> +.BR mount_setattr (2),
> +.BR move_mount (2),
> +.BR open_tree (2),
> +.BR mount_namespaces (7)
> 
> -- 
> 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