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 [off-list ref]
Signed-off-by: David Howells <dhowells@redhat.com>
Co-authored-by: Christian Brauner [off-list ref]
Signed-off-by: Christian Brauner <brauner@kernel.org>
Signed-off-by: Aleksa Sarai <redacted>
---
 man/man2/fsconfig.2 | 729 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 729 insertions(+)

diff --git a/man/man2/fsconfig.2 b/man/man2/fsconfig.2
new file mode 100644
index 0000000000000000000000000000000000000000..a2d844a105c74f17af640d6991046dbd5fa69cf0
--- /dev/null
+++ b/man/man2/fsconfig.2

@@ -0,0 +1,729 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH fsconfig 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+fsconfig \- configure new or existing filesystem context
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/mount.h>
+.P
+.BI "int fsconfig(int " fd ", unsigned int " cmd ,
+.BI "             const char *_Nullable " key ,
+.BI "             const void *_Nullable " value ", int " aux );
+.fi
+.SH DESCRIPTION
+The
+.BR fsconfig ()
+system call is part of
+the suite of file-descriptor-based mount facilities in Linux.
+.P
+.BR fsconfig ()
+is used to supply parameters to
+and issue commands against
+the filesystem configuration context
+associated with the file descriptor
+.IR fd .
+Filesystem configuration contexts can be created with
+.BR fsopen (2)
+or be instantiated from an extant filesystem instance with
+.BR fspick (2).
+.P
+The
+.I cmd
+argument indicates the command to be issued.
+Some commands supply parameters to the context
+(equivalent to mount options specified with
+.BR mount (8)),
+while others are meta-operations on the filesystem context.
+The list of valid
+.I cmd
+values are:
+.RS
+.TP
+.B FSCONFIG_SET_FLAG
+Set the flag parameter named by
+.IR key .
+.I value
+must be NULL,
+and
+.I aux
+must be 0.
+.TP
+.B FSCONFIG_SET_STRING
+Set the string parameter named by
+.I key
+to the value specified by
+.IR value .
+.I value
+points to a null-terminated string,
+and
+.I aux
+must be 0.
+.TP
+.B FSCONFIG_SET_BINARY
+Set the blob parameter named by
+.I key
+to the contents of the binary blob
+specified by
+.IR value .
+.I value
+points to
+the start of a buffer
+that is
+.I aux
+bytes in length.
+.TP
+.B FSCONFIG_SET_FD
+Set the file parameter named by
+.I key
+to the open file description
+referenced by the file descriptor
+.IR aux .
+.I value
+must be NULL.
+.IP
+You may also use
+.B \%FSCONFIG_SET_STRING
+for file parameters,
+with
+.I 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
+.BR mount (2)-based
+programs,
+and only works for parameters
+that
+.I only
+accept file descriptor arguments.
+.TP
+.B FSCONFIG_SET_PATH
+Set the path parameter named by
+.I key
+to the object at a provided path,
+resolved in a similar manner to
+.BR openat (2).
+.I value
+points to a null-terminated pathname string,
+and
+.I aux
+is equivalent to the
+.I dirfd
+argument to
+.BR openat (2).
+See
+.BR openat (2)
+for an explanation of the need for
+.BR \%FSCONFIG_SET_PATH .
+.IP
+You may also use
+.B \%FSCONFIG_SET_STRING
+for path parameters,
+the behaviour of which is equivalent to
+.B \%FSCONFIG_SET_PATH
+with
+.I aux
+set to
+.BR \%AT_FDCWD .
+.TP
+.B FSCONFIG_SET_PATH_EMPTY
+As with
+.BR \%FSCONFIG_SET_PATH ,
+except that if
+.I value
+is an empty string,
+the file descriptor specified by
+.I aux
+is operated on directly
+and may be any type of file
+(not just a directory).
+This is equivalent to the behaviour of
+.B \%AT_EMPTY_PATH
+with most "*at()" system calls.
+If
+.I aux
+is
+.BR \%AT_FDCWD ,
+the parameter will be set to
+the current working directory
+of the calling process.
+.TP
+.B 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.
+.I key
+and
+.I value
+must be NULL,
+and
+.I aux
+must be 0.
+.IP
+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
+.I fd
+now references the created filesystem instance,
+and is placed into a special "awaiting-mount" mode
+that allows you to use
+.BR fsmount (2)
+to create a mount object from the filesystem instance.
+.\" FS_CONTEXT_AWAITING_MOUNT is the term the kernel uses for this.
+If the operation fails,
+in most cases
+the filesystem context is placed in a failed mode
+and cannot be used for any further
+.BR fsconfig ()
+operations
+(though you may still retrieve diagnostic messages
+through the message retrieval interface,
+as described in
+the corresponding subsection of
+.BR fsopen (2)).
+.IP
+This command can only be issued against
+filesystem configuration contexts
+that were created with
+.BR fsopen (2).
+In order to create a filesystem instance,
+the calling process must have the
+.B \%CAP_SYS_ADMIN
+capability.
+.IP
+An important thing to be aware of is that
+the Linux kernel will
+.I 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
+.B \%FSCONFIG_CMD_CREATE
+may, in fact, be a reference
+to an extant filesystem instance in the kernel.
+(For reference,
+this behaviour also applies to
+.BR mount (2).)
+.IP
+One side-effect of this behaviour is that
+if an extant filesystem instance is reused,
+.I all
+parameters configured
+for this filesystem configuration context
+are
+.I silently ignored
+(with the exception of the
+.I ro
+and
+.I 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
+.BR EBUSY ).
+This also means that
+.B \%FSCONFIG_CMD_RECONFIGURE
+commands issued against
+the "created" filesystem instance
+will also affect any mount objects associated with
+the extant filesystem instance.
+.IP
+Programs that need to ensure
+that they create a new filesystem instance
+with specific parameters
+(notably, security-related parameters
+such as
+.I acl
+to enable POSIX ACLs\[em]\c
+as described in
+.BR acl (5))
+should use
+.B \%FSCONFIG_CMD_CREATE_EXCL
+instead.
+.TP
+.BR FSCONFIG_CMD_CREATE_EXCL " (since Linux 6.6)"
+.\" commit 22ed7ecdaefe0cac0c6e6295e83048af60435b13
+.\" commit 84ab1277ce5a90a8d1f377707d662ac43cc0918a
+As with
+.BR \%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
+.B EBUSY
+instead.
+.IP
+As a result (unlike
+.BR \%FSCONFIG_CMD_CREATE ),
+if this operation succeeds
+then the calling process can be sure that
+all of the parameters successfully configured with
+.BR fsconfig ()
+will actually be applied
+to the created filesystem instance.
+.TP
+.B 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.
+.I key
+and
+.I value
+must be NULL,
+and
+.I aux
+must be 0.
+.IP
+This is primarily intended for use with
+.BR fspick (2),
+but may also be used to modify
+the parameters of a filesystem instance
+after
+.B \%FSCONFIG_CMD_CREATE
+was used to create it
+and a mount object was created using
+.BR fsmount (2).
+In order to reconfigure an extant filesystem instance,
+the calling process must have the
+.B CAP_SYS_ADMIN
+capability.
+.IP
+If the operation succeeds,
+the filesystem context is reset
+but remains in reconfiguration mode
+and thus can be reused for subsequent
+.B \%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
+.BR fsconfig ()
+operations
+(though you may still retrieve diagnostic messages
+through the message retrieval interface,
+as described in
+the corresponding subsection of
+.BR fsopen (2)).
+.RE
+.P
+Parameters specified with
+.BI FSCONFIG_SET_ *
+do not take effect
+until a corresponding
+.B \%FSCONFIG_CMD_CREATE
+or
+.B \%FSCONFIG_CMD_RECONFIGURE
+command is issued.
+.SH RETURN VALUE
+On success,
+.BR fsconfig ()
+returns 0.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH 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
+.BR read (2)
+on the filesystem instance or filesystem configuration context
+referenced by the file descriptor
+.IR fd .
+(See the "Message retrieval interface" subsection in
+.BR fsopen (2)
+for more details on the message format.)
+.P
+Even after an error occurs,
+the filesystem configuration context is
+.I not
+invalidated,
+and thus can still be used with other
+.BR 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.
+.P
+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.
+.TP
+.B EACCES
+A component of a path
+provided as a path parameter
+was not searchable.
+(See also
+.BR path_resolution (7).)
+.TP
+.B EACCES
+.B \%FSCONFIG_CMD_CREATE
+was attempted
+for a read-only filesystem
+without specifying the
+.RB ' ro '
+flag parameter.
+.TP
+.B EACCES
+A specified block device parameter
+is located on a filesystem
+mounted with the
+.B \%MS_NODEV
+option.
+.TP
+.B EBADF
+The file descriptor given by
+.I fd
+(or possibly by
+.IR aux ,
+depending on the command)
+is invalid.
+.TP
+.B EBUSY
+The filesystem context associated with
+.I fd
+is in the wrong state
+for the given command.
+.TP
+.B EBUSY
+The filesystem instance cannot be reconfigured as read-only
+with
+.B \%FSCONFIG_CMD_RECONFIGURE
+because some programs
+still hold files open for writing.
+.TP
+.B EBUSY
+A new filesystem instance was requested with
+.B \%FSCONFIG_CMD_CREATE_EXCL
+but a matching superblock already existed.
+.TP
+.B EFAULT
+One of the pointer arguments
+points to a location
+outside the calling process's accessible address space.
+.TP
+.B EINVAL
+.I fd
+does not refer to
+a filesystem configuration context
+or filesystem instance.
+.TP
+.B EINVAL
+One of the values of
+.IR name ,
+.IR value ,
+and/or
+.I aux
+were set to a non-zero value when
+.I cmd
+required that they be zero
+(or NULL).
+.TP
+.B EINVAL
+The parameter named by
+.I name
+cannot be set
+using the type specified with
+.IR cmd .
+.TP
+.B EINVAL
+One of the source parameters
+referred to
+an invalid superblock.
+.TP
+.B ELOOP
+Too many links encountered
+during pathname resolution
+of a path argument.
+.TP
+.B ENAMETOOLONG
+A path argument was longer than
+.BR PATH_MAX .
+.TP
+.B ENOENT
+A path argument had a non-existent component.
+.TP
+.B ENOENT
+A path argument is an empty string,
+but
+.I cmd
+is not
+.BR \%FSCONFIG_SET_PATH_EMPTY .
+.TP
+.B ENOMEM
+The kernel could not allocate sufficient memory to complete the operation.
+.TP
+.B ENOTBLK
+The parameter named by
+.I name