Message-ID: <y77zyujsduf5furdf2biphuszil63kftb44cs74ed2d2hf2gdr@hci7mzt6yh7b>
Date: Sun, 21 Sep 2025 10:53:05 +0200
From: Alejandro Colomar <alx@...nel.org>
To: Aleksa Sarai <cyphar@...har.com>
Cc: "Michael T. Kerrisk" <mtk.manpages@...il.com>, 
	Alexander Viro <viro@...iv.linux.org.uk>, Jan Kara <jack@...e.cz>, Askar Safin <safinaskar@...omail.com>, 
	"G. Branden Robinson" <g.branden.robinson@...il.com>, linux-man@...r.kernel.org, linux-api@...r.kernel.org, 
	linux-fsdevel@...r.kernel.org, linux-kernel@...r.kernel.org, 
	David Howells <dhowells@...hat.com>, Christian Brauner <brauner@...nel.org>
Subject: Re: [PATCH v4 03/10] man/man2/fspick.2: document "new" mount API

Hi Aleksa,

On Fri, Sep 19, 2025 at 11:59:44AM +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-authored-by: David Howells <dhowells@...hat.com>
> Signed-off-by: David Howells <dhowells@...hat.com>
> Co-authored-by: Christian Brauner <brauner@...nel.org>
> Signed-off-by: Christian Brauner <brauner@...nel.org>
> Signed-off-by: Aleksa Sarai <cyphar@...har.com>
> ---
>  man/man2/fspick.2 | 342 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 342 insertions(+)
> 
> diff --git a/man/man2/fspick.2 b/man/man2/fspick.2
> new file mode 100644
> index 0000000000000000000000000000000000000000..1f87293f44658adeb7ab7cffebcac3174888f040
> --- /dev/null
> +++ b/man/man2/fspick.2
> @@ -0,0 +1,342 @@
> +.\" 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
> +.BR "#include <fcntl.h>" "          /* Definition of " AT_* " constants */"
> +.B #include <sys/mount.h>
> +.P
> +.BI "int fspick(int " dirfd ", const char *" path ", 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 extant filesystem instance
> +associated with the path described by
> +.IR dirfd
> +and
> +.IR path ,
> +places it into reconfiguration mode
> +(similar to
> +.BR mount (8)
> +with the
> +.I -o remount
> +option).
> +A new file descriptor
> +associated with the filesystem configuration context
> +is then returned.
> +The calling process must have the
> +.BR CAP_SYS_ADMIN

This should use '.B. (Bold).  BR means alternating Bold and Roman, but
this only has one token, so it can't alternate.

If you run `make -R build-catman-troff`, this will trigger a diagnostic:

	an.tmac: <page>:<line>: style: .BR expects at least 2 arguments, got 1

> +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
> +filesystem 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.
> +Please note that\[em]in contrast to
> +the behaviour of
> +.B MS_REMOUNT
> +with
> +.BR mount (2)\[em] fspick ()

Only have one important keyword per macro call.  In this case, I prefer
em dashes to only be attached to one side, as if they were parentheses,
so we don't need any tricks:

	Please note that
	\[em]in contrast to
	...
	.BR mount (2)\[em]
	.BR fspick ()

