--- name: "fsconfig" section: "2" platform: "linux" package: "man-pages" version: "6.19-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/fsconfig" --- # fsconfig(2) configure new or existing filesystem context ## NAME fsconfig - configure new or existing filesystem context ## LIBRARY Standard C library (*libc*, *-lc*) ## SYNOPSIS ``` #include ``` **int fsconfig(int** *fd***, unsigned int** *cmd***,** **const char \*\_Nullable** *key***,** **const void \*\_Nullable** *value***, int** *aux***);** ## DESCRIPTION The **fsconfig**() system call is part of the suite of file-descriptor-based mount facilities in Linux. **fsconfig**() is used to supply parameters to and issue commands against the filesystem configuration context associated with the file descriptor *fd*. Filesystem configuration contexts can be created with [**fsopen**(2)](/fsopen/2.md) or be instantiated from an extant filesystem instance with [**fspick**(2)](/fspick/2.md). The *cmd* argument indicates the command to be issued. Some commands supply parameters to the context (equivalent to mount options specified with [**mount**(8)](/mount/8.md)), while others are meta-operations on the filesystem context. The list of valid *cmd* values are: - **FSCONFIG\_SET\_FLAG** Set the flag parameter named by *key*. *value* must be NULL, and *aux* must be 0. - **FSCONFIG\_SET\_STRING** Set the string parameter named by *key* to the value specified by *value*. *value* points to a null-terminated string, and *aux* must be 0. - **FSCONFIG\_SET\_BINARY** Set the blob parameter named by *key* to the contents of the binary blob specified by *value*. *value* points to the start of a buffer that is *aux* bytes in length. - **FSCONFIG\_SET\_FD** Set the file parameter named by *key* to the open file description referenced by the file descriptor *aux*. *value* must be NULL. - You may also use **FSCONFIG\_SET\_STRING** for file parameters, with *value* set to a null-terminated string containing a base-10 representation of the file descriptor number. This mechanism is primarily intended for compatibility with older [**mount**(2)](/mount/2.md)-based programs, and only works for parameters that *only* accept file descriptor arguments. - **FSCONFIG\_SET\_PATH** Set the path parameter named by *key* to the object at a provided path, resolved in a similar manner to [**openat**(2)](/openat/2.md). *value* points to a null-terminated pathname string, and *aux* is equivalent to the *dirfd* argument to [**openat**(2)](/openat/2.md). See [**openat**(2)](/openat/2.md) for an explanation of the need for **FSCONFIG\_SET\_PATH**. - You may also use **FSCONFIG\_SET\_STRING** for path parameters, the behavior of which is equivalent to **FSCONFIG\_SET\_PATH** with *aux* set to **AT\_FDCWD**. - **FSCONFIG\_SET\_PATH\_EMPTY** As with **FSCONFIG\_SET\_PATH**, except that if *value* is an empty string, the file descriptor specified by *aux* is operated on directly and may be any type of file (not just a directory). This is equivalent to the behavior of **AT\_EMPTY\_PATH** with most "\*at()" system calls. If *aux* is **AT\_FDCWD**, the parameter will be set to the current working directory of the calling process. - **FSCONFIG\_CMD\_CREATE** This command instructs the filesystem driver to instantiate an instance of the filesystem in the kernel with the parameters specified in the filesystem configuration context. *key* and *value* must be NULL, and *aux* must be 0. - This command can only be issued once in the lifetime of a filesystem context. If the operation succeeds, the filesystem context associated with file descriptor *fd* now references the created filesystem instance, and is placed into a special "awaiting-mount" mode that allows you to use [**fsmount**(2)](/fsmount/2.md) to create a mount object from the filesystem instance. If the operation fails, in most cases the filesystem context is placed in a failed mode and cannot be used for any further **fsconfig**() operations (though you may still retrieve diagnostic messages through the message retrieval interface, as described in the corresponding subsection of [**fsopen**(2)](/fsopen/2.md)). - This command can only be issued against filesystem configuration contexts that were created with [**fsopen**(2)](/fsopen/2.md). In order to create a filesystem instance, the calling process must have the **CAP\_SYS\_ADMIN** capability. - An important thing to be aware of is that the Linux kernel will *silently* reuse extant filesystem instances depending on the filesystem type and the configured parameters (each filesystem driver has its own policy for how filesystem instances are reused). This means that the filesystem instance "created" by **FSCONFIG\_CMD\_CREATE** may, in fact, be a reference to an extant filesystem instance in the kernel. (For reference, this behavior also applies to [**mount**(2)](/mount/2.md).) - One side-effect of this behavior is that if an extant filesystem instance is reused, *all* parameters configured for this filesystem configuration context are *silently ignored* (with the exception of the *ro* and *rw* flag parameters; if the state of the read-only flag in the extant filesystem instance and the filesystem configuration context do not match, this operation will return **EBUSY**). This also means that **FSCONFIG\_CMD\_RECONFIGURE** commands issued against the "created" filesystem instance will also affect any mount objects associated with the extant filesystem instance. - Programs that need to ensure that they create a new filesystem instance with specific parameters (notably, security-related parameters such as *acl* to enable POSIX ACLs—as described in [**acl**(5)](/acl/5.md)) should use **FSCONFIG\_CMD\_CREATE\_EXCL** instead. - **FSCONFIG\_CMD\_CREATE\_EXCL** (since Linux 6.6) As with **FSCONFIG\_CMD\_CREATE**, except that the kernel is instructed to not reuse extant filesystem instances. If the operation would be forced to reuse an extant filesystem instance, this operation will return **EBUSY** instead. - As a result (unlike **FSCONFIG\_CMD\_CREATE**), if this operation succeeds then the calling process can be sure that all of the parameters successfully configured with **fsconfig**() will actually be applied to the created filesystem instance. - **FSCONFIG\_CMD\_RECONFIGURE** This command instructs the filesystem driver to apply the parameters specified in the filesystem configuration context to the extant filesystem instance referenced by the filesystem configuration context. *key* and *value* must be NULL, and *aux* must be 0. - This is primarily intended for use with [**fspick**(2)](/fspick/2.md), but may also be used to modify the parameters of a filesystem instance after **FSCONFIG\_CMD\_CREATE** was used to create it and a mount object was created using [**fsmount**(2)](/fsmount/2.md). In order to reconfigure an extant filesystem instance, the calling process must have the **CAP\_SYS\_ADMIN** capability. - If the operation succeeds, the filesystem context is reset but remains in reconfiguration mode and thus can be reused for subsequent **FSCONFIG\_CMD\_RECONFIGURE** commands. If the operation fails, in most cases the filesystem context is placed in a failed mode and cannot be used for any further **fsconfig**() operations (though you may still retrieve diagnostic messages through the message retrieval interface, as described in the corresponding subsection of [**fsopen**(2)](/fsopen/2.md)). Parameters specified with **FSCONFIG\_SET\_***\** do not take effect until a corresponding **FSCONFIG\_CMD\_CREATE** or **FSCONFIG\_CMD\_RECONFIGURE** command is issued. ## RETURN VALUE On success, **fsconfig**() returns 0. On error, -1 is returned, and *errno* is set to indicate the error. ## ERRORS If an error occurs, the filesystem driver may provide additional information about the error through the message retrieval interface for filesystem configuration contexts. This additional information can be retrieved at any time by calling [**read**(2)](/read/2.md) on the filesystem instance or filesystem configuration context referenced by the file descriptor *fd*. (See the "Message retrieval interface" subsection in [**fsopen**(2)](/fsopen/2.md) for more details on the message format.) Even after an error occurs, the filesystem configuration context is *not* invalidated, and thus can still be used with other **fsconfig**() commands. This means that users can probe support for filesystem parameters on a per-parameter basis, and adjust which parameters they wish to set. The error values given below result from filesystem type independent errors. Each filesystem type may have its own special errors and its own special behavior. See the Linux kernel source code for details. - **EACCES** A component of a path provided as a path parameter was not searchable. (See also [**path\_resolution**(7)](/path_resolution/7.md).) - **EACCES** **FSCONFIG\_CMD\_CREATE** was attempted for a read-only filesystem without specifying the '**ro**' flag parameter. - **EACCES** A specified block device parameter is located on a filesystem mounted with the **MS\_NODEV** option. - **EBADF** The file descriptor given by *fd* (or possibly by *aux*, depending on the command) is invalid. - **EBUSY** The filesystem context associated with *fd* is in the wrong state for the given command. - **EBUSY** The filesystem instance cannot be reconfigured as read-only with **FSCONFIG\_CMD\_RECONFIGURE** because some programs still hold files open for writing. - **EBUSY** A new filesystem instance was requested with **FSCONFIG\_CMD\_CREATE\_EXCL** but a matching superblock already existed. - **EFAULT** One of the pointer arguments points to a location outside the calling process's accessible address space. - **EINVAL** *fd* does not refer to a filesystem configuration context or filesystem instance. - **EINVAL** One of the values of *key*, *value*, and/or *aux* were set to a non-zero value when *cmd* required that they be zero (or NULL). - **EINVAL** The parameter named by *key* cannot be set using the type specified with *cmd*. - **EINVAL** One of the source parameters referred to an invalid superblock. - **ELOOP** Too many links encountered during pathname resolution of a path argument. - **ENAMETOOLONG** A path argument was longer than **PATH\_MAX**. - **ENOENT** A path argument had a non-existent component. - **ENOENT** A path argument is an empty string, but *cmd* is not **FSCONFIG\_SET\_PATH\_EMPTY**. - **ENOMEM** The kernel could not allocate sufficient memory to complete the operation. - **ENOTBLK** The parameter named by *key* must be a block device, but the provided parameter value was not a block device. - **ENOTDIR** A component of the path prefix of a path argument was not a directory. - **EOPNOTSUPP** The command given by *cmd* is not valid. - **ENXIO** The major number of a block device parameter is out of range. - **EPERM** The command given by *cmd* was **FSCONFIG\_CMD\_CREATE**, **FSCONFIG\_CMD\_CREATE\_EXCL**, or **FSCONFIG\_CMD\_RECONFIGURE**, but the calling process does not have the required **CAP\_SYS\_ADMIN** capability. ## STANDARDS Linux. ## HISTORY Linux 5.2. glibc 2.36. ## NOTES ### Generic filesystem parameters Each filesystem driver is responsible for parsing most parameters specified with **fsconfig**(), meaning that individual filesystems may have very different behavior when encountering parameters with the same name. In general, you should not assume that the behavior of **fsconfig**() when specifying a parameter to one filesystem type will match the behavior of the same parameter with a different filesystem type. However, the following generic parameters apply to all filesystems and have unified behavior. They are set using the listed **FSCONFIG\_SET\_***\** command. - **ro** and **rw** (**FSCONFIG\_SET\_FLAG**) Configure whether the filesystem instance is read-only. - **dirsync** (**FSCONFIG\_SET\_FLAG**) Make directory changes on this filesystem instance synchronous. - **sync** and **async** (**FSCONFIG\_SET\_FLAG**) Configure whether writes on this filesystem instance will be made synchronous (as though the **O\_SYNC** flag to [**open**(2)](/open/2.md) was specified for all file opens in this filesystem instance). - **lazytime** and **nolazytime** (**FSCONFIG\_SET\_FLAG**) Configure whether to reduce on-disk updates of inode timestamps on this filesystem instance (as described in the **MS\_LAZYTIME** section of [**mount**(2)](/mount/2.md)). - **mand** and **nomand** (**FSCONFIG\_SET\_FLAG**) Configure whether the filesystem instance should permit mandatory locking. Since Linux 5.15, mandatory locking has been deprecated and setting this flag is a no-op. - **source** (**FSCONFIG\_SET\_STRING**) This parameter is equivalent to the *source* parameter passed to [**mount**(2)](/mount/2.md) for the same filesystem type, and is usually the pathname of a block device containing the filesystem. This parameter may only be set once per filesystem configuration context transaction. In addition, any filesystem parameters associated with Linux Security Modules (LSMs) are also generic with respect to the underlying filesystem. See the documentation for the LSM you wish to configure for more details. ### Mount attributes and filesystem parameters Some filesystem parameters (traditionally associated with [**mount**(8)](/mount/8.md)-style options) have a sibling mount attribute with superficially similar user-facing behavior. For a description of the distinction between mount attributes and filesystem parameters, see the "Mount attributes and filesystem parameters" subsection of [**mount\_setattr**(2)](/mount_setattr/2.md). ## CAVEATS ### Filesystem parameter types As a result of each filesystem driver being responsible for parsing most parameters specified with **fsconfig**(), some filesystem drivers may have unintuitive behavior with regards to which **FSCONFIG\_SET\_***\** commands are permitted to configure a given parameter. In order for filesystem parameters to be backwards compatible with [**mount**(2)](/mount/2.md), they must be parseable as strings; this almost universally means that **FSCONFIG\_SET\_STRING** can also be used to configure them. However, other **FSCONFIG\_SET\_***\** commands need to be opted into by each filesystem driver's parameter parser. One of the most user-visible instances of this inconsistency is that many filesystems do not support configuring path parameters with **FSCONFIG\_SET\_PATH** (despite the name), which can lead to somewhat confusing **EINVAL** errors. (For example, the generic *source* parameter—which is usually a path—can only be configured with **FSCONFIG\_SET\_STRING**.) When writing programs that use **fsconfig**() to configure parameters with commands other than **FSCONFIG\_SET\_STRING**, users should verify that the **FSCONFIG\_SET\_***\** commands used to configure each parameter are supported by the corresponding filesystem driver. ## EXAMPLES To illustrate the different kinds of flags that can be configured with **fsconfig**(), here are a few examples of some different filesystems being created: ``` int fsfd, mntfd; fsfd = fsopen("tmpfs", FSOPEN_CLOEXEC); fsconfig(fsfd, FSCONFIG_SET_FLAG, "inode64", NULL, 0); fsconfig(fsfd, FSCONFIG_SET_STRING, "uid", "1234", 0); fsconfig(fsfd, FSCONFIG_SET_STRING, "huge", "never", 0); fsconfig(fsfd, FSCONFIG_SET_FLAG, "casefold", NULL, 0); fsconfig(fsfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0); mntfd = fsmount(fsfd, FSMOUNT_CLOEXEC, MOUNT_ATTR_NOEXEC); move_mount(mntfd, "", AT_FDCWD, "/tmp", MOVE_MOUNT_F_EMPTY_PATH); fsfd = fsopen("erofs", FSOPEN_CLOEXEC); fsconfig(fsfd, FSCONFIG_SET_STRING, "source", "/dev/loop0", 0); fsconfig(fsfd, FSCONFIG_SET_FLAG, "acl", NULL, 0); fsconfig(fsfd, FSCONFIG_SET_FLAG, "user_xattr", NULL, 0); fsconfig(fsfd, FSCONFIG_CMD_CREATE_EXCL, NULL, NULL, 0); mntfd = fsmount(fsfd, FSMOUNT_CLOEXEC, MOUNT_ATTR_NOSUID); move_mount(mntfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH); ``` Usually, specifying the same parameter named by *key* multiple times with **fsconfig**() causes the parameter value to be replaced. However, some filesystems may have unique behavior: ``` int fsfd, mntfd; int lowerdirfd = open("/o/ctr/lower1", O_DIRECTORY | O_CLOEXEC); fsfd = fsopen("overlay", FSOPEN_CLOEXEC); /* "lowerdir+" appends to the lower dir stack each time */ fsconfig(fsfd, FSCONFIG_SET_FD, "lowerdir+", NULL, lowerdirfd); fsconfig(fsfd, FSCONFIG_SET_STRING, "lowerdir+", "/o/ctr/lower2", 0); fsconfig(fsfd, FSCONFIG_SET_STRING, "lowerdir+", "/o/ctr/lower3", 0); fsconfig(fsfd, FSCONFIG_SET_STRING, "lowerdir+", "/o/ctr/lower4", 0); fsconfig(fsfd, FSCONFIG_SET_STRING, "xino", "auto", 0); fsconfig(fsfd, FSCONFIG_SET_STRING, "nfs_export", "off", 0); fsconfig(fsfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0); mntfd = fsmount(fsfd, FSMOUNT_CLOEXEC, 0); move_mount(mntfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH); ``` And here is an example of how [**fspick**(2)](/fspick/2.md) can be used with **fsconfig**() to reconfigure the parameters of an extant filesystem instance attached to */proc*: ``` int fsfd = fspick(AT_FDCWD, "/proc", FSPICK_CLOEXEC); fsconfig(fsfd, FSCONFIG_SET_STRING, "hidepid", "ptraceable", 0); fsconfig(fsfd, FSCONFIG_SET_STRING, "subset", "pid", 0); fsconfig(fsfd, FSCONFIG_CMD_RECONFIGURE, NULL, NULL, 0); ``` ## SEE ALSO [**fsmount**(2)](/fsmount/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)