Changes: Ready for 6.05

The commands shown in the commit message for d4e80a7748ea ("Changes:
Ready for 6.01") were slightly wrong; let's update them:

A few useful commands:

List of contributors:

$ git log man-pages-6.04..HEAD \
  | grep '<.*@.*>' \
  | sed 's/^ *//' \
  | sed 's/[^:]*: //' \
  | sort \
  | uniq;

List of new pages:

$ git diff man-pages-6.04..HEAD \
  | grep -A1 '^--- /dev/null' \
  | grep -v -e '\--' -e '\--- /dev/null' \
  | sed 's,+++ b/,,' \
  | grep '^man' \
  | xargs grep -L '^\.so ' \
  | sed 's,.*/,,';

List of new links:

$ git diff man-pages-6.04..HEAD \
  | grep '^+++ ' \
  | sed 's,+++ b/,,' \
  | grep '^man' \
  | xargs grep -l '^\.so ' \
  | sed 's,.*/,,';

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

RELEASE: Recommend checking the latest releases

Instead of pointing to specific releases, suggest checking all 6.*
releases.  Show the commands necessary to do so.

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

ipv6.7: srcfix

Protect literals in a (very long) paragraph tag from hyphenation by
using hypenation control escape sequences, instead of `nh` and `hy`
requests.  The latter approach is incorrect for use with groff(1) since
'.hy' does not restore the previous hyphenation mode but sets it to 1,
which is not appropriate for the English-language hyphenation patterns
groff uses.  (Also, AT&T man(7) used a hyphenation mode of 14.)

Also wrap long input line with \newline escape sequence.

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

setnetgrent.3, unlocked_stdio.3: ffix

Stop attempting to manipulate adjustment outside of tbl(1) text blocks.

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

man3/: srcfix

Clean up in preparation for "MR sed".

Protect (non-cross-referenced) man page names from hyphenation.  Use the
hyphenation control escape sequence `\%` to do this rather than
bracketing a region of the page with `na` and `hy` requests, which
enables automatic hyphenation even when it is not desired and uses the
wrong hyphenation mode for English to boot.

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

pthread_setcancelstate.3: ffix

Clean up in preparation for "MR sed".

Protect man page name from hyphenation.  `MR` will take care of
that for us; this change is to detect a regression when migrating to it.

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

pthread_setcancelstate.3: srcfix

Continue commit 9e54434ead, 19 July.

Fix half-bracketed table that didn't turn hyphenation off prior to the
`TS` call in the first place.

Fizes: 9e54434ead ("man*/: ffix (un-bracket tables)")
Signed-off-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

termios.3: srcfix

Continue commit 9e54434ead, 19 July.

Fix an anomalously bracketed table, not detected by my sed script
because of the intrusion of a *roff comment.

Fizes: 9e54434ead ("man*/: ffix (un-bracket tables)")
Signed-off-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

man*/: ffix (un-bracket tables, continued)

Continue commit 9e54434ead, 19 July.

4 pages issued requests to manipulate adjustment and automatic
hyphenation around tbl(1) tables in a different order from the other 525
documents in the tree that performed this trick.

I produced this change with the following GNU sed script.

/^\.nh/{N;/\n\.ad l/{N;/\n\.TS/s/.*/.TS/}}
/^\.TE/{N;/\n\.ad/{N;/\n\.hy/s/.*/.TE/}}

Fizes: 9e54434ead ("man*/: ffix (un-bracket tables)")
Signed-off-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

syscalls.2: srcfix

Clean up in preparation for "MR sed".

Use font style alternation macros instead of font selection escape
sequences to mark up man page cross references in table entry text
blocks.  Also protect them from hyphenation.  (`MR` will take care of
that for us.)

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

memcmp.3: Recast security caveat

Use terminology more carefully.

* Refer to the info sec property of confidentiality[1] instead of saying,
  vaguely, "security-critical".
* Try not to confuse anyone who's studied the analysis of algorithms:
  don't say "constant time" when "deterministic time" is meant.  The
  time to perform the memory comparison remains linear (O(n)), not
  constant (O(1)).
* Tighten wording.

Link: [1] <https://informationsecurity.wustl.edu/items/confidentiality-integrity-and-availability-the-cia-triad/>
Signed-off-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

time.1: ffix

Mark up ellipses properly.  They should be in roman.  The item preceding
an ellipsis should be in the singular.  Use unbreakable space between
metasyntactic variable and subsequent ellipsis.  (Whitespace-separated
arguments should be separated from a subsequent ellipsis.  "[-v...]"
suggests that both "-vv" and "-v -v" are permitted; "[-v ...]" suggests
only the latter.)

Quoting groff_man_style(7):

    • Symbols that are neither to be typed literally nor replaced at the
      user’s discretion appear in the roman style; brackets surround
      optional arguments, and an ellipsis indicates that the previous
      syntactical element may be repeated arbitrarily.
[...]
    • The dummy character escape sequence \& follows the ellipsis when
      further text will follow after space on the output line, keeping
      its last period from being interpreted as the end of a sentence
      and causing additional inter‐sentence space to be placed after it.
[...]
    \|  Thin space (one‐sixth em on typesetters, zero‐width on
        terminals); a non‐breaking space.  Used primarily in ellipses
        (“.\|.\|.”) to space the dots more pleasantly on typesetting
        devices like dvi, pdf, and ps.
[...]
    Several features of the above example are of note. [...]

    • The non‐breaking adjustable space escape sequence \~ is used to
      prevent the output line from being broken within the option
      brackets; see subsection “Portability” below.
[...]
    • Why doesn’t the package provide a string to insert an ellipsis?
        Examples of ellipsis usage are shown above, in subsection
        “Command synopsis macros”.  The idiomatic roff ellipsis is three
        dots (periods) with thin space escape sequences \| internally
        separating them.  Since dots both begin control lines and are
        candidate end‐of‐sentence characters, however, it is sometimes
        necessary to prefix and/or suffix an ellipsis with the dummy
        character escape sequence \&.  That fact stands even if a string
        is defined to contain the sequence; further, if the string ends
        with \&, end‐of‐sentence detection is defeated when you use the
        string at the end of an actual sentence.  (Ending a sentence
        with an ellipsis is often poor style, but not always.)  A
        hypothetical string EL that contained an ellipsis, but not the
        trailing dummy character \&, would then need to be suffixed with
        the latter when not ending a sentence.

            Instead of...              ...do this.
        ──────────────────────────────────────────────────
        .ds EL \&.\|.\|.         Arguments are
        Arguments are            .IR src‐file\~ .\|.\|.\&
        .IR src‐file\~ \*(EL\&   .IR dest‐dir .
        .IR dest‐dir .
        ──────────────────────────────────────────────────

        The first column practices a false economy; the savings in
        typing is offset by the cost of obscuring even the suggestion of
        an ellipsis to a casual reader of the source document, and
        reduced portability to non‐roff man page formatters that cannot
        handle string definitions.

        There is an ellipsis code point in Unicode, and some fonts have
        an ellipsis glyph, which some man pages have accessed in a non‐
        portable way with the font‐dependent \N escape sequence.  We
        discourage the use of these; on terminals, they may crowd the
        dots into a half‐width character cell, and will not render at
        all if the output device doesn’t have the glyph.  In syntax
        synopses, missing ellipses can cause great confusion.  Dots and
        space are universally supported.

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

pipe.2: tfix: refer to correct section

Commit 4131356cdab8 reorganized the sections a bit breaking the
reference.  Fix it.

Fixes: 4131356cdab8 ("man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY: Reorganize sections")
Signed-off-by: Thomas Weißschuh <thomas@t-8ch.de>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

string_copying.7: tfix

On some of the commas: There are a few of instances of

Subject verb object partclause, advphrase.

For example:

This function catenates the input character sequence
| subject     | verb    | object                   |

contained in a null-padded wixed-width buffer,
| participial clause                        |

into a destination string.
| adverbial phrase       |

Imagining the participial clause away, there shouldn't be a comma
preceding the restrictive adverbial phrase: The input character sequence
is really, always catenated into a destination string; that is
essential. For example:

This function catenates the input character sequence into
a destination string.

The participial clause, being non-restrictive---there is but one input
character sequence that could be meant---, should be enclosed by commas.
That is the existing comma's purpose and doesn't work without the added,
first comma.

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

man.7: ffix

The `\c` escape sequence works in an argument to a macro call that is
part of a paragraph tag with font style alternation macros, but not the
ordinary font macros `B` and `I`.  This is because `TP`, `B`, and `I`
all set up input traps; the six font style alternation macros do not.

The old formatting would, for some versions of some formatters, set the
"[trailer]" text as part of the paragraph body, not the tag--like this.

       .UE    [trailer] Terminate the link text  of  the  preceding  .UR
              macro,  with  the  optional trailer (if present, usually a
(and so on)

This was a poorly understood--and undocumented--interaction of man(7)
features until recently.  Gory details involving nroff on Unix Version 7
(1979) running on a simulated PDP-11/45 are available.[1]

Here is a comparison of the former and new markup.

before
======
groff 1.22.3: BAD
groff 1.22.4: GOOD
groff 1.23.0: BAD
mandoc 1.14.6: BAD

now
===
groff 1.22.3: BAD
groff 1.22.4: GOOD
groff 1.23.0: GOOD
mandoc 1.14.6: GOOD

[1] https://savannah.gnu.org/bugs/?51468
    https://lists.gnu.org/archive/html/groff/2022-06/msg00020.html

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

string_copying.7: don't grant strl{cpy,cat} magic

A function can't check whether a pointer points to the start of a
string.  What it certainly can do is to keep reading until you either
find a null byte or read the secret key that lies adjacent in memory and
post it to your favorite mailing list.

strlcpy and strlcat behave the exact same way any other function
accepting a string behaves:  If you don't pass a string, the behavior is
undefined.  And that, I believe, does not deserve a special mention
here, seeing as all the other string functions don't get such a mention
either.

Link: <https://lore.kernel.org/linux-man/ZMQVYtquNN-s0IJr@beryllium/T/#u>
Signed-off-by: Lennart Jablonka <humm@ljabl.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

prctl.2: Use mathematical notation for a range

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

man*/: srcfix

[Clean up in preparation for "MR sed".]

Drop spurious, nilpotent uses of *roff `\c` escape sequence.

Quoting groff_man_style(7):

    \c  End a text line without inserting space or attempting a break.
        Normally, if filling is enabled, the end of a text line is
        treated like a space; an output line _may_ be broken there (if
        not, an adjustable space is inserted); if filling is disabled,
        the line _will_ be broken there, as in .EX/.EE examples.  The
        next line is interpreted as usual and can include a macro call
        (contrast with \newline).  \c is useful when three font styles
        are needed in a single word, as in a command synopsis.

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

vfork.2: ffix

[Clean up in preparation for "MR sed".]

* Use typographer's quotation marks.
* Quote the 4.2BSD vfork(2) page _exactly_, including font styling.

https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.2BSD/usr/man/man2/vfork.2

This is to remove a false positive in preparation for a sed(1)-driven
update of man page cross references to use the groff 1.23.0 `MR` macro.

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

man.7: srcfix

[Clean up in preparation for "MR sed".]

Drop spurious uses of *roff `\&` escape sequence.

Quoting groff_man_style(7):

    \&  Dummy character.  Insert at the beginning of an input line to
        prevent a dot or apostrophe from being interpreted as beginning
        a roff control line.  Append to an end‐of‐sentence punctuation
        sequence to keep it from being recognized as such.

Neither case applies to the uses in this page.

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

gettimeofday.2: Add details about the nullability of tv in different libc's

tv arg is allowed to be NULL in bionic.

POSIX says this behavior is undefined, and bionic just exposes the Linux
syscall directly.  There's no code in bionic for
gettimeofday/settimeofday; just a description of the syscall name and
arguments from which an assembler stub is automatically generated at
build time.  musl and glibc go out of their way to behave differently
from the Linux kernel, but no idea why.

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

bpf.2: Added missing EAGAIN error case for BPF_PROG_LOAD

Since commit c3494801cd1785e2 ("bpf: check pending signals while
verifying programs"), bpf() may also fail with EAGAIN if the verifier
detects pending signals.

This was triggered in the cmld of GyroidOS when loading a cgroups device
program during container start.  We had a look in the man page and were
confused that EAGAIN was not listed as possible error.  Digging in the
kernel source revealed the EAGAIN in the verifier introduced by the
commit above.  Further investigation showed that libbpf already wraps
that case, by a retry loop.

Since GyroidOS uses the system call directly and not libbpf, we missed
to handle this error correctly.  Thus, this hint in the man page for the
bpf() system call should be helpful for others who implement on the
low-level interface, too.

Signed-off-by: Michael Weiß <michael.weiss@aisec.fraunhofer.de>
Cc: Alexei Starovoitov <ast@kernel.org>
[alx: wfix]
Signed-off-by: Alejandro Colomar <alx@kernel.org>

abort.3: Clarify consequences of calling abort()

Clarify that atexit(3)/on_exit(3) are not called because those are
called only on normal process termination (as documented on their
respective manual pages).

Check with the following test program:

```c
 #define _DEFAULT_SOURCE

 #include <stdio.h>
 #include <stdlib.h>

void one(void)
{
    puts("atexit called");
}

void two(int, void*)
{
    puts("on_exit called");
}

int main(void)
{
    atexit(one);
    on_exit(two, NULL);

    puts("terminating");
    //abort();
    exit(EXIT_SUCCESS);
}
```

Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: Stefan Puiu <stefan.puiu@gmail.com>
Signed-off-by: Tomáš Golembiovský <tgolembi@redhat.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

tmpfs.5: Update reference to CONFIG_TRANSPARENT_HUGEPAGE

In commit 462a385e9a2 ("tmpfs.5: Document current mount options"), there
is a reference to CONFIG_TRANSPARENT_HUGE_PAGECACHE. However, that
option was removed from the kernel via commit 396bcc5299c2 ("mm: remove
CONFIG_TRANSPARENT_HUGE_PAGECACHE"), a couple of years later.

The net effect is that CONFIG_TRANSPARENT_HUGEPAGE is now used in all
the remaining places in the kernel where
CONFIG_TRANSPARENT_HUGE_PAGECACHE had previously been used.

This has caused some minor confusion at the man page level, though. So
let's fix it by updating the man page to refer to
CONFIG_TRANSPARENT_HUGEPAGE.

Reported-by: Vahid Noormofidi <vnoormof@nvidia.com>
Cc: Matthew Wilcox (Oracle) <willy@infradead.org>
Cc: Kirill A. Shutemov <kirill.shutemov@linux.intel.com>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: Carsten Grohmann <carstengrohmann@gmx.de>
Cc: Mike Frysinger <vapier@gentoo.org>
Signed-off-by: John Hubbard <jhubbard@nvidia.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

man*/: ffix (un-bracket tables)

*  Stop disabling adjustment and automatic hyphenation before tables,
   and incorrectly "restoring" it afterward.  In addition to repetitious
   boilerplate around tables, the `ad` and `hy` requests, when not given
   arguments, do not behave as many man page authors expect.  If
   adjustment was initially disabled when rendering the page, it was
   being activated after `TE` calls, frustrating the desire of the
   reader.  Furthermore, `hy` when given no argument enables automatic
   hyphenation in mode "1", which is not an appropriate value for the
   TeX-based hyphenation patterns for English that groff has used for
   over 30 years.  And analogously to `ad`, a simple `hy` request would
   reactivate automatic hyphenation even if the reader had disabled it.

   Moreover, such fiddling is often unnecessary.  tbl(1) from groff
   1.23.0 describes how tbl(1) has always worked, dating back to Michael
   Lesk's original implementation at Bell Labs in the 1970s.

   "Ordinarily, a table entry is typeset rigidly.  It is not filled,
   broken, hyphenated, adjusted, or populated with additional inter-
   sentence space.  ...  Text blocks are formatted as was the text prior
   to the table, modified by applicable column descriptors.  ...  Add na
   or ad requests to the beginning of a text block to alter its
   adjustment distinctly from other text in the document.  As with other
   table entries, when a text block ends, any alterations to formatting
   parameters are discarded.  They do not affect subsequent table
   entries, not even other text blocks."

*  Apropos of the foregoing, add `na` and `nh` requests to the
   "Interface" columns of MT-safety tables in pages' "ATTRIBUTES"
   sections, so that C function names are not inappropriately hyphenated.

I produced this change with the following GNU sed script.

:start
/^\.ad l/{N;/\n\.nh/{N;/\n\.TS/s/.*/.TS/}}
/^\.TE/{N;/\n\.hy/{N;/\n\.ad/s/.*/.TE/}}
/^Interface.*Attribute.*Value/{N;/\nT{/s/.*/&\n.na\n.nh/
:loop
n
/T{/s/.*/&\n.na\n.nh/
/^\.TE/b start;
b loop
}

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

man*/: ffix (use `\%`)

Protect instances of some literals from hyphenation.  These are only
those necessary to improve analyzability of a large-scale (500+ file),
sed-driven change to improve adjustment and hyphenation enablement
management around tables.

*  man2/getrlimit.2: Protect some instances of `RLIMIT_MSGQUEUE`,
   `RLIMIT_SIGPENDING`, `RLIMIT_FSIZE`, and `getrlimit` from
   hyphenation.
*  man2/sigaltstack.2: Protect an instance of `setrlimit` from
   hyphenation.
*  man3/gethostbyname.3: Protect an instance of `endhostent` from
   hyphenation.
*  man3/getmntent.3: Protect an instance of `getmntinfo` from
   hyphenation.

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

recv.2: Document MSG_CMSG_CLOEXEC as returned in msg_flags

Ever since commit 4a19542e5f69 ("O_CLOEXEC for SCM_RIGHTS") added the
MSG_CMSG_CLOEXEC flag to recvmsg(2), the flag has also been copied into
the returned msg->msg_flags when specified, regardless of whether any
file descriptors were actually received, or whether the protocol
supports receiving file descriptors at all.  This behavior was primarily
an implementation artifact: by copying MSG_CMSG_CLOEXEC into the
msg_flags, scm_detach_fds() in net/core/scm.c (and its _compat()
counterpart in net/compat.c) could determine whether it was set without
having to receive a copy of the recvmsg(2) flags.

This mechanism was closely modeled after the internal MSG_CMSG_COMPAT
flag, which is passed by the compat versions of the send[m]msg(2) and
recv[m]msg(2) syscalls to inform various functions that user space
expects a compat layout.  When the flag was first implemented by commits
3225fc8a85f4 ("[NET]: Simplify scm handling and sendmsg/recvmsg
invocation, consolidate net compat syscalls.") and 7e8d06bc1d90
("[COMPAT]: Fix MSG_CMSG_COMPAT flag passing, kill
cmsg_compat_recvmsg_fixup.") (in history/history.git), the behavior was
very similar: recvmsg(2) would add MSG_CMSG_COMPAT to the msg_flags, and
put_cmsg() and scm_detach_fds() in net/core/scm.c would read the flag to
determine whether to delegate to their _compat() counterparts.

However, after the initial implementation, more work was done to hide
MSG_CMSG_COMPAT from user space. First, commit 37f7f421cce1 ("[NET]: Do
not leak MSG_CMSG_COMPAT into userspace.") started scrubbing the bit
from msg_flags right before copying it back into user space.  Then,
since passing the MSG_CMSG_COMPAT flag into the syscalls from non-compat
code could confuse the kernel, commits 1be374a0518a ("net: Block
MSG_CMSG_COMPAT in send(m)msg and recv(m)msg") and a7526eb5d06b ("net:
Unbreak compat_sys_{send,recv}msg") made them return -EINVAL if user
space attempted to pass the flag.  But to reduce breakage, commit
d720d8cec563 ("net: compat: Ignore MSG_CMSG_COMPAT in
compat_sys_{send, recv}msg") rolled that back somewhat, making
MSG_CMSG_COMPAT an error for the non-compat syscalls and a no-op for the
compat syscalls, which is the current status quo.

Even though MSG_CMSG_CLOEXEC was implemented after the kernel started
scrubbing MSG_CMSG_COMPAT from the returned msg_flags, the newer flag
never received the same treatment.  At this point, this behavior has
effectively become part of the user-space API, to the extent that
io_uring has been careful in commit 9bb66906f23e ("io_uring: support
multishot in recvmsg") to replicate the behavior in its multishot
IORING_OP_RECVMSG operation.

Therefore, document this behavior to avoid confusion when user space
sees MSG_CMSG_CLOEXEC returned in msg->msg_flags.

On 2023-07-18 15:24, Ulrich Drepper wrote:
> On Tue, Jul 18, 2023 at 2:10 PM Alejandro Colomar <alx@kernel.org> wrote:
>> On 2023-07-18 08:00, Matthew House wrote:
>>>
>>> As for the original purpose of the behavior, it's not really clear,
>>> and it may well have been an implementation artifact that got
>>> enshrined in the user space ABI.
>>> (Even io_uring is careful to replicate this behavior!)
>>
>> This is what worries me.  I've CCd a bunch of people to see if they can
>> bring some light.
>
> It definitely was an artifact of the implementation.  I haven't tested
> getting the close-on-exec flag information for all interfaces.  The
> assumption was that the information about the close-on-exec flag is
> received with the universal fcntl() call.

Cc: linux-api@vger.kernel.org
Cc: netdev@vger.kernel.org
Cc: Ulrich Drepper <drepper@redhat.com>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Matthew House <mattlloydhouse@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

statfs.2: Unshade as deprecated, but direct to statvfs(3)

Link: https://lore.kernel.org/linux-man/f54kudgblgk643u32tb6at4cd3kkzha6hslahv24szs4raroaz@ogivjbfdaqtb/t/#u
Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

grantpt.3: It's a no-op on modern glibc and other UNIXes; HISTORYise

FreeBSD, OpenBSD, and Linux (/dev/ptmx) do all intialisation in open(2),
and grantpt(3) is a no-op (that checks whether the fd is a pty, except
on musl).

The illumos gate and NetBSD do a ioctl (and, indeed, illumos-gate commit
 facf4a8d7b59fde89a8662b4f4c73a758e6c402c ("PSARC/2003/246 Filesystem
  Driven Device Naming"), which kills pt_chmod, notes that it's been
 "6464196 bfu should remove pt_chmod, obsoleted by /dev filesystem").

glibc 2.33 completely kills BSD PTY support on Linux
(Debian hasn't configured with them on any architecture since 2007:
   https://bugs.debian.org/338404
 and even earlier on some arches; they're really just trivia under
 Linux ‒ this may be better served stuffed into HISTORY as an explainer
 for the SIGCHLD thing, since regardless of the "version", the behaviour
 is well-defined and consistent).

There really aren't many cohesive "versions" of this ‒ indeed, so long
as grantpt(3) exists it behaves precisely as described here ‒
inasmuch as different systems, historically, had different ptys,
and thus different implementations.  These are all but trivia.

Cc: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

complex.7: Add LIBRARY section (libm)

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

cpuset.7: wfix

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

ld.so.8: ffix

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

CONTRIBUTING: tzselect(8) also comes from tz

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

*.mk: Escape newlines instead of using +=

It's more robust to only spell the variable name once.  We've fixed typos
related to that in the past, and in this patch we're fixing another one:

DEFAULT_CPPCHECKFLAgS += --inconclusive

Even if we could merge some of those lines into one (because they're
short), I prefer to keep one line per option.  Semantic newlines, aren't
they?  :)

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

Makefile: Simplify

Suggested-by: Andreas Schwab <schwab@suse.de>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

ld.so.8: tfix: Correct linker option name

The linker option that sets the DF_1_NODEFLIB flag is -z nodefaultlib.
-z nodeflib is invalid.

```
% ld.bfd -m elf_x86_64 -e 0 /dev/null -z nodeflib
ld.bfd: warning: -z nodeflib ignored
% ld.lld -m elf_x86_64 -e 0 /dev/null -z nodeflib
ld.lld: warning: unknown -z value: nodeflib
```

Signed-off-by: Fangrui Song <maskray@google.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

Makefile: Simplify

Suggested-by: Dmitry Goncharov <dgoncharov@users.sf.net>
Suggested-by: Torbjorn SVENSSON <torbjorn.svensson@foss.st.com>
Cc: Philip Guenther <guenther@gmail.com>
Cc: Bruno Haible <bruno@clisp.org>
Cc: Paul Smith <psmith@gnu.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

Makefile: Add include guard

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

epoll_create.2: HISTORYise "max_user_instances" EMFILE

/proc/sys/fs/epoll/max_user_instances hasn't existed since
  commit 9df04e1f25effde823a600e755b51475d438f56b
  ("epoll: drop max_user_instances and rely only on max_user_watches")
from
  Date:   Thu Jan 29 14:25:26 2009 -0800
which describes to v2.6.29-rc3-24-g9df04e1f25ef.

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

Makefile: Improve Makefile troubleshooting

Add an empty double-colon rule that targets the makefiles, to instruct
make(1) to not remake makefiles.  This improves (considerably reduces)
the output of 'make -d'.

Suggested-by: Dmitry Goncharov <dgoncharov@users.sf.net>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

crypt.3, encrypt.3: Fix library name and description

libcrypt is the password hashing library, and libcrypto is a completely
different library (OpenSSL cryptography library).  While the encrypt()
function can "encrypt" things, it uses a broken algorithm so let's not
call libcrypt an "encryption" library at all.  In crypt.3, also replace
"encrypt" with "hash" except several places where it really means
"encrypt".

Signed-off-by: Xi Ruoyao <xry111@xry111.site>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

man2/: Use SPDX-License-Identifier: Linux-man-pages-copyleft-var

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

LICENSES/Linux-man-pages-copyleft-var.txt: Add license text

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

pipe.7: document read()s with O_NONBLOCK

Which don't behave like you may expect them to;
unprimed, I expected the natural extension of either:
files   (being a  filesystem object), always returning 0 if no data, or
sockets (being an IPC mechanism),     always EAGAINing   if no data.

The pipe semantics make sense of course ‒ pipes can be modelled as
sockets if there aren't writers, but files if there are; indeed,
this makes sense as the writer continuously appending a sliding
"window" over a file ‒ but they're unique amongst the UNIX file types,
but arriving at that specific interaction table is non-obvious,
especially to a user.

Quoth Issue 8 Draft 3:
60746  When attempting to read from an empty pipe or FIFO:
60747    • If no process has the pipe open for writing, read( ) shall return 0 to indicate end-of-file.
60748    • If some process has the pipe open for writing and O_NONBLOCK is set, read( ) shall return
60749      −1 and set errno to [EAGAIN].
60750    • If some process has the pipe open for writing and O_NONBLOCK is clear, read( ) shall
60751      block the calling thread until some data is written or the pipe is closed by all processes that
60752      had the pipe open for writing.

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

man2/: Use SPDX-License-Identifier: Linux-man-pages-copyleft-2-para

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

LICENSES/Linux-man-pages-copyleft-2-para.txt: Add license text

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

man*/: Use SPDX-License-Identifier: Linux-man-pages-1-para

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

LICENSES/Linux-man-pages-1-para.txt: Add license text

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

.mailmap: Remove file

It's unmaintainable.

Reported-by: Serge Hallyn <serge@hallyn.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

socket.7: tfix

Signed-off-by: Eric Biggers <ebiggers@google.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

prctl.2: tfix

Signed-off-by: Eric Biggers <ebiggers@google.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

man*/: Prefer off_t over off64_t for splice(2), etc.

For the few functions that come only in 64-bit off_t flavors,
document their APIs as using off_t instead of off64_t,
and say also that code should #define _FILE_OFFSET_BITS 64.
This documents what user code is (and should be) doing anyway,
if it needs to work on traditional x86 and ARM Linux.

Reported-by: Rich Felker <dalias@libc.org>
Fixes: 9bebb17e5b57 ("splice.2: Use 'off64_t' instead of 'loff_t'")
Fixes: 76c5631fb442 ("copy_file_range.2: Document glibc wrapper instead of kernel syscall")
Fixes: 5cabfa06b407 ("man-pages 1.68")
Fixes: 3ca974e3988a ("New page for sync_file_range(2), new in kernel 2.6.17.")
Fixes: 9bebb17e5b57 ("sync_file_range.2: Document the architecture-specific sync_file_range2() system call")
Fixes: 79bf8cdcf36a ("Document fopencookie(3), a library function that allows custom implementation of a stdio stream.")
Signed-off-by: Paul Eggert <eggert@cs.ucla.edu>
Reviewed-by: Sam James <sam@gentoo.org>
Cc: Jonathan Wakely <jwakely@redhat.com>
Cc: Szabolcs Nagy <nsz@port70.net>
Cc: Jakub Wilk <jwilk@jwilk.net>
Cc: A. Wilcox <AWilcox@wilcox-tech.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

dir_colors.5: Relicense page

On 2023-07-08 22:14, Martin (Joey) Schulze wrote:
> For the record,
>
> I would like to re-license dir_colors(5) under the GPLv2+
>
> Please adjust the manpage source accordingly.
>
> .\" Copyright (c) 2001 Martin Schulze <joey@infodrom.org>
> .\"
> .\" This is free documentation; you can redistribute it and/or
> .\" modify it under the terms of the GNU General Public License as
> .\" published by the Free Software Foundation; either version 2 of
> .\" the License, or (at your option) any later version.
> .\"
> .\" The GNU General Public License's references to "object code"
> .\" and "executables" are to be interpreted as the output of any
> .\" document formatting or typesetting system, including
> .\" intermediate and printed output.
> .\"
> .\" This manual is distributed in the hope that it will be useful,
> .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
> .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
> .\" GNU General Public License for more details.
> .\"
> .\" You should have received a copy of the GNU General Public
> .\" License along with this manual; if not, write to the Free
> .\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
> .\" USA.
>
> This should help keep the manpage free and a version in Fedora.

Link: <https://gitlab.com/fedora/legal/fedora-license-data/-/issues/211>
Reported-by: Adam Dobes <adobes@redhat.com>
Cc: Brian Inglis <Brian.Inglis@Shaw.ca>
Cc: Martin (Joey) Schulze <joey@infodrom.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

statvfs.3: note f_favail = f_ffree on Linux

Quoting myself from #musl:
01:59:40 hm, I think this was just invented for symmetry with bfree/bavail
02:00:46 FFS has minfree for space but nothing equivalent for inodes
02:32:31 (this is mirrored in ext4;
  a global grep over DragonFlyBSD and the illumos gate
  showed just NFSv3 forwarding from the server;
  OpenBSD always sets it to the same thing as f_ffree;
  oddly, NetBSD /does/ calculate it differently
  for LFS and FFS but due to queued writes or
  w/e not because of root reservation;
  and as expected a lot of "/* what to put in here? */"
                       and "// XXX same??")

Link: https://lore.kernel.org/linux-man/f54kudgblgk643u32tb6at4cd3kkzha6hslahv24szs4raroaz@ogivjbfdaqtb/t/#u
Cc: Tom Schwindl <schwindl@posteo.de>
Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

isalpha.3: Move NOTES to CAVEATS, and clarify some Undefined Behavior

Reported-by: Yedidyah Bar David <didi@redhat.com>
Acked-by: Sam James <sam@gentoo.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

CONTRIBUTING, INSTALL, README, RELEASE: Reflow to 72 columns

This makes it easier to quote in emails.

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

regex.3: ffix: "([^...])" is not an end of sentence

Caused a double space before "not".

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Tested-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: Tom Schwindl <schwindl@posteo.de>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

ip.7: Document IP_LOCAL_PORT_RANGE socket option

Linux commit 91d0b78c5177 ("inet: Add IP_LOCAL_PORT_RANGE socket option")
introduced a new socket option available for AF_INET and AF_INET6 sockets.

Option is available starting from Linux 6.3. Document it.

Reviewed-by: Simon Horman <simon.horman@corigine.com>
Signed-off-by: Jakub Sitnicki <jakub@cloudflare.com>
[alx: semantic newlines]
Signed-off-by: Alejandro Colomar <alx@kernel.org>

proc.5: Clarify that boot arguments can be embedded in image

With the advent of the CONFIG_BOOT_CONFIG Kconfig option, kernel boot
arguments can now be embedded in the kernel image, either attached
to the end of initramfs or embedded in the kernel itself.  Document
this possibility in the /proc/cmdline entry of proc.5.

Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Cc: Michael Kerrisk <mtk.manpages@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: Nick Desaulniers <ndesaulniers@google.com>
Cc: Vlastimil Babka <vbabka@suse.cz>
Cc: Johannes Weiner <hannes@cmpxchg.org>
Reviewed-by: Masami Hiramatsu <mhiramat@kernel.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

landlock_add_rule.2: tfix

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

fanotify_init.2: remove empty pre-header line

Which yields an empty line in the formatted output.

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Fixes: e9f14fa0bbc1 ("fanotify.7, fanotify_init.2: Document FAN_REPORT_DIR_FID")
Signed-off-by: Alejandro Colomar <alx@kernel.org>

inotify.7: wds are in the range [1, INT_MAX], not [0,

Naturally, the first inotify_add_watch() returns 1,
but also fs/notify/inotify.c:inotify_add_to_idr() allocates them with
  idr_alloc_cyclic(idr, i_mark, start=1, end=0, GFP_NOWAIT);
(start inclusive, end exclusive).

(From SYSCALL_DEFINE3(inotify_add_watch, ...),
 from inotify_update_watch(),
 from inotify_new_watch()).

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

epoll_event.3type: epoll_ctl is (2)

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

prctl.2: Document PR_GET_AUXV

Signed-off-by: Josh Triplett <josh@joshtriplett.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

poll.2: explicitly say what happens for regular files &c.

Naively, one may consider being "ready" to mean, for example,
  lseek(0, 0, SEEK_END); poll({.fd = 0, .events = POLLIN}, 0);
to be able to say whether new data has appeared at the end of the file.

This is not the case, and poll() is only meaningful as
"will a read or a write sleep": regular files and block devices are
always ready to return an empty read in this case, for example,
and you need to use inotify to achieve this.

Under Linux this is governed by DEFAULT_POLLMASK
  (EPOLLIN | EPOLLOUT | EPOLLRDNORM | EPOLLWRNORM)
being returned if no explicit poll operation is defined for the file.

As contrast, unpollables like the above are refused by epoll_ctl(ADD).

I explicitly hit the two keywords I searched for (regular, block)
before just writing a test program to confirm that poll() behaved as
expected and is not a good fit for my use-case.

This behaviour is guaranteed by POSIX (Issue 8 Draft 3):
51381  The poll( ) and ppoll( ) functions shall support regular files, terminal and pseudo-terminal
51382  devices, FIFOs, pipes, and sockets. The behavior of poll( ) and ppoll( ) on elements of fds that refer
51383  to other types of file is unspecified.

51384  Regular files shall always poll TRUE for reading and writing.

51385  A file descriptor for a socket that is listening for connections shall indicate that it is ready for
51386  reading, once connections are available. A file descriptor for a socket that is connecting
51387  asynchronously shall indicate that it is ready for writing, once a connection has been established.

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

memchr.3: rawmemchr doesn't have an n parameter

The /point/ is it's unbounded;
  git grep -F 'void "' | grep -F '[]'
didn't return anything so I reverted it to a void*.

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Fixes: c64cd13e0025 ("Various pages: SYNOPSIS: Use VLA syntax in 'void *' function parameters")
Signed-off-by: Alejandro Colomar <alx@kernel.org>

boot.7: LILO is not used often anymore

On 6/18/23 22:05, Oskari Pirhonen wrote:
> On Sat, Jun 17, 2023 at 13:11:29 +0200, Helge Kreutzmann wrote:
>> Hello Alejandro,
>> On Sun, Mar 12, 2023 at 12:31:37AM +0100, Alejandro Colomar wrote:
>>> On 3/11/23 18:13, Helge Kreutzmann wrote:
>>>> Without further ado, the following was found:
>>>>
>>>> Issue:    This is true only on x86 and Lilo is probably not much
>>>>           used anymore; also systemd has its own (?) bootloader
>>
>> Lilo has just been removed from Debian, so to my knowledge only
>> Mageia ships it.
>>
>
> FWIW, Gentoo still has LILO in the repos.  This doesn't change the
> fact that it probably does not see much use anymore.  Definitely not
> enough to warrant being mentioned as "is often".  Maybe a historical
> note, if anything.

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

malloc.3: write about another possible reason for ENOMEM

Signed-off-by: Masatake YAMATO <yamato@redhat.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

statx.2: Fix Linux version

$ git describe --contains 80340fe3
v5.8-rc1~203^2~4

Fixes: 4ca216bacc7d ("statx.2: Document STAT_ATTR_MOUNT_ROOT")
Reported-by: Yang Xu <xuyang2018.jy@fujitsu.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

unshare.2: ffix: indentation inconsistencies

Signed-off-by: Günther Noack <gnoack@google.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

malloc.3: srcfix

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

ddp.7: Relicense to Linux-man-pages-copyleft

Alan Cox gave me explicit permission to relicense it for consistency
with the rest of the project.

Cc: Alan Cox <alan@llwyncelyn.cymru>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

proc.5: Clarify the format of /proc/$PID/cmdline

It is possible to produce /proc/$PID/cmdline files which do not follow
the NUL-seperated format, by using the tricks described in the
paragraph below.

Signed-off-by: Günther Noack <gnoack@google.com>
[ fix semantic newlines ]
Signed-off-by: Alejandro Colomar <alx@kernel.org>

List a fifth condition when iconv(3) may stop.

The wording regarding transliteration is vague, because this man page is not
the right place for going into the details of the transliteration.
Here are the details:
GNU libc and GNU libiconv support transliteration, for example, of "½" to "1/2",
or of "å" to "aa" in a Danish locale. The transliteration maps a multibyte
character of the input encoding to zero or more characters in the output.
There are two kinds of transliteration rules:
  - Those that are valid regardless of locale. Typically this means that the
    original and the transliterated character have similar glyphs, such as
    in the case "½" to "1/2".
    In GNU libc, these are collected in the files
    glibc/localedata/locales/translit_*.
  - Those that are valid in a single locale only. Often such a rule
    reflects similar pronounciation of the original and the transliterated
    characters. Some locales have script-based transliteration, for example
    from the Cyrillic script to the Latin script.
    In GNU libc, these are collected in the file
    glibc/localedata/locales/<locale>.
    In GNU libiconv, transliterations of this kind are not supported.

Link: https://sourceware.org/bugzilla/show_bug.cgi?id=29913#c4
Link: https://bugzilla.kernel.org/show_bug.cgi?id=217059
Reported-by: Steffen Nurpmeso <steffen@sdaoden.eu>
Reported-by: Reuben Thomas <rrt@sc3d.org>
Signed-off-by: Bruno Haible <bruno@clisp.org>
[ fix semantic newlines ]
Signed-off-by: Alejandro Colomar <alx@kernel.org>

statx.2: Document STAT_ATTR_MOUNT_ROOT

Linux 5.10 adds STATX_ATTR_MOUNT_ROOT support.
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=80340fe3605c

Add the text to the statx man page.

Signed-off-by: Yang Xu <xuyang2018.jy@fujitsu.com>
[ alx: ffix ]
Signed-off-by: Alejandro Colomar <alx@kernel.org>

putenv.3: tfix

Fixes: commit b324e17d3208c940622ab192609b836928d5aa8d ("Many pages: wfix")
Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

putenv.3: Originated in SysVr2; in 4.3BSD-Reno; fixed on modern systems

Fixed in:
  NetBSD 6     src lib/libc/stdlib/putenv.c 1.13
  FreeBSD 7    putenv(3) says so
  OpenBSD 4.6  src lib/libc/stdlib/setenv.c 1.10
and is correct under current(?) MacOS as well

The current wording implies that all of 4.4BSD's descenants also carry
this bug (at least it did to me): they did until like 2009 but they're
fine now

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

bash_aliases: Increase robustness of sed_rm_ccomments()

Thanks to perl(1), we can use a non-greedy match to remove several
C89-style comments in the same line.  And by splitting (and slightly
modifying) the other sed(1) call, we can handle multi-line comments that
start in the same line that the previous one ends.

Now the only remaining issue is nested comments, but that's rare, so
let's ignore it for now.

$ cat com.c
/* let's see */ int foo/*how about here?*/; // meh
int bar; /* Let's see
how this
behaves */ int baz; /* like this?
like that! */ int qwe; // asdasd

$ sed_rm_ccomments <com.c
 int foo;
int bar;
 int baz;
 int qwe;

Here's what can and will be problematic:

// /*
int foo;
/* */

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

.mailmap: Add Serge Hallyn

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

.mailmap: Add Andrew Clayton

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

.mailmap: Add Ingo Schwarze

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

open.2, prctl.2: SYNOPSIS: Document these as variadic functions

I remember I discussed this with Michael Kerrisk a long ago and we
agreed to apply this fix, as I felt that using overload syntax was
confusing (especially since C doesn't allow overloads), but then I
didn't feel urged to write a patch.  Florian confirmed recently that
this is confusing to more programmers, so let's do it.

Link: <https://bugzilla.kernel.org/show_bug.cgi?id=216876#c1>
Reported-by: Florian Weimer <fweimer@redhat.com>
Cc: Michael Kerrisk <mtk.manpages@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

posix_memalign.3: Update aligned_alloc(3) to match C17

Link: <https://sourceware.org/pipermail/libc-alpha/2023-May/147810.html>
Link: <https://patchwork.sourceware.org/project/glibc/patch/33ec9e0c1e587813b90e8aa771c2c8e6e379dd48.camel@posteo.net/>
Link: <https://lore.kernel.org/linux-man/d79b505c-5b19-331c-5b25-d40adc9cc843@wanadoo.fr/>
Cc: John Scott <jscott@posteo.net>
Cc: Paul Floyd <pjfloyd@wanadoo.fr>
Signed-off-by: DJ Delorie <dj@redhat.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

system_data_types.7: tfix

The actual field names omit the 'g', matching sigevent.7.

Signed-off-by: Eric Wong <e@80x24.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

.mailmap: Add Bruno Haible

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

README: tfix

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

fflush.3, unlocked_stdio.3: SYNOPSIS: The streams can be null

Cc: Xi Ruoyao <xry111@xry111.site>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

*.mk: Use -wbreak in TROFFFLAGS, and -ww in NROFFFLAGS

We don't need to see all warnings everywhere we call troff(1).  Instead,
put all warnings in nroff mode, which we only run for the warnings, and
then only ask for warnings that depend on the output in other
invocations of troff(1).

-wbreak happens to enable only and all so-called "output warnings".  It
is an implementation detail of groff(1), but that's the best we can do
now.  If groff(1) changes their warnings organization, we'll need to
adapt to it.

Link: <https://lists.gnu.org/archive/html/groff/2023-05/msg00046.html>
Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

mbind.2: Clarify MPOL_MF_MOVE with MPOL_INTERLEAVE policy

There was user confusion about specifying MPOL_MF_MOVE* with
MPOL_INTERLEAVE policy [1].  Add clarification.

[1] https://lore.kernel.org/linux-mm/20230501185836.GA85110@monkey/

Signed-off-by: Mike Kravetz <mike.kravetz@oracle.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

resolv.conf.5: tfix

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

sched_yield.2: Rename NOTES to CAVEATS, and reorder contents

Put the last paragraph at the top of the CAVEATS section, since it's
probably the most important for readers.  This system call is likely not
the right one for most programs; let's discourage its use.

Link: <https://www.realworldtech.com/forum/?threadid=189711&curpostid=189752>
Cc: Andrew Clayton <a.clayton@nginx.com>
Signed-off-by: Alejandro Colomar <alx@nginx.com>

sched_yield.2: NOTES: Remove misleading sentence

sched_yield(2) is not the right thing for heavily contended resources.
The right thing to do is to call functions that wake the waiting threads.

Link: <https://www.realworldtech.com/forum/?threadid=189711&curpostid=189752>
Cc: Andrew Clayton <a.clayton@nginx.com>
Signed-off-by: Alejandro Colomar <alx@nginx.com>

sched_yield.2: HISTORY: POSIX.1-2008 makes this non-optional

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

malloc.3: SYNOPSIS: Add the _Nullable qualifier

These functions accept NULL.

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

malloc.3: ffix

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

man*/, man.ignore.grep: srcfix; warn about blank lines

-  Use the dummy character to avoid warnings in examples.
-  Re-enable the warning.

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

*.mk, *.grep: Move grep patterns to .grep files

This simplifies the makefiles, and has the benefit that we can edit them
without editing the makefile (thus without causing unnecessary rebuilds).

Suggested-by: Bjarni Ingi Gislason <bjarniig@simnet.is>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

ascii.7: ffix

Simplify formatting of ASCII tables.

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

uri.7: ffix

Reported-by: groff(1) (`make build-catman-troff`)
Cowritten-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

man*/: srcfix

Reported-by: groff(1) (`make build-catman-troff`)
Signed-off-by: Alejandro Colomar <alx@kernel.org>