[PATCH 00/10] man2: add man pages for 'new' mount API

[PATCH 00/10] man2: add man pages for 'new' mount API

[Aleksa Sarai]

Back in 2019, the new mount API was merged into mainline[1]. David Howells
then set about writing man pages for these new APIs, and sent some
patches back in 2020[2]. Unfortunately, these patches were never merged,
which meant that these APIs were practically undocumented for many
years -- arguably this may have been a contributing factor to the
relatively slow adoption of these new (far better) APIs. I have often
discovered that many folks are unaware of the read(2)-based message
retrieval interface provided by filesystem context file descriptors.

In 2024, Christian Brauner set aside some time to provide some
documentation of these new APIs and so adapted David Howell's original
man pages into the easier-to-edit Markdown format and published them on
GitHub[3]. These have been maintained since, including updated
information on new features added since David Howells's 2020 draft pages
(such as MOVE_MOUNT_BENEATH).

While this was a welcome improvement to the previous status quo (that
had lasted over 6 years), speaking personally my experience is that not
having access to these man pages from the terminal has been a fairly
common painpoint.

So, this is a modern version of the man pages for these APIs, in the hopes
that we can finally (7 years later) get proper documentation for these
APIs in the man-pages project.

One important thing to note is that most of these were re-written by me,
with very minimal copying from the versions available from Christian[2].
The reasons for this are two-fold:

 * Both Howells's original version and Christian's maintained versions
   contain crucial mistakes that I have been bitten by in the past (the
   most obvious being that all of these APIs were merged in Linux 5.2,
   but the man pages all claim they were merged in different versions.)

 * As the man pages appear to have been written from Howells's
   perspective while implementing them, some of the wording is a little
   too tied to the implementation (or appears to describe features that
   don't really exist in the merged versions of these APIs).

I decided that the best way to resolve these issues is to rewrite them
from the perspective of an actual user of these APIs (me), and check
that we do not repeat the mistakes I found in the originals.

I have also done my best to resolve the issues raised by Michael Kerrisk
on the original patchset sent by Howells[1].

In addition, I have also included a man page for open_tree_attr(2) (as a
subsection of the new open_tree(2) man page), which was merged in Linux
6.15.

[1]: https://lore.kernel.org/all/20190507204921.GL23075@ZenIV.linux.org.uk/
[2]: https://lore.kernel.org/linux-man/159680892602.29015.6551860260436544999.stgit@warthog.procyon.org.uk/
[3]: https://github.com/brauner/man-pages-md

Co-developed-by: David Howells <dhowells@redhat.com>
Co-developed-by: Christian Brauner <brauner@kernel.org>
Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
---
Aleksa Sarai (10):
      mount_setattr.2: document glibc >= 2.36 syscall wrappers
      mount_setattr.2: move mount_attr struct to mount_attr.2type
      fsopen.2: document 'new' mount api
      fspick.2: document 'new' mount api
      fsconfig.2: document 'new' mount api
      fsmount.2: document 'new' mount api
      move_mount.2: document 'new' mount api
      open_tree.2: document 'new' mount api
      mount_setattr.2: mirror opening sentence from fsopen(2)
      open_tree_attr.2, open_tree.2: document new open_tree_attr() api

 man/man2/fsconfig.2           | 446 +++++++++++++++++++++++++++++++++++++++
 man/man2/fsmount.2            | 185 +++++++++++++++++
 man/man2/fsopen.2             | 275 ++++++++++++++++++++++++
 man/man2/fspick.2             | 274 ++++++++++++++++++++++++
 man/man2/mount_setattr.2      |  67 ++----
 man/man2/move_mount.2         | 470 ++++++++++++++++++++++++++++++++++++++++++
 man/man2/open_tree.2          | 440 +++++++++++++++++++++++++++++++++++++++
 man/man2/open_tree_attr.2     |   1 +
 man/man2type/mount_attr.2type |  58 ++++++
 9 files changed, 2166 insertions(+), 50 deletions(-)
---
base-commit: f23e8249a6dcf695d38055483802779c36aedbba
change-id: 20250802-new-mount-api-436db984f432

Best regards,
-- 
Aleksa Sarai <cyphar@cyphar.com>

[PATCH 01/10] mount_setattr.2: document glibc >= 2.36 syscall wrappers

[Aleksa Sarai]

Glibc 2.36 added syscall wrappers for the entire family of fd-based
mount syscalls, including mount_setattr(2). Thus it's no longer
necessary to instruct users to do raw syscall(2) operations.

Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
---
 man/man2/mount_setattr.2 | 45 ++++++++-------------------------------------
 1 file changed, 8 insertions(+), 37 deletions(-)

diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2
index 60d9cf9de8aa..b8ddc3e22aef 100644
--- a/man/man2/mount_setattr.2
+++ b/man/man2/mount_setattr.2
@@ -10,21 +10,14 @@ Standard C library
 .RI ( libc ,\~ \-lc )
 .SH SYNOPSIS
 .nf
-.BR "#include <linux/fcntl.h>" " /* Definition of " AT_* " constants */"
-.BR "#include <linux/mount.h>" " /* Definition of " MOUNT_ATTR_* " constants */"
-.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
+.B #define _GNU_SOURCE
+.B #include <sys/mount.h>
 .B #include <unistd.h>
+.BR "#include <fcntl.h>" "       /* Definition of " AT_* " constants */"
 .P
-.BI "int syscall(SYS_mount_setattr, int " dirfd ", const char *" path ,
-.BI "            unsigned int " flags ", struct mount_attr *" attr \
-", size_t " size );
+.BI "int mount_setattr(int " dirfd ", const char *" path ", unsigned int " flags ",
+.BI "                  struct mount_attr *" attr ", size_t " size );
 .fi
-.P
-.IR Note :
-glibc provides no wrapper for
-.BR mount_setattr (),
-necessitating the use of
-.BR syscall (2).
 .SH DESCRIPTION
 The
 .BR mount_setattr ()
@@ -586,6 +579,7 @@ Linux 5.12.
 .\" commit 7d6beb71da3cc033649d641e1e608713b8220290
 .\" commit 2a1867219c7b27f928e2545782b86daaf9ad50bd
 .\" commit 9caccd41541a6f7d6279928d9f971f6642c361af
+Glibc 2.36.
 .SH NOTES
 .SS ID-mapped mounts
 Creating an ID-mapped mount makes it possible to
@@ -914,37 +908,14 @@ with a structure which has every byte nonzero
 #include <err.h>
 #include <fcntl.h>
 #include <getopt.h>
-#include <linux/mount.h>
-#include <linux/types.h>
+#include <sys/mount.h>
+#include <sys/types.h>
 #include <stdbool.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
-#include <sys/syscall.h>
 #include <unistd.h>
 \&
