man-pages.7: Correct escaping of \~ advice

\e[ti] renders as \[ti] -- using \[ti] in a man page will produce a
literal tilde (~), not a nonbreaking space.

The intention here is to recommend \~, which produces a nonbreaking
space, so we need some more escaping.

Apply bold formatting too, which I believe is in accordance with the
advice in this section.

Fixes: 36f73ba37945 ("man-pages.7: Recommend using \[..] instead of \(.. escapes")
Signed-off-by: Brian Norris <briannorris@chromium.org>
Message-ID: <20240613205329.3240669-1-briannorris@chromium.org>
Cc: "G. Branden Robinson" <branden@debian.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

sched_setattr.2: ERRORS: Break EINVAL into separate blocks

The current EINVAL description has a complex boolean expression, and I'm
planning to add one more condition to it. Let's separate it into
different EINVAL descriptions to make it easier to read.  Tweak the
punctuation a bit too while I'm at it.

Signed-off-by: Brian Norris <briannorris@chromium.org>
Message-ID: <20240612204504.2651521-1-briannorris@chromium.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

share/mk/: Skip spurious warning from mandoc(1)

$ make lint-man-mandoc
MANDOC .tmp/man/man2/ioctl_eventpoll.2.lint-man.mandoc.touch
mandoc: .tmp/man/man2/ioctl_eventpoll.2:25:2: STYLE: fill mode already disabled, skipping: EX
mandoc: .tmp/man/man2/ioctl_eventpoll.2:35:2: STYLE: fill mode already enabled, skipping: fi
make: *** [/home/alx/src/linux/man-pages/man-pages/contrib/share/mk/lint/man/mandoc.mk:39: .tmp/man/man2/ioctl_eventpoll.2.lint-man.mandoc.touch] Error 1

Link: <https://lists.gnu.org/archive/html/groff/2024-06/msg00010.html>
Cc: Joe Damato <jdamato@fastly.com>
Cc: "G. Branden Robinson" <branden@debian.org>
Cc: Ingo Schwarze <schwarze@openbsd.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

ioctl_eventpoll.2, EPIOC[GS]PARAMS.2const: New page describing epoll ioctl(2)

A new page is added which describes epoll fd ioctls: EPIOCSPARAMS and
EPIOCGPARAMS which allow the user to control epoll-based busy polling.

Also add link pages for EPIOCSPARAMS and EPIOCGPARAMS.

Signed-off-by: Joe Damato <jdamato@fastly.com>
Message-ID: <20240611210941.1791446-2-jdamato@fastly.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

ctime.3, tzset.3, tm.3type: Adjust for POSIX, and don't overpromise

Merge changes from Paul Eggert.

Link: <https://lore.kernel.org/linux-man/d054fc63-6ea4-425b-94ce-14402d448ccf@cs.ucla.edu/T/>
Cc: Paul Eggert <eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

tm.3type: HISTORY: Say when tm_zone, tm_gmtoff standardized

Message-ID: <20240611153005.3066-12-eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

tzset.3: STANDARDS: timezone & daylight in POSIX.1-2001

Message-ID: <20240611153005.3066-11-eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

ctime.3, tzset.3: Update more POSIX citations and quotes

Message-ID: <20240611153005.3066-10-eggert@cs.ucla.edu>
Co-developed-by: Alejandro Colomar <alx@kernel.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

tm.3type: Update STANDARDS, HISTORY

The current standards are C23 and POSIX.1-2024.
This stuff was first standardized in C89 and POSIX.1-1988.

Message-ID: <20240611153005.3066-9-eggert@cs.ucla.edu>
Link: <https://www.reddit.com/r/C_Programming/comments/1ay92d4/latest_working_draft_n3220/?rdt=49226>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

tzset.3: Omit colon in example

Message-ID: <20240611153005.3066-8-eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

tzset.3: TZ=":EST5" works

Message-ID: <20240611153005.3066-7-eggert@cs.ucla.edu>
[alx: \fI => .I]
Signed-off-by: Alejandro Colomar <alx@kernel.org>

tzset.3: Use NZ's current rules in example

