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.
