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/ (local)
[2]: https://lore.kernel.org/linux-man/159680892602.29015.6551860260436544999.stgit@warthog.procyon.org.uk/ (local)
[3]: https://github.com/brauner/man-pages-md

Co-authored-by: David Howells [off-list ref]
Signed-off-by: David Howells <dhowells@redhat.com>
Co-authored-by: Christian Brauner [off-list ref]
Signed-off-by: Christian Brauner <brauner@kernel.org>
Signed-off-by: Aleksa Sarai <redacted>

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 (local)>

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/ (local)>
- {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 (local)>

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/ (local)>.
- 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 (local)>

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 (local)>

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