getdents.2: Add note to misleading field "d_off" in struct linux_dirent64
The getdents.2 man page details a pair syscalls: getdents() and
getdents64(), both of which are used to get the entries of a directory.
The results are populated into a structure, with the difference between
both syscalls being mostly bitwidth related.
However, the behaviour or the 'd_off' field in both struct linux_dirent
and linux_dirent64 is wrongly documented in this man page.
According to the current manual page, 'd_off' is used to store the
"Offset to the next linux_dirent [...] the distance from the start of
the directory to the start of the next linux_dirent."
This value, though, is filesystem dependent, and much of the time it
stores no such offset.
According to readdir.3 [1] manpage:
> The value returned in d_off is the same as would be returned by
> calling telldir(3) at the current position in the directory stream.
> Be aware that despite its type and name, the d_off field is seldom
> any kind of directory offset on modern filesystems. Applications
> should treat this field as an opaque value, making no assumptions
> about its contents; see also telldir(3).
Of course, readdir(3) is a glibc function with no ties to
getdents(2), but it was implemented with such syscall and considering
that readdir(3) doesn't process the data from getdents(2) my belief is
that it inherited said behaviour from it [2]. telldir(3) tells a
similar story.
On the example provided at the end of getdents.2, notable is the d_off
value of the very last entry:
Below is a patch that adds a warning besides the d_off field in both
structures, plus a brief explanation on why this field can be mislea-
ding (while also directing the user towards the readdir.3 man page).
share/mk/: dist: FORCE regeneration of version file if necessary
If any of $DISTVERSION, $DISTNAME, or $DISTDATE have changed since the
last 'make dist', force regeneration of the version file, even if it
wouldn't change due to normal dependencies. This makes sure that the
tarball has correct values.
We don't call git(1) inside tarballs anymore to get the $DISTNAME, so we
can safely assume that git(1) should never fail, and if it fails, we
better get an error message.
share/mk/: Use a variable to prefix recursive make(1) output
Piping the output to sed(1) didn't behave well with -Orecurse. Using a
variable behaves well, keeping output synchronized. The length of the
variable name is specific, so that `$(INFO_)` uses exactly 8 characters,
a tab.
Mark Wielaard [Mon, 12 Feb 2024 12:07:04 +0000 (13:07 +0100)]
close_range.2: Add _GNU_SOURCE and <unistd.h> to SYNOPSIS
close_range() is defined in <unistd.h> when _GNU_SOURCE is defined.
The <linux/close_range.h> header file only defines the (linux-specific)
flags constants. The flags argument is an int, not an unsigned int, in
the glibc wrapper. Use the close_range() library call in the example
code instead of syscall().
Fixes: 71a62d6c3c56 ("close_range.2: Glibc added a wrapper recently") Fixes: c2356ba085ed ("close_range.2: Glibc 2.34 has added a close_range() wrapper") Reported-by: Alexandra Hájková <ahajkova@redhat.com> Signed-off-by: Mark Wielaard <mark@klomp.org>
[alx: ffix] Signed-off-by: Alejandro Colomar <alx@kernel.org>
Štěpán Němec [Mon, 12 Feb 2024 09:09:03 +0000 (10:09 +0100)]
getaddrinfo.3: tfix
(Incidentally, the glibc function source does name the parameter
"name" rather than "node", unlike this man page. (The POSIX man
page uses "nodename".))
share/mk/: Move configuration variables to share/mk/configure/
Some variables are only part of the implementation of our build system,
and users should not modify them; others are designed to be set by users
when they invoke make(1). Define the latter in share/mk/configure/, so
that they are more visible.
I cut PA-RISC and the Alpha. They have 10 and 6 popcon entries,
respectively, and AFAICT they haven't seen a processor released
in over a decade, they aren't relevant to any modern reader.
Similarly, use "POWER" instead of "PowerPC" ‒ the consensus branding
is "POWER"+version (POWER8/POWER9); PowerPC is itself a POWER variant
and doesn't really deserve its own special mention, especially in 2024.
* sysdeps/unix/sysv/linux/seteuid.c (seteuid): Use setresuid32
syscall directly if possible. If __ASSUME_SETRESUID_SYSCALL is
defined drop compatibility code.
[...]
The change in implementation from setreuid()/setregid() is also
already mentioned two paragraphs earlier in the same man page.
Fixes: a36b2bb0eca4 ("seteuid.2: seteuid() and setegid() are implemented as library functions") Fixes: 8554dd0324b0 ("seteuid.2: tfix") Signed-off-by: Štěpán Němec <stepnem@smrk.net> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Refactor table format specification: use column modifiers to set heading
rows in bold instead of populating every entry in them with font
selection escape sequences. Use a single '_' to indicate a horizontal
rule spanning the table. Put vertical space before the table
(making it resemble a typographical "display") rather than after the
after the column heading.
Recast to use language paralleling that of the MREMAP_DONTUNMAP
discussion elsewhere in the page. Spotted these (excessively?)
abbreviated cross references while preparing for the `MR` man(7) macro
migration.
Break lines containing a parametric prefix to a man page name into two
lines, using distinct font alternation macros and the `\c` escape
sequence to "connect" the output. This prepares for adoption of the
`MR` man(7) macro in groff 1.23.0.
The style seen here assumes that the typeface used for man page names is
bold, which is ahistorical and which the `MR` feature makes
configurable. It might be better to recast this shorthand into English.
...that proved surprisingly tough to troubleshoot.
I got the following output from my working copy.
grotty:...:(man5/locale.5):32291: error: output above first line discarded
grotty:...:(man5/locale.5):32291: error: output above first line discarded
grotty:...:(man5/locale.5):32291: error: output above first line discarded
grotty:...:(man5/locale.5):32291: error: output above first line discarded
grotty:...:(man5/locale.5):32291: error: output above first line discarded
grotty:...:(man5/locale.5):32291: error: output above first line discarded
grotty:...:(man5/locale.5):32291: error: output above first line discarded
grotty:...:(man5/locale.5):32291: error: output above first line discarded
grotty:...:(man5/locale.5):32291: error: output above first line discarded
grotty:...:(man5/locale.5):32292: error: output above first line discarded
grotty:...:(man5/locale.5):32294: error: output above first line discarded
grotty:...:(man5/locale.5):32294: error: output above first line discarded
grotty:...:(man5/locale.5):32294: error: output above first line discarded
grotty:...:(man5/locale.5):32294: error: output above first line discarded
grotty:...:(man5/locale.5):32294: error: output above first line discarded
`\r` is a perfectly legal *roff escape sequence, but one generally never
sees it in man pages. In that case, the input line in question was at
the top of the "page" in continuous rendering mode, and so the attempt
at a reverse vertical motion did indeed put the drawing position above
the top of the page.
grepping reveals no other occurrences of '\r' in the man-pages corpus.
наб [Thu, 4 Jan 2024 22:31:21 +0000 (23:31 +0100)]
cpuid.4: Note which CPUs don't support CPUID and what happens
"Early 486" comes from an uncited wikipedia table, added in
<https://en.wikipedia.org/w/index.php?title=CPUID&diff=prev&oldid=592047209>
<https://en.wikipedia.org/w/index.php?title=CPUID&diff=prev&oldid=592047978>
but I spot-checked the rest of the table accurate to CPUs in my house
(the oldest of which is an original Celeron, so no 486),
and "early 486" is better than "early x86" which can mean anything.
This does leave earlier x86 unmentioned,
but Linux hasn't targeted those in over a decade,
so they're out of scope anyway.
That paragraph may be confusing to those who don't know about PGP, so
reduce strength of encouragement. But to those that know about PGP, and
know how to use it, please, please use it.
The infrastructure of the list was recently modified. Now, all the
information to subscribe, unsubscribe, or other actions, are in
<https://subspace.kernel.org/vger.kernel.org.html>.
Günther Noack [Fri, 1 Dec 2023 12:26:45 +0000 (13:26 +0100)]
ioctl_console.2: Document new CAP_SYS_ADMIN restrictions (since Linux 6.7)
Since Linux commit 8d1b43f6a6df7bce ("tty: Restrict access to TIOCLINUX'
copy-and-paste subcommands"), the TIOCL_SETSEL, TIOCL_PASTESEL and
TIOCL_SELLOADLUT subcommands require CAP_SYS_ADMIN.
Alexey Tikhonov [Wed, 20 Dec 2023 17:28:34 +0000 (18:28 +0100)]
unix.7: SO_PEERCRED: Mention listen(2)
In case of connected AF_UNIX stream sockets, server-side credentials are
set at the time of a call to listen(2), not when client-side calls
connect(2).
This is important if server side process changes UID/GID after listen(2)
and before connect(2).
Reproducer is available in [1].
Behavior was confirmed in the email thread [2].
string_copying.7: Use NITEMS() instead of sizeof()
For these byte functions, sizeof() works as well as NITEMS(), since
CHAR_BIT == 1. However, equivalent wide-character functions need
NITEMS(), which is semantically more appropriate, and also safer (it
cannot be applied to pointers).
Yafang Shao [Fri, 8 Dec 2023 09:05:53 +0000 (09:05 +0000)]
mbind.2: Add mode flag MPOL_F_NUMA_BALANCING
In Linux Kernel 5.12, a new mode flag, MPOL_F_NUMA_BALANCING, was
added to set_mempolicy() to optimize the page placement among the
NUMA nodes with the NUMA balancing mechanism even if the memory of
the applications is bound with MPOL_BIND.
In Linux Kernel 5.15, this mode flag was extended to mbind(2). Let's
also add man-page for mbind(2). It is copied from set_mempoicy(2)
man-page with subtle modifications.
projects / thirdparty / man-pages.git / log