> +instantiates the filesystem configuration context
> +with a copy of
> +the extant filesystem's filesystem parameters,
> +meaning that a subsequent
> +.B \%FSCONFIG_CMD_RECONFIGURE
> +operation
> +will only update filesystem parameters
> +explicitly modified with
> +.BR fsconfig (2).
> +.P
> +As with "*at()" system calls,
> +.BR fspick ()
> +uses the
> +.I dirfd
> +argument in conjunction with the
> +.I path
> +argument to determine the path to operate on, as follows:
> +.IP \[bu] 3
> +If the pathname given in
> +.I path
> +is absolute, then
> +.I dirfd
> +is ignored.
> +.IP \[bu]
> +If the pathname given in
> +.I path
> +is relative and
> +.I dirfd
> +is the special value
> +.BR \%AT_FDCWD ,
> +then
> +.I path
> +is interpreted relative to
> +the current working directory
> +of the calling process (like
> +.BR open (2)).
> +.IP \[bu]
> +If the pathname given in
> +.I path
> +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 (2)
> +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 path
> +is an empty string,
> +and
> +.I flags
> +contains
> +.BR \%FSPICK_EMPTY_PATH ,
> +then the file descriptor
> +.I dirfd
> +is operated on directly.
> +In this case,
> +.I dirfd
> +may refer to any type of file,
> +not just a directory.
> +.P
> +See
> +.BR openat (2)
> +for an explanation of why the
> +.I dirfd
> +argument is useful.
> +.P
> +.I flags
> +can be used to control aspects of how
> +.I path
> +is resolved and
> +properties of the returned file descriptor.
> +A value for
> +.I flags
> +is constructed by bitwise ORing
> +zero or more of the following constants:
> +.RS
> +.TP
> +.B 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 path
> +is an empty string,
> +operate on the file referred to by
> +.I dirfd
> +(which may have been obtained from
> +.BR open (2),
> +.BR fsmount (2),
> +or
> +.BR open_tree (2)).
> +In this case,
> +.I dirfd
> +may refer to any type of file,
> +not just a directory.
> +If
> +.I dirfd
> +is
> +.BR \%AT_FDCWD ,
> +.BR fspick ()
> +will operate on the current working directory
> +of the calling process.
> +.TP
> +.B FSPICK_SYMLINK_NOFOLLOW
> +Do not follow symbolic links
> +in the terminal component of
> +.IR path .
> +If
> +.I path
> +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 automount any automount points encountered
> +while resolving
> +.IR path .
> +This allows you to reconfigure an automount point,
> +rather than the location that would be mounted.
> +This flag has no effect if
> +the automount point has already been mounted over.

I'll amend other similar issues if I find them, but in general, I'd put
the 'if' in the next line, as it is more tied to that part of the
sentence (think for example that if you reversed the sentence to say
"if ..., then ...", you'd move the 'if' with what follows it.  You don't
need to search for all of these and fix them; just keep it in mind for
next time.  In general I like the break points you used.


Have a lovely day!
Alex

> +.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 path .
> +(See also
> +.BR path_resolution (7).)
> +.TP
> +.B EBADF
> +.I path
> +is relative but
> +.I dirfd
> +is neither
> +.B \%AT_FDCWD
> +nor a valid file descriptor.
> +.TP
> +.B EFAULT
> +.I path
> +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 path .
> +.TP
> +.B EMFILE
> +The calling process has too many open files to create more.
> +.TP
> +.B ENAMETOOLONG
> +.I path
> +is longer than
> +.BR PATH_MAX .
> +.TP
> +.B ENFILE
> +The system has too many open files to create more.
> +.TP
> +.B ENOENT
> +A component of
> +.I path
> +does not exist,
> +or is a dangling symbolic link.
> +.TP
> +.B ENOENT
> +.I path
> +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 path
> +is not a directory;
> +or
> +.I path
> +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 EPERM
> +The calling process does not have the required
> +.B \%CAP_SYS_ADMIN
> +capability.
> +.SH STANDARDS
> +Linux.
> +.SH HISTORY
> +Linux 5.2.
> +.\" commit cf3cba4a429be43e5527a3f78859b1bfd9ebc5fb
> +.\" commit 400913252d09f9cfb8cce33daee43167921fc343
> +glibc 2.36.
> +.SH EXAMPLES
> +The following example sets the read-only flag
> +on the filesystem instance referenced by
> +the mount object attached at
> +.IR /tmp .
> +.P
> +.in +4n
> +.EX
> +int fsfd = fspick(AT_FDCWD, "/tmp", FSPICK_CLOEXEC);
> +fsconfig(fsfd, FSCONFIG_SET_FLAG, "ro", NULL, 0);
> +fsconfig(fsfd, FSCONFIG_CMD_RECONFIGURE, NULL, NULL, 0);
> +.EE
> +.in
> +.P
> +The above procedure is roughly 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
> +.P
> +With the notable caveat that
> +in this example,
> +.BR mount (2)
> +will clear all other filesystem parameters
> +(such as
> +.B MS_NOSUID
> +or
> +.BR MS_NOEXEC );
> +.BR fsconfig (2)
> +will only modify the
> +.I ro
> +parameter.
> +.SH SEE ALSO
> +.BR fsconfig (2),
> +.BR fsmount (2),
> +.BR fsopen (2),
> +.BR mount (2),
> +.BR mount_setattr (2),
> +.BR move_mount (2),
> +.BR open_tree (2),
> +.BR mount_namespaces (7)
> +
> 
> -- 
> 2.51.0
> 

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

Download attachment "signature.asc" of type "application/pgp-signature" (834 bytes)

Powered by blists - more mailing lists