ioctl_tty.2, poll.2, getpt.3, grantpt.3, openpty.3, posix_openpt.3, ptsname.3, ttyname.3, unlockpt.3, pts.4, pty.7: Eliminate problematic "master-slave" terminology

The "master-slave" terminology used in describing pseudoterminals
is problematic, and not even very technically descriptive. Rewrite
various manual pages to eliminate that language. The following
replacement terms are used:

slave ==> "terminal device"
       (or "terminal end of the pseudoterminal device pair")

master ==> "pseudoterminal device"
       (or "pseudoterminal end of the pseudoterminal device pair")

pseudoterminal (device) ==> "pseudoterminal device pair"

Another notable wording change is the use of phrasings such as
"the corresponding terminal device", when emphasizing the linkage
between the pseudoterminal and terminal ends of a pseudoterminal
device pair.

The terminology originates in golang (which made a similar
terminology change in 2019), and was suggested for Linux
man-pages by Elliot Hughes.

Reported-by: Elliott Hughes <enh@google.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pts.4: Remove NOTES on BSD pseuodterminals

This information is already covered better in pty(7). No need to
mention it again here.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pts.4: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

openpty.3: Minor wording fixes

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pty.7: Explicitly mention CONFIG_LEGACY_PTYS

Explicitly mention CONFIG_LEGACY_PTYS, and note that it is disabled
by default since Linux 2.6.30.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pty.7: Relocate a paragraph to NOTES

The paragraph noting applications that use pseudoterminals is better
placed in NOTES than in the DESCRTIPTION.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

unlockpt.3: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

ttyname.3: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

ptsname.3: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

grantpt.3: Minor wording fix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getpt.3, posix_openpt.3, pts.4: Use the term "pseudoterminal multiplexor device" for /dev/ptmx

Let's use some consistent terminology for this device.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getpt.3: Minor wording fixes

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getpt.3, pts.4: Minor wording fixes

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

ioctl_tty.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

ioctl_tty.2: Minor wording and formatting fixes

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

ioctl_tty.2: Fix a confusing wording error in description of TIOCSPTLCK

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

Various pages: Drop t comment header

Historically, a comment of the following form at the top of a
manual page was used to indicate too man(1) that the use of tbl(1)
was required in order to process tables:

    '\" t

However, at least as far back as 2001 (according to Branden),
man-db's man(1) automatically uses tbl(1) as needed, rendering
this comment unnecessary. And indeed many existing pages in
man-pages that have tables don't have this comment at the top of
the file.  So, drop the comment from those files where it is
present.

[mtk: completely rewrote commit message]

Reported-by: G. Branden Robinson <g.branden.robinson@gmail.com>
Signed-off-by: Mike Frysinger <vapier@gentoo.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

seccomp.2: Minor tweaks to Andy Lutomirski's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

seccomp.2: Improve x32 and nr truncation notes

Signed-off-by: Andy Lutomirski <luto@kernel.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

open.2: Say a bit more about what happens when 'mode' is wrongly omitted

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

open.2: Minor wording fixes

Add some paragraph breaks to the discussion of 'mode' to make
the details a bit easier to read.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

open.2: srcfix: use saner macros to achieve same formatting effect

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

Various pages: Trim leading blank comment line

Very few pages do this, so trim them.

Signed-off-by: Mike Frysinger <vapier@gentoo.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

Various pages: Use standard .\" comment style

The \" comment produces blank lines.  Use the .\" that the vast
majority of the codebase uses instead.

Signed-off-by: Mike Frysinger <vapier@gentoo.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

posix_memalign.3: Clarify how to free the result of posix_memalign

The man page did not tell how a memory block obtained through
posix_memalign() can be freed. POSIX:2018 says it.
https://pubs.opengroup.org/onlinepubs/9699919799/functions/posix_memalign.html
I verified using a test program that this is true for glibc.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

wctob.3: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

ioctl_fat.2, dladdr.3: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

ld.so.8: Clean up page internal cross references after Florian Weimer's patch

The subsection named "Rpath token expansion" was renamed to
"Dynamic string tokens". Update the cross-references inside
the page accordingly.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

ld.so.8: Minor tweaks to Florian Weimer's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

ld.so.8: List more places in which dynamic string tokens are expanded

This happens for more than just DT_RPATH/DT_RUNPATH.

Signed-off-by: Florian Weimer <fweimer@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

