Re: [PATCH v5 0/8] man2: document "new" mount API

Alejandro Colomar
2025-10-01T18:20:49Z

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

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@redhat.com>
> Signed-off-by: David Howells <dhowells@redhat.com>
> Co-authored-by: Christian Brauner <brauner@kernel.org>
> Signed-off-by: Christian Brauner <brauner@kernel.org>
> Signed-off-by: Aleksa Sarai <cyphar@cyphar.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/>).

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