scripts/LinuxManBook/: Simplify pipeline

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>

strtol.3, strtoul.3: ERRORS: Clarify that these don't set errno on success

That's a guarantee made by POSIX.

Reported-by: Jakub Wilk <jwilk@jwilk.net>
Cc: Florian Weimer <fweimer@redhat.com>
Cc: Iker Pedrosa <ipedrosa@redhat.com>
Cc: Michael Kerrisk <mtk.manpages@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

posix_memalign.3: wfix

Remove superfluous words.

Suggested-by: Jonny Grant <jg@jguk.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

posix_memalign.3: ERRORS: wfix

Simplify, and make it consistent with malloc(3).

Suggested-by: Jonny Grant <jg@jguk.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

scripts/LinuxManBook/: Shorten names of scripts

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>

proc_sys_user.5: tfix

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

proc_pid_oom_score_adj.5: tfix

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

proc_pid_mountinfo.5: spfix

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

proc_crypto.5: spfix

"Cypher" is a valid but less common spelling of "cipher".
The latter is used everywhere else, so let's use it here too.

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

pthread_key_create.3: tfix

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

CONTRIBUTING: Say it's us who recommend signing emails

Also link to <gnupg.org>, since they also recommend it.

Suggested-by: "G. Branden Robinson" <branden@debian.org>
Acked-by: "G. Branden Robinson" <branden@debian.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

scripts/LinuxManBook/prepare_linux_man_book.pl: Don't support trailing white space nor \r

Signed-off-by: Alejandro Colomar <alx@kernel.org>

*: Remove trailing white space

Scripted change:

$ grep -rl '\s$' | xargs sed -i 's/ * * *$//g'

Signed-off-by: Alejandro Colomar <alx@kernel.org>

scripts/LinuxManBook/build_linux_man_book.sh: Simplify groff(1) call

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.

Signed-off-by: Alejandro Colomar <alx@kernel.org>

scripts/LinuxManBook/build_linux_man_book.sh: Explicitly preprocess before calling groff(1)

Signed-off-by: Alejandro Colomar <alx@kernel.org>

scripts/LinuxManBook/build_linux_man_book.sh: Allow running from any working directory

Signed-off-by: Alejandro Colomar <alx@kernel.org>

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).

Signed-off-by: Alejandro Colomar <alx@kernel.org>

CONTRIBUTING: Please sign your emails with PGP

Cc: Matthew House <mattlloydhouse@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

stpncpy.3: Rename third parameter to 'dsize'

This better clarifies that the size is of dst.

Signed-off-by: Alejandro Colomar <alx@kernel.org>

scripts/LinuxManBook/build_linux_man_book.sh: License

Signed-off-by: Alejandro Colomar <alx@kernel.org>

scripts/LinuxManBook/prepare_linux_man_book.pl: Use a helper function for building pages

Signed-off-by: Alejandro Colomar <alx@kernel.org>

scripts/LinuxManBook/prepare_linux_man_book.pl: wsfix

Signed-off-by: Alejandro Colomar <alx@kernel.org>

stpncpy.3: Reword, saying 'byte' instead of 'character'

These functions are also used with multi-byte characters, so character
can be confusing.

Suggested-by: Paul Eggert <eggert@cs.ucla.edu>
Cowritten-by: Paul Eggert <eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

stpncpy.3: EXAMPLES: errx(3) instead of warnx(3) if truncation occurs

Truncation is not acceptable in most cases.  Don't suggest that it's
just fine.

Signed-off-by: Alejandro Colomar <alx@kernel.org>

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>

stpncpy.3: NAME: Clarify that these functions only pad if necessary

Suggested-by: Paul Eggert <eggert@cs.ucla.edu>
Cowritten-by: Paul Eggert <eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

stpncpy.3: Optimize possible implementation of stpncpy()

Don't zero twice, since it can be confusing.  Since bzero(3) returns
void, we need memset(3) here.

