--- name: "fsmount" section: "2" platform: "linux" package: "man-pages" version: "6.19-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/fsmount/2" --- # fsmount(2) instantiate mount object from filesystem context ## NAME fsmount - instantiate mount object from filesystem context ## LIBRARY Standard C library (*libc*, *-lc*) ## SYNOPSIS ``` #include ``` **int fsmount(int** *fsfd***, unsigned int** *flags***, unsigned int** *attr\_flags***);** ## DESCRIPTION The **fsmount**() system call is part of the suite of file-descriptor-based mount facilities in Linux. **fsmount**() creates a new detached mount object for the root of the new filesystem instance referenced by the filesystem context file descriptor *fsfd*. A new file descriptor associated with the detached mount object is then returned. In order to create a mount object with **fsmount**(), the calling process must have the **CAP\_SYS\_ADMIN** capability. The filesystem context must have been created with a call to [**fsopen**(2)](/fsopen/2.md) and then had a filesystem instance instantiated with a call to [**fsconfig**(2)](/fsconfig/2.md) with **FSCONFIG\_CMD\_CREATE** or **FSCONFIG\_CMD\_CREATE\_EXCL** in order to be in the correct state for this operation (the "awaiting-mount" mode in kernel-developer parlance). Unlike [**open\_tree**(2)](/open_tree/2.md) with **OPEN\_TREE\_CLONE**, **fsmount**() can only be called once in the lifetime of a filesystem context to produce a mount object. As with file descriptors returned from [**open\_tree**(2)](/open_tree/2.md) called with **OPEN\_TREE\_CLONE**, the returned file descriptor can then be used with [**move\_mount**(2)](/move_mount/2.md), [**mount\_setattr**(2)](/mount_setattr/2.md), 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 [**move\_mount**(2)](/move_mount/2.md). (Note that the unmount operation on [**close**(2)](/close/2.md) is lazy—akin to calling [**umount2**(2)](/umount2/2.md) with **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 [**open**(2)](/open/2.md) with **O\_PATH**, meaning it can also be used as a *dirfd* argument to "\*at()" system calls. *flags* controls the creation of the returned file descriptor. A value for *flags* is constructed by bitwise ORing zero or more of the following constants: - **FSMOUNT\_CLOEXEC** Set the close-on-exec (**FD\_CLOEXEC**) flag on the new file descriptor. See the description of the **O\_CLOEXEC** flag in [**open**(2)](/open/2.md) for reasons why this may be useful. *attr\_flags* specifies mount attributes which will be applied to the created mount object, in the form of **MOUNT\_ATTR\_***\** flags. The flags are interpreted as though [**mount\_setattr**(2)](/mount_setattr/2.md) was called with *attr.attr\_set* set to the same value as *attr\_flags*. **MOUNT\_ATTR\_***\** flags which would require specifying additional fields in [**mount\_attr**(2type)](/mount_attr/2type.md) (such as **MOUNT\_ATTR\_IDMAP**) are not valid flag values for *attr\_flags*. If the **fsmount**() operation is successful, the filesystem context associated with the file descriptor *fsfd* is reset and placed into reconfiguration mode, as if it were just returned by [**fspick**(2)](/fspick/2.md). You may continue to use [**fsconfig**(2)](/fsconfig/2.md) with the now-reset filesystem context, including issuing the **FSCONFIG\_CMD\_RECONFIGURE** command to reconfigure the filesystem instance. ## RETURN VALUE On success, a new file descriptor is returned. On error, -1 is returned, and *errno* is set to indicate the error. ## ERRORS - **EBUSY** The filesystem context associated with *fsfd* is not in the right state to be used by **fsmount**(). - **EINVAL** *flags* had an invalid flag set. - **EINVAL** *attr\_flags* had an invalid **MOUNT\_ATTR\_***\** flag set. - **EMFILE** The calling process has too many open files to create more. - **ENFILE** The system has too many open files to create more. - **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 [**namespaces**(7)](/namespaces/7.md).) - **ENOMEM** The kernel could not allocate sufficient memory to complete the operation. - **EPERM** The calling process does not have the required **CAP\_SYS\_ADMIN** capability. ## STANDARDS Linux. ## HISTORY Linux 5.2. glibc 2.36. ## EXAMPLES ``` 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); ``` ## SEE ALSO [**fsconfig**(2)](/fsconfig/2.md), [**fsopen**(2)](/fsopen/2.md), [**fspick**(2)](/fspick/2.md), [**mount**(2)](/mount/2.md), [**mount\_setattr**(2)](/mount_setattr/2.md), [**move\_mount**(2)](/move_mount/2.md), [**open\_tree**(2)](/open_tree/2.md), [**mount\_namespaces**(7)](/mount_namespaces/7.md)