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>
man/man2const/PR_FUTEX_HASH.2const: Update as of Linux v6.17-rc2
The PR_FUTEX_HASH prctl interface was updated shortly before the release
of v6.16. The changes are:
- The functionality was disabled in v6.16 and enabled v6.17-rc1 after
some updates address the performance concerns.
- The "IMMUTABLE" functionality was removed.
Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
Message-ID: <20250819071728.1431543-2-bigeasy@linutronix.de> Signed-off-by: Alejandro Colomar <alx@kernel.org>
man/man3/posix_spawn.3: EXAMPLES: Validate the number of arguments
Make the example check for an executable name on the command line
rather than segfaulting in the child.
Signed-off-by: Dr. David Alan Gilbert <dave@treblig.org>
Message-ID: <20250818225910.101238-1-dave@treblig.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Alex Yang [Mon, 18 Aug 2025 07:59:05 +0000 (00:59 -0700)]
man/man2/getrusage.2: Use correct unit (KiB) for .ru_maxrss
The .ru_maxrss member was documented as using "kilobytes" as its unit.
However, the value is actually in multiples of 1024 bytes, which is
correctly referred to as "kibibytes" (KiB) according to the IEC
standard.
man/man2/syslog.2: SYNOPSIS: Remove incorrect include
It doesn't provide any macros, as said later in the page. The
programmer must either define the macros itself, or use the raw values.
Fixes: e5a173829179 (2021-06-20; "syslog.2: Use syscall(SYS_...); for raw system calls") Closes: <https://bugzilla.kernel.org/show_bug.cgi?id=220273> Reported-by: Nathaniel Manista <nathaniel@google.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
The current mallinfo2() example segfaults on 64bit Linux.
This happens because it builds a large 'alloc' array
on the stack, which is currently 2M entries, each of which
is a pointer, so hitting 16MB which is more than the default
Linux stack ulimit of 8MiB.
Reduce it.
Signed-off-by: "Dr. David Alan Gilbert" <dave@treblig.org>
Message-ID: <20250816204252.63616-1-dave@treblig.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Lorenzo Stoakes [Mon, 11 Aug 2025 14:59:38 +0000 (15:59 +0100)]
man/man2/mremap.2: Describe multiple-mapping move
Document the new behaviour introduced in Linux 6.17 whereby it is now
possible to move multiple mappings in a single operation, as long as the
operation is purely a move, that is, old_size == new_size and
MREMAP_FIXED is specified.
This change also explains the limitations of this method and the
possibility of partial failure.
Finally, we pluralise language where it makes sense to so the documentation
does not contradict either this new capability nor the pre-existing edge
case.
Example code is enclosed below demonstrating the behaviour which is now
possible:
Lorenzo Stoakes [Mon, 11 Aug 2025 14:59:37 +0000 (15:59 +0100)]
man/man2/mremap.2: Explicitly document the simple move operation
In preparation for discussing newly introduced mremap() behaviour to
permit the move of multiple mappings at once, add a section to the
this manual page to describe these operations in general.
Signed-off-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
Message-ID: <0a5d0d6e9f75e8e2de05506f73c41b069d77de36.1754924278.git.lorenzo.stoakes@oracle.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
glibc 2.36 added syscall wrappers for the entire family of fd-based
mount syscalls, including mount_setattr(2). Thus it's no longer
necessary to instruct users to do raw syscall(2) operations.
Signed-off-by: Aleksa Sarai <cyphar@cyphar.com> Cc: <linux-api@vger.kernel.org> Cc: <linux-fsdevel@vger.kernel.org> Cc: <linux-kernel@vger.kernel.org> Cc: "Michael T. Kerrisk" <mtk.manpages@gmail.com> Cc: Alexander Viro <viro@zeniv.linux.org.uk> Cc: Jan Kara <jack@suse.cz> Cc: Askar Safin <safinaskar@zohomail.com> Cc: "G. Branden Robinson" <branden@debian.org> Cc: David Howells <dhowells@redhat.com> Cc: Christian Brauner <brauner@kernel.org>
Message-ID: <20250807-new-mount-api-v2-1-558a27b8068c@cyphar.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
man/man2/openat2.2: HISTORY: Include epilogue about FreeBSD
While RESOLVE_BENEATH was based on FreeBSD's O_BENEATH, there was a
well-known safety issue in O_BENEATH that we explicitly avoided
replicating -- FreeBSD would only verify whether the lookup escaped the
dirfd *at the end of the path lookup*.
This meant that even with O_BENEATH, an attacker could gain information
about the structure of the filesystem outside of the dirfd through
timing attacks or other side-channels.
Once Linux had RESOLVE_BENEATH, FreeBSD implemented O_RESOLVE_BENEATH to
mimic the same behaviour[1] and eventually removed O_BENEATH entirely
from their system[2]. It seems prudent to provide this epilogue in the
HISTORY section of the openat2(2) man page (the FreeBSD man page does
for open(2) not reference this historical connection with Linux at all,
as far as I can tell).
The commands in 4a2750a06f98 (2023-08-01; "Changes: Ready for 6.05")
need as update for the new man/ directory. I've also added code to get
the page which link pages link to.
In future we might want to note that it's _not_ available on iOS/macOS
and the BSDs, since that's the caveat I usually give when recommending
the use of %m.
projects / thirdparty / man-pages.git / log