-static inline int
-mount_setattr(int dirfd, const char *path, unsigned int flags,
-              struct mount_attr *attr, size_t size)
-{
-    return syscall(SYS_mount_setattr, dirfd, path, flags,
-                   attr, size);
-}
-\&
-static inline int
-open_tree(int dirfd, const char *filename, unsigned int flags)
-{
-    return syscall(SYS_open_tree, dirfd, filename, flags);
-}
-\&
-static inline int
-move_mount(int from_dirfd, const char *from_path,
-           int to_dirfd, const char *to_path, unsigned int flags)
-{
-    return syscall(SYS_move_mount, from_dirfd, from_path,
-                   to_dirfd, to_path, flags);
-}
-\&
 static const struct option longopts[] = {
     {"map\-mount",       required_argument,  NULL,  \[aq]a\[aq]},
     {"recursive",       no_argument,        NULL,  \[aq]b\[aq]},

-- 
2.50.1

[PATCH 02/10] mount_setattr.2: move mount_attr struct to mount_attr.2type

[Aleksa Sarai]

As with openat2(2type), it makes sense to move this to a separate man
page. In addition, future man pages added in this patchset will want to
reference mount_attr(2type).

Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
---
 man/man2/mount_setattr.2      | 16 +++---------
 man/man2type/mount_attr.2type | 58 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 62 insertions(+), 12 deletions(-)

diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2
index b8ddc3e22aef..e863be64deb5 100644
--- a/man/man2/mount_setattr.2
+++ b/man/man2/mount_setattr.2
@@ -116,18 +116,10 @@ The
 .I attr
 argument of
 .BR mount_setattr ()
-is a structure of the following form:
-.P
-.in +4n
-.EX
-struct mount_attr {
-    __u64 attr_set;     /* Mount properties to set */
-    __u64 attr_clr;     /* Mount properties to clear */
-    __u64 propagation;  /* Mount propagation type */
-    __u64 userns_fd;    /* User namespace file descriptor */
-};
-.EE
-.in
+is a pointer to a
+.I mount_attr
+structure, described in
+.BR mount_attr (2type).
 .P
 The
 .I attr_set
diff --git a/man/man2type/mount_attr.2type b/man/man2type/mount_attr.2type
new file mode 100644
index 000000000000..733dbc3c8cdb
--- /dev/null
+++ b/man/man2type/mount_attr.2type
@@ -0,0 +1,58 @@
+
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH mount_attr 2type (date) "Linux man-pages (unreleased)"
+.SH NAME
+mount_attr \- what mount properties to set and clear
+.SH LIBRARY
+Linux kernel headers
+.SH SYNOPSIS
+.EX
+.B #include <sys/mount.h>
+.P
+.B struct mount_attr {
+.BR "    __u64 attr_set;" "     /* Mount properties to set */"
+.BR "    __u64 attr_clr;" "     /* Mount properties to clear */"
+.BR "    __u64 propagation;" "  /* Mount propagation type */"
+.BR "    __u64 userns_fd;" "    /* User namespace file descriptor */"
+    /* ... */
+.B };
+.EE
+.SH DESCRIPTION
+Specifies which mount properties should be changed with
+.BR mount_setattr (2).
+.P
+The fields are as follows:
+.TP
+.I attr_set
+This field specifies which
+.B MOUNT_ATTR_*
+attribute flags to set.
+.TP
+.I attr_clr
+This fields specifies which
+.B MOUNT_ATTR_*
+attribute flags to clear.
+.TP
+.I propagation
+This field specifies what mount propagation will be applied.
+The valid values of this field are the same propagation types described in
+.BR mount_namespaces (7).
+.TP
+.I userns_fd
+This fields specifies a file descriptor that indicates which user namespace to
+use as a reference for ID-mapped mounts with
+.BR MOUNT_ATTR_IDMAP .
+.SH VERSIONS
+Extra fields may be appended to the structure, with a zero value in a new field
+resulting in the kernel behaving as though that extension field was not
+present.
+Therefore, a user
+.I must
+zero-fill this structure on initialization.
+.SH STANDARDS
+Linux.
+.SH SEE ALSO
+.BR mount_setattr (2)

-- 
2.50.1

[PATCH 03/10] fsopen.2: document 'new' mount api

[Aleksa Sarai]

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-developed-by: David Howells <dhowells@redhat.com>
Co-developed-by: Christian Brauner <brauner@kernel.org>
Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
---
 man/man2/fsopen.2 | 275 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 275 insertions(+)

diff --git a/man/man2/fsopen.2 b/man/man2/fsopen.2
new file mode 100644
index 000000000000..43a1709ec5b4
--- /dev/null
+++ b/man/man2/fsopen.2
@@ -0,0 +1,275 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH fsopen 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+fsopen \- create a new filesystem context
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <sys/mount.h>"
+.BR "#include <unistd.h>"
+.P
+.BI "int fsopen(const char *" fsname ", unsigned int " flags ");
+.fi
+.SH DESCRIPTION
+The
+.BR fsopen ()
+system call is part of the suite of file descriptor based mount facilities in
+Linux.
+.P
+.BR fsopen ()
+creates a blank filesystem configuration context within the kernel for the
+filesystem named by
+.IR fsname ,
+puts the context into creation mode and attaches it to a file descriptor, which
+is then returned.
+The calling process must have the
+.BR CAP_SYS_ADMIN
+capability in order to create a new filesystem configuration context.
+.P
+After obtaining a filesystem configuration context with
+.BR fsopen (),
+the general workflow for operating on the context looks like the following:
+.RS
+.IP 1. 3
+Pass the filesystem context file descriptor to
+.BR fsconfig (2)
+to specify any desired filesystem parameters.
+This can be done as many times as necessary.
+.IP 2.
+Pass the same filesystem context file descriptor to
+.BR fsconfig (2)
+with
+.B FSCONFIG_CMD_CREATE
+to create an instance of the configured filesystem.
+.IP 3.
+Pass the same filesystem context file descriptor to
+.BR fsmount (2)
+to create a new mount object for the root of the filesystem, which is then
+attached to a new file descriptor.
+.IP 4.
+Use the mount object file descriptor as a
+.I dirfd
+argument to "*at()" system calls; or attach the mount object to a mount point
+by passing the mount object file descriptor to
+.BR move_mount (2).
+.RE
+.P
+A filesystem configuration context is an in-kernel representation of a pending
+transaction containing a set of configuration parameters that are to be applied
+when creating a new instance of a filesystem or modifying the configuration of
+an existing filesystem instance.
+The filesystem context will move between different modes throughout its
+lifecycle (such as the creation phase when created with
+.BR fsopen (),
+the reconfiguration phase when an existing filesystem instance is selected by
+.BR fspick (2),
+and the needs-mount phase between
+.BR FSCONFIG_CMD_CREATE
+and
+.BR fsmount (2)),
+which has an impact on what operations are permitted on the filesystem context.
+.P
+The file descriptor returned by
+.BR fsopen ()
+also acts as a channel for filesystems to provide more comprehensive error,
+warning, and information messages than normally provided using the
+.BR errno (3)
+interface.
+If an error occurs at any time during the workflow mentioned above, calling
+.BR read (2)
+on the filesystem context file descriptor will retrieve any ancillary
+information about the encountered errors.
+(See the "Message Retrieval Interface" section for more details on the message
+format.)
+.P
+.I flags
+can be used to control aspects of the creation of the file configuration
+context.
+A value for
+.I flags
+is constructed by OR'ing together zero or more of the following constants:
+.RS
+.TP
+.B FSOPEN_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
+A list of filesystems supported by the running kernel (and thus a list of valid
+values for
+.IR fsname )
+can be obtained from
+.IR /proc/filesystems .
+(See also
+.BR proc_filesystems (5).)
+.SS Message Retrieval Interface
+When doing operations on a filesystem configuration context, the filesystem
+driver may choose to provide ancillary information to userspace in the form of
+message strings.
+.P
+The filesystem context file descriptors returned by
+.BR fsopen "() and " fspick (2)
+may be queried for message strings at any time by calling
+.BR read (2)
+on the file descriptor.
+This will return newline-separated messages that are prefixed to indicate their
+class:
+.RS
+.TP
+.B "e <message>"
+An error message was logged.
+This is usually associated with an error being returned from the corresponding
+system call which triggered this message.
+.TP
+.B "w <message>"
+A warning message was logged.
+.TP
+.B "i <message>"
+An informational message was logged.
+.RE
+.P
+Messages are removed from the queue as they are read.
+Note that the message queue has limited depth, so it is possible for messages
+to get lost.
+If there are no messages in the message queue,
+.B read(2)
+will return no data.
+.P
+If there are multiple filesystem context file descriptors referencing the same
+filesystem instance (such as if you call
+.BR fspick (2)
+multiple times for the same mount), each one gets its own independent message
+queue.
+This does not apply to file descriptors that were duplicated with
+.BR dup (2).
+.P
+Usually messages will be prefixed by the filesystem driver that logged the
+message, though this may not always be the case.
+See the Linux kernel source code for details.
+.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 EFAULT
+One of the pointer arguments points to a location outside the calling process's
+accessible address space.
+.TP
+.B EINVAL
+.I flags
+had an invalid 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 ENODEV
+The filesystem named by
+.I fsname
+is not supported by the kernel.
+.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 24dcb3d90a1f67fe08c68a004af37df059d74005
+Glibc 2.36.
+.SH EXAMPLES
+To illustrate the workflow for creating a new mount, the following is a sample
+of how to mount an ext4 filesystem stored on "/dev/sdb1" onto "/mnt".
+.P
+.in +4n
+.EX
+int sfd = fsopen("ext4", FSOPEN_CLOEXEC);
+fsconfig(sfd, FSCONFIG_SET_FLAG, "ro", NULL, 0);
+fsconfig(sfd, FSCONFIG_SET_PATH, "source", "/dev/sdb1", AT_FDCWD);
+fsconfig(sfd, FSCONFIG_SET_FLAG, "noatime", NULL, 0);
+fsconfig(sfd, FSCONFIG_SET_FLAG, "acl", NULL, 0);
+fsconfig(sfd, FSCONFIG_SET_FLAG, "user_xattr", NULL, 0);
+fsconfig(sfd, FSCONFIG_SET_FLAG, "iversion", NULL, 0)
+fsconfig(sfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
+int mfd = fsmount(sfd, FSMOUNT_CLOEXEC, MOUNT_ATTR_RELATIME);
+move_mount(mfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH);
+.EE
+.in
+.P
+First, an ext4 configuration context is created and attached to the file
+descriptor
+.IR sfd .
+Then, a series of parameters (such as the source of the filesystem) are
+provided using
+.BR fsconfig (2),
+followed by the filesystem instance being created with
+.BR FSCONFIG_CMD_CREATE .
+.BR fsmount (2)
+is then used to create a new mount object attached to the file descriptor
+.IR mfd ,
+which is then attached to the intended mount point using
+.BR move_mount (2).
+.P
+The above procedure is functionally equivalent to the following mount operation
+using
+.BR mount (2):
+.P
+.in +4n
+.EX
+mount("/dev/sdb1", "/mnt", "ext4", MS_RELATIME,
+      "ro,noatime,acl,user_xattr,iversion");
+.EE
+.in
+.P
+And here's an example of creating a mount object of an NFS server share and
+setting a Smack security module label.
+However, instead of mounting it to a place on the filesystem, the program
+instead uses the mount object directly to open a file from the NFS share.
+.P
+.in +4n
+.EX
+int sfd = fsopen("nfs", 0);
+fsconfig(sfd, FSCONFIG_SET_STRING, "source", "example.com/pub/linux", 0);
+fsconfig(sfd, FSCONFIG_SET_STRING, "nfsvers", "3", 0);
+fsconfig(sfd, FSCONFIG_SET_STRING, "rsize", "65536", 0);
+fsconfig(sfd, FSCONFIG_SET_STRING, "wsize", "65536", 0);
+fsconfig(sfd, FSCONFIG_SET_STRING, "smackfsdef", "foolabel", 0);
+fsconfig(sfd, FSCONFIG_SET_FLAG, "rdma", NULL, 0);
+fsconfig(sfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
+int mfd = fsmount(sfd, 0, MOUNT_ATTR_NODEV);
+int fd = openat(mfd, "src/linux-5.2.tar.xz", O_RDONLY);
+.EE
+.in
+.P
+Unlike the previous example, this operation has no trivial equivalent with
+.BR mount (2),
+as it was not previously possible to create a mount object that is not attached
+to any mount point.
+.SH SEE ALSO
+.BR mount (2),
+.BR fsconfig (2),
+.BR fsmount (2),
+.BR fspick (2),
+.BR open_tree (2),
+.BR move_mount (2),
+.BR mount_setattr (2),
+.BR mount_namespaces (7)

-- 
2.50.1

[PATCH 04/10] fspick.2: document 'new' mount api

[Aleksa Sarai]

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-developed-by: David Howells <dhowells@redhat.com>
Co-developed-by: Christian Brauner <brauner@kernel.org>
Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
---
 man/man2/fspick.2 | 274 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 274 insertions(+)

diff --git a/man/man2/fspick.2 b/man/man2/fspick.2
new file mode 100644
index 000000000000..a1e769a8935a
--- /dev/null
+++ b/man/man2/fspick.2
@@ -0,0 +1,274 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH fspick 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+fspick \- select filesystem for reconfiguration
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.B #define _GNU_SOURCE
+.BR "#include <sys/mount.h>"
+.BR "#include <unistd.h>"
+.BR "#include <fcntl.h>" \
+"          /* Definition of " AT_* " constants */"
+.P
+.BI "int fspick(int " dirfd ", const char *" pathname ", unsigned int " flags ");
+.fi
+.SH DESCRIPTION
+The
+.BR fspick ()
+system call is part of the suite of file descriptor based mount facilities in
+Linux.
+.P
+.BR fspick()
+creates a new filesystem configuration context for the filesystem instance
+associated with the path described by
+.IR dirfd " and " pathname ,
+places it into reconfiguration mode (similar to
+.BR mount (8)
+with the "-o remount" option), and attaches it to a new file descriptor, which
+is then returned.
+The calling process must have the
+.BR CAP_SYS_ADMIN
+capability in order to create a new filesystem configuration context.
+.P
+The resultant file descriptor can be used with
+.BR fsconfig (2)
+to specify the desired set of changes to mount parameters of the filesystem
+instance.
+Once the desired set of changes have been configured, the changes can be
+effectuated by calling
+.BR fsconfig (2)
+with the
+.B FSCONFIG_CMD_RECONFIGURE
+command.
+.P
+As with most "*at()" system calls,
+.BR fspick ()
+uses the
+.I dirfd
+argument in conjunction with the
+.I pathname
+argument to determine the path to operate on, as follows:
+.RS
+.IP \[bu] 3
+If the pathname given in
+.I pathname
+is absolute, then
+.I dirfd
+is ignored.
+.IP \[bu]
+If the pathname given in
+.I pathname
+is relative and
+.I dirfd
+is the special value
+.BR AT_FDCWD ,
+then
+.I pathname
+is interpreted relative to the current working
+directory of the calling process (like
+.BR open ()).
+.IP \[bu]
+If the pathname given in
+.I pathname
+is relative, then it is interpreted relative to the directory
+referred to by the file descriptor
+.I dirfd
+(rather than relative to the current working directory of
+the calling process, as is done by
+.BR open ()
+for a relative pathname).
+In this case,
+.I dirfd
+must be a directory that was opened for reading
+.RB ( O_RDONLY )
+or using the
+.B O_PATH
+flag.
+.IP \[bu]
+If
+.I pathname
+is an empty string, and
+.I flags
+contains
+.BR FSPICK_EMPTY_PATH ,
+then the file descriptor referenced by
+.I dirfd
+is operated on directly.
+In this case,
+.I dirfd
+can refer to any type of file, not just a directory.
+.RE
+.P
+.I flags
+can be used to control aspects of the path lookup and properties of the
+returned file descriptor.
+A value for
+.I flags
+is constructed by OR'ing together zero or more of the following constants:
+.RS
+.TP
+.B FSPICK_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.
+.TP
+.B FSPICK_EMPTY_PATH
+If
+.I pathname
+is an empty string, operate on the file referred to by
+.I dirfd
+(which may have been obtained from
+.BR open "(2), " fsmount "(2), or " open_tree "(2).)"
+In this case,
+.I dirfd
+can refer to any type of file, not just a directory.
+If
+.I dirfd
+is
+.BR AT_FDCWD ,
+the call operates on the current working directory.
+.TP
+.B FSPICK_SYMLINK_NOFOLLOW
+Do not follow symbolic links in the terminal component of
+.IR pathname .
+If
+.I pathname
+references a symbolic link, the returned filesystem context will reference the
+filesystem that the symbolic link itself resides on.
+.TP
+.B FSPICK_NO_AUTOMOUNT
+Do not follow automounts in the terminal component of
+.IR pathname .
+.RE
+.P
+As with filesystem contexts created with
+.BR fsopen (2),
+the file descriptor returned by
+.BR fspick ()
+may be queried for message strings at any time by calling
+.BR read (2)
+on the file descriptor.
+(See the "Message Retrieval Interface" subsection in
+.BR fsopen (2)
+for more details on the message format.)
+.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 EACCES
+Search permission is denied for one of the directories
+in the path prefix of
+.IR pathname .
+(See also
+.BR path_resolution (7).)
+.TP
+.B EBADF
+.I pathname
+is relative but
+.I dirfd
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
+.TP
+.B EFAULT
+.I pathname
+is NULL or a pointer to a location outside the calling process's accessible
+address space.
+.TP
+.B EINVAL
+Invalid flag specified in
+.IR flags .
+.TP
+.B ELOOP
+Too many symbolic links encountered when resolving
+.IR pathname .
+.TP
+.B ENAMETOOLONG
+.I pathname
+is longer than
+.BR PATH_MAX .
+.TP
+.B ENOENT
+A component of
+.I pathname
+does not exist, or is a dangling symbolic link.
+.TP
+.B ENOENT
+.I pathname
+is an empty string, but
+.B FSPICK_EMPTY_PATH
+is not specified in
+.IR flags .
+.TP
+.B ENOTDIR
+A component of the path prefix of
+.I pathname
+is not a directory, or
+.I pathname
+is relative and
+.I dirfd
+is a file descriptor referring to a file other than a directory.
+.TP
+.B ENOMEM
+The kernel could not allocate sufficient memory to complete the operation.
+.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 EPERM
+The calling process does not have the required
+.B CAP_SYS_ADMIN
+capability.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 5.2.
+.\" commit cf3cba4a429be43e5527a3f78859b1bfd9ebc5fb
+Glibc 2.36.
+.SH EXAMPLES
+The following example sets the read-only superblock flag on "/tmp".
+.P
+.in +4n
+.EX
+int sfd = fspick(AT_FDCWD, "/tmp", FSPICK_CLOEXEC);
+fsconfig(sfd, FSCONFIG_SET_FLAG, "ro", NULL, 0);
+fsconfig(sfd, FSCONFIG_CMD_RECONFIGURE, NULL, NULL, 0);
+.EE
+.in
+.P
+The above procedure is functionally equivalent to the following mount operation
+using
+.BR mount (2):
+.P
+.in +4n
+.EX
+mount(NULL, "/tmp", NULL, MS_REMOUNT | MS_RDONLY, NULL);
+.EE
+.in
+.SH SEE ALSO
+.BR mount (2),
+.BR fsopen (2),
+.BR fsconfig (2),
+.BR fsmount (2),
+.BR open_tree (2),
+.BR move_mount (2),
+.BR mount_setattr (2),
+.BR mount_namespaces (7)
+

-- 
2.50.1

[PATCH 05/10] fsconfig.2: document 'new' mount api

[Aleksa Sarai]

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

diff --git a/man/man2/fsconfig.2 b/man/man2/fsconfig.2
new file mode 100644
index 000000000000..572e0fc5c1b9
--- /dev/null
+++ b/man/man2/fsconfig.2
@@ -0,0 +1,446 @@
+.\" 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 contexts
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <sys/mount.h>"
+.BR "#include <unistd.h>"
+.P
+.BI "int fsconfig(int " fd ", unsigned int " cmd ",
+.BI "             const char *" key ", const void *" 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 instantiated from an existing mount with
+.BR fspick (2).
+.P
+The
+.I cmd
+argument indicates the command to be issued.
+Some commands simply supply parameters to the context (equivalent to mount
+options specified with
+.BR mount (2)),
+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 NUL-terminated string, and
+.I aux
+must be 0.
+.TP
+.B FSCONFIG_SET_BINARY
+Set the parameter named by
+.I key
+to 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 file 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 NUL-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.
+.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 NUL-terminated pathname string, and
+.I aux
+is equivalent to the
+.I dirfd
+argument to
+.BR openat (2).
+.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, then the file descriptor specified by
+.I aux
+may be any type of file (not just a directory) and will be used as the path
+parameter value, equivalent to the behaviour of
+.B AT_EMPTY_PATH
+with other "*at()" system calls.
+.IP
+Note that this behaviour with empty paths is distinct in some subtle ways to
+.BR FSCONFIG_SET_FD .
+.B FSCONFIG_SET_FD
+indicates that the underlying file for the file descriptor
+.I aux
+should be used as the parameter value directly;
+.B FSCONFIG_SET_PATH_EMPTY
+indicates that the underlying file for the file descriptor
+.I aux
+should be re-opened by the filesystem driver, and the newly created file
+description should be used as the parameter value.
+This can result in slightly different behaviour when dealing with special files
+or files sourced from pseudofilesystems.
+Filesystems may also choose to only support one kind of parameter, and so a
+parameter that accepts
+.B FSCONFIG_SET_FD
+may not work with
+.B FSCONFIG_SET_PATH
+(or vice-versa).
+.TP
+.B FSCONFIG_CMD_CREATE
+This command instructs the filesystem driver to instantiate an instance of the
+filesystem in the kernel with the parameters set in the filesystem
+configuration context referenced by the file descriptor
+.IR fd .
+.IR key " and " value
+must be NULL, and
+.I aux
+must be 0.
+.IP
+If this operation succeeds, the file descriptor
+.I fd
+now references the created filesystem instance, and is placed into a special
+"needs-mount" mode that allows you to use
+.BR fsmount (2)
+to create a mount object from the filesystem instance.
+.IP
+This is intended for use with filesystem configuration contexts created with
+.BR fsopen (2).
+In order to create a filesystem instance, the calling process must have the
+.B CAP_SYS_ADMIN
+capability.
+.IP
+Note that the Linux kernel reuses filesystem instances for many filesystems, so
+(depending on the filesystem being configured and parameters used) it is
+possible the the filesystem instance "created" by
+.B FSCONFIG_CMD_CREATE
+may in fact be a reference to an existing filesystem instance in the kernel.
+The kernel will attempt to merge the specified parameters of this filesystem
+configuration context with those of the filesystem instance being reused, but
+some parameters may be silently ignored.
+.IP
+Programs that need to ensure that they create a new filesystem instance with
+specific parameters (notably, security-related parameters such POSIX ACLs -- 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
+As with
+.BR FSCONFIG_CMD_CREATE ,
+except that the kernel is instructed to create a new filesystem instance
+("superblock" in kernel parlance) rather than reusing an existing one.
+.IP
+If this is not possible (such as with disk-backed filesystems where multiple
+filesystem instances using the same filesystem driver and writing to the same
+underlying device could result in data corruption), this operation will incur
+an
+.B EBUSY
+error.
+.IP
+As a result (unlike
+.BR FSCONFIG_CMD_CREATE ),
+if this command succeeds then the calling process can be sure that all of the
+parameters successfully configured with
+.BR fsconfig ()
+will actually apply to the created filesystem instance.
+.TP
+.B FSCONFIG_CMD_RECONFIGURE
+This command instructs the filesystem driver to apply the parameters set in
+this filesystem configuration context to an already existing filesystem
+instance.
+.IP
+This is primarily intended for use with
+.BR fspick (2),
+but may also be used to modify the parameters of filesystem instance after
+.BR FSCONFIG_CMD_CREATE
+was used to create it.
+In order to reconfigure an existing filesystem instance, the calling process
+must have the
+.B CAP_SYS_ADMIN
+capability.
+.IP
+Once this operation succeeds, the filesystem context is reset but remains in
+reconfiguration mode and thus can be used for subsequent
+.B FSCONFIG_CMD_RECONFIGURE
+commands.
+.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 mount 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.
+.P
+.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
+Mounting a read-only filesystem was attempted 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 attached to
+.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 it still holds 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 ", " value ", and/or " aux
+were set to 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
+must be a block device, but the provided parameter value was not a block
+device.
+.TP
+.B ENOTDIR
+A component of the path prefix of a path argument was not a directory.
+.TP
+.B EOPNOTSUPP
+The command given by
+.I cmd
+is not valid.
+.TP
+.B ENXIO
+The major number of a block device parameter is out of range.
+.TP
+.B EPERM
+The command given by
+.I cmd
+was
+.BR FSCONFIG_CMD_CREATE ", " FSCONFIG_CMD_CREATE_EXCL ", or " \
+FSCONFIG_CMD_RECONFIGURE
+but the calling process does not have the required
+.B CAP_SYS_ADMIN
+capability.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 5.2.
+.\" commit ecdab150fddb42fe6a739335257949220033b782
+Glibc 2.36.
+.SH EXAMPLES
+To illustrate the different kinds of flags that can be configured with
+.BR fsconfig (2),
+here are a few examples of some different filesystems being created:
+.P
+.in +4n
+.EX
+int sfd = fsopen("tmpfs", FSOPEN_CLOEXEC);
+fsconfig(sfd, FSCONFIG_SET_FLAG, "inode64", NULL, 0);
+fsconfig(sfd, FSCONFIG_SET_STRING, "uid", "1234", 0);
+fsconfig(sfd, FSCONFIG_SET_STRING, "huge", "never", 0);
+fsconfig(sfd, FSCONFIG_SET_FLAG, "casefold", NULL, 0);
+fsconfig(sfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
+int mfd = fsmount(sfd, FSMOUNT_CLOEXEC, MOUNT_ATTR_NODEV | MOUNT_ATTR_NOEXEC);
+move_mount(mfd, "", AT_FDCWD, "/tmp", MOVE_MOUNT_F_EMPTY_PATH);
+\&
+int sfd = fsopen("erofs", FSOPEN_CLOEXEC);
+fsconfig(sfd, FSCONFIG_SET_STRING, "source", "/dev/loop0", 0);
+fsconfig(sfd, FSCONFIG_SET_FLAG, "acl", NULL, 0);
+fsconfig(sfd, FSCONFIG_SET_FLAG, "user_xattr", NULL, 0);
+fsconfig(sfd, FSCONFIG_CMD_CREATE_EXCL, NULL, NULL, 0);
+int mfd = fsmount(sfd, FSMOUNT_CLOEXEC, MOUNT_ATTR_NOSUID);
+move_mount(mfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH);
+\&
+int lowerdirfd = open("/overlays/mine/lower1", O_DIRECTORY | O_CLOEXEC);
+int sfd = fsopen("overlay", FSOPEN_CLOEXEC);
+/* "lowerdir+" appends to the lower dir stack */
+fsconfig(sfd, FSCONFIG_SET_FD, "lowerdir+", NULL, lowerdirfd);
+fsconfig(sfd, FSCONFIG_SET_STRING, "lowerdir+", "/overlays/mine/lower2", 0);
+.\" fsconfig(sfd, FSCONFIG_SET_PATH, "lowerdir+", "/overlays/mine/lower3", AT_FDCWD);
+.\" fsconfig(sfd, FSCONFIG_SET_PATH_EMPTY, "lowerdir+", "", lowerdirfd);
+fsconfig(sfd, FSCONFIG_SET_STRING, "xino", "auto", 0);
+fsconfig(sfd, FSCONFIG_SET_STRING, "nfs_export", "off", 0);
+fsconfig(sfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
+int mfd = fsmount(sfd, FSMOUNT_CLOEXEC, 0);
+move_mount(mfd, "", AT_FDCWD, "/mnt/overlay", MOVE_MOUNT_F_EMPTY_PATH);
+\&
+int nsfd = open("/proc/self/ns/pid", O_PATH);
+int nsdirfd = open("/proc/1/ns", O_DIRECTORY);
+int sfd = fsopen("proc", FSOPEN_CLOEXEC);
+/* "pidns" changes the value each time. */
+fsconfig(sfd, FSCONFIG_SET_PATH, "pidns", "/proc/self/ns/pid", AT_FDCWD);
+fsconfig(sfd, FSCONFIG_SET_PATH, "pidns", "pid", NULL, nsdirfd);
+fsconfig(sfd, FSCONFIG_SET_PATH_EMPTY, "pidns", "", nsfd);
+fsconfig(sfd, FSCONFIG_SET_FD, "pidns", NULL, nsfd);
+fsconfig(sfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
+int mfd = fsmount(sfd, FSMOUNT_CLOEXEC, 0);
+move_mount(mfd, "", AT_FDCWD, "/proc", MOVE_MOUNT_F_EMPTY_PATH);
+.EE
+.in
+.P
+And here is an example of how
+.BR fspick (2)
+can be used with
+.BR fsconfig ()
+to reconfigure the parameters of an existing mount:
+.P
+.in +4n
+.EX
+int sfd = fspick(AT_FDCWD, "/proc", FSPICK_CLOEXEC);
+fsconfig(sfd, FSCONFIG_SET_STRING, "hidepid", "ptraceable", 0);
+fsconfig(sfd, FSCONFIG_SET_STRING, "subset", "pid", 0);
+fsconfig(sfd, FSCONFIG_CMD_RECONFIGURE, NULL, NULL, 0);
+.EE
+.in
+.SH SEE ALSO
+.BR mount (2),
+.BR fsopen (2),
+.BR fsmount (2),
+.BR fspick (2),
+.BR open_tree (2),
+.BR move_mount (2),
+.BR mount_setattr (2),
+.BR mount_namespaces (7)
+

-- 
2.50.1

[PATCH 06/10] fsmount.2: document 'new' mount api

[Aleksa Sarai]

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-developed-by: David Howells <dhowells@redhat.com>
Co-developed-by: Christian Brauner <brauner@kernel.org>
Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
---
 man/man2/fsmount.2 | 185 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 185 insertions(+)

diff --git a/man/man2/fsmount.2 b/man/man2/fsmount.2
new file mode 100644
index 000000000000..0653ffe7056d
--- /dev/null
+++ b/man/man2/fsmount.2
@@ -0,0 +1,185 @@
+.\" 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
+.BR "#include <sys/mount.h>"
+.BR "#include <unistd.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 ()
+takes the created filesystem instance referenced by the filesystem context
+associated with the file descriptor
+.I fsfd
+and creates a new mount object for the root of the filesystem instance, which
+is then attached to a new file descriptor and returned.
+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
+.BR FSCONFIG_CMD_CREATE " or " FSCONFIG_CMD_CREATE_EXCL
+in order to be in the correct state for this operation.
+In order to create a mount object with
+.BR fsmount (),
+the calling process must have the
+.BR CAP_SYS_ADMIN
+capability.
+.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 mounted somewhere else by calling
+.BR move_mount (2).
+The resultant file descriptor 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
+other "*at()" system calls.
+.P
+.I flags
+controls the creation of the returned file descriptor.
+A value for
+.I flags
+is constructed by OR'ing together 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 the mount attributes for the created mount object and accepts the
+same set of
+.B MOUNT_ATTR_*
+flags as
+.BR mount_setattr (2),
+except for flags such as
+.B MOUNT_ATTR_IDMAP
+which require specifying additional fields in
+.BR mount_attr (2type).
+.P
+If the
+.BR fsmount ()
+operation is successful, the filesystem context associated with the file
+descriptor
+.I fsfd
+is reset and placed into a reconfiguration state, similar to the one produced
+by
+.BR fspick (2).
+You may coninue to use
+.BR fsconfig (2)
+with the
+.B FSCONFIG_CMD_RECONFIGURE
+command to reconfigure the filesystem instance.
+.P
+Unlike
+.BR open_tree "(2), " fsmount (2)
+can only be called once to produce a mount object for a given filesystem
+configuration context.
+.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 attached to
+.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
+.B 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
+Glibc 2.36.
+.SH EXAMPLES
+.P
+.in +4n
+.EX
+int sfd = fsopen("tmpfs", FSOPEN_CLOEXEC);
+fsconfig(sfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
+int mfd = fsmount(sfd, FSMOUNT_CLOEXEC, MOUNT_ATTR_NODEV | MOUNT_ATTR_NOEXEC);
+\&
+/* Create a new file without attaching the mount object. */
+int tmpfd = openat(sfd, "tmpfile", O_CREAT | O_EXCL | O_RDWR, 0600);
+unlinkat(sfd, "tmpfile", 0);
+\&
+/* Attach the mount object to "/tmp". */
+move_mount(mfd, "", AT_FDCWD, "/tmp", MOVE_MOUNT_F_EMPTY_PATH);
+.EE
+.in
+.SH SEE ALSO
+.BR mount (2),
+.BR fsopen (2),
+.BR fsconfig (2),
+.BR fspick (2),
+.BR open_tree (2),
+.BR move_mount (2),
+.BR mount_setattr (2),
+.BR mount_namespaces (7)
+

-- 
2.50.1

[PATCH 07/10] move_mount.2: document 'new' mount api

[Aleksa Sarai]

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-developed-by: David Howells <dhowells@redhat.com>
Co-developed-by: Christian Brauner <brauner@kernel.org>
Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
---
 man/man2/move_mount.2 | 470 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 470 insertions(+)

diff --git a/man/man2/move_mount.2 b/man/man2/move_mount.2
new file mode 100644
index 000000000000..439eb6a5b018
--- /dev/null
+++ b/man/man2/move_mount.2
@@ -0,0 +1,470 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH move_mount 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+move_mount \- move or attach mount object to filesystem
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.B #define _GNU_SOURCE
+.BR "#include <sys/mount.h>"
+.BR "#include <unistd.h>"
+.BR "#include <fcntl.h>" \
+"          /* Definition of " AT_* " constants */"
+.P
+.BI "int move_mount(int " from_dirfd ", const char *" from_pathname ",
+.BI "               int " to_dirfd ", const char *" to_pathname ",
+.BI "               unsigned int " flags ");
+.fi
+.SH DESCRIPTION
+The
+.BR move_mount ()
+system call is part of the suite of file descriptor based mount facilities in
+Linux.
+.P
+.BR move_mount ()
+moves the mount object indicated by
+.IR from_dirfd " and " from_pathname
+to the path indicated by
+.IR to_dirfd " and " to_pathname .
+The mount object being moved could be an existing mount point in the current
+mount namespace, or it could be a detached mount object created by
+.BR fsmount (2)
+or
+.BR open_tree (2)
+with
+.BR OPEN_TREE_CLONE .
+.P
+To access the source mount object or the destination mount point, no permissions
+are required on the object itself, but if either pathname is supplied, execute
+(search) permission is required on all of the directories specified in
+.IR from_pathname " or " to_pathname .
+.P
+The calling process must have the
+.BR CAP_SYS_ADMIN
+capability in order to attach or move a mount object.
+.P
+As with most "*at()" system calls,
+.BR move_mount ()
+uses the
+.IR from_dirfd " and " to_dirfd
+arguments in conjunction with the
+.IR from_pathname " and " to_pathname
+argument to determine the source and destination objects to operate on
+(respectively), as follows:
+.RS
+.IP \[bu] 3
+If the pathname given in
+.IR *_pathname
+is absolute, then the corresponding
+.I *_dirfd
+is ignored.
+.IP \[bu]
+If the pathname given in
+.I *_pathname
+is relative and the corresponding
+.I *_dirfd
+is the special value
+.BR AT_FDCWD ,
+then the
+.I *_pathname
+is interpreted relative to the current working
+directory of the calling process (like
+.BR open ()).
+.IP \[bu]
+If the pathname given in
+.I *_pathname
+is relative, then it is interpreted relative to the directory
+referred to by the corresponding
+.I *_dirfd
+file descriptor (rather than relative to the current working directory of the
+calling process, as is done by
+.BR open ()
+for a relative pathname).
+In this case, the
+.I *_dirfd
+must be a directory that was opened for reading
+.RB ( O_RDONLY )
+or using the
+.B O_PATH
+flag.
+.IP \[bu]
+If
+.I *_pathname
+is an empty string, and
+.I flags
+contains the appropriate
+.BR MOVE_MOUNT_*_EMPTY_PATH
+flag, then the file descriptor referenced by the corresponding
+.I *_dirfd
+is operated on directly.
+In this case,
+.I *_dirfd
+can refer to any type of file, not just a directory.
+.IP
+This is the most common mechanism used to attach detached mount objects to a
+mount point target.
+.RE
+.P
+.I flags
+can be used to control aspects of the path lookup for both the source and
+destination objects, as well as other properties of the mount operation.
+A value for
+.I flags
+is constructed by OR'ing together zero or more of the following constants:
+.RS
+.TP
+.B MOVE_MOUNT_F_EMPTY_PATH
+If
+.I from_pathname
+is an empty string, operate on the file referred to by
+.I from_dirfd
+(which may have been obtained from
+.BR open "(2), " fsmount "(2), or " open_tree "(2).)"
+In this case,
+.I from_dirfd
+can refer to any type of file, not just a directory.
+If
+.I from_dirfd
+is
+.BR AT_FDCWD ,
+the call operates on the current working directory.
+.TP
+.B MOVE_MOUNT_T_EMPTY_PATH
+As with
+.BR MOVE_MOUNT_F_EMPTY_PATH ,
+except operating on
+.IR to_dirfd " and " to_pathname .
+.TP
+.B MOVE_MOUNT_F_SYMLINKS
+If
+.IR from_pathname
+references a symbolic link, then dereference it.
+The default behaviour for
+.BR move_mount ()
+is to
+.I not follow
+symbolic links.
+.TP
+.B MOVE_MOUNT_T_SYMLINKS
+As with
+.BR MOVE_MOUNT_F_SYMLINKS ,
+except operating on
+.IR to_dirfd " and " to_pathname .
+.TP
+.B MOVE_MOUNT_F_NO_AUTOMOUNT
+Don't automount the terminal ("basename") component of
+.I from_pathname
+if it is a directory that is an automount point.
+This allows a mount object that has an automount point at its root to be moved
+and prevents unintended triggering of an automount point.
+This flag has no effect if the automount point has already been mounted over.
+.TP
+.B MOVE_MOUNT_T_NO_AUTOMOUNT
+As with
+.BR MOVE_MOUNT_F_NO_AUTOMOUNT ,
+except operating on
+.IR to_dirfd " and " to_pathname .
+This allows an automount point to be manually mounted over.
+.TP
+.BR MOVE_MOUNT_SET_GROUP " (since Linux 5.15)"
+Add the attached (private) mount indicated by
+.IR to_dirfd " and " to_pathname
+into the mount propagation "peer group" of the attached (non-private) mount
+indicated by
+.IR from_dirfd " and " from_pathname .
+.IP
+Unlike other
+.BR move_mount ()
+operations, this operation does not move any actual mount objects.
+Instead, it only updates the metadata of existing (attached) mount objects.
+.IP
+This makes it possible to first create a mount tree consisting only of private
+mounts and then configuring the desired propagation layout afterwards.
+(See the "SHARED SUBTREES" section of
+.BR mount_namespaces (7)
+for more information about mount propagation and peer groups.)
+.TP
+.BR MOVE_MOUNT_BENEATH " (since Linux 6.5)"
+If the path indicated by
+.IR to_dirfd " and " to_pathname
+is an existing mount object, rather than placing the mount object indicated by
+.IR from_dirfd " and " from_pathname
+on top of the mount stack, place it below the current top mount on the mount
+stack.
+.IP
+After using
+.BR MOVE_MOUNT_BENEATH ,
+it is possible to
+.BR umount (2)
+the top mount in order to reveal the mount which was moved beneath it earlier.
+This allows for the seamless (and atomic) replacement of complex mount trees,
+which can be used to "upgrade" a mount tree with a newer version.
+.IP
+This operation has several restrictions:
+.RS
+.IP \[bu] 3
+Mounts cannot be moved beneath the rootfs, including the rootfs as configured
+by
+.BR chroot "(2) and " pivot_root (2).
+To mount beneath the rootfs,
+.BR pivot_root (2)
+must be used.
+.IP \[bu]
+The target path indicated by
+.IR to_dirfd " and " to_pathname
+must be an attached mount object.
+It must not be a detached mount given by
+.BR open_tree (2)
+with
+.BR OPEN_TREE_CLONE.
+.IP \[bu]
+The current top mount of the target path's mount stack and its parent mount
+must be in the calling process's mount namespace.
+.IP \[bu]
+The caller must have sufficient privileges to unmount the top mount of the
+target path's mount stack, to prove they have privileges to reveal the
+underlying mount.
+.IP \[bu]
+Mount propagation events triggered by this
+.BR move_mount ()
+operation are calculated based on the parent mount of the current top mount of
+the target path's mount stack.
+.IP \[bu]
+The target path's mount cannot be a parent mount of the source mount object.
+.IP \[bu]
+The source mount object must not have any overmounts, otherwise it would be
+possible to create "shadow mounts" (i.e. two mounts mounted on the same parent
+mount at the same mount point).
+.IP \[bu]
+It is not possible to move a mount beneath a top mount if the parent mount of
+the current top mount propagates to the top mount itself.
+Otherwise,
+.B MOVE_MOUNT_BENEATH
+would cause the mount object to be propagated to the top mount from the parent
+mount, defeating the purpose of using
+.BR MOVE_MOUNT_BENEATH .
+.IP \[bu]
+It is not possible to move a mount beneath a top mount if the parent mount of
+the current top mount propagates to the mount object being mounted beneath.
+Otherwise, this would cause a similar propagation issue to the previous point,
+also defeating the purpose of using
+.BR MOVE_MOUNT_BENEATH .
+.RE
+.RE
+.P
+If
+.BR move_mount ()
+is called repeatedly with a file descriptor that refers to a mount object, then
+the object will be attached (or moved) the first time and then moved again and
+again, detaching it from the previous mount point each time.
+.SH RETURN VALUE
+On success,
+.BR move_mount ()
+returns 0.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EACCES
+Search permission is denied for one of the directories
+in the path prefix of one of
+.IR from_pathname " or " to_pathname .
+(See also
+.BR path_resolution (7).)
+.TP
+.B EBADF
+One of
+.IR from_dirfd " or " to_dirfd
+is not a valid file descriptor.
+.TP
+.B EFAULT
+One of
+.IR from_pathname " or " to_pathname
+is NULL or a pointer to a location outside the calling process's accessible
+address space.
+.TP
+.B EINVAL
+Invalid flag specified in
+.IR flags .
+.TP
+.B EINVAL
+The path indicated by
+.IR from_dirfd " and " from_pathname
+is not a mount object.
+.TP
+.B EINVAL
+The mount object type of the source mount object and target inode are not
+compatible (i.e. the source is a file but the target is a directory, or
+vice-versa).
+.TP
+.B EINVAL
+The source mount object or target path are not in the calling process's mount
+namespace (or an anonymous mount namespace of the calling process).
+.TP
+.B EINVAL
+The source mount object's parent mount has shared mount propagation, and thus
+cannot be moved (as described in
+.BR mount_namespaces (7)).
+.TP
+.B EINVAL
+The source mount has
+.B MS_UNBINDABLE
+child mounts but the target path resides on a mount with shared mount
+propagation, which would otherwise cause the unbindable mounts to be
+propagated (as described in
+.BR mount_namespaces (7)).
+.TP
+.B EINVAL
+.B MOVE_MOUNT_BENEATH
+was attempted, but one of the listed restrictions was violated.
+.TP
+.B ELOOP
+Too many symbolic links encountered when resolving one of
+.IR from_pathname " or " to_pathname .
+.TP
+.B ENAMETOOLONG
+One of
+.IR from_pathname " or " to_pathname
+is longer than
+.BR PATH_MAX .
+.TP
+.B ENOENT
+A component of one of
+.IR from_pathname " or " to_pathname
+does not exist.
+.TP
+.B ENOENT
+One of
+.IR from_pathname " or " to_pathname
+is an empty string, but the corresponding
+.B MOVE_MOUNT_*_EMPTY_PATH
+flag is not specified in
+.IR flags .
+.TP
+.B ENOTDIR
+A component of the path prefix of one of
+.IR from_pathname " or " to_pathname
+is not a directory, or one of
+.IR from_pathname " or " to_pathname
+is relative and the corresponding
+.IR from_dirfd " or " to_dirfd
+is a file descriptor referring to a file other than a directory.
+.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 2db154b3ea8e14b04fee23e3fdfd5e9d17fbc6ae
+Glibc 2.36.
+.SH EXAMPLES
+.BR move_mount ()
+can be used to move attached mounts like the following:
+.P
+.in +4n
+.EX
+move_mount(AT_FDCWD, "/a", AT_FDCWD, "/b", 0);
+.EE
+.in
+.P
+This would move the mount object mounted on "/a" to "/b".
+The above procedure is functionally equivalent to the following mount operation
+using
+.BR mount (2):
+.P
+.in +4n
+.EX
+mount("/a", "/b", NULL, MS_MOVE, NULL);
+.EE
+.in
+.P
+.BR move_mount ()
+can also be used in conjunction with file descriptors returned from
+.BR open_tree "(2) or " open (2):
+.P
+.in +4n
+.EX
+int fd = open_tree(AT_FDCWD, "/mnt", 0); /* or open("/mnt", O_PATH); */
+move_mount(fd, "", AT_FDCWD, "/mnt2", MOVE_MOUNT_F_EMPTY_PATH);
+move_mount(fd, "", AT_FDCWD, "/mnt3", MOVE_MOUNT_F_EMPTY_PATH);
+move_mount(fd, "", AT_FDCWD, "/mnt4", MOVE_MOUNT_F_EMPTY_PATH);
+.EE
+.in
+.P
+This would move the mount object mounted at "/mnt" to "/mnt2", then "/mnt3",
+then "/mnt4".
+.P
+If the source mount object indicated by
+.IR from_dirfd " and " from_pathname
+is a detached mount object,
+.BR move_mount ()
+can be used to attach it to the filesystem:
+.P
+.in +4n
+.EX
+int sfd = fsopen("ext4", FSOPEN_CLOEXEC);
+fsconfig(sfd, FSCONFIG_SET_STRING, "source", "/dev/sda1", 0);
+fsconfig(sfd, FSCONFIG_SET_FLAG, "user_xattr", NULL, 0);
+fsconfig(sfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
+int mfd = fsmount(sfd, FSMOUNT_CLOEXEC, MOUNT_ATTR_NODEV);
+move_mount(mfd, "", AT_FDCWD, "/home", MOVE_MOUNT_F_EMPTY_PATH);
+.EE
+.in
+.P
+This creates a new filesystem configuration context for ext4, configures it,
+creates a mount object, and then attaches it to "/home".
+The above procedure is functionally equivalent to the following mount operation
+using
+.BR mount (2):
+.P
+.in +4n
+.EX
+mount("/dev/sda1", "/home", "ext4", MS_NODEV, "user_xattr");
+.EE
+.in
+.P
+This also works with detached bind-mounts created with
+.BR open_tree (2)
+with
+.BR OPEN_TREE_CLONE :
+.P
+.in +4n
+.EX
+int mfd = open_tree(AT_FDCWD, "/home/cyphar", OPEN_TREE_CLONE);
+move_mount(mfd, "", AT_FDCWD, "/root", MOVE_MOUNT_F_EMPTY_PATH);
+.EE
+.in
+.P
+This creates a new detached bind-mount mount object of "/home/cyphar", and then
+attaches it to "/root".
+The above procedure is functionally equivalent to the following mount operation
+using
+.BR mount (2):
+.P
+.in +4n
+.EX
+mount("/home/cyphar", "/root", NULL, MS_BIND, NULL);
+.EE
+.in
+.SH SEE ALSO
+.BR mount (2),
+.BR fsopen (2),
+.BR fsconfig (2),
+.BR fsmount (2),
+.BR fspick (2),
+.BR open_tree (2),
+.BR mount_setattr (2),
+.BR mount_namespaces (7)
+

-- 
2.50.1

[PATCH 08/10] open_tree.2: document 'new' mount api

[Aleksa Sarai]

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-developed-by: David Howells <dhowells@redhat.com>
Co-developed-by: Christian Brauner <brauner@kernel.org>
Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
---
 man/man2/open_tree.2 | 365 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 365 insertions(+)

diff --git a/man/man2/open_tree.2 b/man/man2/open_tree.2
new file mode 100644
index 000000000000..d58f43d96b20
--- /dev/null
+++ b/man/man2/open_tree.2
@@ -0,0 +1,365 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH open_tree 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+open_tree \- open path or create detached mount object and attach to fd
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.B #define _GNU_SOURCE
+.BR "#include <sys/mount.h>"
+.BR "#include <unistd.h>"
+.BR "#include <fcntl.h>" \
+"          /* Definition of " AT_* " constants */"
+.P
+.BI "int open_tree(int " dirfd ", const char *" pathname ", unsigned int " flags ");
+.fi
+.SH DESCRIPTION
+The
+.BR open_tree ()
+system call is part of the suite of file descriptor based mount facilities in
+Linux.
+.P
+If
+.I flags
+contains
+.BR OPEN_TREE_CLONE ", " open_tree ()
+creates a detached mount object consisting of a bind-mount of the pathname
+specified by the
+.IR pathname ,
+and attaches it to a new file descriptor.
+The mount object is equivalent to a bind-mount that would be created by
+.BR mount (2)
+called with
+.BR MS_BIND ,
+except that it is tied to a file descriptor and is not mounted onto the
+filesystem.
+.P
+As with file descriptors returned from
+.BR fsmount (2),
+the resultant 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).
+.P
+If
+.I flags
+does not contain
+.BR OPEN_TREE_CLONE ", " open_tree ()
+produces a file descriptor that is functionally equivalent to one returned from
+.BR open (2).
+.P
+In either case, the resultant file descriptor acts the same as one produced by
+.BR open (2)
+with
+.BR O_PATH ,
+meaning it can be used as a
+.I dirfd
+argument to
+other "*at()" system calls.
+.P
+As with most "*at()" system calls,
+.BR open_tree ()
+uses the
+.I dirfd
+argument in conjunction with the
+.I pathname
+argument to determine the path to operate on, as follows:
+.RS
+.IP \[bu] 3
+If the pathname given in
+.I pathname
+is absolute, then
+.I dirfd
+is ignored.
+.IP \[bu]
+If the pathname given in
+.I pathname
+is relative and
+.I dirfd
+is the special value
+.BR AT_FDCWD ,
+then
+.I pathname
+is interpreted relative to the current working
+directory of the calling process (like
+.BR open ()).
+.IP \[bu]
+If the pathname given in
+.I pathname
+is relative, then it is interpreted relative to the directory
+referred to by the file descriptor
+.I dirfd
+(rather than relative to the current working directory of
+the calling process, as is done by
+.BR open ()
+for a relative pathname).
+In this case,
+.I dirfd
+must be a directory that was opened for reading
+.RB ( O_RDONLY )
+or using the
+.B O_PATH
+flag.
+.IP \[bu]
+If
+.I pathname
+is an empty string, and
+.I flags
+contains
+.BR AT_EMPTY_PATH ,
+then the file descriptor referenced by
+.I dirfd
+is operated on directly.
+In this case,
+.I dirfd
+can refer to any type of file, not just a directory.
+.RE
+.P
+.I flags
+can be used to control aspects of the path lookup and properties of the
+returned file descriptor.
+A value for
+.I flags
+is constructed by OR'ing together zero or more of the following constants:
+.RS
+.TP
+.B AT_EMPTY_PATH
+If
+.I pathname
+is an empty string, operate on the file referred to by
+.I dirfd
+(which may have been obtained from
+.BR open "(2), from " fsmount "(2), or from another " open_tree "() call.)"
+In this case,
+.I dirfd
+can refer to any type of file, not just a directory.
+If
+.I dirfd
+is
+.BR AT_FDCWD ,
+the call operates on the current working directory.
+This flag is Linux-specific; define
+.B _GNU_SOURCE
+to obtain its definition.
+.TP
+.B AT_NO_AUTOMOUNT
+Don't automount the terminal ("basename") component of
+.I pathname
+if it is a directory that is an automount point.
+This allows the caller to gather attributes of an automount point
+(rather than the location it would mount).
+This flag has no effect if the mount point has already been mounted over.
+This flag is Linux-specific; define
+.B _GNU_SOURCE
+to obtain its definition.
+.TP
+.B AT_SYMLINK_NOFOLLOW
+If
+.I pathname
+is a symbolic link, do not dereference it; instead, create either a handle to
+the link itself or a bind-mount of it.
+The resultant file descriptor is indistinguishable from one produced by
+.BR openat (2)
+with
+.BR O_PATH | O_NOFOLLLOW .
+.TP
+.B OPEN_TREE_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.
+.TP
+.B OPEN_TREE_CLONE
+Rather than opening the path as a regular file
+.RB "(a-la " openat (2)),
+create a detached bind-mount mount object and attach it to the file descriptor.
+In order to do this operation,
+the calling process must have the
+.BR CAP_SYS_ADMIN
+capability.
+.TP
+.B AT_RECURSIVE
+Create a recursive bind-mount of the path
+.RB "(a-la " mount "(2) with " MS_BIND | MS_REC ),
+and attach it to the file descriptor.
+This flag is only permitted in conjunction with
+.BR OPEN_TREE_CLONE .
+.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 EACCES
+Search permission is denied for one of the directories
+in the path prefix of
+.IR pathname .
+(See also
+.BR path_resolution (7).)
+.TP
+.B EPERM
+.I flags
+contains
+.B OPEN_TREE_CLONE
+but the calling process does not have the required
+.B CAP_SYS_ADMIN
+capability.
+.TP
+.B EBADF
+.I pathname
+is relative but
+.I dirfd
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
+.TP
+.B EFAULT
+.I pathname
+is NULL or a pointer to a location outside the calling process's accessible
+address space.
+.TP
+.B EINVAL
+Invalid flag specified in
+.IR flags .
+.TP
+.B ELOOP
+Too many symbolic links encountered when resolving
+.IR pathname .
+.TP
+.B ENAMETOOLONG
+.I pathname
+is longer than
+.BR PATH_MAX .
+.TP
+.B ENOENT
+A component of
+.I pathname
+does not exist, or is a dangling symbolic link.
+.TP
+.B ENOENT
+.I pathname
+is an empty string, but
+.B AT_EMPTY_PATH
+is not specified in
+.IR flags .
+.TP
+.B ENOTDIR
+A component of the path prefix of
+.I pathname
+is not a directory, or
+.I pathname
+is relative and
+.I dirfd
+is a file descriptor referring to a file other than a directory.
+.TP
+.B ENOSPC
+The "anonymous" mount namespace necessary to contain the
+.B OPEN_TREE_CLONE
+detached bind-mount 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 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.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 5.2.
+.\" commit a07b20004793d8926f78d63eb5980559f7813404
+Glibc 2.36.
+.SH NOTES
+.SS Anonymous Mount Namespaces
+The bind-mount mount objects created by
+.BR open_tree ()
+with
+.B OPEN_TREE_CLONE
+are not attached to the mount namespace of the calling process.
+Instead, each mount object is attached to a newly allocated "anonymous" mount
+namespace associated with the calling process.
+.P
+One of the side-effects of this is that (unlike bind-mounts created with
+.BR mount (2)),
+mount propagation (as described in
+.BR mount_namespaces (7))
+will not be applied to bind-mounts created by
+.BR open_tree ()
+until the bind-mount is attached with
+.BR move_mount (2),
+at which point the mount will be associated with the mount namespace where it
+was mounted and mount propagation will resume.
+.SH EXAMPLES
+The following examples show how
+.BR open_tree ()
+can be used in place of more traditional
+.BR mount (2)
+calls with
+.BR MS_BIND .
+.P
+.in +4n
+.EX
+/* mount --bind /var /mnt */
+int err = mount("/var", "/mnt", NULL, MS_BIND, NULL);
+/* ... is equivalent to ... */
+int srcfd = open_tree(AT_FDCWD, "/var", OPEN_TREE_CLONE);
+int err = move_mount(srcfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH);
+\&
+/* mount --rbind /var /mnt */
+int err = mount("/var", "/mnt", NULL, MS_BIND|MS_REC, NULL);
+/* ... is equivalent to ... */
+int srcfd = open_tree(AT_FDCWD, "/var", OPEN_TREE_CLONE | AT_RECURSIVE);
+int err = move_mount(srcfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH);
+\&
+/* mount --bind /proc/self/fd/100 /proc/self/fd/200/foo */
+int err = mount("/proc/self/fd/100", "/proc/self/fd/200/foo", NULL, MS_BIND, NULL);
+/* ... is equivalent to ... */
+int srcfd = open_tree(100, "", AT_EMPTY_PATH | OPEN_TREE_CLONE);
+int err = move_mount(srcfd, "", 200, "foo", MOVE_MOUNT_F_EMPTY_PATH);
+.EE
+.in
+.P
+In addition, you can use the file descriptor returned by
+.BR open_tree ()
+as the
+.I dirfd
+argument to any "*at()" system calls:
+.P
+.in +4n
+.EX
+int dirfd = open_tree(AT_FDCWD, "/etc", OPEN_TREE_CLONE);
+int fd = openat(dirfd, "passwd", O_RDONLY);
+int err = fchmodat(dirfd, "shadow", 0000, 0);
+close(dirfd);
+close(fd);
+/* The bind-mount is now destroyed. */
+.EE
+.in
+.SH SEE ALSO
+.BR mount (2),
+.BR fsopen (2),
+.BR fsconfig (2),
+.BR fsmount (2),
+.BR fspick (2),
+.BR move_mount (2),
+.BR mount_setattr (2),
+.BR mount_namespaces (7)

-- 
2.50.1

[PATCH 09/10] mount_setattr.2: mirror opening sentence from fsopen(2)

[Aleksa Sarai]

All of the other new mount API docs have this lead-in sentence in order
to make this set of APIs feel a little bit more cohesive. Despite being
a bit of a latecomer, mount_setattr(2) is definitely part of this family
of APIs and so deserves the same treatment.

Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
---
 man/man2/mount_setattr.2 | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2
index e863be64deb5..c77bd0ba53eb 100644
--- a/man/man2/mount_setattr.2
+++ b/man/man2/mount_setattr.2
@@ -21,7 +21,11 @@ Standard C library
 .SH DESCRIPTION
 The
 .BR mount_setattr ()
-system call changes the mount properties of a mount or an entire mount tree.
+system call is part of the suite of file descriptor based mount facilities in
+Linux.
+.P
+.BR mount_setattr ()
+changes the mount properties of a mount or an entire mount tree.
 If
 .I path
 is relative,

-- 
2.50.1

[PATCH 10/10] open_tree_attr.2, open_tree.2: document new open_tree_attr() api

[Aleksa Sarai]

This is a new API added in Linux 6.15, and is effectively just a minor
expansion of open_tree(2) in order to allow for MOUNT_ATTR_IDMAP to be
changed for an existing ID-mapped mount.

Glibc does not yet have a wrapper for this.

Cc: Christian Brauner <brauner@kernel.org>
Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
---
 man/man2/open_tree.2      | 75 +++++++++++++++++++++++++++++++++++++++++++++++
 man/man2/open_tree_attr.2 |  1 +
 2 files changed, 76 insertions(+)

diff --git a/man/man2/open_tree.2 b/man/man2/open_tree.2
index d58f43d96b20..a6f7d813a115 100644
--- a/man/man2/open_tree.2
+++ b/man/man2/open_tree.2
@@ -17,6 +17,19 @@ Standard C library
 "          /* Definition of " AT_* " constants */"
 .P
 .BI "int open_tree(int " dirfd ", const char *" pathname ", unsigned int " flags ");
+.P
+.BR "#include <sys/syscall.h>" "    /* Definition of " SYS_* " constants */"
+.P
+.BI "int syscall(SYS_open_tree_attr, int " dirfd ", const char *" pathname ","
+.BI "            unsigned int " flags ", struct mount_attr *" attr ", \
+size_t " size ");"
+.fi
+.P
+.IR Note :
+glibc provides no wrapper for
+.BR open_tree_attr (),
+necessitating the use of
+.BR syscall (2).
 .fi
 .SH DESCRIPTION
 The
@@ -196,6 +209,60 @@ Create a recursive bind-mount of the path
 and attach it to the file descriptor.
 This flag is only permitted in conjunction with
 .BR OPEN_TREE_CLONE .
+.SS open_tree_attr()
+The
+.BR open_tree_attr ()
+system call operates in exactly the same way as
+.BR open_tree (),
+except for the differences described here.
+.P
+After performing the same operation as with
+.BR open_tree "(),
+(before returning the resulting file descriptor)
+.BR open_tree_attr ()
+will apply the mount attributes requested in
+.I attr
+to the mount object.
+(See
+.BR mount_attr (2type)
+for a description of the
+.I mount_attr
+structure.
+As described in
+.BR mount_setattr (2),
+.I size
+must be set to
+.I sizeof(struct mount_attr)
+in order to support future extensions.)
+.P
+For the most part, the application of
+.I attr
+has identical semantics to
+.BR mount_setattr (2),
+except that it is possible to change the
+.B MOUNT_ATTR_IDMAP
+attribute for a mount object that is already configured as an ID-mapped mount.
+This is usually forbidden by
+.BR mount_setattr (2)
+and thus
+.BR open_tree_attr ()
+is the only permitted mechanism to change this attribute.
+Changing an ID-mapped mount is only permitted if a new mount object is created
+with
+.BR OPEN_TREE_CLONE .
+.P
+If
+.I flags
+contains
+.BR AT_RECURSIVE ,
+then the attributes are applied recursively (just as when
+.BR mount_setattr (2)
+is called with
+.BR AT_RECURSIVE ).
+This applies in addition to the
+.BR open_tree ()-specific
+behaviour regarding
+.BR AT_RECURSIVE .
 .SH RETURN VALUE
 On success, a new file descriptor is returned.
 On error, \-1 is returned, and
@@ -285,10 +352,18 @@ The system has too many open files to create more.
 .SH STANDARDS
 Linux.
 .SH HISTORY
+.SS open_tree()
 Linux 5.2.
 .\" commit a07b20004793d8926f78d63eb5980559f7813404
 Glibc 2.36.
+.SS open_tree_attr()
+Linux 6.15.
+.\" commit c4a16820d90199409c9bf01c4f794e1e9e8d8fd8
 .SH NOTES
+Glibc does not (yet) provide a wrapper for the
+.BR open_tree_attr ()
+system call; call it using
+.BR syscall (2).
 .SS Anonymous Mount Namespaces
 The bind-mount mount objects created by
 .BR open_tree ()
diff --git a/man/man2/open_tree_attr.2 b/man/man2/open_tree_attr.2
new file mode 100644
index 000000000000..e57269bbd269
--- /dev/null
+++ b/man/man2/open_tree_attr.2
@@ -0,0 +1 @@
+.so man2/open_tree.2

-- 
2.50.1

Re: [PATCH 01/10] mount_setattr.2: document glibc >= 2.36 syscall wrappers

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 4283 bytes --]

Hi Aleksa,

On Wed, Aug 06, 2025 at 02:25:46AM +1000, Aleksa Sarai wrote:
> Glibc 2.36 added syscall wrappers for the entire family of fd-based
> mount syscalls, including mount_setattr(2). Thus it's no longer
> necessary to instruct users to do raw syscall(2) operations.

Thanks!

> 
> Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
> ---
>  man/man2/mount_setattr.2 | 45 ++++++++-------------------------------------
>  1 file changed, 8 insertions(+), 37 deletions(-)
> 
> diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2
> index 60d9cf9de8aa..b8ddc3e22aef 100644
> --- a/man/man2/mount_setattr.2
> +++ b/man/man2/mount_setattr.2
> @@ -10,21 +10,14 @@ Standard C library
>  .RI ( libc ,\~ \-lc )
>  .SH SYNOPSIS
>  .nf
> -.BR "#include <linux/fcntl.h>" " /* Definition of " AT_* " constants */"
> -.BR "#include <linux/mount.h>" " /* Definition of " MOUNT_ATTR_* " constants */"
> -.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
> +.B #define _GNU_SOURCE
> +.B #include <sys/mount.h>
>  .B #include <unistd.h>
> +.BR "#include <fcntl.h>" "       /* Definition of " AT_* " constants */"

Please keep the include that provides the function prototype last.

And document with a comment the rationale for including all other
headers.

>  .P
> -.BI "int syscall(SYS_mount_setattr, int " dirfd ", const char *" path ,
> -.BI "            unsigned int " flags ", struct mount_attr *" attr \
> -", size_t " size );
> +.BI "int mount_setattr(int " dirfd ", const char *" path ", unsigned int " flags ",
> +.BI "                  struct mount_attr *" attr ", size_t " size );

Please use array notation if you can.  Have a look at, for example,
strncpy(3), for how it's done in source code.

>  .fi
> -.P
> -.IR Note :
> -glibc provides no wrapper for
> -.BR mount_setattr (),
> -necessitating the use of
> -.BR syscall (2).
>  .SH DESCRIPTION
>  The
>  .BR mount_setattr ()
> @@ -586,6 +579,7 @@ Linux 5.12.

This hunk context is a bit useless.  Would you mind having a look at
this?

$ cat ./CONTRIBUTING.d/git | sed -n '/git-diff.*gitattributes/,+8p'
   git-diff(1), gitattributes(5)
       To produce useful hunk contexts in manual pages, we need to hack
       git(1)'s idea of a function name, and also to tell git what is a
       manual page.

           $ git config --global diff.man.xfuncname '^\.S[SHsh] .*$';
           $ mkdir -p ~/.config/git/;
           $ echo '*.[0-9]* diff=man' >>~/.config/git/attributes;

>  .\" commit 7d6beb71da3cc033649d641e1e608713b8220290
>  .\" commit 2a1867219c7b27f928e2545782b86daaf9ad50bd
>  .\" commit 9caccd41541a6f7d6279928d9f971f6642c361af
> +Glibc 2.36.

We say 'glibc' even when it starts a sentence.  It's a name.


Have a lovely day!
Alex

>  .SH NOTES
>  .SS ID-mapped mounts
>  Creating an ID-mapped mount makes it possible to
> @@ -914,37 +908,14 @@ with a structure which has every byte nonzero
>  #include <err.h>
>  #include <fcntl.h>
>  #include <getopt.h>
> -#include <linux/mount.h>
> -#include <linux/types.h>
> +#include <sys/mount.h>
> +#include <sys/types.h>
>  #include <stdbool.h>
>  #include <stdio.h>
>  #include <stdlib.h>
>  #include <string.h>
> -#include <sys/syscall.h>
>  #include <unistd.h>
>  \&
> -static inline int
> -mount_setattr(int dirfd, const char *path, unsigned int flags,
> -              struct mount_attr *attr, size_t size)
> -{
> -    return syscall(SYS_mount_setattr, dirfd, path, flags,
> -                   attr, size);
> -}
> -\&
> -static inline int
> -open_tree(int dirfd, const char *filename, unsigned int flags)
> -{
> -    return syscall(SYS_open_tree, dirfd, filename, flags);
> -}
> -\&
> -static inline int
> -move_mount(int from_dirfd, const char *from_path,
> -           int to_dirfd, const char *to_path, unsigned int flags)
> -{
> -    return syscall(SYS_move_mount, from_dirfd, from_path,
> -                   to_dirfd, to_path, flags);
> -}
> -\&
>  static const struct option longopts[] = {
>      {"map\-mount",       required_argument,  NULL,  \[aq]a\[aq]},
>      {"recursive",       no_argument,        NULL,  \[aq]b\[aq]},
> 
> -- 
> 2.50.1
> 
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 02/10] mount_setattr.2: move mount_attr struct to mount_attr.2type

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 4805 bytes --]

Hi Aleksa,

On Wed, Aug 06, 2025 at 02:25:47AM +1000, Aleksa Sarai wrote:
> As with openat2(2type), it makes sense to move this to a separate man

I guess you meant open_how(2type) instead of openat2(2type).

	$ find man/man2type/
	man/man2type/
	man/man2type/open_how.2type

> page. In addition, future man pages added in this patchset will want to

Please use two spaces after period in commit messages.  See:

$ cat CONTRIBUTING.d/patches/description | grep -A5 Style.guide
    Style guide
	URIs should always be enclosed in <>.

	The correct inter-sentence space amount is two.  See some
	history about this:
	<https://web.archive.org/web/20171217060354/http://www.heracliteanriver.com/?p=324>

> reference mount_attr(2type).
> 
> Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
> ---
>  man/man2/mount_setattr.2      | 16 +++---------
>  man/man2type/mount_attr.2type | 58 +++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 62 insertions(+), 12 deletions(-)
> 
> diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2
> index b8ddc3e22aef..e863be64deb5 100644
> --- a/man/man2/mount_setattr.2
> +++ b/man/man2/mount_setattr.2
> @@ -116,18 +116,10 @@ The
>  .I attr
>  argument of
>  .BR mount_setattr ()
> -is a structure of the following form:
> -.P
> -.in +4n
> -.EX
> -struct mount_attr {
> -    __u64 attr_set;     /* Mount properties to set */
> -    __u64 attr_clr;     /* Mount properties to clear */
> -    __u64 propagation;  /* Mount propagation type */
> -    __u64 userns_fd;    /* User namespace file descriptor */
> -};
> -.EE
> -.in
> +is a pointer to a
> +.I mount_attr
> +structure, described in
> +.BR mount_attr (2type).
>  .P
>  The
>  .I attr_set
> diff --git a/man/man2type/mount_attr.2type b/man/man2type/mount_attr.2type
> new file mode 100644
> index 000000000000..733dbc3c8cdb
> --- /dev/null
> +++ b/man/man2type/mount_attr.2type
> @@ -0,0 +1,58 @@
> +
> +.\" Copyright, the authors of the Linux man-pages project
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH mount_attr 2type (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +mount_attr \- what mount properties to set and clear
> +.SH LIBRARY
> +Linux kernel headers
> +.SH SYNOPSIS
> +.EX
> +.B #include <sys/mount.h>
> +.P
> +.B struct mount_attr {
> +.BR "    __u64 attr_set;" "     /* Mount properties to set */"
> +.BR "    __u64 attr_clr;" "     /* Mount properties to clear */"
> +.BR "    __u64 propagation;" "  /* Mount propagation type */"
> +.BR "    __u64 userns_fd;" "    /* User namespace file descriptor */"
> +    /* ... */
> +.B };
> +.EE
> +.SH DESCRIPTION
> +Specifies which mount properties should be changed with
> +.BR mount_setattr (2).
> +.P
> +The fields are as follows:
> +.TP
> +.I attr_set

Please use .member syntax.  This is the convention we're using for new
documentation.  I'll slowly add consistency to the existing docs.  So:

	.I .attr_set

> +This field specifies which
> +.B MOUNT_ATTR_*

Please use

	.BI MOUNT_ATTR_ *

The variable part should be in italics.

> +attribute flags to set.
> +.TP
> +.I attr_clr
> +This fields specifies which
> +.B MOUNT_ATTR_*

Same here.

> +attribute flags to clear.
> +.TP
> +.I propagation
> +This field specifies what mount propagation will be applied.
> +The valid values of this field are the same propagation types described in
> +.BR mount_namespaces (7).
> +.TP
> +.I userns_fd
> +This fields specifies a file descriptor that indicates which user namespace to
> +use as a reference for ID-mapped mounts with
> +.BR MOUNT_ATTR_IDMAP .
> +.SH VERSIONS
> +Extra fields may be appended to the structure, with a zero value in a new field

Please use semantic newlines.  That is, break after the comma.  See
man-pages(7):

$ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
   Use semantic newlines
       In the source of a manual page, new sentences should be  started
       on  new  lines,  long  sentences  should  be split into lines at
       clause breaks (commas, semicolons, colons, and so on), and  long
       clauses  should be split at phrase boundaries.  This convention,
       sometimes known as "semantic newlines", makes it easier  to  see
       the effect of patches, which often operate at the level of indi‐
       vidual sentences, clauses, or phrases.


Have a lovely day!
Alex

> +resulting in the kernel behaving as though that extension field was not
> +present.
> +Therefore, a user
> +.I must
> +zero-fill this structure on initialization.
> +.SH STANDARDS
> +Linux.
> +.SH SEE ALSO
> +.BR mount_setattr (2)
> 
> -- 
> 2.50.1
> 
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 03/10] fsopen.2: document 'new' mount api

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 12958 bytes --]

Hi Aleksa,

On Wed, Aug 06, 2025 at 02:25:48AM +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-developed-by: David Howells <dhowells@redhat.com>
> Co-developed-by: Christian Brauner <brauner@kernel.org>
> Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
> ---
>  man/man2/fsopen.2 | 275 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 275 insertions(+)
> 
> diff --git a/man/man2/fsopen.2 b/man/man2/fsopen.2
> new file mode 100644
> index 000000000000..43a1709ec5b4
> --- /dev/null
> +++ b/man/man2/fsopen.2
> @@ -0,0 +1,275 @@
> +.\" Copyright, the authors of the Linux man-pages project
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH fsopen 2 (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +fsopen \- create a new filesystem context
> +.SH LIBRARY
> +Standard C library
> +.RI ( libc ,\~ \-lc )
> +.SH SYNOPSIS
> +.nf
> +.BR "#include <sys/mount.h>"
> +.BR "#include <unistd.h>"
> +.P
> +.BI "int fsopen(const char *" fsname ", unsigned int " flags ");

I tend to not have "name" in the name of parameters that are a string
representing a name.  The rationale is that strings very commonly used
for names, and so "fs" would be just as menaingful, and shorter.

The description would make it obvious that it's the fs name.

> +.fi
> +.SH DESCRIPTION
> +The
> +.BR fsopen ()
> +system call is part of the suite of file descriptor based mount facilities in
> +Linux.
> +.P
> +.BR fsopen ()
> +creates a blank filesystem configuration context within the kernel for the
> +filesystem named by
> +.IR fsname ,
> +puts the context into creation mode and attaches it to a file descriptor, which
> +is then returned.
> +The calling process must have the
> +.BR CAP_SYS_ADMIN

This should be B.  BR is for alternating Bold and Roman (normal).

> +capability in order to create a new filesystem configuration context.
> +.P
> +After obtaining a filesystem configuration context with
> +.BR fsopen (),
> +the general workflow for operating on the context looks like the following:
> +.RS
> +.IP 1. 3

Please have a look at man-pages(7) for some conventions on lists in the
project:

$ MANWIDTH=72 man man-pages | grep -A6 Ordered.lists
       Ordered lists
              Elements  are  preceded  by  a number in parentheses (1),
              (2).  These represent a set of steps that have an order.

              When there are  substeps,  they  will  be  numbered  like
              (4.2).

So, we'd use

	.IP (1) 5

Which indeed you can find everywhere (I did some consistency cleanups
about this some years ago):

	$ grep -rn 'IP.*(1)'
	man7/user_namespaces.7:417:.IP (1) 5
	man7/user_namespaces.7:607:.IP (1) 5
	man7/boot.7:22:.IP (1) 5
	man7/signal.7:228:.IP (1) 5
	man7/symlink.7:200:.IP (1) 5
	man7/man-pages.7:504:.IP (1) 5
	man7/epoll.7:84:.IP (1) 5
	man7/epoll.7:151:.IP (1) 5
	man7/locale.7:216:.IP (1) 5
	man7/capabilities.7:1274:.IP (1) 5
	man7/keyrings.7:317:.IP (1) 5
	man7/keyrings.7:452:.IP (1) 5
	man7/unix.7:586:.IP (1) 5
	man7/cpuset.7:1395:.IP (1) 5
	man7/cpuset.7:1435:.IP (1) 5
	man7/cgroups.7:1369:.IP (1) 5
	man7/cgroups.7:1425:.IP (1) 5
	man7/pipe.7:372:.IP (1) 5
	man7/uri.7:583:.IP (1) 5
	man2const/FUTEX_LOCK_PI.2const:70:.IP (1) 5
	man5/locale.5:598:.IP (1) 5
	man8/ld.so.8:63:.IP (1) 5
	man8/ld.so.8:472:.IP (1) 5
	man2/delete_module.2:41:.IP (1) 5
	man2/seccomp_unotify.2:76:.IP (1) 5
	man2/seccomp_unotify.2:441:.IP (1) 5
	man2/seccomp_unotify.2:1003:.IP (1) 5
	man2/seccomp_unotify.2:1106:.IP (1) 5
	man2/timerfd_create.2:487:.IP (1) 5
	man2/listen.2:89:.IP (1) 5
	man2/close.2:119:.IP (1) 5
	man2/request_key.2:206:.IP (1) 5
	man2/ptrace.2:2603:.IP (1) 5
	man2/memfd_create.2:261:.IP (1) 5
	man3/dlinfo.3:106:.IP (1) 5
	man3/posix_spawn.3:213:.IP (1) 5
	man3/newlocale.3:210:.IP (1) 5
	man3/tempnam.3:55:.IP (1) 5
	man3/pthread_cancel.3:62:.IP (1) 5
	man4/cciss.4:288:.IP (1) 5
	man4/cciss.4:334:.IP (1) 5
	man4/initrd.4:67:.IP (1) 5
	man4/initrd.4:305:.IP (1) 5

> +Pass the filesystem context file descriptor to
> +.BR fsconfig (2)
> +to specify any desired filesystem parameters.
> +This can be done as many times as necessary.
> +.IP 2.

Similarly, this should be

	.IP (2)

> +Pass the same filesystem context file descriptor to
> +.BR fsconfig (2)
> +with
> +.B FSCONFIG_CMD_CREATE
> +to create an instance of the configured filesystem.
> +.IP 3.
> +Pass the same filesystem context file descriptor to
> +.BR fsmount (2)
> +to create a new mount object for the root of the filesystem, which is then
> +attached to a new file descriptor.
> +.IP 4.
> +Use the mount object file descriptor as a
> +.I dirfd
> +argument to "*at()" system calls; or attach the mount object to a mount point
> +by passing the mount object file descriptor to
> +.BR move_mount (2).
> +.RE
> +.P
> +A filesystem configuration context is an in-kernel representation of a pending
> +transaction containing a set of configuration parameters that are to be applied
> +when creating a new instance of a filesystem or modifying the configuration of
> +an existing filesystem instance.
> +The filesystem context will move between different modes throughout its
> +lifecycle (such as the creation phase when created with
> +.BR fsopen (),
> +the reconfiguration phase when an existing filesystem instance is selected by
> +.BR fspick (2),
> +and the needs-mount phase between
> +.BR FSCONFIG_CMD_CREATE
> +and
> +.BR fsmount (2)),
> +which has an impact on what operations are permitted on the filesystem context.
> +.P
> +The file descriptor returned by
> +.BR fsopen ()
> +also acts as a channel for filesystems to provide more comprehensive error,
> +warning, and information messages than normally provided using the
> +.BR errno (3)
> +interface.
> +If an error occurs at any time during the workflow mentioned above, calling
> +.BR read (2)
> +on the filesystem context file descriptor will retrieve any ancillary
> +information about the encountered errors.
> +(See the "Message Retrieval Interface" section for more details on the message
> +format.)
> +.P
> +.I flags
> +can be used to control aspects of the creation of the file configuration
> +context.
> +A value for
> +.I flags
> +is constructed by OR'ing together zero or more of the following constants:
> +.RS
> +.TP
> +.B FSOPEN_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
> +A list of filesystems supported by the running kernel (and thus a list of valid
> +values for
> +.IR fsname )
> +can be obtained from
> +.IR /proc/filesystems .
> +(See also
> +.BR proc_filesystems (5).)
> +.SS Message Retrieval Interface
> +When doing operations on a filesystem configuration context, the filesystem
> +driver may choose to provide ancillary information to userspace in the form of
> +message strings.
> +.P
> +The filesystem context file descriptors returned by
> +.BR fsopen "() and " fspick (2)
> +may be queried for message strings at any time by calling
> +.BR read (2)
> +on the file descriptor.
> +This will return newline-separated messages that are prefixed to indicate their
> +class:
> +.RS
> +.TP
> +.B "e <message>"
> +An error message was logged.
> +This is usually associated with an error being returned from the corresponding
> +system call which triggered this message.
> +.TP
> +.B "w <message>"
> +A warning message was logged.
> +.TP
> +.B "i <message>"
> +An informational message was logged.
> +.RE
> +.P
> +Messages are removed from the queue as they are read.
> +Note that the message queue has limited depth, so it is possible for messages
> +to get lost.
> +If there are no messages in the message queue,
> +.B read(2)
> +will return no data.
> +.P
> +If there are multiple filesystem context file descriptors referencing the same
> +filesystem instance (such as if you call
> +.BR fspick (2)
> +multiple times for the same mount), each one gets its own independent message
> +queue.
> +This does not apply to file descriptors that were duplicated with
> +.BR dup (2).
> +.P
> +Usually messages will be prefixed by the filesystem driver that logged the
> +message, though this may not always be the case.
> +See the Linux kernel source code for details.
> +.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 EFAULT
> +One of the pointer arguments points to a location outside the calling process's
> +accessible address space.
> +.TP
> +.B EINVAL
> +.I flags
> +had an invalid 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 ENODEV
> +The filesystem named by
> +.I fsname
> +is not supported by the kernel.
> +.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 24dcb3d90a1f67fe08c68a004af37df059d74005
> +Glibc 2.36.
> +.SH EXAMPLES
> +To illustrate the workflow for creating a new mount, the following is a sample
> +of how to mount an ext4 filesystem stored on "/dev/sdb1" onto "/mnt".
> +.P
> +.in +4n
> +.EX
> +int sfd = fsopen("ext4", FSOPEN_CLOEXEC);

'sfd' is common for socket file descriptor.  Shouldn't we use fsfd?

> +fsconfig(sfd, FSCONFIG_SET_FLAG, "ro", NULL, 0);
> +fsconfig(sfd, FSCONFIG_SET_PATH, "source", "/dev/sdb1", AT_FDCWD);
> +fsconfig(sfd, FSCONFIG_SET_FLAG, "noatime", NULL, 0);
> +fsconfig(sfd, FSCONFIG_SET_FLAG, "acl", NULL, 0);
> +fsconfig(sfd, FSCONFIG_SET_FLAG, "user_xattr", NULL, 0);
> +fsconfig(sfd, FSCONFIG_SET_FLAG, "iversion", NULL, 0)
> +fsconfig(sfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
> +int mfd = fsmount(sfd, FSMOUNT_CLOEXEC, MOUNT_ATTR_RELATIME);

Please separate declarations from code.  And use a blank between them
A blank in the source of an example should be a line containing

	\&


Have a lovely day!
Alex

> +move_mount(mfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH);
> +.EE
> +.in
> +.P
> +First, an ext4 configuration context is created and attached to the file
> +descriptor
> +.IR sfd .
> +Then, a series of parameters (such as the source of the filesystem) are
> +provided using
> +.BR fsconfig (2),
> +followed by the filesystem instance being created with
> +.BR FSCONFIG_CMD_CREATE .
> +.BR fsmount (2)
> +is then used to create a new mount object attached to the file descriptor
> +.IR mfd ,
> +which is then attached to the intended mount point using
> +.BR move_mount (2).
> +.P
> +The above procedure is functionally equivalent to the following mount operation
> +using
> +.BR mount (2):
> +.P
> +.in +4n
> +.EX
> +mount("/dev/sdb1", "/mnt", "ext4", MS_RELATIME,
> +      "ro,noatime,acl,user_xattr,iversion");
> +.EE
> +.in
> +.P
> +And here's an example of creating a mount object of an NFS server share and
> +setting a Smack security module label.
> +However, instead of mounting it to a place on the filesystem, the program
> +instead uses the mount object directly to open a file from the NFS share.
> +.P
> +.in +4n
> +.EX
> +int sfd = fsopen("nfs", 0);
> +fsconfig(sfd, FSCONFIG_SET_STRING, "source", "example.com/pub/linux", 0);
> +fsconfig(sfd, FSCONFIG_SET_STRING, "nfsvers", "3", 0);
> +fsconfig(sfd, FSCONFIG_SET_STRING, "rsize", "65536", 0);
> +fsconfig(sfd, FSCONFIG_SET_STRING, "wsize", "65536", 0);
> +fsconfig(sfd, FSCONFIG_SET_STRING, "smackfsdef", "foolabel", 0);
> +fsconfig(sfd, FSCONFIG_SET_FLAG, "rdma", NULL, 0);
> +fsconfig(sfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
> +int mfd = fsmount(sfd, 0, MOUNT_ATTR_NODEV);
> +int fd = openat(mfd, "src/linux-5.2.tar.xz", O_RDONLY);
> +.EE
> +.in
> +.P
> +Unlike the previous example, this operation has no trivial equivalent with
> +.BR mount (2),
> +as it was not previously possible to create a mount object that is not attached
> +to any mount point.
> +.SH SEE ALSO
> +.BR mount (2),
> +.BR fsconfig (2),
> +.BR fsmount (2),
> +.BR fspick (2),
> +.BR open_tree (2),
> +.BR move_mount (2),
> +.BR mount_setattr (2),
> +.BR mount_namespaces (7)
> 
> -- 
> 2.50.1
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 04/10] fspick.2: document 'new' mount api

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 9410 bytes --]

Hi Aleksa,

On Wed, Aug 06, 2025 at 02:25:49AM +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-developed-by: David Howells <dhowells@redhat.com>
> Co-developed-by: Christian Brauner <brauner@kernel.org>
> Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
> ---
>  man/man2/fspick.2 | 274 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 274 insertions(+)
> 
> diff --git a/man/man2/fspick.2 b/man/man2/fspick.2
> new file mode 100644
> index 000000000000..a1e769a8935a
> --- /dev/null
> +++ b/man/man2/fspick.2
> @@ -0,0 +1,274 @@
> +.\" Copyright, the authors of the Linux man-pages project
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH fspick 2 (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +fspick \- select filesystem for reconfiguration
> +.SH LIBRARY
> +Standard C library
> +.RI ( libc ,\~ \-lc )
> +.SH SYNOPSIS
> +.nf
> +.B #define _GNU_SOURCE
> +.BR "#include <sys/mount.h>"
> +.BR "#include <unistd.h>"
> +.BR "#include <fcntl.h>" \
> +"          /* Definition of " AT_* " constants */"

Please reduce the amount of space so that it fits in a single source
line (if possible).  But use at least two spaces (if possible).

> +.P
> +.BI "int fspick(int " dirfd ", const char *" pathname ", unsigned int " flags ");

Please use 'path' instead of 'pathname' for parameter names.  It's
shorter, and conveys essentially the same information.  I did some
consistency fixes about it recently.  See:

	$ git log -1 a239bc4520d6
	commit a239bc4520d6cb8b4d217510c22eddd7c3fd5d10
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   Wed Jan 15 20:41:01 2025 +0100

	    man/: Consistently use 'path' for parameters referring to pathnames
	    
	    And use 'pathname' in the descriptions.
	    
	    'pathname' is the POSIXly correct term, and 'path' is a reasonable
	    abbreviation for it in parameter names.
	    
	    Cc: "G. Branden Robinson" <branden@debian.org>
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

Please have a look at the diff in that commit if you have doubts.

> +.fi
> +.SH DESCRIPTION
> +The
> +.BR fspick ()
> +system call is part of the suite of file descriptor based mount facilities in
> +Linux.
> +.P
> +.BR fspick()
> +creates a new filesystem configuration context for the filesystem instance
> +associated with the path described by
> +.IR dirfd " and " pathname ,

Please don't put more than one identifier in a source line:

	.I dirfd
	and
	.IR pathname ,

> +places it into reconfiguration mode (similar to
> +.BR mount (8)
> +with the "-o remount" option), and attaches it to a new file descriptor, which
> +is then returned.
> +The calling process must have the
> +.BR CAP_SYS_ADMIN

s/BR/B/

BTW, you can use 'make -R -j4 lint-man' to lint some of these yourself
(depending on how recent your system is).  Please have a look at
'make -R help' to see what dependencies you need for that.

> +capability in order to create a new filesystem configuration context.
> +.P
> +The resultant file descriptor can be used with
> +.BR fsconfig (2)
> +to specify the desired set of changes to mount parameters of the filesystem
> +instance.
> +Once the desired set of changes have been configured, the changes can be
> +effectuated by calling
> +.BR fsconfig (2)
> +with the
> +.B FSCONFIG_CMD_RECONFIGURE
> +command.
> +.P
> +As with most "*at()" system calls,
> +.BR fspick ()
> +uses the
> +.I dirfd
> +argument in conjunction with the
> +.I pathname
> +argument to determine the path to operate on, as follows:
> +.RS
> +.IP \[bu] 3
> +If the pathname given in
> +.I pathname
> +is absolute, then
> +.I dirfd
> +is ignored.
> +.IP \[bu]
> +If the pathname given in
> +.I pathname
> +is relative and
> +.I dirfd
> +is the special value
> +.BR AT_FDCWD ,
> +then
> +.I pathname
> +is interpreted relative to the current working
> +directory of the calling process (like
> +.BR open ()).
> +.IP \[bu]
> +If the pathname given in
> +.I pathname
> +is relative, then it is interpreted relative to the directory
> +referred to by the file descriptor
> +.I dirfd
> +(rather than relative to the current working directory of
> +the calling process, as is done by
> +.BR open ()
> +for a relative pathname).
> +In this case,
> +.I dirfd
> +must be a directory that was opened for reading
> +.RB ( O_RDONLY )
> +or using the
> +.B O_PATH
> +flag.
> +.IP \[bu]
> +If
> +.I pathname
> +is an empty string, and
> +.I flags
> +contains
> +.BR FSPICK_EMPTY_PATH ,
> +then the file descriptor referenced by
> +.I dirfd
> +is operated on directly.
> +In this case,
> +.I dirfd
> +can refer to any type of file, not just a directory.
> +.RE
> +.P
> +.I flags
> +can be used to control aspects of the path lookup and properties of the
> +returned file descriptor.
> +A value for
> +.I flags
> +is constructed by OR'ing together zero or more of the following constants:
> +.RS
> +.TP
> +.B FSPICK_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.
> +.TP
> +.B FSPICK_EMPTY_PATH
> +If
> +.I pathname
> +is an empty string, operate on the file referred to by
> +.I dirfd
> +(which may have been obtained from
> +.BR open "(2), " fsmount "(2), or " open_tree "(2).)"

One function per line.

> +In this case,
> +.I dirfd
> +can refer to any type of file, not just a directory.
> +If
> +.I dirfd
> +is
> +.BR AT_FDCWD ,
> +the call operates on the current working directory.
> +.TP
> +.B FSPICK_SYMLINK_NOFOLLOW
> +Do not follow symbolic links in the terminal component of
> +.IR pathname .
> +If
> +.I pathname
> +references a symbolic link, the returned filesystem context will reference the
> +filesystem that the symbolic link itself resides on.
> +.TP
> +.B FSPICK_NO_AUTOMOUNT
> +Do not follow automounts in the terminal component of
> +.IR pathname .
> +.RE
> +.P
> +As with filesystem contexts created with
> +.BR fsopen (2),
> +the file descriptor returned by
> +.BR fspick ()
> +may be queried for message strings at any time by calling
> +.BR read (2)
> +on the file descriptor.
> +(See the "Message Retrieval Interface" subsection in
> +.BR fsopen (2)
> +for more details on the message format.)
> +.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 EACCES
> +Search permission is denied for one of the directories
> +in the path prefix of
> +.IR pathname .
> +(See also
> +.BR path_resolution (7).)
> +.TP
> +.B EBADF
> +.I pathname
> +is relative but
> +.I dirfd
> +is neither
> +.B AT_FDCWD
> +nor a valid file descriptor.
> +.TP
> +.B EFAULT
> +.I pathname
> +is NULL or a pointer to a location outside the calling process's accessible
> +address space.

In a lot of places, please use semantic newlines.  See man-pages(7).


Have a lovely day!
Alex

> +.TP
> +.B EINVAL
> +Invalid flag specified in
> +.IR flags .
> +.TP
> +.B ELOOP
> +Too many symbolic links encountered when resolving
> +.IR pathname .
> +.TP
> +.B ENAMETOOLONG
> +.I pathname
> +is longer than
> +.BR PATH_MAX .
> +.TP
> +.B ENOENT
> +A component of
> +.I pathname
> +does not exist, or is a dangling symbolic link.
> +.TP
> +.B ENOENT
> +.I pathname
> +is an empty string, but
> +.B FSPICK_EMPTY_PATH
> +is not specified in
> +.IR flags .
> +.TP
> +.B ENOTDIR
> +A component of the path prefix of
> +.I pathname
> +is not a directory, or
> +.I pathname
> +is relative and
> +.I dirfd
> +is a file descriptor referring to a file other than a directory.
> +.TP
> +.B ENOMEM
> +The kernel could not allocate sufficient memory to complete the operation.
> +.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 EPERM
> +The calling process does not have the required
> +.B CAP_SYS_ADMIN
> +capability.
> +.SH STANDARDS
> +Linux.
> +.SH HISTORY
> +Linux 5.2.
> +.\" commit cf3cba4a429be43e5527a3f78859b1bfd9ebc5fb
> +Glibc 2.36.
> +.SH EXAMPLES
> +The following example sets the read-only superblock flag on "/tmp".
> +.P
> +.in +4n
> +.EX
> +int sfd = fspick(AT_FDCWD, "/tmp", FSPICK_CLOEXEC);
> +fsconfig(sfd, FSCONFIG_SET_FLAG, "ro", NULL, 0);
> +fsconfig(sfd, FSCONFIG_CMD_RECONFIGURE, NULL, NULL, 0);
> +.EE
> +.in
> +.P
> +The above procedure is functionally equivalent to the following mount operation
> +using
> +.BR mount (2):
> +.P
> +.in +4n
> +.EX
> +mount(NULL, "/tmp", NULL, MS_REMOUNT | MS_RDONLY, NULL);
> +.EE
> +.in
> +.SH SEE ALSO
> +.BR mount (2),
> +.BR fsopen (2),
> +.BR fsconfig (2),
> +.BR fsmount (2),
> +.BR open_tree (2),
> +.BR move_mount (2),
> +.BR mount_setattr (2),
> +.BR mount_namespaces (7)
> +
> 
> -- 
> 2.50.1
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 04/10] fspick.2: document 'new' mount api

[Aleksa Sarai]

[-- Attachment #1: Type: text/plain, Size: 10816 bytes --]

On 2025-08-05, Alejandro Colomar <alx@kernel.org> wrote:
> Hi Aleksa,
> 
> On Wed, Aug 06, 2025 at 02:25:49AM +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-developed-by: David Howells <dhowells@redhat.com>
> > Co-developed-by: Christian Brauner <brauner@kernel.org>
> > Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
> > ---
> >  man/man2/fspick.2 | 274 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 274 insertions(+)
> > 
> > diff --git a/man/man2/fspick.2 b/man/man2/fspick.2
> > new file mode 100644
> > index 000000000000..a1e769a8935a
> > --- /dev/null
> > +++ b/man/man2/fspick.2
> > @@ -0,0 +1,274 @@
> > +.\" Copyright, the authors of the Linux man-pages project
> > +.\"
> > +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> > +.\"
> > +.TH fspick 2 (date) "Linux man-pages (unreleased)"
> > +.SH NAME
> > +fspick \- select filesystem for reconfiguration
> > +.SH LIBRARY
> > +Standard C library
> > +.RI ( libc ,\~ \-lc )
> > +.SH SYNOPSIS
> > +.nf
> > +.B #define _GNU_SOURCE
> > +.BR "#include <sys/mount.h>"
> > +.BR "#include <unistd.h>"
> > +.BR "#include <fcntl.h>" \
> > +"          /* Definition of " AT_* " constants */"
> 
> Please reduce the amount of space so that it fits in a single source
> line (if possible).  But use at least two spaces (if possible).
> 
> > +.P
> > +.BI "int fspick(int " dirfd ", const char *" pathname ", unsigned int " flags ");
> 
> Please use 'path' instead of 'pathname' for parameter names.  It's
> shorter, and conveys essentially the same information.  I did some
> consistency fixes about it recently.  See:

Oh, I actually changed it from 'path' to 'pathname' to match some of the
other "*at()" man pages but it seems the man pages on my machine are
from before some of these reworks you've mentioned...

> 	$ git log -1 a239bc4520d6
> 	commit a239bc4520d6cb8b4d217510c22eddd7c3fd5d10
> 	Author: Alejandro Colomar <alx@kernel.org>
> 	Date:   Wed Jan 15 20:41:01 2025 +0100
> 
> 	    man/: Consistently use 'path' for parameters referring to pathnames
> 	    
> 	    And use 'pathname' in the descriptions.
> 	    
> 	    'pathname' is the POSIXly correct term, and 'path' is a reasonable
> 	    abbreviation for it in parameter names.
> 	    
> 	    Cc: "G. Branden Robinson" <branden@debian.org>
> 	    Signed-off-by: Alejandro Colomar <alx@kernel.org>
> 
> Please have a look at the diff in that commit if you have doubts.
> 
> > +.fi
> > +.SH DESCRIPTION
> > +The
> > +.BR fspick ()
> > +system call is part of the suite of file descriptor based mount facilities in
> > +Linux.
> > +.P
> > +.BR fspick()
> > +creates a new filesystem configuration context for the filesystem instance
> > +associated with the path described by
> > +.IR dirfd " and " pathname ,
> 
> Please don't put more than one identifier in a source line:
> 
> 	.I dirfd
> 	and
> 	.IR pathname ,
> 
> > +places it into reconfiguration mode (similar to
> > +.BR mount (8)
> > +with the "-o remount" option), and attaches it to a new file descriptor, which
> > +is then returned.
> > +The calling process must have the
> > +.BR CAP_SYS_ADMIN
> 
> s/BR/B/
> 
> BTW, you can use 'make -R -j4 lint-man' to lint some of these yourself
> (depending on how recent your system is).  Please have a look at
> 'make -R help' to see what dependencies you need for that.
> 
> > +capability in order to create a new filesystem configuration context.
> > +.P
> > +The resultant file descriptor can be used with
> > +.BR fsconfig (2)
> > +to specify the desired set of changes to mount parameters of the filesystem
> > +instance.
> > +Once the desired set of changes have been configured, the changes can be
> > +effectuated by calling
> > +.BR fsconfig (2)
> > +with the
> > +.B FSCONFIG_CMD_RECONFIGURE
> > +command.
> > +.P
> > +As with most "*at()" system calls,
> > +.BR fspick ()
> > +uses the
> > +.I dirfd
> > +argument in conjunction with the
> > +.I pathname
> > +argument to determine the path to operate on, as follows:
> > +.RS
> > +.IP \[bu] 3
> > +If the pathname given in
> > +.I pathname
> > +is absolute, then
> > +.I dirfd
> > +is ignored.
> > +.IP \[bu]
> > +If the pathname given in
> > +.I pathname
> > +is relative and
> > +.I dirfd
> > +is the special value
> > +.BR AT_FDCWD ,
> > +then
> > +.I pathname
> > +is interpreted relative to the current working
> > +directory of the calling process (like
> > +.BR open ()).
> > +.IP \[bu]
> > +If the pathname given in
> > +.I pathname
> > +is relative, then it is interpreted relative to the directory
> > +referred to by the file descriptor
> > +.I dirfd
> > +(rather than relative to the current working directory of
> > +the calling process, as is done by
> > +.BR open ()
> > +for a relative pathname).
> > +In this case,
> > +.I dirfd
> > +must be a directory that was opened for reading
> > +.RB ( O_RDONLY )
> > +or using the
> > +.B O_PATH
> > +flag.
> > +.IP \[bu]
> > +If
> > +.I pathname
> > +is an empty string, and
> > +.I flags
> > +contains
> > +.BR FSPICK_EMPTY_PATH ,
> > +then the file descriptor referenced by
> > +.I dirfd
> > +is operated on directly.
> > +In this case,
> > +.I dirfd
> > +can refer to any type of file, not just a directory.
> > +.RE
> > +.P
> > +.I flags
> > +can be used to control aspects of the path lookup and properties of the
> > +returned file descriptor.
> > +A value for
> > +.I flags
> > +is constructed by OR'ing together zero or more of the following constants:
> > +.RS
> > +.TP
> > +.B FSPICK_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.
> > +.TP
> > +.B FSPICK_EMPTY_PATH
> > +If
> > +.I pathname
> > +is an empty string, operate on the file referred to by
> > +.I dirfd
> > +(which may have been obtained from
> > +.BR open "(2), " fsmount "(2), or " open_tree "(2).)"
> 
> One function per line.
> 
> > +In this case,
> > +.I dirfd
> > +can refer to any type of file, not just a directory.
> > +If
> > +.I dirfd
> > +is
> > +.BR AT_FDCWD ,
> > +the call operates on the current working directory.
> > +.TP
> > +.B FSPICK_SYMLINK_NOFOLLOW
> > +Do not follow symbolic links in the terminal component of
> > +.IR pathname .
> > +If
> > +.I pathname
> > +references a symbolic link, the returned filesystem context will reference the
> > +filesystem that the symbolic link itself resides on.
> > +.TP
> > +.B FSPICK_NO_AUTOMOUNT
> > +Do not follow automounts in the terminal component of
> > +.IR pathname .
> > +.RE
> > +.P
> > +As with filesystem contexts created with
> > +.BR fsopen (2),
> > +the file descriptor returned by
> > +.BR fspick ()
> > +may be queried for message strings at any time by calling
> > +.BR read (2)
> > +on the file descriptor.
> > +(See the "Message Retrieval Interface" subsection in
> > +.BR fsopen (2)
> > +for more details on the message format.)
> > +.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 EACCES
> > +Search permission is denied for one of the directories
> > +in the path prefix of
> > +.IR pathname .
> > +(See also
> > +.BR path_resolution (7).)
> > +.TP
> > +.B EBADF
> > +.I pathname
> > +is relative but
> > +.I dirfd
> > +is neither
> > +.B AT_FDCWD
> > +nor a valid file descriptor.
> > +.TP
> > +.B EFAULT
> > +.I pathname
> > +is NULL or a pointer to a location outside the calling process's accessible
> > +address space.
> 
> In a lot of places, please use semantic newlines.  See man-pages(7).

In this particular case, where would you want a newline inserted? I
do somewhat understand wanting a newline after commas, but I don't see
which clause you would want to be split. Something like this?

.B EFAULT
.I pathname
is NULL
or a pointer
to a location outside the calling process's accessible address space?

...?

Thanks.

> Have a lovely day!
> Alex
> 
> > +.TP
> > +.B EINVAL
> > +Invalid flag specified in
> > +.IR flags .
> > +.TP
> > +.B ELOOP
> > +Too many symbolic links encountered when resolving
> > +.IR pathname .
> > +.TP
> > +.B ENAMETOOLONG
> > +.I pathname
> > +is longer than
> > +.BR PATH_MAX .
> > +.TP
> > +.B ENOENT
> > +A component of
> > +.I pathname
> > +does not exist, or is a dangling symbolic link.
> > +.TP
> > +.B ENOENT
> > +.I pathname
> > +is an empty string, but
> > +.B FSPICK_EMPTY_PATH
> > +is not specified in
> > +.IR flags .
> > +.TP
> > +.B ENOTDIR
> > +A component of the path prefix of
> > +.I pathname
> > +is not a directory, or
> > +.I pathname
> > +is relative and
> > +.I dirfd
> > +is a file descriptor referring to a file other than a directory.
> > +.TP
> > +.B ENOMEM
> > +The kernel could not allocate sufficient memory to complete the operation.
> > +.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 EPERM
> > +The calling process does not have the required
> > +.B CAP_SYS_ADMIN
> > +capability.
> > +.SH STANDARDS
> > +Linux.
> > +.SH HISTORY
> > +Linux 5.2.
> > +.\" commit cf3cba4a429be43e5527a3f78859b1bfd9ebc5fb
> > +Glibc 2.36.
> > +.SH EXAMPLES
> > +The following example sets the read-only superblock flag on "/tmp".
> > +.P
> > +.in +4n
> > +.EX
> > +int sfd = fspick(AT_FDCWD, "/tmp", FSPICK_CLOEXEC);
> > +fsconfig(sfd, FSCONFIG_SET_FLAG, "ro", NULL, 0);
> > +fsconfig(sfd, FSCONFIG_CMD_RECONFIGURE, NULL, NULL, 0);
> > +.EE
> > +.in
> > +.P
> > +The above procedure is functionally equivalent to the following mount operation
> > +using
> > +.BR mount (2):
> > +.P
> > +.in +4n
> > +.EX
> > +mount(NULL, "/tmp", NULL, MS_REMOUNT | MS_RDONLY, NULL);
> > +.EE
> > +.in
> > +.SH SEE ALSO
> > +.BR mount (2),
> > +.BR fsopen (2),
> > +.BR fsconfig (2),
> > +.BR fsmount (2),
> > +.BR open_tree (2),
> > +.BR move_mount (2),
> > +.BR mount_setattr (2),
> > +.BR mount_namespaces (7)
> > +
> > 
> > -- 
> > 2.50.1
> > 
> 
> -- 
> <https://www.alejandro-colomar.es/>



-- 
Aleksa Sarai
Senior Software Engineer (Containers)
SUSE Linux GmbH
https://www.cyphar.com/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 01/10] mount_setattr.2: document glibc >= 2.36 syscall wrappers

[Aleksa Sarai]

[-- Attachment #1: Type: text/plain, Size: 5092 bytes --]

On 2025-08-05, Alejandro Colomar <alx@kernel.org> wrote:
> Hi Aleksa,
> 
> On Wed, Aug 06, 2025 at 02:25:46AM +1000, Aleksa Sarai wrote:
> > Glibc 2.36 added syscall wrappers for the entire family of fd-based
> > mount syscalls, including mount_setattr(2). Thus it's no longer
> > necessary to instruct users to do raw syscall(2) operations.
> 
> Thanks!
> 
> > 
> > Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
> > ---
> >  man/man2/mount_setattr.2 | 45 ++++++++-------------------------------------
> >  1 file changed, 8 insertions(+), 37 deletions(-)
> > 
> > diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2
> > index 60d9cf9de8aa..b8ddc3e22aef 100644
> > --- a/man/man2/mount_setattr.2
> > +++ b/man/man2/mount_setattr.2
> > @@ -10,21 +10,14 @@ Standard C library
> >  .RI ( libc ,\~ \-lc )
> >  .SH SYNOPSIS
> >  .nf
> > -.BR "#include <linux/fcntl.h>" " /* Definition of " AT_* " constants */"
> > -.BR "#include <linux/mount.h>" " /* Definition of " MOUNT_ATTR_* " constants */"
> > -.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
> > +.B #define _GNU_SOURCE
> > +.B #include <sys/mount.h>
> >  .B #include <unistd.h>
> > +.BR "#include <fcntl.h>" "       /* Definition of " AT_* " constants */"
> 
> Please keep the include that provides the function prototype last.
> 
> And document with a comment the rationale for including all other
> headers.

*All* of the headers? <sys/mount.h> includes both the prototype and
MOUNT_ATTR_* constants, and most other man pages only include an
explanation for some of the includes AFAICS.

> >  .P
> > -.BI "int syscall(SYS_mount_setattr, int " dirfd ", const char *" path ,
> > -.BI "            unsigned int " flags ", struct mount_attr *" attr \
> > -", size_t " size );
> > +.BI "int mount_setattr(int " dirfd ", const char *" path ", unsigned int " flags ",
> > +.BI "                  struct mount_attr *" attr ", size_t " size );
> 
> Please use array notation if you can.  Have a look at, for example,
> strncpy(3), for how it's done in source code.

"struct mount_attr *attr" is not an array argument, it's an extensible
struct. mount_setattr(2) already has docs explaining this (in the
"Extensbility" section, as well as later in DESCRIPTION).

> >  .fi
> > -.P
> > -.IR Note :
> > -glibc provides no wrapper for
> > -.BR mount_setattr (),
> > -necessitating the use of
> > -.BR syscall (2).
> >  .SH DESCRIPTION
> >  The
> >  .BR mount_setattr ()
> > @@ -586,6 +579,7 @@ Linux 5.12.
> 
> This hunk context is a bit useless.  Would you mind having a look at
> this?
> 
> $ cat ./CONTRIBUTING.d/git | sed -n '/git-diff.*gitattributes/,+8p'
>    git-diff(1), gitattributes(5)
>        To produce useful hunk contexts in manual pages, we need to hack
>        git(1)'s idea of a function name, and also to tell git what is a
>        manual page.
> 
>            $ git config --global diff.man.xfuncname '^\.S[SHsh] .*$';
>            $ mkdir -p ~/.config/git/;
>            $ echo '*.[0-9]* diff=man' >>~/.config/git/attributes;
> 
> >  .\" commit 7d6beb71da3cc033649d641e1e608713b8220290
> >  .\" commit 2a1867219c7b27f928e2545782b86daaf9ad50bd
> >  .\" commit 9caccd41541a6f7d6279928d9f971f6642c361af
> > +Glibc 2.36.
> 
> We say 'glibc' even when it starts a sentence.  It's a name.
> 
> 
> Have a lovely day!
> Alex
> 
> >  .SH NOTES
> >  .SS ID-mapped mounts
> >  Creating an ID-mapped mount makes it possible to
> > @@ -914,37 +908,14 @@ with a structure which has every byte nonzero
> >  #include <err.h>
> >  #include <fcntl.h>
> >  #include <getopt.h>
> > -#include <linux/mount.h>
> > -#include <linux/types.h>
> > +#include <sys/mount.h>
> > +#include <sys/types.h>
> >  #include <stdbool.h>
> >  #include <stdio.h>
> >  #include <stdlib.h>
> >  #include <string.h>
> > -#include <sys/syscall.h>
> >  #include <unistd.h>
> >  \&
> > -static inline int
> > -mount_setattr(int dirfd, const char *path, unsigned int flags,
> > -              struct mount_attr *attr, size_t size)
> > -{
> > -    return syscall(SYS_mount_setattr, dirfd, path, flags,
> > -                   attr, size);
> > -}
> > -\&
> > -static inline int
> > -open_tree(int dirfd, const char *filename, unsigned int flags)
> > -{
> > -    return syscall(SYS_open_tree, dirfd, filename, flags);
> > -}
> > -\&
> > -static inline int
> > -move_mount(int from_dirfd, const char *from_path,
> > -           int to_dirfd, const char *to_path, unsigned int flags)
> > -{
> > -    return syscall(SYS_move_mount, from_dirfd, from_path,
> > -                   to_dirfd, to_path, flags);
> > -}
> > -\&
> >  static const struct option longopts[] = {
> >      {"map\-mount",       required_argument,  NULL,  \[aq]a\[aq]},
> >      {"recursive",       no_argument,        NULL,  \[aq]b\[aq]},
> > 
> > -- 
> > 2.50.1
> > 
> > 
> 
> -- 
> <https://www.alejandro-colomar.es/>



-- 
Aleksa Sarai
Senior Software Engineer (Containers)
SUSE Linux GmbH
https://www.cyphar.com/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 03/10] fsopen.2: document 'new' mount api

[Aleksa Sarai]

[-- Attachment #1: Type: text/plain, Size: 15144 bytes --]

On 2025-08-05, Alejandro Colomar <alx@kernel.org> wrote:
> Hi Aleksa,
> 
> On Wed, Aug 06, 2025 at 02:25:48AM +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-developed-by: David Howells <dhowells@redhat.com>
> > Co-developed-by: Christian Brauner <brauner@kernel.org>
> > Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
> > ---
> >  man/man2/fsopen.2 | 275 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 275 insertions(+)
> > 
> > diff --git a/man/man2/fsopen.2 b/man/man2/fsopen.2
> > new file mode 100644
> > index 000000000000..43a1709ec5b4
> > --- /dev/null
> > +++ b/man/man2/fsopen.2
> > @@ -0,0 +1,275 @@
> > +.\" Copyright, the authors of the Linux man-pages project
> > +.\"
> > +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> > +.\"
> > +.TH fsopen 2 (date) "Linux man-pages (unreleased)"
> > +.SH NAME
> > +fsopen \- create a new filesystem context
> > +.SH LIBRARY
> > +Standard C library
> > +.RI ( libc ,\~ \-lc )
> > +.SH SYNOPSIS
> > +.nf
> > +.BR "#include <sys/mount.h>"
> > +.BR "#include <unistd.h>"
> > +.P
> > +.BI "int fsopen(const char *" fsname ", unsigned int " flags ");
> 
> I tend to not have "name" in the name of parameters that are a string
> representing a name.  The rationale is that strings very commonly used
> for names, and so "fs" would be just as menaingful, and shorter.
> 
> The description would make it obvious that it's the fs name.

Personally, as a documentation reader I would find "const char *fs" more
confusing -- a filesystem-related "open" operation that takes a non-path
argument is already a little bit fruity, but "fsname" at least provides
some indication that the string argument is a _name_ rather than a
_path_. Just having "fs" is less clear IMHO.

(Also this is the parameter name in the kernel implementation, though I
understand that doesn't really have a big impact on how we document
these things in man-pages.)

> > +.fi
> > +.SH DESCRIPTION
> > +The
> > +.BR fsopen ()
> > +system call is part of the suite of file descriptor based mount facilities in
> > +Linux.
> > +.P
> > +.BR fsopen ()
> > +creates a blank filesystem configuration context within the kernel for the
> > +filesystem named by
> > +.IR fsname ,
> > +puts the context into creation mode and attaches it to a file descriptor, which
> > +is then returned.
> > +The calling process must have the
> > +.BR CAP_SYS_ADMIN
> 
> This should be B.  BR is for alternating Bold and Roman (normal).

Grr, I thought I fixed all of these typos. My bad.

> > +capability in order to create a new filesystem configuration context.
> > +.P
> > +After obtaining a filesystem configuration context with
> > +.BR fsopen (),
> > +the general workflow for operating on the context looks like the following:
> > +.RS
> > +.IP 1. 3
> 
> Please have a look at man-pages(7) for some conventions on lists in the
> project:

I will admit that I wasn't aware of how detailed (and particular)
man-pages(7) was about the style guide. I'll read through and adjust the
patches accordingly. Mea culpa.

> $ MANWIDTH=72 man man-pages | grep -A6 Ordered.lists
>        Ordered lists
>               Elements  are  preceded  by  a number in parentheses (1),
>               (2).  These represent a set of steps that have an order.
> 
>               When there are  substeps,  they  will  be  numbered  like
>               (4.2).
> 
> So, we'd use
> 
> 	.IP (1) 5
> 
> Which indeed you can find everywhere (I did some consistency cleanups
> about this some years ago):
> 
> 	$ grep -rn 'IP.*(1)'
> 	man7/user_namespaces.7:417:.IP (1) 5
> 	man7/user_namespaces.7:607:.IP (1) 5
> 	man7/boot.7:22:.IP (1) 5
> 	man7/signal.7:228:.IP (1) 5
> 	man7/symlink.7:200:.IP (1) 5
> 	man7/man-pages.7:504:.IP (1) 5
> 	man7/epoll.7:84:.IP (1) 5
> 	man7/epoll.7:151:.IP (1) 5
> 	man7/locale.7:216:.IP (1) 5
> 	man7/capabilities.7:1274:.IP (1) 5
> 	man7/keyrings.7:317:.IP (1) 5
> 	man7/keyrings.7:452:.IP (1) 5
> 	man7/unix.7:586:.IP (1) 5
> 	man7/cpuset.7:1395:.IP (1) 5
> 	man7/cpuset.7:1435:.IP (1) 5
> 	man7/cgroups.7:1369:.IP (1) 5
> 	man7/cgroups.7:1425:.IP (1) 5
> 	man7/pipe.7:372:.IP (1) 5
> 	man7/uri.7:583:.IP (1) 5
> 	man2const/FUTEX_LOCK_PI.2const:70:.IP (1) 5
> 	man5/locale.5:598:.IP (1) 5
> 	man8/ld.so.8:63:.IP (1) 5
> 	man8/ld.so.8:472:.IP (1) 5
> 	man2/delete_module.2:41:.IP (1) 5
> 	man2/seccomp_unotify.2:76:.IP (1) 5
> 	man2/seccomp_unotify.2:441:.IP (1) 5
> 	man2/seccomp_unotify.2:1003:.IP (1) 5
> 	man2/seccomp_unotify.2:1106:.IP (1) 5
> 	man2/timerfd_create.2:487:.IP (1) 5
> 	man2/listen.2:89:.IP (1) 5
> 	man2/close.2:119:.IP (1) 5
> 	man2/request_key.2:206:.IP (1) 5
> 	man2/ptrace.2:2603:.IP (1) 5
> 	man2/memfd_create.2:261:.IP (1) 5
> 	man3/dlinfo.3:106:.IP (1) 5
> 	man3/posix_spawn.3:213:.IP (1) 5
> 	man3/newlocale.3:210:.IP (1) 5
> 	man3/tempnam.3:55:.IP (1) 5
> 	man3/pthread_cancel.3:62:.IP (1) 5
> 	man4/cciss.4:288:.IP (1) 5
> 	man4/cciss.4:334:.IP (1) 5
> 	man4/initrd.4:67:.IP (1) 5
> 	man4/initrd.4:305:.IP (1) 5
> 
> > +Pass the filesystem context file descriptor to
> > +.BR fsconfig (2)
> > +to specify any desired filesystem parameters.
> > +This can be done as many times as necessary.
> > +.IP 2.
> 
> Similarly, this should be
> 
> 	.IP (2)
> 
> > +Pass the same filesystem context file descriptor to
> > +.BR fsconfig (2)
> > +with
> > +.B FSCONFIG_CMD_CREATE
> > +to create an instance of the configured filesystem.
> > +.IP 3.
> > +Pass the same filesystem context file descriptor to
> > +.BR fsmount (2)
> > +to create a new mount object for the root of the filesystem, which is then
> > +attached to a new file descriptor.
> > +.IP 4.
> > +Use the mount object file descriptor as a
> > +.I dirfd
> > +argument to "*at()" system calls; or attach the mount object to a mount point
> > +by passing the mount object file descriptor to
> > +.BR move_mount (2).
> > +.RE
> > +.P
> > +A filesystem configuration context is an in-kernel representation of a pending
> > +transaction containing a set of configuration parameters that are to be applied
> > +when creating a new instance of a filesystem or modifying the configuration of
> > +an existing filesystem instance.
> > +The filesystem context will move between different modes throughout its
> > +lifecycle (such as the creation phase when created with
> > +.BR fsopen (),
> > +the reconfiguration phase when an existing filesystem instance is selected by
> > +.BR fspick (2),
> > +and the needs-mount phase between
> > +.BR FSCONFIG_CMD_CREATE
> > +and
> > +.BR fsmount (2)),
> > +which has an impact on what operations are permitted on the filesystem context.
> > +.P
> > +The file descriptor returned by
> > +.BR fsopen ()
> > +also acts as a channel for filesystems to provide more comprehensive error,
> > +warning, and information messages than normally provided using the
> > +.BR errno (3)
> > +interface.
> > +If an error occurs at any time during the workflow mentioned above, calling
> > +.BR read (2)
> > +on the filesystem context file descriptor will retrieve any ancillary
> > +information about the encountered errors.
> > +(See the "Message Retrieval Interface" section for more details on the message
> > +format.)
> > +.P
> > +.I flags
> > +can be used to control aspects of the creation of the file configuration
> > +context.
> > +A value for
> > +.I flags
> > +is constructed by OR'ing together zero or more of the following constants:
> > +.RS
> > +.TP
> > +.B FSOPEN_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
> > +A list of filesystems supported by the running kernel (and thus a list of valid
> > +values for
> > +.IR fsname )
> > +can be obtained from
> > +.IR /proc/filesystems .
> > +(See also
> > +.BR proc_filesystems (5).)
> > +.SS Message Retrieval Interface
> > +When doing operations on a filesystem configuration context, the filesystem
> > +driver may choose to provide ancillary information to userspace in the form of
> > +message strings.
> > +.P
> > +The filesystem context file descriptors returned by
> > +.BR fsopen "() and " fspick (2)
> > +may be queried for message strings at any time by calling
> > +.BR read (2)
> > +on the file descriptor.
> > +This will return newline-separated messages that are prefixed to indicate their
> > +class:
> > +.RS
> > +.TP
> > +.B "e <message>"
> > +An error message was logged.
> > +This is usually associated with an error being returned from the corresponding
> > +system call which triggered this message.
> > +.TP
> > +.B "w <message>"
> > +A warning message was logged.
> > +.TP
> > +.B "i <message>"
> > +An informational message was logged.
> > +.RE
> > +.P
> > +Messages are removed from the queue as they are read.
> > +Note that the message queue has limited depth, so it is possible for messages
> > +to get lost.
> > +If there are no messages in the message queue,
> > +.B read(2)
> > +will return no data.
> > +.P
> > +If there are multiple filesystem context file descriptors referencing the same
> > +filesystem instance (such as if you call
> > +.BR fspick (2)
> > +multiple times for the same mount), each one gets its own independent message
> > +queue.
> > +This does not apply to file descriptors that were duplicated with
> > +.BR dup (2).
> > +.P
> > +Usually messages will be prefixed by the filesystem driver that logged the
> > +message, though this may not always be the case.
> > +See the Linux kernel source code for details.
> > +.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 EFAULT
> > +One of the pointer arguments points to a location outside the calling process's
> > +accessible address space.
> > +.TP
> > +.B EINVAL
> > +.I flags
> > +had an invalid 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 ENODEV
> > +The filesystem named by
> > +.I fsname
> > +is not supported by the kernel.
> > +.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 24dcb3d90a1f67fe08c68a004af37df059d74005
> > +Glibc 2.36.
> > +.SH EXAMPLES
> > +To illustrate the workflow for creating a new mount, the following is a sample
> > +of how to mount an ext4 filesystem stored on "/dev/sdb1" onto "/mnt".
> > +.P
> > +.in +4n
> > +.EX
> > +int sfd = fsopen("ext4", FSOPEN_CLOEXEC);
> 
> 'sfd' is common for socket file descriptor.  Shouldn't we use fsfd?

It's not really a "filesystem fd" because there is an in-kernel
distinction between "filesystem context file descriptors" which are tied
to superblock lifecycles and "mount object file descriptors" that act
like a filesystem.

As such, I'm not sure if "fsfd" is more descriptive in an example. The
"s" in "sfd" stands for "superblock" and is a fairly common pattern
userspace users of this API tend to use.

But I'm not too fussed about it, if you really prefer fsfd, I'll swap to
that.

> > +fsconfig(sfd, FSCONFIG_SET_FLAG, "ro", NULL, 0);
> > +fsconfig(sfd, FSCONFIG_SET_PATH, "source", "/dev/sdb1", AT_FDCWD);
> > +fsconfig(sfd, FSCONFIG_SET_FLAG, "noatime", NULL, 0);
> > +fsconfig(sfd, FSCONFIG_SET_FLAG, "acl", NULL, 0);
> > +fsconfig(sfd, FSCONFIG_SET_FLAG, "user_xattr", NULL, 0);
> > +fsconfig(sfd, FSCONFIG_SET_FLAG, "iversion", NULL, 0)
> > +fsconfig(sfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
> > +int mfd = fsmount(sfd, FSMOUNT_CLOEXEC, MOUNT_ATTR_RELATIME);
> 
> Please separate declarations from code.  And use a blank between them
> A blank in the source of an example should be a line containing
> 
> 	\&
> 
> 
> Have a lovely day!
> Alex
> 
> > +move_mount(mfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH);
> > +.EE
> > +.in
> > +.P
> > +First, an ext4 configuration context is created and attached to the file
> > +descriptor
> > +.IR sfd .
> > +Then, a series of parameters (such as the source of the filesystem) are
> > +provided using
> > +.BR fsconfig (2),
> > +followed by the filesystem instance being created with
> > +.BR FSCONFIG_CMD_CREATE .
> > +.BR fsmount (2)
> > +is then used to create a new mount object attached to the file descriptor
> > +.IR mfd ,
> > +which is then attached to the intended mount point using
> > +.BR move_mount (2).
> > +.P
> > +The above procedure is functionally equivalent to the following mount operation
> > +using
> > +.BR mount (2):
> > +.P
> > +.in +4n
> > +.EX
> > +mount("/dev/sdb1", "/mnt", "ext4", MS_RELATIME,
> > +      "ro,noatime,acl,user_xattr,iversion");
> > +.EE
> > +.in
> > +.P
> > +And here's an example of creating a mount object of an NFS server share and
> > +setting a Smack security module label.
> > +However, instead of mounting it to a place on the filesystem, the program
> > +instead uses the mount object directly to open a file from the NFS share.
> > +.P
> > +.in +4n
> > +.EX
> > +int sfd = fsopen("nfs", 0);
> > +fsconfig(sfd, FSCONFIG_SET_STRING, "source", "example.com/pub/linux", 0);
> > +fsconfig(sfd, FSCONFIG_SET_STRING, "nfsvers", "3", 0);
> > +fsconfig(sfd, FSCONFIG_SET_STRING, "rsize", "65536", 0);
> > +fsconfig(sfd, FSCONFIG_SET_STRING, "wsize", "65536", 0);
> > +fsconfig(sfd, FSCONFIG_SET_STRING, "smackfsdef", "foolabel", 0);
> > +fsconfig(sfd, FSCONFIG_SET_FLAG, "rdma", NULL, 0);
> > +fsconfig(sfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
> > +int mfd = fsmount(sfd, 0, MOUNT_ATTR_NODEV);
> > +int fd = openat(mfd, "src/linux-5.2.tar.xz", O_RDONLY);
> > +.EE
> > +.in
> > +.P
> > +Unlike the previous example, this operation has no trivial equivalent with
> > +.BR mount (2),
> > +as it was not previously possible to create a mount object that is not attached
> > +to any mount point.
> > +.SH SEE ALSO
> > +.BR mount (2),
> > +.BR fsconfig (2),
> > +.BR fsmount (2),
> > +.BR fspick (2),
> > +.BR open_tree (2),
> > +.BR move_mount (2),
> > +.BR mount_setattr (2),
> > +.BR mount_namespaces (7)
> > 
> > -- 
> > 2.50.1
> > 
> 
> -- 
> <https://www.alejandro-colomar.es/>



-- 
Aleksa Sarai
Senior Software Engineer (Containers)
SUSE Linux GmbH
https://www.cyphar.com/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 05/10] fsconfig.2: document 'new' mount api

[Askar Safin]

> and so a parameter that accepts FSCONFIG_SET_FD may not work with FSCONFIG_SET_PATH (or vice-versa).

You probably meant FSCONFIG_SET_PATH_EMPTY here.

Also, when I render this manpage using "man", I see this:

> that the  underlying  file  for  the  file  descriptor  aux  should  be  used  as  the  parameter  value  directly;  FSCON‐
> FIG_SET_PATH_EMPTY  indicates  that  the  underlying file for the file descriptor aux should be re-opened by the filesystem

As you can see, "man" breaks word "FSCONFIG_SET_PATH_EMPTY": "FSCON" appears on one line and "FIG_SET_PATH_EMPTY" on another line.
Can you somehow prevent this? I. e. to prevent breaking of API names. This is very annoying.

> And here is an example of how fspick(2) can be used with fsconfig() to reconfigure the parameters of an existing mount

As well as I understand, you meant filesystem (i. e. superblock) here, not mount. Please, re-read all your manpages and double-check
that you use terms "mount" and "filesystem/superblock" correctly everywhere. As well as I understand, clear separation
between superblocks and mounts was one of original motivations for creating "new" mount API. So, this is very important.

So, it makes sense to write definitions of "filesystem/superblock" and "mount" somewhere (for example, to the top of manpage for
"fsopen") and then to use these terms consistently.

Also, thank you, thank you and again big thank you for this big work! We waited for these manpages for many years!

--
Askar Safin

Re: [PATCH 04/10] fspick.2: document 'new' mount api

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 920 bytes --]

Hi Aleksa,

On Wed, Aug 06, 2025 at 12:46:46PM +1000, Aleksa Sarai wrote:
> > > +.TP
> > > +.B EFAULT
> > > +.I pathname
> > > +is NULL or a pointer to a location outside the calling process's accessible
> > > +address space.
> > 
> > In a lot of places, please use semantic newlines.  See man-pages(7).
> 
> In this particular case, where would you want a newline inserted? I
> do somewhat understand wanting a newline after commas, but I don't see
> which clause you would want to be split. Something like this?
> 
> .B EFAULT
> .I pathname
> is NULL
> or a pointer
> to a location outside the calling process's accessible address space?

I would have done

	.TP
	.B EFAULT
	.I pathname
	is NULL
	or a pointer to a location
	outside the calling process's accessible address space.

Your version isn't bad either.


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 05/10] fsconfig.2: document 'new' mount api

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1264 bytes --]

At 2025-08-06T10:45:03+0300, Askar Safin wrote:
> Also, when I render this manpage using "man", I see this:
> 
> > that the  underlying  file  for  the  file  descriptor  aux  should
> > be  used  as  the  parameter  value  directly;  FSCON‐
> > FIG_SET_PATH_EMPTY  indicates  that  the  underlying file for the
> > file descriptor aux should be re-opened by the filesystem
> 
> As you can see, "man" breaks word "FSCONFIG_SET_PATH_EMPTY": "FSCON"
> appears on one line and "FIG_SET_PATH_EMPTY" on another line.  Can you
> somehow prevent this? I. e. to prevent breaking of API names. This is
> very annoying.

Yes.  Use the `\%` escape sequence to suppress hyphenation.

groff_man_style(7):

     \%        Control hyphenation.  The location of this escape
               sequence within a word marks a hyphenation point,
               supplementing groff’s automatic hyphenation patterns.  At
               the beginning of a word, it suppresses any hyphenation
               breaks within except those specified with \%.

(This is a *roff feature, not a characteristic of the man(7) macro
package; that is why groff_man(7) itself does not document it.)

Thus one might say:

.B \%FSCONFIG_SET_PATH_EMPTY

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 01/10] mount_setattr.2: document glibc >= 2.36 syscall wrappers

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2087 bytes --]

Hi Aleksa,

On Wed, Aug 06, 2025 at 12:55:15PM +1000, Aleksa Sarai wrote:
> > > @@ -10,21 +10,14 @@ Standard C library
> > >  .RI ( libc ,\~ \-lc )
> > >  .SH SYNOPSIS
> > >  .nf
> > > -.BR "#include <linux/fcntl.h>" " /* Definition of " AT_* " constants */"
> > > -.BR "#include <linux/mount.h>" " /* Definition of " MOUNT_ATTR_* " constants */"
> > > -.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
> > > +.B #define _GNU_SOURCE
> > > +.B #include <sys/mount.h>
> > >  .B #include <unistd.h>
> > > +.BR "#include <fcntl.h>" "       /* Definition of " AT_* " constants */"
> > 
> > Please keep the include that provides the function prototype last.
> > 
> > And document with a comment the rationale for including all other
> > headers.
> 
> *All* of the headers? <sys/mount.h> includes both the prototype and
> MOUNT_ATTR_* constants, and most other man pages only include an
> explanation for some of the includes AFAICS.

Not all of them.  The only exception is the header that provides the
prototype; we never comment that one.

So, since this prototype is in <sys/mount.h>, this header should come
last and not have a comment.  But you should add a comment for why we
want <unistd.h>.

> 
> > >  .P
> > > -.BI "int syscall(SYS_mount_setattr, int " dirfd ", const char *" path ,
> > > -.BI "            unsigned int " flags ", struct mount_attr *" attr \
> > > -", size_t " size );
> > > +.BI "int mount_setattr(int " dirfd ", const char *" path ", unsigned int " flags ",
> > > +.BI "                  struct mount_attr *" attr ", size_t " size );
> > 
> > Please use array notation if you can.  Have a look at, for example,
> > strncpy(3), for how it's done in source code.
> 
> "struct mount_attr *attr" is not an array argument, it's an extensible
> struct. mount_setattr(2) already has docs explaining this (in the
> "Extensbility" section, as well as later in DESCRIPTION).

Ahhh, sorry.  So this is a versioning size.  Thanks!


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 03/10] fsopen.2: document 'new' mount api

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 3050 bytes --]

Hi Aleksa,

On Wed, Aug 06, 2025 at 01:05:00PM +1000, Aleksa Sarai wrote:
> > > +.SH SYNOPSIS
> > > +.nf
> > > +.BR "#include <sys/mount.h>"
> > > +.BR "#include <unistd.h>"
> > > +.P
> > > +.BI "int fsopen(const char *" fsname ", unsigned int " flags ");
> > 
> > I tend to not have "name" in the name of parameters that are a string
> > representing a name.  The rationale is that strings very commonly used
> > for names, and so "fs" would be just as menaingful, and shorter.
> > 
> > The description would make it obvious that it's the fs name.
> 
> Personally, as a documentation reader I would find "const char *fs" more
> confusing -- a filesystem-related "open" operation that takes a non-path
> argument is already a little bit fruity, but "fsname" at least provides
> some indication that the string argument is a _name_ rather than a
> _path_. Just having "fs" is less clear IMHO.

Sounds reasonable.  Let's keep it as fsname.

> > > +.BR CAP_SYS_ADMIN
> > 
> > This should be B.  BR is for alternating Bold and Roman (normal).
> 
> Grr, I thought I fixed all of these typos. My bad.

No problem.  :-)

You could run the build system to find some of those for you, BTW.  Let
me know if you have any troubles with it.

> > > +capability in order to create a new filesystem configuration context.
> > > +.P
> > > +After obtaining a filesystem configuration context with
> > > +.BR fsopen (),
> > > +the general workflow for operating on the context looks like the following:
> > > +.RS
> > > +.IP 1. 3
> > 
> > Please have a look at man-pages(7) for some conventions on lists in the
> > project:
> 
> I will admit that I wasn't aware of how detailed (and particular)
> man-pages(7) was about the style guide. I'll read through and adjust the
> patches accordingly. Mea culpa.

No problem.  Most people don't know about it.  :)

> > > +.SH EXAMPLES
> > > +To illustrate the workflow for creating a new mount, the following is a sample
> > > +of how to mount an ext4 filesystem stored on "/dev/sdb1" onto "/mnt".
> > > +.P
> > > +.in +4n
> > > +.EX
> > > +int sfd = fsopen("ext4", FSOPEN_CLOEXEC);
> > 
> > 'sfd' is common for socket file descriptor.  Shouldn't we use fsfd?
> 
> It's not really a "filesystem fd" because there is an in-kernel
> distinction between "filesystem context file descriptors" which are tied
> to superblock lifecycles and "mount object file descriptors" that act
> like a filesystem.
> 
> As such, I'm not sure if "fsfd" is more descriptive in an example. The
> "s" in "sfd" stands for "superblock" and is a fairly common pattern
> userspace users of this API tend to use.

Hmmm, okay.  Then sfd or sbfd sounds reasonable.  Feel free to do what
you think more appropriate here.

> But I'm not too fussed about it, if you really prefer fsfd, I'll swap to
> that.

Nah, if fsfd might be confusing let's not use it.  But maybe if sbfd is
reasonable to you, we could use that.


Cheers,
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 02/10] mount_setattr.2: move mount_attr struct to mount_attr.2type