Message-ID: <20240611153005.3066-6-eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

tzset.3: time hh range is now [-167, 167]

Message-ID: <20240611153005.3066-5-eggert@cs.ucla.edu>
[alx: use mathematical notation for the range, and \fI => .I]
Signed-off-by: Alejandro Colomar <alx@kernel.org>

tzset.3: TZ can also be empty

Message-ID: <20240611153005.3066-4-eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

tzset.3: CAVEATS: Recommend tm_gmtoff, tm_zone instead

New section CAVEATS for why time zone state is dicey.

Message-ID: <20240611153005.3066-3-eggert@cs.ucla.edu>
[alx: use .I instead of \fI]
Signed-off-by: Alejandro Colomar <alx@kernel.org>

tzset.3: State vars unspecified if geographical TZ

Message-ID: <20240611153005.3066-2-eggert@cs.ucla.edu>
[alx: use em dashes instead of commas]
Signed-off-by: Alejandro Colomar <alx@kernel.org>

ctime.3: Simplify coverage of tzname etc.

* man/man3/ctime.3: Simplify by referring to tzset(3) for details
about how it sets tzname etc.  This simplifies a later patch,
which changes tzset(3)'s description.

Message-ID: <20240611153005.3066-1-eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

share/mk/: Skip expected failures

These are all due to long URIs, which are fine.  It's just that groff
can't adjust to both margins.

Link: <https://lore.kernel.org/linux-man/y35l3wyxcjk5tsq4hd5mtqvpor577fmysaufv3gntu5uwsyzrf@wiqk4rbxkm4w/T/#t>
Reported-by: Joe Damato <jdamato@fastly.com>
Reported-by: "G. Branden Robinson" <branden@debian.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

address_families.7: Add break-point in long URI

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

share/mk/: TROFFFLAGS: -rU0: Disable generation of OSC 8 URI hyperlinks

This is the default in groff-1.23.0.  However, some distros turn it on,
which silenced some warnings.

Link: <https://lore.kernel.org/linux-man/y35l3wyxcjk5tsq4hd5mtqvpor577fmysaufv3gntu5uwsyzrf@wiqk4rbxkm4w/T/#m569eab0d60420fdeac9e48bf237712f18ea91c4e>
Suggested-by: "G. Branden Robinson" <branden@debian.org>
Cc: Joe Damato <jdamato@fastly.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

PR_*.2const: SYNOPSIS: Some of these calls don't need all args

Some prctl()s just ignore unused parameters.  Users don't need to
specify them all.

Fixes: 2534dc7ad5e9 ("prctl.2, PR_*.2const: Make sashimi")
Signed-off-by: Alejandro Colomar <alx@kernel.org>

prctl.2, PR_*.2const: SYNOPSIS: #include <linux/prctl.h> for the PR_* constants

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

prctl.2: CAVEATS: Document the necessity of using the 'L' suffix

Link: <https://lore.kernel.org/linux-man/ddbdyaiptesjalgfmztxideej67e3yaob7ucsmbf6qvriwxiif@dohhxrqgwhrf/T/#med306b5b003f9cc7cc2de69fcdd7ee2d056d0954>
Cc: Xi Ruoyao <xry111@xry111.site>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

ioctl_iflags.2: Document FS_APPEND_FL ('a') on directories

For some reason, neither chattr(1) nor this page document it;
this is supported by all tested filesystems (ext4, tmpfs, ZFS).

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

open_by_handle_at.2: Correct the name of the FreeBSD equivalent

The open_by_handle_at equivalent in FreeBSD is called fhopen, not
openfh.

Signed-off-by: Christoph Hellwig <hch@lst.de>
Message-ID: <20240527113800.1098633-1-hch@lst.de>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

PR_SET_KEEPCAPS.2const: Use 0L and 1L for arguments to prctl(2)

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

prctl.2, PR_*.2const: Make sashimi

prctl(2) was a huge page, which was quite hard to maintain, extend,
read, and refer to.  Split the page into small pages for the different
operations.  Some operations have suboperations, and some of them have
also been split into one page for each suboperation.