Reported-by: Paul Eggert <eggert@cs.ucla.edu>
Cowritten-by: Paul Eggert <eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

stpncpy.3: SYNOPSIS: ffix

Reported-by: Paul Eggert <eggert@cs.ucla.edu>
Cowritten-by: Paul Eggert <eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

stpncpy.3: Don't say 'width' when 'size' is meant

Reported-by: Paul Eggert <eggert@cs.ucla.edu>
Cowritten-by: Paul Eggert <eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

strncat.3: CAVEATS: wfix

Signed-off-by: Alejandro Colomar <alx@kernel.org>

strncat.3: Reword description

While rewording, use "byte" instead of "character".  This function is
also used with multi-byte characters, so character can be confusing.

Suggested-by: Paul Eggert <eggert@cs.ucla.edu>
Cowritten-by: Paul Eggert <eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

strncat.3: Say that if dst isn't a string, the behavior is undefined

Suggested-by: Paul Eggert <eggert@cs.ucla.edu>
Cowritten-by: Paul Eggert <eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

strncat.3: SEE ALSO: tfix

Reported-by: Paul Eggert <eggert@cs.ucla.edu>
Cowritten-by: Paul Eggert <eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

strncat.3: EXAMPLES: Fix name of variable

It was called maxsize, but it was really a number of elements.  And it
wasn't maximum; it was exact.

Reported-by: Paul Eggert <eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

strncat.3: Simplify possible implementation of strncat()

Cowritten-by: Paul Eggert <eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

strncat.3: Rename third parameter to ssize

This better clarifies that the size is of src.

Signed-off-by: Alejandro Colomar <alx@kernel.org>

strncat.3: Fix bug in possible implementation of strncat(3)

Reported-by: Paul Eggert <eggert@cs.ucla.edu>
Cowritten-by: Paul Eggert <eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

strncat.3: SYNOPSIS: ffix

Reported-by: Paul Eggert <eggert@cs.ucla.edu>
Cowritten-by: Paul Eggert <eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

strncat.3: Don't say 'width' when 'size' is meant

Reported-by: Paul Eggert <eggert@cs.ucla.edu>
Cowritten-by: Paul Eggert <eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

strncat.3: Say append instead of (con)catenate

Cowritten-by: Paul Eggert <eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

scripts/LinuxManBook/: Split the pipeline for building the Linux Man Book

This helps understand how this book is built.  The Perl script was too
magic for my taste.  Now it does less magic.  :)

Signed-off-by: Alejandro Colomar <alx@kernel.org>

README: Versions: Document PDF books in <https://www.alejandro-colomar.es/share/dist/man-pages/>

I also publish the books in my server.  See for example:
<https://www.alejandro-colomar.es/share/dist/man-pages/6/6.05/6.05.01/>

Signed-off-by: Alejandro Colomar <alx@kernel.org>

man*/: srcfix

Clean up in preparation for "MR sed".

Format only one man page cross reference per input line.

Begin parentheticals on their own input lines.

Also, groff 1.23.0's (and Plan 9 from User Space's) `MR` is not a font
style alternation macro; there is no "reversed" form as with `BR` and
`RB`.  So when a man page cross reference must be immediately preceded
by punctuation, put that punctuation on the previous text line and use
the `\c` escape sequence to connect them.

Signed-off-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

mbsrtowcs.3: Clarify that mbsrtowcs(3) is a restartable version of mbstowcs(3)

Signed-off-by: Alejandro Colomar <alx@kernel.org>

mbsrtowcs.3: Clarify how to ensure a full conversion

This text is based on a similar one from mbstowcs(3).

Suggested-by: Andriy Utkin <andriy_utkin@fastmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

ffs.3: All these functions live in <strings.h>.

In most cases you'll get them transitively through <string.h>, but it's
misleading for the man page to claim that they're _in_ <string.h>, and
especially weird to claim they're in _different_ headers from each
other!