[Aleksa Sarai]

[-- Attachment #1: Type: text/plain, Size: 7104 bytes --]

On 2025-08-05, Alejandro Colomar <alx@kernel.org> wrote:
> Hi Aleksa,
> 
> On Wed, Aug 06, 2025 at 02:25:47AM +1000, Aleksa Sarai wrote:
> > As with openat2(2type), it makes sense to move this to a separate man
> 
> I guess you meant open_how(2type) instead of openat2(2type).
> 
> 	$ find man/man2type/
> 	man/man2type/
> 	man/man2type/open_how.2type
> 
> > page. In addition, future man pages added in this patchset will want to
> 
> Please use two spaces after period in commit messages.  See:
> 
> $ cat CONTRIBUTING.d/patches/description | grep -A5 Style.guide
>     Style guide
> 	URIs should always be enclosed in <>.
> 
> 	The correct inter-sentence space amount is two.  See some
> 	history about this:
> 	<https://web.archive.org/web/20171217060354/http://www.heracliteanriver.com/?p=324>

I'm really sorry to be difficult, but is this really a necessary
requirement for man-pages submissions?

I understand how much of a stickler you folks are for the formatting of
roff files (though it seems quite arbitrary to me at times), since the
need to maintain ~600k lines of roff is hardly an enviable task (and you
folks do a great job of it!) so spending more time reworking roff
layouts could be seen as a reasonable price of entry for contributors
(even if it results in man page submissions getting abandoned -- which
is IMHO what happened with the first iteration of these pages).

But what practical reason is there to extend minor style guide quirks to
*commit messages*? To me, this seems akin to correcting minor
grammatical mistakes made in commit messages by non-native speakers'
contributions -- but man-pages doesn't do this, right? How many people
are going to read most commit messages, outside of "git blame"? How
often are commit messages typeset?

I didn't grow up using double spaces after periods, so I find it
incredibly strange to do it when writing. I don't mind folks who prefer
it, but to quote the article you linked:

> For any non-typographers who made it all the way through this article,
> if you want to double-space, do it.  If you want to single-space,
> fine.  Just please don’t try to enforce your view on the world.  Stop
> judging people.

I also have ":set nojoinspaces", because otherwise all of my documents
will have mixed double-spacing depending on whether the spaces were
added by "gw" or by hand. (So I would need to manually fix this each
time I re-wrap text.)

I mean, it is just one 0x20 byte at the end of the day, so I'll go ahead
and add it if necessary. I just struggle to see _why_ this is seen as
necessary...

> > reference mount_attr(2type).
> > 
> > Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
> > ---
> >  man/man2/mount_setattr.2      | 16 +++---------
> >  man/man2type/mount_attr.2type | 58 +++++++++++++++++++++++++++++++++++++++++++
> >  2 files changed, 62 insertions(+), 12 deletions(-)
> > 
> > diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2
> > index b8ddc3e22aef..e863be64deb5 100644
> > --- a/man/man2/mount_setattr.2
> > +++ b/man/man2/mount_setattr.2
> > @@ -116,18 +116,10 @@ The
> >  .I attr
> >  argument of
> >  .BR mount_setattr ()
> > -is a structure of the following form:
> > -.P
> > -.in +4n
> > -.EX
> > -struct mount_attr {
> > -    __u64 attr_set;     /* Mount properties to set */
> > -    __u64 attr_clr;     /* Mount properties to clear */
> > -    __u64 propagation;  /* Mount propagation type */
> > -    __u64 userns_fd;    /* User namespace file descriptor */
> > -};
> > -.EE
> > -.in
> > +is a pointer to a
> > +.I mount_attr
> > +structure, described in
> > +.BR mount_attr (2type).
> >  .P
> >  The
> >  .I attr_set
> > diff --git a/man/man2type/mount_attr.2type b/man/man2type/mount_attr.2type
> > new file mode 100644
> > index 000000000000..733dbc3c8cdb
> > --- /dev/null
> > +++ b/man/man2type/mount_attr.2type
> > @@ -0,0 +1,58 @@
> > +
> > +.\" Copyright, the authors of the Linux man-pages project
> > +.\"
> > +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> > +.\"
> > +.TH mount_attr 2type (date) "Linux man-pages (unreleased)"
> > +.SH NAME
> > +mount_attr \- what mount properties to set and clear
> > +.SH LIBRARY
> > +Linux kernel headers
> > +.SH SYNOPSIS
> > +.EX
> > +.B #include <sys/mount.h>
> > +.P
> > +.B struct mount_attr {
> > +.BR "    __u64 attr_set;" "     /* Mount properties to set */"
> > +.BR "    __u64 attr_clr;" "     /* Mount properties to clear */"
> > +.BR "    __u64 propagation;" "  /* Mount propagation type */"
> > +.BR "    __u64 userns_fd;" "    /* User namespace file descriptor */"
> > +    /* ... */
> > +.B };
> > +.EE
> > +.SH DESCRIPTION
> > +Specifies which mount properties should be changed with
> > +.BR mount_setattr (2).
> > +.P
> > +The fields are as follows:
> > +.TP
> > +.I attr_set
> 
> Please use .member syntax.  This is the convention we're using for new
> documentation.  I'll slowly add consistency to the existing docs.  So:
> 
> 	.I .attr_set
> 
> > +This field specifies which
> > +.B MOUNT_ATTR_*
> 
> Please use
> 
> 	.BI MOUNT_ATTR_ *
> 
> The variable part should be in italics.
> 
> > +attribute flags to set.
> > +.TP
> > +.I attr_clr
> > +This fields specifies which
> > +.B MOUNT_ATTR_*
> 
> Same here.
> 
> > +attribute flags to clear.
> > +.TP
> > +.I propagation
> > +This field specifies what mount propagation will be applied.
> > +The valid values of this field are the same propagation types described in
> > +.BR mount_namespaces (7).
> > +.TP
> > +.I userns_fd
> > +This fields specifies a file descriptor that indicates which user namespace to
> > +use as a reference for ID-mapped mounts with
> > +.BR MOUNT_ATTR_IDMAP .
> > +.SH VERSIONS
> > +Extra fields may be appended to the structure, with a zero value in a new field
> 
> Please use semantic newlines.  That is, break after the comma.  See
> man-pages(7):
> 
> $ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
>    Use semantic newlines
>        In the source of a manual page, new sentences should be  started
>        on  new  lines,  long  sentences  should  be split into lines at
>        clause breaks (commas, semicolons, colons, and so on), and  long
>        clauses  should be split at phrase boundaries.  This convention,
>        sometimes known as "semantic newlines", makes it easier  to  see
>        the effect of patches, which often operate at the level of indi‐
>        vidual sentences, clauses, or phrases.
> 
> 
> Have a lovely day!
> Alex
> 
> > +resulting in the kernel behaving as though that extension field was not
> > +present.
> > +Therefore, a user
> > +.I must
> > +zero-fill this structure on initialization.
> > +.SH STANDARDS
> > +Linux.
> > +.SH SEE ALSO
> > +.BR mount_setattr (2)
> > 
> > -- 
> > 2.50.1
> > 
> > 
> 
> -- 
> <https://www.alejandro-colomar.es/>



-- 
Aleksa Sarai
Senior Software Engineer (Containers)
SUSE Linux GmbH
https://www.cyphar.com/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 05/10] fsconfig.2: document 'new' mount api

[Aleksa Sarai]

[-- Attachment #1: Type: text/plain, Size: 4434 bytes --]

On 2025-08-06, Askar Safin <safinaskar@zohomail.com> wrote:
> > and so a parameter that accepts FSCONFIG_SET_FD may not work with FSCONFIG_SET_PATH (or vice-versa).
> 
> You probably meant FSCONFIG_SET_PATH_EMPTY here.

No, in this case I did actually meant FSCONFIG_SET_PATH (or rather
"FSCONFIG_SET_PATH or FSCONFIG_SET_PATH_EMPTY", but that felt too
wordy).

The point being made is that fsparam_fd() parameters are not compatible
with fsparam_path() -- though it turns out nothing in the kernel uses
fsparam_path().

I am working on an update to [1] which will add an fsparam_fd_or_path()
that does what userspace probably expects (and port overlayfs to it),
but most filesystems only accept one type for a parameter argument.

FSCONFIG_SET_PATH_EMPTY is a special case of FSCONFIG_SET_PATH, so I
opted to mention the general case here.

[1]: https://lore.kernel.org/r/20250805-procfs-pidns-api-v4-0-705f984940e7@cyphar.com

> 
> Also, when I render this manpage using "man", I see this:
> 
> > that the  underlying  file  for  the  file  descriptor  aux  should  be  used  as  the  parameter  value  directly;  FSCON‐
> > FIG_SET_PATH_EMPTY  indicates  that  the  underlying file for the file descriptor aux should be re-opened by the filesystem
> 
> As you can see, "man" breaks word "FSCONFIG_SET_PATH_EMPTY": "FSCON" appears on one line and "FIG_SET_PATH_EMPTY" on another line.
> Can you somehow prevent this? I. e. to prevent breaking of API names. This is very annoying.
> 
> > And here is an example of how fspick(2) can be used with fsconfig() to reconfigure the parameters of an existing mount
> 
> As well as I understand, you meant filesystem (i. e. superblock) here, not mount. Please, re-read all your manpages and double-check
> that you use terms "mount" and "filesystem/superblock" correctly everywhere. As well as I understand, clear separation
> between superblocks and mounts was one of original motivations for creating "new" mount API. So, this is very important.
>
> So, it makes sense to write definitions of "filesystem/superblock" and "mount" somewhere (for example, to the top of manpage for
> "fsopen") and then to use these terms consistently.

I intentionally tried to avoid using the term "superblock" as much as
possible, because the term is not generally used nor well understood by
userspace. The kernel terminology for it is even more fraught with
ambiguity because the closest thing approximating common usage of
"superblock" in userspace is the on-disk concept of a "superblock"[2] --
which doesn't make sense to refer to when talking about runtime
filesystem parameters. Kernel developers, of course, are referring to
something completely different -- a _conceptual_ "struct super_block"
that has little to do with the on-disk kind.

If we rely on the term, we would probably need to add a superblock(7) to
describe what a superblock is, which is a much larger documentation
topic than just the "new" mount API. It's not really enough to just
define it at the top of the fsopen(2) man page (as you suggested),
because most of the other man pages would need to cross-reference it.

The compromise I came up with was to use "mount object" when referring
to mounts (read: "struct (vfs)mount"), "filesystem configuration
context" or "filesystem context" when talking about "struct fs_context",
and "filesystem instance" when talking about "struct super". Those
seemed more self-descriptive to me, which would hopefully let me avoid
having to write 3 extra man7 pages. Though to be honest, I'm still not
sure that "filesystem context" is a sufficiently helpful term here, even
with the introductory paragraph in fsopen(2).

In this case, this should probably read "filesystem instance" but that
sounded strange to me when the comparison we use is with mount(2) which
uses the term "mount" for the same operation. I wasn't sure whether to
go with what users are more familiar with in an EXAMPLES section, or to
use the more common words. I guess there's a stronger argument to go
with "filesystem instance" here...

[2]: https://en.wikipedia.org/wiki/Superblock_(file_system)

> Also, thank you, thank you and again big thank you for this big work! We waited for these manpages for many years!
> 
> --
> Askar Safin

-- 
Aleksa Sarai
Senior Software Engineer (Containers)
SUSE Linux GmbH
https://www.cyphar.com/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 02/10] mount_setattr.2: move mount_attr struct to mount_attr.2type

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2906 bytes --]

Hi Aleksa,

On Wed, Aug 06, 2025 at 06:10:36PM +1000, Aleksa Sarai wrote:
> > > page. In addition, future man pages added in this patchset will want to
> > 
> > Please use two spaces after period in commit messages.  See:
> > 
> > $ cat CONTRIBUTING.d/patches/description | grep -A5 Style.guide
> >     Style guide
> > 	URIs should always be enclosed in <>.
> > 
> > 	The correct inter-sentence space amount is two.  See some
> > 	history about this:
> > 	<https://web.archive.org/web/20171217060354/http://www.heracliteanriver.com/?p=324>
> 
> I'm really sorry to be difficult, but is this really a necessary
> requirement for man-pages submissions?

It's not a requirement; it's a nice-to-have.  I'll amend your commits if
something remains.  But if you'll be contributing often, I recommend
doing that yourself.  And in general, I recommend using two spaces after
period, as it results in more readable text.

> I understand how much of a stickler you folks are for the formatting of
> roff files (though it seems quite arbitrary to me at times), since the
> need to maintain ~600k lines of roff is hardly an enviable task (and you
> folks do a great job of it!) so spending more time reworking roff
> layouts could be seen as a reasonable price of entry for contributors
> (even if it results in man page submissions getting abandoned -- which
> is IMHO what happened with the first iteration of these pages).
> 
> But what practical reason is there to extend minor style guide quirks to
> *commit messages*? To me, this seems akin to correcting minor
> grammatical mistakes made in commit messages by non-native speakers'
> contributions -- but man-pages doesn't do this, right? How many people
> are going to read most commit messages, outside of "git blame"? How
> often are commit messages typeset?
> 
> I didn't grow up using double spaces after periods, so I find it
> incredibly strange to do it when writing. I don't mind folks who prefer
> it, but to quote the article you linked:
> 
> > For any non-typographers who made it all the way through this article,
> > if you want to double-space, do it.  If you want to single-space,
> > fine.  Just please don’t try to enforce your view on the world.  Stop
> > judging people.
> 
> I also have ":set nojoinspaces", because otherwise all of my documents
> will have mixed double-spacing depending on whether the spaces were
> added by "gw" or by hand. (So I would need to manually fix this each
> time I re-wrap text.)
> 
> I mean, it is just one 0x20 byte at the end of the day, so I'll go ahead
> and add it if necessary. I just struggle to see _why_ this is seen as
> necessary...

Okay, no problem.  If it's difficult for you, I can amend that while
applying.  I was suggesting it in case it was easy for you.


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 05/10] fsconfig.2: document 'new' mount api

