Hi Aleksa,

On Wed, Aug 06, 2025 at 02:25:49AM +1000, Aleksa Sarai wrote:

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 [off-list ref]
	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" [off-list ref]
	    Signed-off-by: Alejandro Colomar [off-list ref]

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/>