proc.5: Use "pwd -P" for printing cwd

"/bin/pwd" happens to work with the GNU coreutils implementation,
which has -P as the default, contrary to POSIX requirements.

Use "pwd -P" instead, which is shorter, easier to type, and should
work everywhere.

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

proc.5: tfix

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

prctl.2: tfix

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

lseek.2: List gfs2 support for SEEK_HOLE/SEEK_DATA

Signed-off-by: Andrew Price <anprice@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

capabilities.7: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

capabilities.7: CAP_SYS_RESOURCE: add two more items for POSIX message queues

CAP_SYS_RESOURCE also allows overriding /proc/sys/fs/mqueue/msg_max
and /proc/sys/fs/mqueue/msgsize_max.

Signed-off-by: Saikiran Madugula <hummerbliss@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_rwlockattr_setkind_np.3: Clarify a PTHREAD_RWLOCK_PREFER_WRITER_NP detail

Clarify that it is recursive read locks on the read-write lock
that make it difficult to implement
PTHREAD_RWLOCK_PREFER_WRITER_NP.

Update the libc-alpha URL and provide the URL to the POSIX wording
that is quoted in the comment.

Reported-by: Kumar Kartikeya Dwivedi <memxor@gmail.com>
Signed-off-by: Carlos O'Donell <carlos@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

cgroup_namespaces.7: wfix

Signed-off-by: Benjamin Peterson <benjamin@python.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

setns.2: EXAMPLE: use O_CLOEXEC when opening namespace file descriptor

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pidfd_open.2: Close the pidfd in EXAMPLE

Close the PID file descriptor in the example program, to hint to
the reader that like every other kind of file descriptor, a PID FD
should be closed.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

truncate.2: tfix

Reported-by: Diogo Miguel Ferreira Rodrigues <dmfrodrigues2000@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

prctl.2: The parent death signal is cleared on some credential changes

See kernel/cred.c::commit_creds() in the Linux 5.6 source code.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

intro.1, localedef.1, memusage.1, memusagestat.1, bpf.2, execve.2, fork.2, keyctl.2, request_key.2, sigaction.2, signal.2, socket.2, dlopen.3, getauxval.3, gnu_get_libc_version.3, pthread_atfork.3, sem_post.3, setjmp.3, strftime.3, veth.4, locale.5, nscd.conf.5, resolv.conf.5, address_families.7, armscii-8.7, ascii.7, capabilities.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, keyrings.7, koi8-r.7, koi8-u.7, libc.7, locale.7, man.7, network_namespaces.7, persistent-keyring.7, session-keyring.7, signal.7, unicode.7, uri.7, user-keyring.7, user-session-keyring.7: ffix: replace - with real\-

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

move_pages.2: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

strfmon.3: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

strfmon.3: ffix