[Aleksa Sarai]

[-- Attachment #1: Type: text/plain, Size: 1962 bytes --]

On 2025-08-06, G. Branden Robinson <g.branden.robinson@gmail.com> wrote:
> At 2025-08-06T10:45:03+0300, Askar Safin wrote:
> > Also, when I render this manpage using "man", I see this:
> > 
> > > that the  underlying  file  for  the  file  descriptor  aux  should
> > > be  used  as  the  parameter  value  directly;  FSCON‐
> > > FIG_SET_PATH_EMPTY  indicates  that  the  underlying file for the
> > > file descriptor aux should be re-opened by the filesystem
> > 
> > As you can see, "man" breaks word "FSCONFIG_SET_PATH_EMPTY": "FSCON"
> > appears on one line and "FIG_SET_PATH_EMPTY" on another line.  Can you
> > somehow prevent this? I. e. to prevent breaking of API names. This is
> > very annoying.
> 
> Yes.  Use the `\%` escape sequence to suppress hyphenation.
> 
> groff_man_style(7):
> 
>      \%        Control hyphenation.  The location of this escape
>                sequence within a word marks a hyphenation point,
>                supplementing groff’s automatic hyphenation patterns.  At
>                the beginning of a word, it suppresses any hyphenation
>                breaks within except those specified with \%.
> 
> (This is a *roff feature, not a characteristic of the man(7) macro
> package; that is why groff_man(7) itself does not document it.)
> 
> Thus one might say:
> 
> .B \%FSCONFIG_SET_PATH_EMPTY

Is there any way of knowing how long an identifier can be before it's
necessary to \%-ify it? I don't know if the man-pages folks will accept
a man page that is just full of \% for every identifier (and there
doesn't appear to be any rule when it comes to existing \% usage).

I guess groff has some typesetting rule that decides whether or not to
do hyphenation, so there probably is a number somewhere, not sure if
it's documented (or guaranteed).

> Regards,
> Branden

-- 
Aleksa Sarai
Senior Software Engineer (Containers)
SUSE Linux GmbH
https://www.cyphar.com/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 02/10] mount_setattr.2: move mount_attr struct to mount_attr.2type

[Aleksa Sarai]

[-- Attachment #1: Type: text/plain, Size: 3713 bytes --]

On 2025-08-06, Alejandro Colomar <alx@kernel.org> wrote:
> Hi Aleksa,
> 
> On Wed, Aug 06, 2025 at 06:10:36PM +1000, Aleksa Sarai wrote:
> > > > page. In addition, future man pages added in this patchset will want to
> > > 
> > > Please use two spaces after period in commit messages.  See:
> > > 
> > > $ cat CONTRIBUTING.d/patches/description | grep -A5 Style.guide
> > >     Style guide
> > > 	URIs should always be enclosed in <>.
> > > 
> > > 	The correct inter-sentence space amount is two.  See some
> > > 	history about this:
> > > 	<https://web.archive.org/web/20171217060354/http://www.heracliteanriver.com/?p=324>
> > 
> > I'm really sorry to be difficult, but is this really a necessary
> > requirement for man-pages submissions?
> 
> It's not a requirement; it's a nice-to-have.  I'll amend your commits if
> something remains.  But if you'll be contributing often, I recommend
> doing that yourself.  And in general, I recommend using two spaces after
> period, as it results in more readable text.

I don't want to add more needless work to your hands -- if you were
going to do it amend my commits manually (which it appears you have done
for my previous contributions), then I'll just do it for you.

I just found this a little perplexing. I also think the readability
thing depends a little on the form of the text (and the reader, of
course) -- for typeset text it does look nicer, but for plain-text I
personally find it distracting. Though, I'm sure you find not having it
distracting instead! ;)

> > I understand how much of a stickler you folks are for the formatting of
> > roff files (though it seems quite arbitrary to me at times), since the
> > need to maintain ~600k lines of roff is hardly an enviable task (and you
> > folks do a great job of it!) so spending more time reworking roff
> > layouts could be seen as a reasonable price of entry for contributors
> > (even if it results in man page submissions getting abandoned -- which
> > is IMHO what happened with the first iteration of these pages).
> > 
> > But what practical reason is there to extend minor style guide quirks to
> > *commit messages*? To me, this seems akin to correcting minor
> > grammatical mistakes made in commit messages by non-native speakers'
> > contributions -- but man-pages doesn't do this, right? How many people
> > are going to read most commit messages, outside of "git blame"? How
> > often are commit messages typeset?
> > 
> > I didn't grow up using double spaces after periods, so I find it
> > incredibly strange to do it when writing. I don't mind folks who prefer
> > it, but to quote the article you linked:
> > 
> > > For any non-typographers who made it all the way through this article,
> > > if you want to double-space, do it.  If you want to single-space,
> > > fine.  Just please don’t try to enforce your view on the world.  Stop
> > > judging people.
> > 
> > I also have ":set nojoinspaces", because otherwise all of my documents
> > will have mixed double-spacing depending on whether the spaces were
> > added by "gw" or by hand. (So I would need to manually fix this each
> > time I re-wrap text.)
> > 
> > I mean, it is just one 0x20 byte at the end of the day, so I'll go ahead
> > and add it if necessary. I just struggle to see _why_ this is seen as
> > necessary...
> 
> Okay, no problem.  If it's difficult for you, I can amend that while
> applying.  I was suggesting it in case it was easy for you.
> 
> 
> Have a lovely day!
> Alex
> 
> -- 
> <https://www.alejandro-colomar.es/>



-- 
Aleksa Sarai
Senior Software Engineer (Containers)
SUSE Linux GmbH
https://www.cyphar.com/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

How and when to control hyphenation (was: [PATCH 05/10] fsconfig.2: document 'new' mount api)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 4640 bytes --]

Hi Aleksa,

At 2025-08-06T18:40:32+1000, Aleksa Sarai wrote:
> On 2025-08-06, G. Branden Robinson <g.branden.robinson@gmail.com> wrote:
> > At 2025-08-06T10:45:03+0300, Askar Safin wrote:
> > > As you can see, "man" breaks word "FSCONFIG_SET_PATH_EMPTY":
> > > "FSCON" appears on one line and "FIG_SET_PATH_EMPTY" on another
> > > line.  Can you somehow prevent this? I. e. to prevent breaking of
> > > API names. This is very annoying.
> > 
> > Yes.  Use the `\%` escape sequence to suppress hyphenation.
[...]
> > Thus one might say:
> > 
> > .B \%FSCONFIG_SET_PATH_EMPTY
> 
> Is there any way of knowing how long an identifier can be before it's
> necessary to \%-ify it?

TL;DR: five letters.[1]

I use the following shell script to aid me while composing pages:

[snip]
$ cat ~/bin/hyphen
#!/bin/sh

: ${HY:=4}

for W
do
    printf ".hy $HY\n.ll 1u\n%s\n" "$W" | nroff -Wbreak | sed '/^$/d' \
        | tr -d '\n'
    echo
done

# vim:set ai et sw=4 ts=4 tw=80:
[end snip]

Long story short, that tells groff to hyphenate as aggressively possible
(within the context of the English hyphenation patterns it uses), and
show every hyphenation point.  Though I'd love to explain exactly how it
works, that'd be off-topic for the linux-man list.

Example:

$ hyphen FSCONFIG_SET_PATH_EMPTY
FS‐CON‐FIG_SET_PATH_EMPTY

> I don't know if the man-pages folks will accept a man page that is
> just full of \% for every identifier (and there doesn't appear to be
> any rule when it comes to existing \% usage).

It's a question of house style.  I tend not to bother suppressing
hyphenation of "lengthy" (> 5 characters) identifiers when:

* the text where the word appears is not being "filled"; or
* I know for sure the word appears at the beginning of an output line.

The latter situation incorporates paragraphs that start with a literal,
and the use of literals as tags of tagged paragraphs (`TP`).

However, some "houses" (projects) might choose to mandate that literals
be protected from hyphenation regardless of position in filled text,
because recasting might move them closer to the right margin.

These are questions of taste and policy, and I'm not situated to tell
the Linux man-pages project what to do; I see my charter, as groff
maintainer, as supporting the satisfactory achievement of desired
formatting.  I do make style recommendations informed by popular English
style manuals and the history of Unix documentary praxis, but I lack a
strong prescription on the present point.

> I guess groff has some typesetting rule that decides whether or not to
> do hyphenation, so there probably is a number somewhere, not sure if
> it's documented (or guaranteed).

The groff_man_style(7) page in recent revisions attempts to teach
basic concepts of typesetting briefly enough to fit on a napkin while
still equipping the document author to predict the formatter's behavior.

   Fundamental concepts
     groff is a programming system for typesetting: we thus often use
     the verb “to set” in the sense “to typeset”.  The formatter
     troff(1) collects words from the input and fills output lines with
     as many as can fit.  Words are separated by spaces and newlines.  A
     transition to a new output line is called a break.  Breaks can
     occur at explicit hyphens, at \% or \: escape sequences (see
     subsection “Portability” below), or at predetermined locations in a
     word if automatic hyphenation is enabled (see the -rHY option in
     section “Options” below).  An output line may be supplemented with
     inter‐sentence space, then potentially adjusted with more space to
     a consistent length (see the -dAD option).  roff(7) details these
     processes.  The formatter prepares output for terminals or for more
     capable typesetters that can change the type size and font family.

(Italics and boldface appear where helpful when the foregoing is
rendered in the terminal.)

I'm intensely interested to hear about any deficiencies that you find in
groff's documentation.

Regards,
Branden

[1] TeX's English hyphenation patterns, which groff uses, assume that
    hyphenation is forbidden within the first two and the last three
    letters of any word: no word of five letters or shorter will be
    _automatically_ hyphenated.

    Explicit hyphens _are_ hyphenation points, as might be seen in
    "can-do attitude" or "ha-ha, green team wins".

    For more, see:
    https://www.gnu.org/software/groff/manual/groff.html.node/Manipulating-Hyphenation.html

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: How and when to control hyphenation (was: [PATCH 05/10] fsconfig.2: document 'new' mount api)

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2198 bytes --]