This is also true of Apple's headers, and FreeBSD (the other BSDs only
have ffs(), not its siblings).

Signed-off-by: Elliott Hughes <enh@google.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

mbstowcs.3: Reorder text

So that it appears in the same order as in mbsrtowcs(3), for being able
to diff(1) the two pages.

Signed-off-by: Alejandro Colomar <alx@kernel.org>

mbsrtowcs.3, mbstowcs.3: Remove unnecessary references to the function name

This allows diffing both pages, which are very similar:

$ diff -u <(man mbstowcs) <(man mbsrtowcs)

Signed-off-by: Alejandro Colomar <alx@kernel.org>

mbsrtowcs.3, mbstowcs.3: Use dsize for dst size; not len, and not n

This makes it clear that it's a size, not a length.

Signed-off-by: Alejandro Colomar <alx@kernel.org>

string.3: strncpy(): wfix

Say "size" not "width" for byte counts; "width" is for the number of
bits in a word.  Say "leading" to make it clear we don’t care about what
the source contains after its first null byte.

Signed-off-by: Alejandro Colomar <alx@kernel.org>

string.3: strncpy(): Talk about bytes, not characters

These functions are also the way to copy multibyte strings, so be
generic and say that they just copy bytes.  Not every byte is a valid
character in (for example) UTF-8 locales.

Cowritten-by: Paul Eggert <eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

string.3: strncpy(): Reword so as to not imply the result has some null padding.

Cowritten-by: Paul Eggert <eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

string.3: tfix

Replace “‐” (U+2020 HYPHEN) with “-” (U+002D HYPHEN-MINUS).

Reported-by: Paul Eggert <eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

stpecpyx.3: Remove link page

* Remove man3/stpecpyx.3; no longer present.

Signed-off-by: Alejandro Colomar <alx@kernel.org>

string_copying.7: Recommend failing instead of truncating

Especially for validating input, code should fail, not truncate.

Signed-off-by: Alejandro Colomar <alx@kernel.org>

stpecpy.3, ustpcpy.3, ustr2stp.3, zustr2stp.3, zustr2ustp.3: Remove link pages that don't correspond to a libc function

Reported-by: Paul Eggert <eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

string_copying.7: Use 'dsize' and 'ssize' for 'dst size' and 'src size'

Signed-off-by: Alejandro Colomar <alx@kernel.org>

string_copying.7: Add strtcpy(3)

Add this new truncating string-copying function.  It intends to fully
replace strlcpy(3), which has important bugs (documented in the
preceeding commit).

It is almost identical to Linux kernel's strscpy(9), so reduce the
documentation of strscpy(9) in this page to the minimum, giving
preference to strtcpy(3).  Provide a reference implementation, since no
libc provides it.

Providing an easy, safe, and relatively fast truncating string-copying
function should prevent users from rolling their own, in which they
might introduce bugs accidentally.  We already made enough mistakes
while discussing these functions, so it's certainly not something that
should be written often.

Cc: Paul Eggert <eggert@cs.ucla.edu>
Cc: Jonny Grant <jg@jguk.org>
Cc: DJ Delorie <dj@redhat.com>
Cc: Matthew House <mattlloydhouse@gmail.com>
Cc: Oskari Pirhonen <xxc3ncoredxx@gmail.com>
Cc: Thorsten Kukuk <kukuk@suse.com>
Cc: Adhemerval Zanella Netto <adhemerval.zanella@linaro.org>
Cc: Zack Weinberg <zack@owlfolio.org>
Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: Carlos O'Donell <carlos@redhat.com>
Cc: Xi Ruoyao <xry111@xry111.site>
Cc: Stefan Puiu <stefan.puiu@gmail.com>
Cc: Andreas Schwab <schwab@linux-m68k.org>
Cc: Guillem Jover <guillem@hadrons.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

string_copying.7: BUGS: Document strl{cpy,cat}(3)'s performance problems

Also point to BUGS from other sections that talk about these functions.

