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]. Unfortunately, these patches were never merged, which meant that these APIs were practically undocumented for many years -- arguably this has been a contributing factor to the relatively slow adoption of these new (far better) APIs. For instance, I have often discovered that many folks are unaware of the read(2)-based message retrieval interface provided by filesystem context file descriptors. In 2024, Christian Brauner adapted David Howell's original man pages into the easier-to-edit Markdown format and published them on GitHub[3]. These have been maintained since, including updated information on new features added since David Howells's 2020 draft pages (such as MOVE_MOUNT_BENEATH). While this was a welcome improvement to the previous status quo (that had lasted over 6 years), speaking personally my experience is that not having access to these man pages from the terminal has been a fairly common painpoint. So, this is a modern version of the man pages for these APIs, in the hopes that we can finally (6 years later) get proper documentation for these APIs in the man-pages project. One important thing to note is that most of these were re-written by me, with very minimal copying from the versions available from Christian[2]. The reasons for this are two-fold: * Both Howells's original version and Christian's maintained versions contain crucial mistakes that I have been bitten by in the past (the most obvious being that all of these APIs were merged in Linux 5.2, but the man pages all claim they were merged in different versions.) * As the man pages appear to have been written from Howells's perspective while implementing them, some of the wording is a little too tied to the implementation (or appears to describe features that don't really exist in the merged versions of these APIs). * The original versions of the man-pages lacked bigger-picture explanations of the reasoning behind the API, which would make it easier for readers to understand what operations are doing. I decided that the best way to resolve these issues is to rewrite them from the perspective of an actual user of these APIs (me), and check that we do not repeat the mistakes I found in the originals. I have also done my best to resolve the issues raised by Michael Kerrisk on the original patchset sent by Howells[1]. 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@xxxxxxxxxxxxxxxxxx/ [2]: https://lore.kernel.org/linux-man/159680892602.29015.6551860260436544999.stgit@xxxxxxxxxxxxxxxxxxxxxx/ [3]: https://github.com/brauner/man-pages-md Co-authored-by: David Howells <dhowells@xxxxxxxxxx> Signed-off-by: David Howells <dhowells@xxxxxxxxxx> Co-authored-by: Christian Brauner <brauner@xxxxxxxxxx> Signed-off-by: Christian Brauner <brauner@xxxxxxxxxx> Signed-off-by: Aleksa Sarai <cyphar@xxxxxxxxxx> --- 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@xxxxxxxxxx/>. - 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@xxxxxxxxxx> 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@xxxxxxxxxx> --- Aleksa Sarai (12): man/man2/statx.2: correctly document AT_NO_AUTOMOUNT man/man2/mount_setattr.2: fix stray quote in SYNOPSIS man/man2/mount_setattr.2: move mount_attr struct to mount_attr(2type) 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/mount_setattr.2: mirror opening sentence from fsopen(2) 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 | 681 ++++++++++++++++++++++++++++++++++++++++++ man/man2/fsmount.2 | 220 ++++++++++++++ man/man2/fsopen.2 | 384 ++++++++++++++++++++++++ man/man2/fspick.2 | 309 +++++++++++++++++++ man/man2/mount_setattr.2 | 62 +++- man/man2/move_mount.2 | 640 +++++++++++++++++++++++++++++++++++++++ man/man2/open_tree.2 | 593 ++++++++++++++++++++++++++++++++++++ man/man2/open_tree_attr.2 | 1 + man/man2/statx.2 | 6 +- man/man2type/mount_attr.2type | 61 ++++ 10 files changed, 2940 insertions(+), 17 deletions(-) --- base-commit: e473affca7b039fd018eedb839d6c80e4fd3df17 change-id: 20250802-new-mount-api-436db984f432 Kind regards, -- Aleksa Sarai Senior Software Engineer (Containers) SUSE Linux GmbH https://www.cyphar.com/