Hi Branden, Aleksa,

On Wed, Aug 06, 2025 at 04:11:57AM -0500, G. Branden Robinson wrote:
> > Is there any way of knowing how long an identifier can be before it's
> > necessary to \%-ify it?
> 
> TL;DR: five letters.[1]

Good to know.

> I use the following shell script to aid me while composing pages:

[...]

> Example:
> 
> $ hyphen FSCONFIG_SET_PATH_EMPTY
> FS‐CON‐FIG_SET_PATH_EMPTY

While I see the usefulness, I'd find it cumbersome having to ask it
about every identifier I'll be using.

> > I don't know if the man-pages folks will accept a man page that is
> > just full of \% for every identifier (and there doesn't appear to be
> > any rule when it comes to existing \% usage).

I haven't made my mind yet about it.  So far, I err on the side of too
few of these, but I don't reject patches which use it abundantly.

I personally never use it, unless I read the page and find some line
break ugly.  And *never* use it in manual page references (BR), with the
rationale being that we'll eventually replace them with MR, which does
that for us.

The Linux man-pages project now provides a few scripts under ./bin/src/
which distros might be installing (Arch maybe, since it's one of the few
that has packaged the latest releases already).  Among those, there's
diffman-git(1), which you can use to see the changes of your patches to
a manual page.  You can also run the script from the source repository,
of course.  For example:

	$ diffman-git HEAD
	grotty:<standard input>:(<standard input>):9: warning: unrecognized X command 'sgr 0' ignored
	grotty:<standard input>:(<standard input>):9: warning: unrecognized X command 'sgr 0' ignored
	--- HEAD^:man/man2const/PR_GET_TIMING.2const
	+++ HEAD:man/man2const/PR_GET_TIMING.2const
	@@ -10,7 +10,7 @@
		#include <linux/prctl.h>  /* Definition of PR_* constants */
		#include <sys/prctl.h>
	 
	-       int prctl(PR_SET_TIMING);
	+       int prctl(PR_GET_TIMING);
	 
	 DESCRIPTION
		Return which process timing method is currently in use.