This change introduces a new sub-chapter: '2const'.

The new pages have the name of the constants for the operations, and
they're placed in 2const accordingly.

The prctl(2) page now describes the system call itself, without details
of each operation.  Errors and details common to all operations are
described in this page, while errors and other details of each operation
are described in the page for the operation.

While doing this splitting, some mistakes have been silently fixed.  The
most notable one being that 0L must be passed to this call (and in
general, integers of 'long' width), due to how variadic argument lists
work in C.

Also, the prototypes of the operations now show the specific arguments
that these calls expect, even if the actual prototype has a variadic
argument list.  Where a specific value is expected, such as 0L or 1L,
that specific value is shown.

Link: <https://lore.kernel.org/linux-man/ddbdyaiptesjalgfmztxideej67e3yaob7ucsmbf6qvriwxiif@dohhxrqgwhrf/T/#med306b5b003f9cc7cc2de69fcdd7ee2d056d0954>
Cc: Xi Ruoyao <xry111@xry111.site>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

share/mk/: Skip expected failures

The SEE ALSO section of prctl(2) is problematic.  MR will fix that; for
now, let's skip the errors.

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

prctl.2: Tweak after making sashimi of this page

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

PR_GET_MDWE.2const: Tweak after split

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

prctl.2, PR_GET_MDWE.2const: Split PR_GET_MDWE from prctl(2)

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

PR_SET_MDWE.2const: Tweak after split

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

prctl.2, PR_SET_MDWE.2const: Split PR_SET_MDWE from prctl(2)

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

PR_GET_AUXV.2const: Tweak after split

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

prctl.2, PR_GET_AUXV.2const: Split PR_GET_AUXV from prctl(2)

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

PR_GET_UNALIGN.2const: Tweak after split

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

prctl.2, PR_GET_UNALIGN.2const: Split PR_GET_UNALIGN from prctl(2)

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

PR_SET_UNALIGN.2const: Tweak after split

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

prctl.2, PR_SET_UNALIGN.2const: Split PR_SET_UNALIGN from prctl(2)

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

PR_GET_TSC.2const: Tweak after split

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

prctl.2, PR_GET_TSC.2const: Split PR_GET_TSC from prctl(2)

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

PR_SET_TSC.2const: Tweak after split

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

prctl.2, PR_SET_TSC.2const: Split PR_SET_TSC from prctl(2)

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

PR_GET_TIMING.2const: Tweak after split

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

prctl.2, PR_GET_TIMING.2const: Split PR_GET_TIMING from prctl(2)

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

PR_SET_TIMING.2const: Tweak after split

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

prctl.2, PR_SET_TIMING.2const: Split PR_SET_TIMING from prctl(2)

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

PR_GET_TIMERSLACK.2const: Tweak after split

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

prctl.2, PR_GET_TIMERSLACK.2const: Split PR_GET_TIMERSLACK from prctl(2)

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

PR_SET_TIMERSLACK.2const: Tweak after split

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

prctl.2, PR_SET_TIMERSLACK.2const: Split PR_SET_TIMERSLACK from prctl(2)

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

PR_GET_TID_ADDRESS.2const: Tweak after split

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

prctl.2, PR_GET_TID_ADDRESS.2const: Split PR_GET_TID_ADDRESS from prctl(2)

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

PR_GET_THP_DISABLE.2const: Tweak after split

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

prctl.2, PR_GET_THP_DISABLE.2const: Split PR_GET_THP_DISABLE from prctl(2)

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

PR_SET_THP_DISABLE.2const: Tweak after split

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

prctl.2, PR_SET_THP_DISABLE.2const: Split PR_SET_THP_DISABLE from prctl(2)

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

PR_TASK_PERF_EVENTS_DISABLE.2const: Tweak after split

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

prctl.2, PR_TASK_PERF_EVENTS_{EN,DIS}ABLE.2const: Split PR_TASK_PERF_EVENTS_* from prctl(2)

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

PR_GET_TAGGED_ADDR_CTRL.2const: Tweak after split

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