Reported-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man[13]/*: ffix: change '--' to '\-\-' (options) or '\(em' (em-dash)

  Change '--' to '\-\-' for options and '--' between words to '\(em'
(em-dash).

Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

Changes.old: tfix

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

termios.3: tfix

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

prctl.2: tfix

Remove duplicated word.

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

math_error.7: wfix

Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

resolv.conf.5: Clarify that ip6-bytestring was removed in 2.25

Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

strcmp.3: wfix

Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

strcmp.3: tfix

Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

shmop.2: tfix

Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

resolver.3: tfix

Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

proc.5: srcfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

proc.5: wfix

Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

open.2: tfix

Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

mremap.2: tfix

Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

mmap.2: wfix

Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getusershell.3: ffix

Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

execve.2: tfix

Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

dsp56k.4: ffix

Reported-by: Helge Kreutzmann <debian@helgefjell.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

send.2, recv.2: Add msg_iovlen POSIX note

msg_iovlen is incorrectly typed (according to POSIX) in addition
to msg_controllen, but unlike msg_controllen, this wasn't
mentioned for msg_iovlen.

msg_iovlen being incorrectly typed hasn't been reported as a GCC
bug, but there's no point since it is caused by the same
underlying issue.

Sources: POSIX.1-2017 (<sys/socket.h>), Linux
(include/linux/socket.h)

Signed-off-by: Alyssa Ross <hi@alyssa.is>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

mount.2: ERRORS: add EINVAL for bind mount of mount namespace inode

See kernel commit 8823c079ba7136dc1948d6f6dcb5f8022bde438e
and the in fs/namespace.c::do_loopback():

        err = -EINVAL;
        if (mnt_ns_loop(old_path.dentry))
                goto out;

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

strfromd.3: ffix: use \- for minus sign

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man3/*: ffix: change '-' to '\-' for options

  Change '-' to '\-' for the prefix of names to indicate an option.

Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man8/*: ffix: change '-' to '\-' for options

  Change '-' to '\-' for the prefix of names to indicate an option.

Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man7/*: ffix: change '-' to '\-' for options and to '\(en' for a range

  Change '-' to '\-' for the prefix of names to indicate an option.

  Change '-' to '\(en' for a range.

Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man5/*: ffix: change '-' to '\-' for options

  Change '-' to '\-' for the prefix of names to indicate an option.

Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man4/*: ffix: change '-' to '\-' for options

  Change '-' to '\-' for the prefix of names to indicate an option.

Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man2/*: ffix: change '-' to '\-' for options

  Change '-' to '\-' for the prefix of names to indicate an option.

Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man1/*: ffix: change '-' to '\-' for options

  Change '-' to '\-' for the prefix of names to indicate an option.

Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

ftw.3: srcfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

cgroups.7, cpuset.7: Update kernel cgroup documentation references

cgroups-v1/v2 documentation got moved to the "admin-guide" subfolder
and converted from .txt files to .rst

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

hosts.5: Clarify capability for IPv6 outside of examples

Resolves https://bugzilla.kernel.org/show_bug.cgi?id=208279

Signed-off-by: Thomas Bartelsmeier <t.bartelsmeier@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

strfromd.3: wfix (null character --> null byte)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

iopl.2: Minor tweaks to Thomas Piekarski's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

iopl.2: Updating description of permissions and disabling interrupts

Update description of permissions for port-mapped I/O set
per-thread and not per-process. Mention that iopl() can not
disable interrupts since Linux 5.5 anymore and is in general
deprecated and only provided for legacy X servers.

See https://bugzilla.kernel.org/show_bug.cgi?id=205317

Reported-by: victorm007@yahoo.com
Signed-off-by: Thomas Piekarski <t.piekarski@deloquencia.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

prctl.2: srcfix: add various people to copyright

Based on git history.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

prctl.2: Minor fixes to Dave Martin's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

prctl.2: Add tagged address ABI control prctls (arm64)

Add documentation for the the PR_SET_TAGGED_ADDR_CTRL and
PR_GET_TAGGED_ADDR_CTRL prctls added in Linux 5.4 for arm64.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
Reviewed-by: Catalin Marinas <catalin.marinas@arm.com>
Cc: Vincenzo Frascino <vincenzo.frascino@arm.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

prctl.2: Minor tweaks to Dave Martin's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

prctl.2: Add SVE prctls (arm64)

Add documentation for the the PR_SVE_SET_VL and PR_SVE_GET_VL
prctls added in Linux 4.15 for arm64.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
Cc: Catalin Marinas <catalin.marinas@arm.com>
Cc: Will Deacon <will@kernel.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

locale.5: srcfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

locale.5: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

cciss.4: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

clone.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

semctl.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

sync.2: Minor fixes

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

sync.2: Minor tweaks to Jeff Layton's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

sync.2: syncfs() now returns errors if writeback fails

A patch has been merged for v5.8 that changes how syncfs() reports
errors. Change the sync() manpage accordingly.

Signed-off-by: Jeff Layton <jlayton@kernel.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

tcp.7: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

gethostid.3: wfix: s/is intended/was intended/

The host ID might once have been intended to be globally unique,
but that turned out not to feasible.

Reported-by: Rich Felker <dalias@libc.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

ld.so.8: Explain than empty entry in LD_LIBRARY_PATH means cwd

If this was ever going to change the test case is very simple:

$ cd /tmp
$ touch libc.so.6
$ LD_LIBRARY_PATH=: sh
sh: error while loading shared libraries: libc.so.6: file too short

Signed-off-by: Arkadiusz Drabczyk <arkadiusz@drabczyk.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

ip.7: Remove mention of ipfw(4) which was in long obsolete ipchains project

Reported-by: Stephen Hemminger <stephen@networkplumber.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

mmap.2: tfix

Reported-by: Bruno Haible <bruno@clisp.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

capabilities.7: Clarify that CAP_SYS_NICE relates to *lowering* the nice value

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

standards.7: Add an entry for POSIX.1-1988

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>