(BTW, Branden, why am I seeing those error messages recently?)


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 05/10] fsconfig.2: document 'new' mount api

[Askar Safin]

 ---- On Wed, 06 Aug 2025 12:33:03 +0400  Aleksa Sarai <cyphar@cyphar.com> wrote --- 
 > I intentionally tried to avoid using the term "superblock" as much as
 > possible, because the term is not generally used nor well understood by
 > userspace. The kernel terminology for it is even more fraught with
 > ambiguity because the closest thing approximating common usage of
 > "superblock" in userspace is the on-disk concept of a "superblock"[2] --
 > which doesn't make sense to refer to when talking about runtime
 > filesystem parameters. Kernel developers, of course, are referring to
 > something completely different -- a _conceptual_ "struct super_block"
 > that has little to do with the on-disk kind.
 > 
 > If we rely on the term, we would probably need to add a superblock(7) to
 > describe what a superblock is, which is a much larger documentation
 > topic than just the "new" mount API. It's not really enough to just
 > define it at the top of the fsopen(2) man page (as you suggested),
 > because most of the other man pages would need to cross-reference it.
 > 
 > The compromise I came up with was to use "mount object" when referring
 > to mounts (read: "struct (vfs)mount"), "filesystem configuration
 > context" or "filesystem context" when talking about "struct fs_context",
 > and "filesystem instance" when talking about "struct super". Those
 > seemed more self-descriptive to me, which would hopefully let me avoid
 > having to write 3 extra man7 pages. Though to be honest, I'm still not
 > sure that "filesystem context" is a sufficiently helpful term here, even
 > with the introductory paragraph in fsopen(2).