prctl.2, PR_GET_TAGGED_ADDR_CTRL.2const: Split PR_GET_TAGGED_ADDR_CTRL from prctl(2)

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

PR_SET_TAGGED_ADDR_CTRL.2const: Tweak after split

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

prctl.2, PR_SET_TAGGED_ADDR_CTRL.2const: Split PR_SET_TAGGED_ADDR_CTRL from prctl(2)

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

PR_SET_SYSCALL_USER_DISPATCH.2const: Tweak after split

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

prctl.2, PR_SET_SYSCALL_USER_DISPATCH.2const: Split PR_SET_SYSCALL_USER_DISPATCH from prctl(2)

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

PR_SVE_GET_VL.2const: Tweak after split

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

prctl.2, PR_SVE_GET_VL.2const: Split PR_SVE_GET_VL from prctl(2)

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

PR_SVE_SET_VL.2const: Tweak after split

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

prctl.2, PR_SVE_SET_VL.2const: Split PR_SVE_SET_VL from prctl(2)

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

PR_GET_SPECULATION_CTRL.2const: Tweak after split

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

prctl.2, PR_GET_SPECULATION_CTRL.2const: Split PR_GET_SPECULATION_CTRL from prctl(2)

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

PR_SET_SPECULATION_CTRL.2const: Tweak after split

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

prctl.2, PR_SET_SPECULATION_CTRL.2const: Split PR_SET_SPECULATION_CTRL from prctl(2)

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

PR_GET_SECUREBITS.2const: Tweak after split

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

prctl.2, PR_GET_SECUREBITS.2const: Split PR_GET_SECUREBITS from prctl(2)

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

PR_SET_SECUREBITS.2const: Tweak after split

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

prctl.2, PR_SET_SECUREBITS.2const: Split PR_SET_SECUREBITS from prctl(2)

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

PR_GET_SECCOMP.2const: Tweak after split

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

prctl.2, PR_GET_SECCOMP.2const: Split PR_GET_SECCOMP from prctl(2)

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

PR_SET_SECCOMP.2const: Tweak after split

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

prctl.2, PR_SET_SECCOMP.2const: Split PR_SET_SECCOMP from prctl(2)

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

PR_SET_PTRACER.2const: Tweak after split

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

prctl.2, PR_SET_PTRACER.2const: Split PR_SET_PTRACER from prctl(2)

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

PR_GET_PDEATHSIG.2const: Tweak after split

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

prctl.2, PR_GET_PDEATHSIG.2const: Split PR_GET_PDEATHSIG from prctl(2)

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

PR_SET_PDEATHSIG.2const: Tweak after split

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

prctl.2, PR_SET_PDEATHSIG.2const: Split PR_SET_PDEATHSIG from prctl(2)

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

PR_PAC_RESET_KEYS.2const: Tweak after split

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

prctl.2, PR_PAC_RESET_KEYS.2const: Split PR_PAC_RESET_KEYS from prctl(2)

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

PR_GET_NO_NEW_PRIVS.2const: Tweak after split

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

prctl.2, PR_GET_NO_NEW_PRIVS.2const: Split PR_GET_NO_NEW_PRIVS from prctl(2)

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

PR_SET_NO_NEW_PRIVS.2const: Tweak after split

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

prctl.2, PR_SET_NO_NEW_PRIVS.2const: Split PR_SET_NO_NEW_PRIVS from prctl(2)

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

PR_SET_NAME.2const: Tweak after split

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

prctl.2, PR_[SG]ET_NAME.2const: Split PR_[SG]ET_NAME from prctl(2)

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

PR_MPX_ENABLE_MANAGEMENT.2const: Tweak after split

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

prctl.2, PR_MPX_{EN,DIS}ABLE_MANAGEMENT.2const: Split PR_MPX_*_MANAGEMENT from prctl(2)

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

PR_SET_VMA.2const: Tweak after split

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

prctl.2, PR_SET_VMA.2const: Split PR_SET_VMA from prctl(2)

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

PR_SET_MM.2const, PR_SET_MM_MAP{,_SIZE}.2const: Split PR_SET_MM_MAP* from PR_SET_MM(2const)

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