.\" 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)