Re: [PATCH v2 00/11] man2: add man pages for 'new' mount API

[Christian Brauner]

On Thu, Aug 07, 2025 at 03:44:34AM +1000, Aleksa Sarai wrote:
> 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

"Lies, damned lies, and statistics."

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

Thanks for doing this! Just a point of order. If you add CdB you also
need to add SoB for all of them.