These functions are doomed due to the design decision of mirroring
snprintf(3)'s return value.  They must return strlen(src), which makes
them terribly slow, and vulnerable to DoS if an attacker can control
strlen(src).

A better design would have been to return -1 when truncating.

Reported-by: Paul Eggert <eggert@cs.ucla.edu>
Cc: Jonny Grant <jg@jguk.org>
Cc: DJ Delorie <dj@redhat.com>
Cc: Matthew House <mattlloydhouse@gmail.com>
Cc: Oskari Pirhonen <xxc3ncoredxx@gmail.com>
Cc: Thorsten Kukuk <kukuk@suse.com>
Cc: Adhemerval Zanella Netto <adhemerval.zanella@linaro.org>
Cc: Zack Weinberg <zack@owlfolio.org>
Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: Carlos O'Donell <carlos@redhat.com>
Cc: Xi Ruoyao <xry111@xry111.site>
Cc: Stefan Puiu <stefan.puiu@gmail.com>
Cc: Andreas Schwab <schwab@linux-m68k.org>
Cc: Guillem Jover <guillem@hadrons.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

string_copying.7: BUGS: *cat(3) functions aren't always bad

The compiler will sometimes optimize them to normal *cpy(3) functions,
since the length of dst is usually known, if the previous *cpy(3) is
visible to the compiler.  And they provide for cleaner code.  If you
know that they'll get optimized, you could use them.

Cc: Paul Eggert <eggert@cs.ucla.edu>
Cc: Jonny Grant <jg@jguk.org>
Cc: DJ Delorie <dj@redhat.com>
Cc: Matthew House <mattlloydhouse@gmail.com>
Cc: Oskari Pirhonen <xxc3ncoredxx@gmail.com>
Cc: Thorsten Kukuk <kukuk@suse.com>
Cc: Adhemerval Zanella Netto <adhemerval.zanella@linaro.org>
Cc: Zack Weinberg <zack@owlfolio.org>
Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: Carlos O'Donell <carlos@redhat.com>
Cc: Xi Ruoyao <xry111@xry111.site>
Cc: Stefan Puiu <stefan.puiu@gmail.com>
Cc: Andreas Schwab <schwab@linux-m68k.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

string_copying.7: wfix

Don't start this paragraph with a fragment.  Also, remove "by nature",
which is superfluous.

Signed-off-by: Alejandro Colomar <alx@kernel.org>

string_copying.7: DESCRIPTION::Functions: ustpcpy() and ustr2stp() are not provided by any libc

Reported-by: Jonny Grant <jg@jguk.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

string_copying.7: RETURN VALUE: ffix

Put the text after the function names, like the rest of the page.

Suggested-by: Jonny Grant <jg@jguk.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

string_copying.7: wfix

Remove superfluous words.

Suggested-by: Jonny Grant <jg@jguk.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

man*/: Improve timestamp documentation

Improve discussion of leap seconds, year-2038 etc.

Cc: Elliott Hughes <enh@google.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

hostname.7: ffix

Add missing man-page reference.

Fixes: 921e2cfd1fc6 ("hostname.7: HOSTALIASES/search path processing is DNS-specific")
Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Cc: Mario Blaettermann <mario.blaettermann@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

README: Update links

-  Mention the mirrors in my web server, both for dist (recently added),
   and git.
-  Use HTTPS for all links.  Remove git: and http: links.

Signed-off-by: Alejandro Colomar <alx@kernel.org>

README: Files: Remove .mailmap

.mailmap was removed with 2231a165.  Therefore, remove its reference
from the README file.

Fixes: 2231a1659621 (".mailmap: Remove file")
Signed-off-by: Florian Lehner <dev@der-flo.net>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

stpncpy.3, string.3, string_copying.7: Clarify that st[rp]ncpy() pad with null bytes

The previous wording could be interpreted as if the nulls were already
in place.  Clarify that it's this function which pads with null bytes.