I agree.

 > In this case, this should probably read "filesystem instance" but that
 > sounded strange to me when the comparison we use is with mount(2) which
 > uses the term "mount" for the same operation. I wasn't sure whether to
 > go with what users are more familiar with in an EXAMPLES section, or to
 > use the more common words. I guess there's a stronger argument to go
 > with "filesystem instance" here...

I still think that "parameters of an existing mount" should be changed to
"parameters of an existing filesystem instance". Yes, I agree that no major changes
should be done to manpages, but I kindly ask you fix this particular sentence.
I still think that difference between mount and filesystem instance is important.
Also, if mount(2) manpage confuses these terms, then it should be changed, too.
(Of course, this doesn't mean that you should change it. I just mean that somebody
should change it.)

--
Askar Safin
https://types.pl/@safinaskar

Re: [PATCH 06/10] fsmount.2: document 'new' mount api

[Askar Safin]

> The resultant file descriptor acts the same as one produced by open(2) with O_PATH,
> meaning it can also be used as a dirfd argument to other "*at()" system calls.

This may be interpreted by somebody that fsmount returns exactly same fd as open(2) with O_PATH returns.
This is not true, because, for example, you can use move_mount with fd, returned by fsmount,
but cannot use move_mount with fd, returned by open with O_PATH.

So, please replace "acts the same as one" with "can be used as one" or something.

Also, please, replace 'to other "*at()"' with 'to "*at()"'. No at-syscalls were
mentioned in this paragraph before, so "other" is not needed here.

> /* Create a new file without attaching the mount object. */
> int tmpfd = openat(sfd, "tmpfile", O_CREAT | O_EXCL | O_RDWR, 0600);
> unlinkat(sfd, "tmpfile", 0);

You meant mfd here, not sfd.

--
Askar Safin

Re: How and when to control hyphenation (was: [PATCH 05/10] fsconfig.2: document 'new' mount api)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 3670 bytes --]

Hi Alex,

At 2025-08-06T13:45:46+0200, Alejandro Colomar wrote:
> > > Is there any way of knowing how long an identifier can be before it's
> > > necessary to \%-ify it?
> > 
> > TL;DR: five letters.[1]
[...]
> > Example:
> > 
> > $ hyphen FSCONFIG_SET_PATH_EMPTY
> > FS‐CON‐FIG_SET_PATH_EMPTY
> 
> While I see the usefulness, I'd find it cumbersome having to ask it
> about every identifier I'll be using.

I find myself having to ask relatively seldom.  Most of us can subitize
a word such that we discern whether its more than five letters.  And
erring by prefixing an (automatically) unhyphenable word of any length
does no harm to document correctness or rendering.

A more likely source of error is forgetting what *roff considers a word.

Here's an example that's bitten me.

[snip]
commit 2c5853ec5afbc4d58c320457083aa6eaa9d046e9
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sat Jun 8 04:08:55 2024 -0500

    man/curs_inopts.3x: Fix markup error.

    Use of `\%` as a hyphenation suppressor _must_ come at the beginning of
    a word.

