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.
strtol.3: Clarify that the base should be tested beforehand, if at all
Normally, the base need not be tested, and the only interesting errno
value should be ERANGE.
If the base needs to be tested, it should be tested in a call that
would not otherwise fail. Otherwise, it would be easy to trigger
Undefined Behavior. Consider the following example:
errno = 0;
val = strtol("foo", &end, -42);
There's no portable way to know if the call failed due to the string or
the base.
Cc: Matthew House <mattlloydhouse@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
sscanf.3: Remove term 'deprecated', and expand BUGS
Several programmers have been confused about this use of 'deprecated'.
Also, maximum field width can be used with these fields to mitigate the
problem. Still, it's only a mitigation, since it limits the number of
characters read, but that means an input of LONG_MAX+1 --which takes up
the same number of characters than LONG_MAX-- would still cause UB; or
one can limit that to well below the limit of UB, but then it
artificially invalidates valid input. No good way to avoid UB with
sscanf(3), but it's not necessarily bad with trusted input (and
strtol(3) isn't the panacea either: it avoids UB, but error checking is
hard; strtoi(3) is good, though, but not standard).
For the functions that are designed to be used with utmp(5) or similar
APIs, use utmp(5) in the example, which results in a clearer example,
and also more realistic. It better clarifies how these functions are to
be used.
Users reported complains about having so many invented functions, and
the complexity of remembering all of them.
In these two cases, open-coding mempcpy(3) isn't so bad. In fact, it's
quite readable. It has the problem of type safety, since this function
accepts almost everything, but let users come up with a wrapper if they
need it; it's not like you would be calling these functions often.
Document how to use mempcpy(3) well in those cases.
Cc: "Serge E. Hallyn" <serge@hallyn.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Call the groff(1) pipeline only once. This optimizes around 2 seconds,
while also simplifying the code.
This change was originally written by Deri, with some parts written by
Brian. I took the script that Deri sent, and split it so that the
groff(1) pipeline is called from the shell script, and the Perl script
is limited to editing the man(7) pages. This helps me understand the
process, since my understanding of Perl is very limited. It also makes
this change smaller, so that it's less of a big-bang.
Link: <https://lore.kernel.org/linux-man/ZWkO4qPC4BxkwBNm@debian/T/#m3d453440b02dd189bc12d2e629c4026206025b40> Co-developed-by: Deri James <deri@chuzzlewit.myzen.co.uk> Co-developed-by: Brian Inglis <Brian.Inglis@Shaw.ca> Signed-off-by: Alejandro Colomar <alx@kernel.org>
scripts/LinuxManBook/prepare_linux_man_book.pl: Add new function BuildSec()
The intention is to move some code from BuildPage() into this function,
reducing the complexity of that inner function. As a side effect, just
by adding this function, I've already noticed an optimization of 0.3 s.
The reason, I guess, is that it starts processing pages without waiting
for the entire sort to complete, which reduces the latency of the script.
Cc: Deri James <deri@chuzzlewit.myzen.co.uk> Signed-off-by: Alejandro Colomar <alx@kernel.org>
scripts/LinuxManBook/build_linux_man_book.sh: Call pic(1), and call it after preconv(1)
Call it, just in case we want to use in manual pages in the future. It
doesn't hurt performance. And call it after preconv(1), which should be
the first program in the groff(1) pipeline.
Suggested-by: Deri James <deri@chuzzlewit.myzen.co.uk> Signed-off-by: Alejandro Colomar <alx@kernel.org>
We're suppressing formatted device-independent output of troff(1),
so it doesn't make sense to pass an option to gropdf(1) with -P.
We don't need the fonts either. We don't even need groff(1), since
we're only using troff(1).
Redirect to /dev/null, instead of using -z. It's more explicit.
scripts/LinuxManBook/build_linux_man_book.sh: Use pipes instead of temporary files
It's still easy to debug, by inserting |tee /dev/tty|, but the script
is cleaner if it doesn't generate intermediary files, and it's also
faster (on my desktop computer, it goes down from 18.5 s to 16.3 s).
stpncpy.3: EXAMPLES: Use fwrite(3) instead of printf(3)
fwrite(3) is more appropriate for printing a character sequence with
known lenght. printf(3) has a limitation of INT_MAX, and also requires
more complex (less readable) code.
Suggested-by: Paul Eggert <eggert@cs.ucla.edu> Cowritten-by: Paul Eggert <eggert@cs.ucla.edu> Signed-off-by: Alejandro Colomar <alx@kernel.org>
projects / thirdparty / man-pages.git / log