Also, it copies "characters" from the src string.  That's a bit more
specific than copying "bytes", and makes it clearer that the terminating
null byte in src is not part of the copy.

Suggested-by: Jonny Grant <jg@jguk.org>
Cc: DJ Delorie <dj@redhat.com>
Cc: Matthew House <mattlloydhouse@gmail.com>
Cc: Oskari Pirhonen <xxc3ncoredxx@gmail.com>
Cc: Thorsten Kukuk <kukuk@suse.com>
Cc: Adhemerval Zanella Netto <adhemerval.zanella@linaro.org>
Cc: Zack Weinberg <zack@owlfolio.org>
Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: Carlos O'Donell <carlos@redhat.com>
Cc: Paul Eggert <eggert@cs.ucla.edu>
Cc: Xi Ruoyao <xry111@xry111.site>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

stpncpy.3, string_copying.7: Clarify that st[rp]ncpy() do NOT produce a string

These copy *from* a string.  But the destination is a simple character
sequence within an array; not a string.

Suggested-by: DJ Delorie <dj@redhat.com>
Acked-by: Oskari Pirhonen <xxc3ncoredxx@gmail.com>
Cc: Jonny Grant <jg@jguk.org>
Cc: Matthew House <mattlloydhouse@gmail.com>
Cc: Thorsten Kukuk <kukuk@suse.com>
Cc: Adhemerval Zanella Netto <adhemerval.zanella@linaro.org>
Cc: Zack Weinberg <zack@owlfolio.org>
Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: Carlos O'Donell <carlos@redhat.com>
Cc: Paul Eggert <eggert@cs.ucla.edu>
Cc: Xi Ruoyao <xry111@xry111.site>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

stpncpy.3: tfix

Fixes: 4131356cdab8 ("man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY: Reorganize sections")
Reported-by: Jonathan Wakely <jwakely@redhat.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

bcmp.3: wfix

Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Cc: Mario Blaettermann <mario.blaettermann@gmail.com>
Suggested-by: Stefan Puiu <stefan.puiu@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

regex.7: ffix

Fixes: de9137cb670e ("man-pages 1.20")
Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Cc: Mario Blaettermann <mario.blaettermann@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

setlogmask.3: ffix

Fixes: c06eb28eb622 ("man-pages 1.41")
Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Cc: Mario Blaettermann <mario.blaettermann@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

catan.3: ffix

Fixes: 8d332a95081b ("man-pages 1.57")
Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Cc: Mario Blaettermann <mario.blaettermann@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

readlink.2: tfix (Remove repeated word)

Fixes: f06a3f30fa66 ("readlink.2: Fix an off-by-one error in example code")
Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Cc: Mario Blaettermann <mario.blaettermann@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

syscalls.2: wfix

Fixes: b324e17d3208 ("Many pages: wfix")
Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Cc: Mario Blaettermann <mario.blaettermann@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

posixoptions.7: pfix

Fixes: 17282a589f2f ("posixoptions.7: Make function lists more consistent and less cluttered")
Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Cc: Mario Blaettermann <mario.blaettermann@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

syscalls.2: Mention Linux 6.x series

Suggested-by: Helge Kreutzmann <debian@helgefjell.de>
Cc: Mario Blaettermann <mario.blaettermann@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

malloc_get_state.3: tfix

Fixes: 30ed4712c794 ("chroot.2, dup.2, nfsservctl.2, utimensat.2, malloc_get_state.3, pthread_setaffinity_np.3, ddp.7, fifo.7, ip.7: Remove some out-of-date/obsolete/irrelevant FIXMEs")
Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Cc: Mario Blaettermann <mario.blaettermann@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

getent.1: tfix (Add missing page section)

Fixes: 4a009a370890 ("getent.1: New page to document 'getent' binary provided by glibc")
Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Cc: Mario Blaettermann <mario.blaettermann@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

man*/: wfix (say 'null pointer', not 'NULL pointer')

