Linux doesn’t usually suffer from a lack of powerful interfaces.
What it sometimes lacks is something far more basic: usable documentation.
The Linux kernel’s “new mount API” is a perfect example. Introduced back in 2019 with Linux 5.2, it took more than six years before developers could finally read about it in official man pages.
By the time the documentation arrived, the API itself was already old news.
Table of Contents
A More Flexible Way to Mount File Systems
The so-called “new mount API” isn’t just a minor tweak to the classic mount() system call.
Instead of a single, all-or-nothing operation, it introduces a multi-step, file-descriptor-based workflow built around system calls such as:
fsopenfsconfig- and related helpers
This design offers significantly more flexibility and control. It allows mount operations to be configured incrementally, validated more safely, and extended more easily over time. From an architectural standpoint, it’s clearly the direction Linux wants to move toward.
The Kernel Was Ready — File Systems Followed
Support for the new mount API has been present in the kernel since Linux 5.2. Over the following years, most major file systems gradually adopted it.
Earlier this year, F2FS finally added support, making it one of the last major file systems to do so. At that point, the API could reasonably be considered mature.
Yet despite all this progress, real-world usage remained limited.
See also: Mastering the Linux Command Line — Your Complete Free Training Guide
The Missing Piece: Man Pages
The reason was surprisingly simple.
For years, there were no proper man pages describing how the new mount API worked.
In the Linux world, that’s a serious problem. If an interface doesn’t show up in man 2, many developers effectively treat it as nonexistent. Reading kernel source code or scattered documentation isn’t a realistic entry point for most users.
As Askar Safin, who helped review the eventual man pages, pointed out, this lack of documentation likely hurt adoption for more than half a decade.
Documentation Attempts That Never Made It
This wasn’t for lack of effort.
- An initial attempt to add man page documentation dates back to 2018, before the API even fully landed.
- Another attempt followed in 2020.
- Both stalled and were eventually abandoned.
Meanwhile, Christian Brauner, one of the key developers involved, maintained a Markdown-based version of the documentation outside the official man pages.
Only in 2024 did that work finally make its way into the man-pages project, resulting in proper documentation with the man-pages 6.16 release. Even now, it’s still waiting to appear on widely used sites like man7.org.
A Bigger Problem With Man Pages Themselves
The episode also reignited a broader debate.
Brauner has openly argued that the continued reliance on groff as the man page source format is itself a barrier. Compared to Markdown, groff is harder to write, harder to review, and far less inviting to contributors.
In a world where most technical documentation has moved on, man pages remain stubbornly rooted in older tooling—and Linux may be paying the price.
Better Late Than Never
The good news is that the documentation finally exists.
Developers interested in the new mount API can now rely on official man pages instead of reverse-engineering kernel behavior. But the story serves as a reminder:
Sometimes, it’s not the lack of good interfaces that slows Linux down — it’s the lack of good documentation.
