Message-ID: <hk5kr2fbrpalyggobuz3zpqeekzqv7qlhfh6sjfifb6p5n5bjs@gjowkgi776ey>
Date: Wed, 1 Oct 2025 20:20:44 +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 v5 0/8] man2: document "new" mount API

Hi Aleksa, Askar,

On Thu, Sep 25, 2025 at 01:31:22AM +1000, Aleksa Sarai wrote:
> Back in 2019, the new mount API was merged[1]. David Howells then set
> about writing man pages for these new APIs, and sent some patches back
> in 2020[2].
> 

[...]

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

The full patch set has been merged now.  I've done a merge commit where
I've pasted this cover letter, and amended it so that Aleksa is the
author of the merge commit.  I've also included Askar's Reviewed-by tag
in the merge commit itself.

I'll have it in a separate branch for a few days, in case I need to fix
anything.  You can check it here:

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?h=fs>

I editorialized the titles, but other than that, I didn't do much.
I think I mentioned most of the changes in replies to each patch.

Thanks a lot for your contributions!


Have a lovely night!
Alex

> ---
> Changes in v5:
> - `sed -i s|file descriptor based|file-descriptor-based|`.
>   [Alejandro Colomar]
> - fsconfig(2): use bullets instead of ordered list for workflow
>   description. [Alejandro Colomar]
> - mount_setattr(2): fix minor wording nit in new attribute-parameter
>   subsection.
> - fsopen(2): remove brackets around "message" for message retrieval
>   interface description. [Alejandro Colomar]
> - {move_mount,fspick}(2): fix remaining incorrect no-automount text.
>   [Askar Safin]
> - {fsmount,open_tree}(2): `sed -i s|MOUNT_DETACH|MNT_DETACH|g`.
>   [Askar Safin]
> - mount_setattr(2): fix copy-paste snafu in attribute-parameter
>   subsection. [Askar Safin]
> - *: clean `make -R build-catman-troff`. [Alejandro Colomar]
> - *: switch to \[em]\c where appropriate.
> - open_tree(2): clean up MNT_DETACH-on-close description and make it
>   slightly more prominent. [Alejandro Colomar]
> - open_tree(2): mention the distinction from open(O_PATH) with regards
>   to automounts. Askar suggested it be put in the section about
>   ~OPEN_TREE_CLONE, but the change in behaviour also applies to
>   OPEN_TREE_CLONE and it looked awkward to include it in the
>   dentry_open() case because O_PATH only gets mentioned in the following
>   paragraph (where I've put the text now). [Askar Safin]
> - {move_mount,open_tree{,_attr}}(2): fix column-width-related "make -R
>   check" failures.
> - *: fix remaining "make -R lint" failures.
> - open_tree_attr(2): add example using MOUNT_ATTR_IDMAP.
> - v4: <https://lore.kernel.org/r/20250919-new-mount-api-v4-0-1261201ab562@cyphar.com>
> 
> Changes in v4:
> - `sed -i s|\\% |\\%|g`.
> - Remove unneeded quotes in SYNOPSIS. [Alejandro Colomar]
> - open_tree(2): fix leftover confusing usages of "attach" when referring
>   to file descriptors being associated with mount objects.
> - open_tree(2): rename "Anonymous mount namespaces" NOTES subsection to
>   the far more informative "Mount propagation" and clean up the wording
>   a little.
> - open_tree_attr(2): add a code comment about
>   <https://lore.kernel.org/all/20250808-open_tree_attr-bugfix-idmap-v1-0-0ec7bc05646c@cyphar.com/>
> - {fsconfig,open_tree_attr}(2): use _Nullable.
> - {fsmount,open_tree}(2): mention the the unmount-on-close behaviour is
>   actually lazy (a-la MNT_DETACH).
> - {fsconfig,mount_setattr}(2): improve "mount attributes and filesystem
>   parameters" wording to make it clearer that superblock and mount flags
>   are sibling properties, not the same thing.
> - open_tree(2): mention that any mount propagation events while the
>   mount object is detached are completely lost -- i.e., they don't get
>   replayed once you attach the mount somewhere.
> - fsconfig(2): fix minor grammatical / missing joining word issues.
> - fsconfig(2): fix final leftover `.IR A " and " B` cases.
> - fsconfig(2): explain that failed fsconfig(FSCONFIG_CMD_*) operations
>   render the filesystem context invalid.
> - fsconfig(2): rework the description of superblock reuse, as the
>   previous text was very wrong. (Though there has been discussion about
>   changing this behaviour...)
> - fsconfig(2): remove misleading wording in FSCONFIG_CMD_CREATE_EXCL
>   about how we are requesting a new filesystem instance -- in theory
>   filesystems could take this request into account but in practice none
>   do (and it seems unlikely any ever will).
> - fsconfig(2): mention that key, value, and aux must be 0 or NULL for
>   FSCONFIG_CMD_RECONF.
> - fsmount(2): fix usage of "filesystem instance" in relation to
>   fsmount() and open_tree() comparison. [Askar Safin]
> - move_mount(2): "as attached" -> "as a detached" [Askar Safin]
> - fspick(2): add note about filesystem parameter list being copied
>   rather than reset with FSCONFIG_CMD_RECONFIGURE. [Askar Safin]
> - v3: <https://lore.kernel.org/r/20250809-new-mount-api-v3-0-f61405c80f34@cyphar.com>
> 
> Changes in v3:
> - `sed -i s|Co-developed-by|Co-authored-by|g`. [Alejandro Colomar]
>   - Add Signed-off-by for co-authors. [Christian Brauner]
> - `sed -i s|needs-mount|awaiting-mount|g`, to match the kernel parlance.
> - Fix VERSIONS/HISTORY mixup in mount_attr(2type) that was copied from
>   open_how(2type). [Alejandro Colomar]
> - Fix incorrect .BR usage in SYNOPSIS.
> - Some more semantic newlines fixes. [Alejandro Colomar]
> - Minor fixes suggested by Alejandro. [Alejandro Colomar]
> - open_tree_attr(2): heavily reword everything to be better formatted
>   and more explicit about its behaviour.
> - open_tree(2): write proper explanatory paragraphs for the EXAMPLES.
> - mount_setattr(2): fix stray doublequote in SYNOPSIS. [Askar Safin]
> - fsopen(2): rework structure of the DESCRIPTION introduction.
> - fsopen(2): explicitly say that read(2) errors in the message retrieval
>   interface are actual errors, not return 0. [Askar Safin]
> - fsopen(2): add BUGS section to describe the unfortunate -ENODATA
>   message dropping behaviour that should be fixed by
>   <https://lore.kernel.org/r/20250807-fscontext-log-cleanups-v3-0-8d91d6242dc3@cyphar.com/>.
> - fsconfig(2): add a NOTES subsection about generic filesystem
>   parameters.
> - fsconfig(2): add comment about the weirdness surrounding
>   FSCONFIG_SET_PATH.
> - {fspick,open_tree}(2): Correct AT_NO_AUTOMOUNT description (copied
>   from David, who probably copied it from statx(2)) -- AT_NO_AUTOMOUNT
>   applies to all path components, not just the final one. [Christian
>   Brauner]
> - statx(2): fix AT_NO_AUTOMOUNT documentation.
> - open_tree(2): swap open(2) reference for openat(2) when saying that
>   the result is identical. [Askar Safin]
> - fsmount(2): fix DESCRIPTION introduction, and rework attr_flags
>   description to better reference mount_setattr(2).
> - {fsopen,fspick,fsmount,open_tree}(2): don't use "attach" when talking
>   about the file descriptors we return that reference in-kernel objects,
>   to avoid confusing readers with mount object attachment status.
> - fsconfig(2): remove pidns argument example, as it was kind of unclear
>   and referenced kernel features not yet merged.
> - fsconfig(2): remove rambling FSCONFIG_SET_PATH_EMPTY text (which
>   mostly describes an academic issue that doesn't apply to any existing
>   filesystem), and instead add a CAVEATS section which touches on the
>   weird type behaviour of fsconfig(2).
> - v2: <https://lore.kernel.org/r/20250807-new-mount-api-v2-0-558a27b8068c@cyphar.com>
> 
> Changes in v2:
> - `make -R lint-man`. [Alejandro Colomar]
> - `sed -i s|Glibc|glibc|g`. [Alejandro Colomar]
> - `sed -i s|pathname|path|g` [Alejandro Colomar]
> - Clean up macro usage, example code, and synopsis. [Alejandro Colomar]
> - Try to use semantic newlines. [Alejandro Colomar]
> - Make sure the usage of "filesystem context", "filesystem instance",
>   and "mount object" are consistent. [Askar Safin]
> - Avoid referring to these syscalls without an "at" suffix as "*at()
>   syscalls". [Askar Safin]
> - Use \% to avoid hyphenation of constants. [Askar Safin, G. Branden Robinson]
> - Add a new subsection to mount_setattr(2) to describe the distinction
>   between mount attributes and filesystem parameters.
> - (Under protest) double-space-after-period formatted commit messages.
> - v1: <https://lore.kernel.org/r/20250806-new-mount-api-v1-0-8678f56c6ee0@cyphar.com>
> 
> ---
> Aleksa Sarai (8):
>       man/man2/fsopen.2: document "new" mount API
>       man/man2/fspick.2: document "new" mount API
>       man/man2/fsconfig.2: document "new" mount API
>       man/man2/fsmount.2: document "new" mount API
>       man/man2/move_mount.2: document "new" mount API
>       man/man2/open_tree.2: document "new" mount API
>       man/man2/open_tree{,_attr}.2: document new open_tree_attr() API
>       man/man2/{fsconfig,mount_setattr}.2: add note about attribute-parameter distinction
> 
>  man/man2/fsconfig.2       | 741 ++++++++++++++++++++++++++++++++++++++++++++++
>  man/man2/fsmount.2        | 231 +++++++++++++++
>  man/man2/fsopen.2         | 385 ++++++++++++++++++++++++
>  man/man2/fspick.2         | 343 +++++++++++++++++++++
>  man/man2/mount_setattr.2  |  39 +++
>  man/man2/move_mount.2     | 646 ++++++++++++++++++++++++++++++++++++++++
>  man/man2/open_tree.2      | 709 ++++++++++++++++++++++++++++++++++++++++++++
>  man/man2/open_tree_attr.2 |   1 +
>  8 files changed, 3095 insertions(+)
> ---
> base-commit: f17990c243eafc1891ff692f90b6ce42e6449be8
> change-id: 20250802-new-mount-api-436db984f432
> 
> 
> Kind regards,
> -- 
> Aleksa Sarai
> Senior Software Engineer (Containers)
> SUSE Linux GmbH
> https://www.cyphar.com/
> 

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