'NULL' is a null pointer _constant_.  A 'null pointer' is a broader
concept.  'NULL pointer' is not a thing.  See the link below.

Link: <https://software.codidact.com/posts/278657>
Fixes: 9517cf56fcbd ("pidfd_send_signal.2: New page documenting pidfd_send_signal(2)")
Fixes: fcd1bee32aa9 ("bpf.2: Improvements after comments from Daniel Borkmann")
Fixes: 5d92031a43b4 ("execve.2: Explicitly note that argv[argc] == NULL in the new program")
Fixes: 9f79744c9af3 ("keyctl.2: Improve KEYCTL_INSTANTIATE details")
Fixes: 1b6ab34c5320 ("attributes.7: New page describing POSIX safety concepts")
Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Cc: Mario Blaettermann <mario.blaettermann@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

connect.2: ffix

Fixes: d5bc35a7a9cc ("connect.2: wfix")
Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Cc: Mario Blaettermann <mario.blaettermann@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

clone.2: ffix

Fixes: 184ecd225079 ("clone.2: Note EINVAL when exit_signal + bad flags")
Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Cc: Mario Blaettermann <mario.blaettermann@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

prctl.2: tfix (Add a missing TP)

A paragraph break was missing in the enumeration of possible reasons for EINVAL.

Fixes: 8165500d4c9c ("prctl.2: Add PR_PAC_RESET_KEYS (arm64)")
Signed-off-by: Bruno Haible <bruno@clisp.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

prctl.2: Use a better term

The first argument of prctl() was denoted as "option" here.  This makes
no sense, because
-  The first argument is not optional; it is mandatory.
   A choice is an "option" only if it is possible to choose none of
   the available choices.
-  The title of the page is "operations on a process or thread".

A better term is "operation".

Cc: Stefan Puiu <stefan.puiu@gmail.com>
Acked-by: Elliott Hughes <enh@google.com>
Signed-off-by: Bruno Haible <bruno@clisp.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

clone.2: Clarify that CLONE_CLEAR_SIGHAND does not affect SIG_IGN

The old wording was ambiguous, but it is important to know that signals
that were set to SIG_IGN will not be restored to SIG_DFL.

This behavior was documented in the kernel commit that introduced the
feature, in the link below.

Link: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=b612e5df4587c934bd056bf05f4a1deca4de4f75>
Signed-off-by: Max Kellermann <max.kellermann@ionos.com>
[alx: semantic newline; tweak commit message]
Signed-off-by: Alejandro Colomar <alx@kernel.org>

ld.so.8: Describe glibc Hardware capabilities

The feature was added on glibc 2.33 as a way to improve the path search,
since the legacy hardware capabilities combination scheme does not scale
properly with new hardware support.  The legacy support was removed non
glibc 2.37, so it is the only scheme currently supported.

Reviewed-by: Stefan Puiu <stefan.puiu@gmail.com>
Signed-off-by: Adhemerval Zanella <adhemerval.zanella@linaro.org>
[alx: ffix, srcfix, semantic newlines]
Signed-off-by: Alejandro Colomar <alx@kernel.org>

man*/: srcfix (Use .P instead of .PP or .LP)

We're trying to "standardize" on a paragraphing macro from the three
equivalent ones (P, PP, LP).  We (somewhat arbitrarily) agreed on P.

Scripted change:

$ find man* -type f | xargs sed -i '/\.PP/s/PP/P/'
$ find man* -type f | xargs sed -i '/\.LP/s/LP/P/'

Suggested-by: "G. Branden Robinson" <branden@debian.org>
Cc: Ingo Schwarze <schwarze@openbsd.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

strerror.3: Document the string produced by 'strerrorname_np(0);'

Reported-by: Alexander Kozhevnikov <mentalisttraceur@gmail.com>
Link: <https://stackoverflow.com/questions/19885360/how-can-i-print-the-symbolic-name-of-an-errno-in-c/>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

man*/: ffix (Place short options after long options)

