Back in 2019, the new mount API was merged into mainline[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 may have been a contributing factor to the relatively slow adoption of these new (far better) APIs. 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 set aside some time to provide some documentation of these new APIs and so 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 (7 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). 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-developed-by: David Howells <dhowells@xxxxxxxxxx> Co-developed-by: Christian Brauner <brauner@xxxxxxxxxx> Signed-off-by: Aleksa Sarai <cyphar@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 (11): mount_setattr.2: document glibc >= 2.36 syscall wrappers mount_setattr.2: move mount_attr struct to mount_attr.2type fsopen.2: document 'new' mount api fspick.2: document 'new' mount api fsconfig.2: document 'new' mount api fsmount.2: document 'new' mount api move_mount.2: document 'new' mount api open_tree.2: document 'new' mount api mount_setattr.2: mirror opening sentence from fsopen(2) open_tree_attr.2, open_tree.2: document new open_tree_attr() api fsconfig.2, mount_setattr.2: add note about attribute-parameter distinction man/man2/fsconfig.2 | 566 +++++++++++++++++++++++++++++++++++++++ man/man2/fsmount.2 | 209 +++++++++++++++ man/man2/fsopen.2 | 319 ++++++++++++++++++++++ man/man2/fspick.2 | 305 +++++++++++++++++++++ man/man2/mount_setattr.2 | 105 ++++---- man/man2/move_mount.2 | 609 ++++++++++++++++++++++++++++++++++++++++++ man/man2/open_tree.2 | 479 +++++++++++++++++++++++++++++++++ man/man2/open_tree_attr.2 | 1 + man/man2type/mount_attr.2type | 58 ++++ 9 files changed, 2600 insertions(+), 51 deletions(-) --- base-commit: f23e8249a6dcf695d38055483802779c36aedbba change-id: 20250802-new-mount-api-436db984f432 Best regards, -- Aleksa Sarai <cyphar@xxxxxxxxxx>
