Aleksa Sarai [Wed, 1 Oct 2025 18:07:52 +0000 (20:07 +0200)]
man/man2/: Document new mount API set
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.
man/man2/{fsconfig,mount_setattr}.2: NOTES: Add note about attribute-parameter distinction
This was not particularly well documented in mount(8) nor mount(2), and
since this is a fairly notable aspect of the new mount API, we should
probably add some words about it.
man/man2/open_tree{,_attr}.2: Document open_tree_attr(), and add link page
This is a new API added in Linux 6.15, and is effectively just a minor
expansion of open_tree(2) in order to allow for MOUNT_ATTR_IDMAP to be
changed for an existing ID-mapped mount. glibc does not yet have a
wrapper for this.
While working on this man-page, I discovered a bug in open_tree_attr(2)
that accidentally permitted changing MOUNT_ATTR_IDMAP for extant
detached ID-mapped mount objects. This is definitely a bug, but there
is no need to add this to BUGS because the patch to fix this has already
been accepted (slated for 6.18, and will be backported to 6.15+).
This is loosely based on the original documentation written by David
Howells and later maintained by Christian Brauner, but has been
rewritten to be more from a user perspective (as well as fixing a few
critical mistakes).
Co-authored-by: David Howells <dhowells@redhat.com> Signed-off-by: David Howells <dhowells@redhat.com> Co-authored-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
Message-ID: <20250925-new-mount-api-v5-6-028fb88023f2@cyphar.com> Reviewed-by: Askar Safin <safinaskar@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
This is loosely based on the original documentation written by David
Howells and later maintained by Christian Brauner, but has been
rewritten to be more from a user perspective (as well as fixing a few
critical mistakes).
Co-authored-by: David Howells <dhowells@redhat.com> Signed-off-by: David Howells <dhowells@redhat.com> Co-authored-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
Message-ID: <20250925-new-mount-api-v5-5-028fb88023f2@cyphar.com> Reviewed-by: Askar Safin <safinaskar@gmail.com>
[alx: ffix] Signed-off-by: Alejandro Colomar <alx@kernel.org>
This is loosely based on the original documentation written by David
Howells and later maintained by Christian Brauner, but has been
rewritten to be more from a user perspective (as well as fixing a few
critical mistakes).
Co-authored-by: David Howells <dhowells@redhat.com> Signed-off-by: David Howells <dhowells@redhat.com> Co-authored-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
Message-ID: <20250925-new-mount-api-v5-4-028fb88023f2@cyphar.com> Reviewed-by: Askar Safin <safinaskar@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
This is loosely based on the original documentation written by David
Howells and later maintained by Christian Brauner, but has been
rewritten to be more from a user perspective (as well as fixing a few
critical mistakes).
Co-authored-by: David Howells <dhowells@redhat.com> Signed-off-by: David Howells <dhowells@redhat.com> Co-authored-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
Message-ID: <20250925-new-mount-api-v5-3-028fb88023f2@cyphar.com> Reviewed-by: Askar Safin <safinaskar@gmail.com>
[alx: s/name/key/; ffix] Signed-off-by: Alejandro Colomar <alx@kernel.org>
This is loosely based on the original documentation written by David
Howells and later maintained by Christian Brauner, but has been
rewritten to be more from a user perspective (as well as fixing a few
critical mistakes).
Co-authored-by: David Howells <dhowells@redhat.com> Signed-off-by: David Howells <dhowells@redhat.com> Co-authored-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
Message-ID: <20250925-new-mount-api-v5-2-028fb88023f2@cyphar.com> Reviewed-by: Askar Safin <safinaskar@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
This is loosely based on the original documentation written by David
Howells and later maintained by Christian Brauner, but has been
rewritten to be more from a user perspective (as well as fixing a few
critical mistakes).
Co-authored-by: David Howells <dhowells@redhat.com> Signed-off-by: David Howells <dhowells@redhat.com> Co-authored-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
Message-ID: <20250925-new-mount-api-v5-1-028fb88023f2@cyphar.com> Reviewed-by: Askar Safin <safinaskar@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
man/man2/mount_setattr.2: Mirror opening sentence from fsopen(2)
All of the other new mount API docs have this lead-in sentence in order
to make this set of APIs feel a little bit more cohesive. Despite being
a bit of a latecomer, mount_setattr(2) is definitely part of this family
of APIs and so deserves the same treatment.
man/man2/mount_setattr.2, man/man2type/mount_attr.2type: Move mount_attr struct to new page mount_attr(2type)
As with open_how(2type), it makes sense to move this to a separate man
page. In addition, future man pages added in this patchset will want to
reference mount_attr(2type).
Within recipes, variables have delayed expansion, which means that we
can't use variables that we've undefined. That's why we need to use
a filter to get the regex file name from the rule prerequisites. This
trick was suggested by Philip.
Cc: Philip Guenther <guenther@gmail.com> Cc: Paul Smith <psmith@gnu.org> Cc: Martin Dorey <Martin.Dorey@hitachivantara.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Reported-by: Christoph Anton Mitterer <calestyo@scientia.org> Suggested-by: Christoph Anton Mitterer <calestyo@scientia.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
share/mk/: Reduce rebuilds, and simplify makefile code
I've verified that the build system produces the same amount of files
with 'make -R -j24 -k lint build-all check'. This was just to make sure
there are no silent regressions.
The file contents are slightly different, but that's because for some
reason groff(1) is not reproducible; I've checked some samples, and the
differences seem trivial, and unrelated to these build-system changes.
I've reported to the groff@ mailing list the lack of reproducibility of
groff(1).
Reported-by: iwyu(1) Fixes: 0e7a39804a3c (2025-08-20; "man/: EXAMPLES: Use err(3) and errc(3bsd) instead of similar macros") Signed-off-by: Alejandro Colomar <alx@kernel.org>
Most of these are false positives, in the sense that a line break is
escaped, and the matching quote is in the next source line.
However, let's remove those escaped line breaks, which make reading the
source more difficult. For this, rename some parameters to be shorter,
and allow some lines to go slightly past the 80-column right margin.
There's also a domain error if z is a NaN, so let's simplify wording.
See the comments in the source code, which remind that POSIX doesn't
mandate some of this, so this is GNU-specific.
Add a description of the RWF_DONTCACHE IO flag, which tells the kernel
that any page cache instantiated by this IO, should be dropped when the
operation has completed.
Reported-by: Christoph Hellwig <hch@infradead.org> Cc: "Darrick J. Wong" <djwong@kernel.org> Cc: Johannes Thumshirn <Johannes.Thumshirn@wdc.com> Cc: linux-fsdevel@vger.kernel.org Co-authored-by: Jens Axboe <axboe@kernel.dk>
[alx: editorial improvements; srcfix, ffix] Signed-off-by: Alejandro Colomar <alx@kernel.org>
On Fri, Aug 22, 2025 at 05:09:42PM +0200, Ingo Schwarze wrote:
> > .TS
> > l l l
> > ---
>
> That's terrible style.
>
> Using "-" in the tbl(7) layout only makes sense when the same layout
> line also contains at least one cell that receives data.
>
> A horizontal line that extends across the table as a whole
> should *not* get its own layout line but can be specified purely
> in the data section of the table. That's not only more robust,
> but also results in source code that is easier to read and maintain.
>
> The above is not just convention, but also makes sense logically
> and is related to the root cause of your earlier blank line woes.
> A table line that receives no data should not be specified in the
> layout because every layout line requires at least one data line,
> so a layout line receiving no data is an oxymoron, and that logical
> contradiction is precisely what causes the issue of needing a
> blank line in the first place.
>
> Note that in a layout line that only contains "-" for *some* cells,
> while at leat one cell receives data, the problem does not occur
> because the coressponding data line(s) do contain actual data
> for at least one cell, so they are not blank.
This table format specification was bogus. It specified 4 columns, but
we were only using 3. Due to the commit in which that was introduced,
I suspect it was just a typo that went unnoticed.
Fixes: 0ab815e900ce (2021-01-06; "man-pages.7: ffix: don't fill text in tables") Reported-by: Ingo Schwarze <schwarze@openbsd.org> Suggested-by: Ingo Schwarze <schwarze@openbsd.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Askar Safin [Tue, 19 Aug 2025 16:10:00 +0000 (16:10 +0000)]
man/man2/syscalls.2: Remove pread and pwrite from list of arch-specific syscalls
Current version says that pread(2) and pwrite(2) only ever existed in
avr32 and blackfin archs, which were removed from kernel.
This is not true. pread(2) and pwrite(2) are present in modern Linux
for all archs. They were merely renamed to pread64(2) and pwrite64(2)
in Linux 2.6, as explained in big table in this manual page.
There is pre-existing logic that appears to be undocumented for an
mremap() shrink operation, where it turns out that the usual 'input
range must span a single mapping' requirement no longer applies.
In fact, it turns out that the input range specified by [old_address,
old_address + old_size) may span any number of mappings.
If shrinking in-place (that is, neither the MREMAP_FIXED nor
MREMAP_DONTUNMAP flags are specified), then the new span may also span
any number of VMAs - [old_address, old_address + new_size).
If shrinking and moving, the range specified by [old_address,
old_address + new_size) must span a single VMA.
There must be at least one VMA contained within the [old_address,
old_address + old_size) range, and old_address must be within the range
of a VMA.
Explicitly document this.
Signed-off-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
Message-ID: <ab2264d8c29d103d400c028f0417cada002ffc11.1754924278.git.lorenzo.stoakes@oracle.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
man/man2/: SYNOPSIS: Use GNU forward-declarations of parameters for sizes of array parameters
Fixes: d2c2db8830f8 (2025-03-14; "man/: SYNOPSIS: Use GNU forward-declarations of parameters for sizes of array parameters") Signed-off-by: Alejandro Colomar <alx@kernel.org>
man/: EXAMPLES: Use err(3) and errc(3bsd) instead of similar macros
These functions are quite portable. And if one doesn't have them for
some reason (but libbsd has been ported to many systems), one can write
them easily as macros, anyway.
man/man3/strftime.3: EXAMPLES: Validate number of arguments
The strftime example requires a format paramter. If you don't pass one,
it crashes. Check for the parameter.
Signed-off-by: Dr. David Alan Gilbert <dave@treblig.org>
Message-ID: <20250818174553.70132-1-dave@treblig.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
projects / thirdparty / man-pages.git / log