This increases the chances that the paragraph will start in the same
line as the tag, wasting less vertical space.

The result seems visually better to me.

On Wed, Oct 25, 2023 at 09:11:03AM -0500, G. Branden Robinson wrote:
> I also like your suggestion that if we really want to economize on
> space, we could present a command's long option form before its short,
> old-style Unix synonym, which will work well when the short option (plus
> its argument, if any) fits within the space for the paragraph tag.  This
> might be a good idea for another reason; in GNU user space, the long
> option is the much more self-documenting form, and the single-character
> option name a kind of "expert mode" alternative.  As a general rule,
> when presenting technical material, one should not lead with "expert
> mode".

Cc: Ingo Schwarze <schwarze@openbsd.org>
Cc: "G. Branden Robinson" <branden@debian.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

iconv.1: ffix (Use TQ where appropriate)

This one was missed in 6fdb1c03075b, becuase it wasn't caught by the
regex I used.  I found it by accident, and there may be other cases
around.

Fixes: 6fdb1c03075b ("man*/: ffix (Use '.TQ' where appropriate)")
Acked-by: "G. Branden Robinson" <branden@debian.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

smartpqi.4: HISTORYise sysfs entry "version"

Remove the "version" sysfs entry.  This entry was changed into
two sysfs entries: driver_version and firmware_version by
patch "(6d90615f1346 scsi: smartpqi: add sysfs entries)" in Linus's
tree Aug 22 2019.

Add HISTORY section.
Enumerate old sysfs entries replaced by newer entries.

Suggested-by: Alejandro Colomar <alx@kernel.org>
Signed-off-by: Don Brace <don.brace@microchip.com>
[alx: tweak commit message]
Signed-off-by: Alejandro Colomar <alx@kernel.org>

smartpqi.4: Add device attributes

Add in some device level sysfs entry descriptions:
lunid
unique_id
path_info
raid_bypass_cnt
sas_ncq_prio_enable

These have already been provided by the driver.

Reviewed-by: Scott Benesh <scott.benesh@microchip.com>
Reviewed-by: Scott Teel <scott.teel@microchip.com>
Reviewed-by: Mike McGowen <mike.mcgowen@microchip.com>
Reviewed-by: Kevin Barnett <kevin.barnett@microchip.com>
Signed-off-by: Don Brace <don.brace@microchip.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

smartpqi.4: Say "volumes" instead of "drives"

Change the word "drives" to "volumes" to match our documentation and how
they are presented to SCSI Mid-layer: as "LOGICAL VOLUMES".

I.E.
[0:1:0:0]    disk    HP       LOGICAL VOLUME   7.02  /dev/sdc

Reviewed-by: Scott Benesh <scott.benesh@microchip.com>
Reviewed-by: Scott Teel <scott.teel@microchip.com>
Reviewed-by: Mike McGowen <mike.mcgowen@microchip.com>
Reviewed-by: Kevin Barnett <kevin.barnett@microchip.com>
Signed-off-by: Don Brace <don.brace@microchip.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

ioctl_pagemap_scan.2: Add page for pagemap_scan IOCTL

Link: <https://lore.kernel.org/all/20231018213453.BF1ACC43395@smtp.kernel.org>
Signed-off-by: Muhammad Usama Anjum <usama.anjum@collabora.com>
[alx: ffix]
Signed-off-by: Alejandro Colomar <alx@kernel.org>

man*/: ffix (Use '.TQ' where appropriate)

When there are multiple tags for a paragraph, using a single TP and
separating the tags with commas makes the man(7) source more complex.
It also has a disadvantage: when searching through a manual page,
heuristics such as "   --option" don't work so well.

By using GNU's TQ, we simplify the source of the pages, and improve the
ability to search them.

Signed-off-by: Alejandro Colomar <alx@kernel.org>

getent.1: ffix (Simplify indentation)

Signed-off-by: Alejandro Colomar <alx@kernel.org>