Hi Aleksa,

On Wed, Aug 06, 2025 at 01:05:00PM +1000, Aleksa Sarai wrote:

quoted

quoted

+.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.

quoted

quoted

+.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.

quoted

quoted

+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.  :)

quoted

quoted

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