diff --git a/man/curs_inopts.3x b/man/curs_inopts.3x
index b69165d39..77b1777f4 100644
--- a/man/curs_inopts.3x
+++ b/man/curs_inopts.3x
@@ -562,9 +562,9 @@ .SH NOTES
 (\*(``cooked\*('') mode from raw and cbreak modes,
 respectively.
 Mixing
-.BR raw / \%noraw
+.BR \%raw / noraw
 calls with
-.BR cbreak / \%nocbreak
+.BR \%cbreak / nocbreak
 calls leads to terminal driver control states that are hard to predict
 or understand;
 doing so is not recommended.
[end snip]

McIlroy's original man(7) implementation could have been more helpful in
marking code literals.  On the other hand, linkers of the day tended to
restrict your externally visible symbols to six characters at most.

If I went to the Temple of Unix at Murray Hill, New Jersey to petition
the giant enthroned statue of Ken Thompson for divine aid, a booming
voice would laugh and mock the folly of mortals in selecting identifier
names that were longer than five characters in the first place.

That's enough for `creat`, `vflag`, and `swtch`...what more do you need?

:-|

> I personally never use it, unless I read the page and find some line
> break ugly.  And *never* use it in manual page references (BR), with the
> rationale being that we'll eventually replace them with MR, which does
> that for us.

I haven't forgotten about my series of sed scripts to rewrite (mainly)
syscalls(2).

> 	grotty:<standard input>:(<standard input>):9: warning: unrecognized X command 'sgr 0' ignored
> 	grotty:<standard input>:(<standard input>):9: warning: unrecognized X command 'sgr 0' ignored
> 
> (BTW, Branden, why am I seeing those error messages recently?)

Did you change distributions recently?  The messages are an artifact of
a downstream patch to groff to force Teletype-style overstriking.  Over
the past two years, distributors that had it in have been taking it out.

https://git.alpinelinux.org/aports/commit/?id=d6fe59c946066adef3e19e75f1e7caffda5a4cd1
https://gitlab.archlinux.org/archlinux/packaging/packages/groff/-/commit/025a63b7e55a24c0a1892045819eef79fdc67873

https://metadata.ftp-master.debian.org/changelogs//main/g/groff/groff_1.23.0-9_changelog
  * Adopt upstream's use of SGR escape sequences for man/mdoc (LP: #610609).
    I turned these off for Debian in 2002 because pagers didn't cope well at
    the time, but it's now 21 years later and things have changed; SGR
    escape sequences resolve some ambiguity (see #963490) and are required
    for new features such as clickable hyperlinks.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 06/10] fsmount.2: document 'new' mount api

[Aleksa Sarai]

[-- Attachment #1: Type: text/plain, Size: 2000 bytes --]

On 2025-08-06, Askar Safin <safinaskar@zohomail.com> wrote:
> > The resultant file descriptor acts the same as one produced by open(2) with O_PATH,
> > meaning it can also be used as a dirfd argument to other "*at()" system calls.
> 
> This may be interpreted by somebody that fsmount returns exactly same fd as open(2) with O_PATH returns.
> This is not true, because, for example, you can use move_mount with fd, returned by fsmount,
> but cannot use move_mount with fd, returned by open with O_PATH.
> 
> So, please replace "acts the same as one" with "can be used as one" or something.

Well, the slightly odd thing is that technically it _is_ just an O_PATH
file descriptor (ditto for open_tree(2), even with OPEN_TREE_CLONE) --
they are constructed with dentry_open(O_PATH). You can also use regular
file descriptors with move_mount(2) to move around (attached) mount
objects.

The only thing that is special about fsmount(2) and OPEN_TREE_CLONE file
descriptors is that they are the root of a mount *in an anonymous mount
namespace* and the mount infrastructure has special handling for that
(on close(2) the mount gets unmounted because of FMODE_NEED_UNMOUNT, and
move_mount(2) permits cross-namespace mounts but only for anonymous
mount namespaces).

I am not sure what is the best way of expressing this -- "can be used
as" doesn't quite convey the fact that they really are almost identical.
(Also, I guess you'd like the text in open_tree(2) to also be adjusted.)

> Also, please, replace 'to other "*at()"' with 'to "*at()"'. No at-syscalls were
> mentioned in this paragraph before, so "other" is not needed here.

Fair enough.

> > /* Create a new file without attaching the mount object. */
> > int tmpfd = openat(sfd, "tmpfile", O_CREAT | O_EXCL | O_RDWR, 0600);
> > unlinkat(sfd, "tmpfile", 0);
> 
> You meant mfd here, not sfd.

:facepalm:

-- 
Aleksa Sarai
Senior Software Engineer (Containers)
SUSE Linux GmbH
https://www.cyphar.com/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: How and when to control hyphenation (was: [PATCH 05/10] fsconfig.2: document 'new' mount api)

[Askar Safin]

 ---- On Wed, 06 Aug 2025 15:45:46 +0400  Alejandro Colomar <alx@kernel.org> wrote --- 
> I personally never use it, unless I read the page and find some line
> break ugly.  And *never* use it in manual page references (BR), with the
> rationale being that we'll eventually replace them with MR, which does
> that for us.

Aaaaaaah! I hate all these quirks. I hate all these roff quirks, mentioned in this thread.

It seems we did not get manpages for "new" mount API earlier, because Brauner gave up on roff.
He said: "Years of writing groff have made me tired" here: https://github.com/brauner/man-pages-md .

So I propose to convert manpages to some other format. For example, to reStructuredText.
This is what kernel uses. This will help attract kernel developers. So, please, convert.
At least mans in man2. reStructuredText can be converted to roff: https://docutils.sourceforge.io/docs/user/manpage.html .

--
Askar Safin
https://types.pl/@safinaskar

Re: How and when to control hyphenation (was: [PATCH 05/10] fsconfig.2: document 'new' mount api)

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2561 bytes --]

[CC trimmed]

Hi Branden,

On Wed, Aug 06, 2025 at 09:01:12AM -0500, G. Branden Robinson wrote:
> If I went to the Temple of Unix at Murray Hill, New Jersey to petition
> the giant enthroned statue of Ken Thompson for divine aid, a booming
> voice would laugh and mock the folly of mortals in selecting identifier
> names that were longer than five characters in the first place.

Funny thing: I'm proposing many string APIs for standardization in C2y:

	streq, wcseq, strpfx, stppfx, strsfx, stpsfx, wcspfx, wcppfx,
	wcssfx, wcpsfx, aprintf, awprintf, stpsep, wcpsep, stpspn,
	stpcspn, wcpspn, wcpcspn

> That's enough for `creat`, `vflag`, and `swtch`...what more do you need?

Oh, I need some more.  :)

> :-|
> 
> > I personally never use it, unless I read the page and find some line
> > break ugly.  And *never* use it in manual page references (BR), with the
> > rationale being that we'll eventually replace them with MR, which does
> > that for us.
> 
> I haven't forgotten about my series of sed scripts to rewrite (mainly)
> syscalls(2).
> 
> > 	grotty:<standard input>:(<standard input>):9: warning: unrecognized X command 'sgr 0' ignored
> > 	grotty:<standard input>:(<standard input>):9: warning: unrecognized X command 'sgr 0' ignored
> > 
> > (BTW, Branden, why am I seeing those error messages recently?)
> 
> Did you change distributions recently?  The messages are an artifact of
> a downstream patch to groff to force Teletype-style overstriking.  Over
> the past two years, distributors that had it in have been taking it out.

I'm using Debian Sid on my laptop (because Devuan doesn't work well in
my Framework laptop), and Devuan Ceres on my desktop.  So yes, I get any
updates that the Debian maintainers decide to change as soon as they
change them.

> https://git.alpinelinux.org/aports/commit/?id=d6fe59c946066adef3e19e75f1e7caffda5a4cd1
> https://gitlab.archlinux.org/archlinux/packaging/packages/groff/-/commit/025a63b7e55a24c0a1892045819eef79fdc67873
> 
> https://metadata.ftp-master.debian.org/changelogs//main/g/groff/groff_1.23.0-9_changelog
>   * Adopt upstream's use of SGR escape sequences for man/mdoc (LP: #610609).
>     I turned these off for Debian in 2002 because pagers didn't cope well at
>     the time, but it's now 21 years later and things have changed; SGR
>     escape sequences resolve some ambiguity (see #963490) and are required
>     for new features such as clickable hyperlinks.

Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: How and when to control hyphenation (was: [PATCH 05/10] fsconfig.2: document 'new' mount api)

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1680 bytes --]

Hi Askar,

On Wed, Aug 06, 2025 at 06:29:40PM +0400, Askar Safin wrote:
>  ---- On Wed, 06 Aug 2025 15:45:46 +0400  Alejandro Colomar <alx@kernel.org> wrote --- 
> > I personally never use it, unless I read the page and find some line
> > break ugly.  And *never* use it in manual page references (BR), with the
> > rationale being that we'll eventually replace them with MR, which does
> > that for us.
> 
> Aaaaaaah! I hate all these quirks. I hate all these roff quirks, mentioned in this thread.
> 
> It seems we did not get manpages for "new" mount API earlier, because Brauner gave up on roff.
> He said: "Years of writing groff have made me tired" here: https://github.com/brauner/man-pages-md .
> 
> So I propose to convert manpages to some other format. For example, to reStructuredText.
> This is what kernel uses. This will help attract kernel developers. So, please, convert.
> At least mans in man2. reStructuredText can be converted to roff: https://docutils.sourceforge.io/docs/user/manpage.html .

No, I will not change from man(7) to RST.

Does rst have no quircks at all?  It probably has them too, somewhere.
What I can do for you is try to make the existing source more
consistent, so that someone can easily write new quality man(7) code
just by imitation.  This is what I've been doing in the last 5 years.

I've also worked on a build system that will help you with diagnostics
if you make mistakes.  Please run 'make -R help' to see what it has to
offer.  'make -R lint-man' is the most obvious thing one should run to
verify their manual-page patches.


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: How and when to control hyphenation (was: [PATCH 05/10] fsconfig.2: document 'new' mount api)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1347 bytes --]

Hi Alex,

At 2025-08-06T16:55:02+0200, Alejandro Colomar wrote:
> > Did you change distributions recently?  The messages are an artifact
> > of a downstream patch to groff to force Teletype-style overstriking.
> > Over the past two years, distributors that had it in have been
> > taking it out.
> 
> I'm using Debian Sid on my laptop (because Devuan doesn't work well in
> my Framework laptop), and Devuan Ceres on my desktop.  So yes, I get
> any updates that the Debian maintainers decide to change as soon as
> they change them.

Colin Watson changed the item in question over 2 years ago.

https://salsa.debian.org/debian/groff/-/commit/f0a34f20ff772f692255b7e32a05630c639f75a8

However, since /etc/groff/{man,mdoc}.local are what Debian terms
"conffiles", their contents can get stale, sometimes through human error
but in my years as X Window System package maintainer I never quite
managed to convince myself that dpkg's conffile change detector couldn't
be fooled.

You might:
* Verify that a recent version of groff is in fact installed.

  Among other things, this commit history is indicative of package
  releases.

  https://salsa.debian.org/debian/groff/-/commits/master?ref_type=HEADS

* Purge and reinstall the groff package if the version available
  "should" be new enough.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: How and when to control hyphenation (was: [PATCH 05/10] fsconfig.2: document 'new' mount api)

[Aleksa Sarai]

[-- Attachment #1: Type: text/plain, Size: 972 bytes --]

On 2025-08-06, Alejandro Colomar <alx@kernel.org> wrote:
> I've also worked on a build system that will help you with diagnostics
> if you make mistakes.  Please run 'make -R help' to see what it has to
> offer.  'make -R lint-man' is the most obvious thing one should run to
> verify their manual-page patches.

Maybe it's just me, but I was confused by the output of "make -R help".
It wasn't clear to me the first few times I read it that the output is
telling me to run

  $ make -R -p nothing \
          | grep '^\.PHONY:' \
          | tr ' ' '\n' \
          | grep -v '^\.PHONY:' \
          | sort;

in order to get a list of make targets (and is actually a generic way of
getting a list of make targets). Would it be possible for "make -R help"
to have a pre-defined list of the most common commands to run, like the
kernel makefile does?

-- 
Aleksa Sarai
Senior Software Engineer (Containers)
SUSE Linux GmbH
https://www.cyphar.com/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 02/10] mount_setattr.2: move mount_attr struct to mount_attr.2type

[Aleksa Sarai]

[-- Attachment #1: Type: text/plain, Size: 684 bytes --]

On 2025-08-05, Alejandro Colomar <alx@kernel.org> wrote:
> > +This field specifies which
> > +.B MOUNT_ATTR_*
> 
> Please use
> 
> 	.BI MOUNT_ATTR_ *
> 
> The variable part should be in italics.

I have changed this, but I took a quick look and it seems that

  .B FOO_*

usage far outweighs

  .BI FOO_ *

usage in the repo (before these patches, the latter is only used in 5
man pages). I guess this is still being worked on?

> > +attribute flags to set.
> > +.TP
> > +.I attr_clr
> > +This fields specifies which
> > +.B MOUNT_ATTR_*
> 
> Same here.

-- 
Aleksa Sarai
Senior Software Engineer (Containers)
SUSE Linux GmbH
https://www.cyphar.com/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: How and when to control hyphenation (was: [PATCH 05/10] fsconfig.2: document 'new' mount api)

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 4368 bytes --]

Hi Aleksa,

On Thu, Aug 07, 2025 at 01:56:03AM +1000, Aleksa Sarai wrote:
> On 2025-08-06, Alejandro Colomar <alx@kernel.org> wrote:
> > I've also worked on a build system that will help you with diagnostics
> > if you make mistakes.  Please run 'make -R help' to see what it has to
> > offer.  'make -R lint-man' is the most obvious thing one should run to
> > verify their manual-page patches.
> 
> Maybe it's just me, but I was confused by the output of "make -R help".
> It wasn't clear to me the first few times I read it that the output is
> telling me to run
> 
>   $ make -R -p nothing \
>           | grep '^\.PHONY:' \
>           | tr ' ' '\n' \
>           | grep -v '^\.PHONY:' \
>           | sort;
> 
> in order to get a list of make targets (and is actually a generic way of
> getting a list of make targets).

Yup; if you add a 'nothing' target to any Makefile, this should work
(if they use .PHONY correctly).  (I just tried it with the Linux
Makefile just to see, and it did a good job.  The names of the targets
are a bit weird, and I don't know what most of them are for, but at
least we can list them.)

I developed that script when I got tired of updating the hard-coded
help, as it always got out of sync with the real Makefile.  :)

> Would it be possible for "make -R help"
> to have a pre-defined list of the most common commands to run, like the
> kernel makefile does?

Yep, I could list and explain these:

	all
	build
	build-all
	check
	clean
	dist
	distcheck
	help
	install
	install-all
	lint
	nothing
	uninstall

And tell the user to run the command for the complete list.
Sounds reasonable to me.

How about this?

	diff --git i/GNUmakefile w/GNUmakefile
	index 9530a66f5..e1cc44bbb 100644
	--- i/GNUmakefile
	+++ w/GNUmakefile
	@@ -46,7 +46,22 @@ nothing:;
	 
	 .PHONY: help
	 help:
	-       $(info  $(INFO_)To see a list of targets, run:)
	+       $(info  $(INFO_)Common targets:)
	+       $(info  $(INFO_)        all             Synonym of 'build')
	+       $(info  $(INFO_)        build           Build the usual stuff)
	+       $(info  $(INFO_)        build-all       Build everything)
	+       $(info  $(INFO_)        check           Check the results of the build)
	+       $(info  $(INFO_)        clean           Remove all temporary files)
	+       $(info  $(INFO_)        dist            Produce the release tarball)
	+       $(info  $(INFO_)        distcheck       Check the release tarball)
	+       $(info  $(INFO_)        help            Print this help)
	+       $(info  $(INFO_)        install         Install the usual stuff)
	+       $(info  $(INFO_)        install-all     Install everything)
	+       $(info  $(INFO_)        lint            Lint the source code)
	+       $(info  $(INFO_)        nothing         Do nothing; useful for debugging)
	+       $(info  $(INFO_)        uninstall       Uninstall everything (might leave traces))
	+       $(info  )
	+       $(info  $(INFO_)To see the full list of targets, run:)
		$(info  $(INFO_)        $$ make -R -p nothing \)
		$(info  $(INFO_)        | grep '^\.PHONY:' \)
		$(info  $(INFO_)        | tr ' ' '\n' \)

Here's the output:

	$ make -R help
	Common targets:
		all		Synonym of 'build'
		build		Build the usual stuff
		build-all	Build everything
		check		Check the results of the build
		clean		Remove all temporary files
		dist		Produce the release tarball
		distcheck	Check the release tarball
		help		Print this help
		install		Install the usual stuff
		install-all	Install everything
		lint		Lint the source code
		nothing		Do nothing; useful for debugging
		uninstall	Uninstall everything (might leave traces)

	To see the full list of targets, run:
		$ make -R -p nothing \
		| grep '^\.PHONY:' \
		| tr ' ' '\n' \
		| grep -v '^\.PHONY:' \
		| sort;

	To see a list of variables, run:
		$ find GNUmakefile share/mk/configure -type f \
		| sort \
		| xargs grep '^[^[:space:]].*=' \
		| sed 's/=.*/=/' \
		| grep -v -e ':DEFAULT_.*=' -e ':MAKEFILE_.*INCLUDED :=';

	To see a list of dependencies (package/program), run:
		$ find share/mk/configure/build-depends -type f \
		| sed 's,share/mk/configure/build-depends/,,' \
		| sed 's,\.mk,,' \
		| sort;


Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 02/10] mount_setattr.2: move mount_attr struct to mount_attr.2type

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 931 bytes --]

Hi Aleksa,

On Thu, Aug 07, 2025 at 01:58:47AM +1000, Aleksa Sarai wrote:
> On 2025-08-05, Alejandro Colomar <alx@kernel.org> wrote:
> > > +This field specifies which
> > > +.B MOUNT_ATTR_*
> > 
> > Please use
> > 
> > 	.BI MOUNT_ATTR_ *
> > 
> > The variable part should be in italics.
> 
> I have changed this, but I took a quick look and it seems that
> 
>   .B FOO_*
> 
> usage far outweighs
> 
>   .BI FOO_ *
> 
> usage in the repo (before these patches, the latter is only used in 5
> man pages). I guess this is still being worked on?

Yup, I'm working on that.  :)


Cheers,
Alex

> 
> > > +attribute flags to set.
> > > +.TP
> > > +.I attr_clr
> > > +This fields specifies which
> > > +.B MOUNT_ATTR_*
> > 
> > Same here.
> 
> -- 
> Aleksa Sarai
> Senior Software Engineer (Containers)
> SUSE Linux GmbH
> https://www.cyphar.com/



-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: How and when to control hyphenation (was: [PATCH 05/10] fsconfig.2: document 'new' mount api)

[Aleksa Sarai]

[-- Attachment #1: Type: text/plain, Size: 4795 bytes --]

On 2025-08-06, Alejandro Colomar <alx@kernel.org> wrote:
> Hi Aleksa,
> 
> On Thu, Aug 07, 2025 at 01:56:03AM +1000, Aleksa Sarai wrote:
> > On 2025-08-06, Alejandro Colomar <alx@kernel.org> wrote:
> > > I've also worked on a build system that will help you with diagnostics
> > > if you make mistakes.  Please run 'make -R help' to see what it has to
> > > offer.  'make -R lint-man' is the most obvious thing one should run to
> > > verify their manual-page patches.
> > 
> > Maybe it's just me, but I was confused by the output of "make -R help".
> > It wasn't clear to me the first few times I read it that the output is
> > telling me to run
> > 
> >   $ make -R -p nothing \
> >           | grep '^\.PHONY:' \
> >           | tr ' ' '\n' \
> >           | grep -v '^\.PHONY:' \
> >           | sort;
> > 
> > in order to get a list of make targets (and is actually a generic way of
> > getting a list of make targets).
> 
> Yup; if you add a 'nothing' target to any Makefile, this should work
> (if they use .PHONY correctly).  (I just tried it with the Linux
> Makefile just to see, and it did a good job.  The names of the targets
> are a bit weird, and I don't know what most of them are for, but at
> least we can list them.)
> 
> I developed that script when I got tired of updating the hard-coded
> help, as it always got out of sync with the real Makefile.  :)

I'll definitely keep this "make -p" pipeline as a neat tool in my
toolbelt.

> > Would it be possible for "make -R help"
> > to have a pre-defined list of the most common commands to run, like the
> > kernel makefile does?
> 
> Yep, I could list and explain these:
> 
> 	all
> 	build
> 	build-all
> 	check
> 	clean
> 	dist
> 	distcheck
> 	help
> 	install
> 	install-all
> 	lint
> 	nothing
> 	uninstall
> 
> And tell the user to run the command for the complete list.
> Sounds reasonable to me.
> 
> How about this?
> 
> 	diff --git i/GNUmakefile w/GNUmakefile
> 	index 9530a66f5..e1cc44bbb 100644
> 	--- i/GNUmakefile
> 	+++ w/GNUmakefile
> 	@@ -46,7 +46,22 @@ nothing:;
> 	 
> 	 .PHONY: help
> 	 help:
> 	-       $(info  $(INFO_)To see a list of targets, run:)
> 	+       $(info  $(INFO_)Common targets:)
> 	+       $(info  $(INFO_)        all             Synonym of 'build')
> 	+       $(info  $(INFO_)        build           Build the usual stuff)
> 	+       $(info  $(INFO_)        build-all       Build everything)
> 	+       $(info  $(INFO_)        check           Check the results of the build)
> 	+       $(info  $(INFO_)        clean           Remove all temporary files)
> 	+       $(info  $(INFO_)        dist            Produce the release tarball)
> 	+       $(info  $(INFO_)        distcheck       Check the release tarball)
> 	+       $(info  $(INFO_)        help            Print this help)
> 	+       $(info  $(INFO_)        install         Install the usual stuff)
> 	+       $(info  $(INFO_)        install-all     Install everything)
> 	+       $(info  $(INFO_)        lint            Lint the source code)
> 	+       $(info  $(INFO_)        nothing         Do nothing; useful for debugging)
> 	+       $(info  $(INFO_)        uninstall       Uninstall everything (might leave traces))
> 	+       $(info  )
> 	+       $(info  $(INFO_)To see the full list of targets, run:)
> 		$(info  $(INFO_)        $$ make -R -p nothing \)
> 		$(info  $(INFO_)        | grep '^\.PHONY:' \)
> 		$(info  $(INFO_)        | tr ' ' '\n' \)
> 
> Here's the output:
> 
> 	$ make -R help
> 	Common targets:
> 		all		Synonym of 'build'
> 		build		Build the usual stuff
> 		build-all	Build everything
> 		check		Check the results of the build
> 		clean		Remove all temporary files
> 		dist		Produce the release tarball
> 		distcheck	Check the release tarball
> 		help		Print this help
> 		install		Install the usual stuff
> 		install-all	Install everything
> 		lint		Lint the source code
> 		nothing		Do nothing; useful for debugging
> 		uninstall	Uninstall everything (might leave traces)
> 
> 	To see the full list of targets, run:
> 		$ make -R -p nothing \
> 		| grep '^\.PHONY:' \
> 		| tr ' ' '\n' \
> 		| grep -v '^\.PHONY:' \
> 		| sort;
> 
> 	To see a list of variables, run:
> 		$ find GNUmakefile share/mk/configure -type f \
> 		| sort \
> 		| xargs grep '^[^[:space:]].*=' \
> 		| sed 's/=.*/=/' \
> 		| grep -v -e ':DEFAULT_.*=' -e ':MAKEFILE_.*INCLUDED :=';
> 
> 	To see a list of dependencies (package/program), run:
> 		$ find share/mk/configure/build-depends -type f \
> 		| sed 's,share/mk/configure/build-depends/,,' \
> 		| sed 's,\.mk,,' \
> 		| sort;

Looks good to me!

-- 
Aleksa Sarai
Senior Software Engineer (Containers)
SUSE Linux GmbH
https://www.cyphar.com/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: How and when to control hyphenation (was: [PATCH 05/10] fsconfig.2: document 'new' mount api)

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1763 bytes --]

On Thu, Aug 07, 2025 at 12:14:00PM +1000, Aleksa Sarai wrote:
> > I developed that script when I got tired of updating the hard-coded
> > help, as it always got out of sync with the real Makefile.  :)
> 
> I'll definitely keep this "make -p" pipeline as a neat tool in my
> toolbelt.

Thanks!  :-)

> > 	$ make -R help
> > 	Common targets:
> > 		all		Synonym of 'build'
> > 		build		Build the usual stuff
> > 		build-all	Build everything
> > 		check		Check the results of the build
> > 		clean		Remove all temporary files
> > 		dist		Produce the release tarball
> > 		distcheck	Check the release tarball
> > 		help		Print this help
> > 		install		Install the usual stuff
> > 		install-all	Install everything
> > 		lint		Lint the source code
> > 		nothing		Do nothing; useful for debugging
> > 		uninstall	Uninstall everything (might leave traces)
> > 
> > 	To see the full list of targets, run:
> > 		$ make -R -p nothing \
> > 		| grep '^\.PHONY:' \
> > 		| tr ' ' '\n' \
> > 		| grep -v '^\.PHONY:' \
> > 		| sort;
> > 
> > 	To see a list of variables, run:
> > 		$ find GNUmakefile share/mk/configure -type f \
> > 		| sort \
> > 		| xargs grep '^[^[:space:]].*=' \
> > 		| sed 's/=.*/=/' \
> > 		| grep -v -e ':DEFAULT_.*=' -e ':MAKEFILE_.*INCLUDED :=';
> > 
> > 	To see a list of dependencies (package/program), run:
> > 		$ find share/mk/configure/build-depends -type f \
> > 		| sed 's,share/mk/configure/build-depends/,,' \
> > 		| sed 's,\.mk,,' \
> > 		| sort;
> 
> Looks good to me!

Thanks!  I've pushed a commit:
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=b67ac0da88ed90f767f89b8eadfae960b7c2230f>


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: How and when to control hyphenation (was: [PATCH 05/10] fsconfig.2: document 'new' mount api)

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1580 bytes --]

Hi Branden,

On Wed, Aug 06, 2025 at 10:26:18AM -0500, G. Branden Robinson wrote:
> At 2025-08-06T16:55:02+0200, Alejandro Colomar wrote:
> > > Did you change distributions recently?  The messages are an artifact
> > > of a downstream patch to groff to force Teletype-style overstriking.
> > > Over the past two years, distributors that had it in have been
> > > taking it out.
> > 
> > I'm using Debian Sid on my laptop (because Devuan doesn't work well in
> > my Framework laptop), and Devuan Ceres on my desktop.  So yes, I get
> > any updates that the Debian maintainers decide to change as soon as
> > they change them.
> 
> Colin Watson changed the item in question over 2 years ago.
> 
> https://salsa.debian.org/debian/groff/-/commit/f0a34f20ff772f692255b7e32a05630c639f75a8
> 
> However, since /etc/groff/{man,mdoc}.local are what Debian terms
> "conffiles", their contents can get stale, sometimes through human error
> but in my years as X Window System package maintainer I never quite
> managed to convince myself that dpkg's conffile change detector couldn't
> be fooled.
> 
> You might:
> * Verify that a recent version of groff is in fact installed.
> 
>   Among other things, this commit history is indicative of package
>   releases.
> 
>   https://salsa.debian.org/debian/groff/-/commits/master?ref_type=HEADS
> 
> * Purge and reinstall the groff package if the version available
>   "should" be new enough.

Thanks!  Purging and reinstalling worked.


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]