From 750fda980b873999d9329d4c82b6089ec4915709 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Thu, 13 Aug 2020 13:49:52 +0200 Subject: [PATCH] Start of man-pages-5.09: updating Changes and Changes.old --- Changes | 319 ++---------------------------------------------- Changes.old | 340 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 348 insertions(+), 311 deletions(-) diff --git a/Changes b/Changes index 36e6f61d1..00ae284f2 100644 --- a/Changes +++ b/Changes @@ -1,6 +1,6 @@ -==================== Changes in man-pages-5.08 ==================== +==================== Changes in man-pages-5.09 ==================== -Released: 2020-08-13, Munich +Released: ????-??-??, Munich Contributors @@ -10,329 +10,26 @@ The following people contributed patches/fixes or (noted in brackets in the changelog below) reports, notes, and ideas that have been incorporated in changes in this release: -Alejandro Colomar -Aleksa Sarai -Alyssa Ross -Andrew Price -Andy Lutomirski -Arkadiusz Drabczyk -Benjamin Peterson -Bjarni Ingi Gislason -Bruno Haible -Carlos O'Donell -Catalin Marinas -Dan Kenigsberg -Dave Martin -Diogo Miguel Ferreira Rodrigues -Florian Weimer -G. Branden Robinson -Geoff Clare -Helge Kreutzmann -Jakub Wilk -Jeff Layton -John Scott -Kumar Kartikeya Dwivedi -Michael Kerrisk -Mike Frysinger -Oleksandr Kravchuk -Philip Adams -Rich Felker -Saikiran Madugula -Stephen Hemminger -Sven Hoexter -Thomas Bartelsmeier -Thomas Piekarski -victorm007@yahoo.com Apologies if I missed anyone! +New and rewritten pages +----------------------- + + Newly documented interfaces in existing pages --------------------------------------------- -prctl.2 - Dave Martin - 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. - Dave Martin [Catalin Marinas] - 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. -setns.2 - Michael Kerrisk - Document the use of PID file descriptors with setns() - Starting with Linux 5.8, setns() can take a PID file descriptor as - an argument, and move the caller into or more of the namespaces of - the thread referred to by that descriptor. - -capabilities.7 - Michael Kerrisk - Document CAP_BPF - Michael Kerrisk - Add CAP_PERFMON - -symlink.7 - Aleksa Sarai - Document magic links more completely +New and changed links +--------------------- Global changes -------------- -A few pages - Michael Kerrisk - Use \` rather than ` - \` produces better rendering in PDF. - -Various pages - Michael Kerrisk [Geoff Clare] - Use "\(ti" instead of "~" - A naked tilde ("~") renders poorly in PDF. Instead use "\(ti", - which renders better in a PDF, and produces the same glyph - when rendering on a terminal. - -Various pages - Michael Kerrisk [Geoff Clare] - Use "\(ha" rather than "^" in code - This renders better in PDF. - -Various pages - Mike Frysinger - Drop "coding: UTF-8" header - This header is used inconsistently -- man pages are UTF-8 encoded - but not setting this marker. It's only respected by the man-db - package, and seems a bit anachronistic at this point when UTF-8 - is the standard default nowadays. - -Various pages - Mike Frysinger - Trim leading blank comment line - Very few pages do this, so trim them. - -Various pages - Mike Frysinger - Use standard .\" comment style - The \" comment produces blank lines. Use the .\" that the vast - majority of the codebase uses instead. - -Various pages - Mike Frysinger [G. Branden Robinson] - 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. - Changes to individual pages --------------------------- -ioctl_tty.2 - Michael Kerrisk - Fix a confusing wording error in description of TIOCSPTLCK - -iopl.2 - Thomas Piekarski [victorm007@yahoo.com] - 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 - -keyctl.2 - Oleksandr Kravchuk - Declare auth_key to fix a compilation error in example code - -lseek.2 - Andrew Price - List gfs2 support for SEEK_HOLE/SEEK_DATA - -mount.2 - Michael Kerrisk - ERRORS: add EINVAL for bind mount of mount namespace inode - -open.2 - Michael Kerrisk - Say a bit more about what happens when 'mode' is wrongly omitted - -pidfd_open.2 - Michael Kerrisk - Add the setns(2) use case for PID file descriptors - Michael Kerrisk - 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. - -prctl.2 - Michael Kerrisk - The parent death signal is cleared on some credential changes - See kernel/cred.c::commit_creds() in the Linux 5.6 source code. - -seccomp.2 - Andy Lutomirski - Improve x32 and nr truncation notes - -send.2 -recv.2 - Alyssa Ross - 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. - -setns.2 - Michael Kerrisk - EXAMPLE: use O_CLOEXEC when opening namespace file descriptor - Michael Kerrisk - It is possible to setns() to the caller's current PID namespace - The page currently incorrectly says that 'fd' must refer to - a descendant PID namespace. However, 'fd' can also refer to - the caller's current PID namespace. Verified by experiment, - and also comments in kernel/pid_namespace.c (Linux 5.8-rc1). - -sync.2 - Jeff Layton - 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. - -syscalls.2 - Michael Kerrisk - Add faccessat2(), added in Linux 5.8 - -sysctl.2 - Michael Kerrisk - glibc removed support for sysctl() starting in version 2.32 - -atoi.3 - Arkadiusz Drabczyk - Explain disadvantages of atoi() - Michael Kerrisk - Relocate BUGS section - Michael Kerrisk - Add NOTES section explaining 0 return value on error - And note that this is not specified by POSIX. - -fread.3 - Arkadiusz Drabczyk - Add example - Arkadiusz Drabczyk - Explain that file position is moved after calling fread()/fwrite() - Corresponding manpage on FreeBSD already contains that - information. - -getpt.3 -posix_openpt.3 -pts.4 - Michael Kerrisk - Use the term "pseudoterminal multiplexor device" for /dev/ptmx - Let's use some consistent terminology for this device. - -posix_memalign.3 - Bruno Haible - Clarify how to free the result of posix_memalign - -pthread_rwlockattr_setkind_np.3 - Carlos O'Donell [Kumar Kartikeya Dwivedi] - Clarify a PTHREAD_RWLOCK_PREFER_WRITER_NP detail - -queue.3 - Alejandro Colomar - Remove wrong code from example - Alejandro Colomar - Comment out text for functions not in glibc (related: 6559169cac) - -pts.4 - Michael Kerrisk - Remove NOTES on BSD pseudoterminals - This information is already covered better in pty(7). No need to - mention it again here. - -hosts.5 - Thomas Bartelsmeier - Clarify capability for IPv6 outside of examples - Resolves https://bugzilla.kernel.org/show_bug.cgi?id=208279 - -proc.5 - Jakub Wilk - 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. - Arkadiusz Drabczyk - Inform that comm in /proc/pid/{stat,status} might also be truncated - pgrep for example searches for a process name in /proc/pid/status - -resolv.conf.5 - Michael Kerrisk [Helge Kreutzmann] - Clarify that ip6-bytestring was removed in 2.25 - -capabilities.7 - Dan Kenigsberg - Clarify that CAP_SYS_NICE relates to *lowering* the nice value - Saikiran Madugula - 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. - Michael Kerrisk [Dan Kenigsberg] - Clarify wording around increasing process nice value - Michael Kerrisk - SEE ALSO: add getpcaps(8) - -cgroups.7 -cpuset.7 - Sven Hoexter - Update kernel cgroup documentation references - cgroups-v1/v2 documentation got moved to the "admin-guide" subfolder - and converted from .txt files to .rst - -ip.7 - Michael Kerrisk [Stephen Hemminger] - Remove mention of ipfw(4) which was in long obsolete ipchains project - -man-pages.7 - Michael Kerrisk - Add some notes on generating optimal glyphs - Getting nice renderings of ^ ` and ~ requires special - steps in the page source. - -pty.7 - Michael Kerrisk - Explicitly mention CONFIG_LEGACY_PTYS - Explicitly mention CONFIG_LEGACY_PTYS, and note that it is disabled - by default since Linux 2.6.30. - Michael Kerrisk - Relocate a paragraph to NOTES - -standards.7 - Michael Kerrisk - Add an entry for POSIX.1-1988 - Michael Kerrisk [Geoff Clare] - Correct various details in the explanation of XPG/POSIX/SUS - -ld.so.8 - Florian Weimer [Michael Kerrisk] - List more places in which dynamic string tokens are expanded - This happens for more than just DT_RPATH/DT_RUNPATH. - Arkadiusz Drabczyk - Explain that empty entry in LD_LIBRARY_PATH means cwd - -zic.8 - Michael Kerrisk - Sync to 2020a tzdb release - From https://www.iana.org/time-zones, version 2020a. diff --git a/Changes.old b/Changes.old index 0e67fe3c8..fd66a5152 100644 --- a/Changes.old +++ b/Changes.old @@ -51867,3 +51867,343 @@ zdump.8 Michael Kerrisk [Marco Curreli, Paul Eggert] Update to latest upstream tz release Look under "Latest version", which is 2020a. + + +==================== Changes in man-pages-5.08 ==================== + +Released: 2020-08-13, Munich + + +Contributors +------------ + +The following people contributed patches/fixes or (noted in brackets +in the changelog below) reports, notes, and ideas that have been +incorporated in changes in this release: + +Alejandro Colomar +Aleksa Sarai +Alyssa Ross +Andrew Price +Andy Lutomirski +Arkadiusz Drabczyk +Benjamin Peterson +Bjarni Ingi Gislason +Bruno Haible +Carlos O'Donell +Catalin Marinas +Dan Kenigsberg +Dave Martin +Diogo Miguel Ferreira Rodrigues +Florian Weimer +G. Branden Robinson +Geoff Clare +Helge Kreutzmann +Jakub Wilk +Jeff Layton +John Scott +Kumar Kartikeya Dwivedi +Michael Kerrisk +Mike Frysinger +Oleksandr Kravchuk +Philip Adams +Rich Felker +Saikiran Madugula +Stephen Hemminger +Sven Hoexter +Thomas Bartelsmeier +Thomas Piekarski +victorm007@yahoo.com + +Apologies if I missed anyone! + + +Newly documented interfaces in existing pages +--------------------------------------------- + +prctl.2 + Dave Martin + 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. + Dave Martin [Catalin Marinas] + 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. + +setns.2 + Michael Kerrisk + Document the use of PID file descriptors with setns() + Starting with Linux 5.8, setns() can take a PID file descriptor as + an argument, and move the caller into or more of the namespaces of + the thread referred to by that descriptor. + +capabilities.7 + Michael Kerrisk + Document CAP_BPF + Michael Kerrisk + Add CAP_PERFMON + +symlink.7 + Aleksa Sarai + Document magic links more completely + + +Global changes +-------------- + +A few pages + Michael Kerrisk + Use \` rather than ` + \` produces better rendering in PDF. + +Various pages + Michael Kerrisk [Geoff Clare] + Use "\(ti" instead of "~" + A naked tilde ("~") renders poorly in PDF. Instead use "\(ti", + which renders better in a PDF, and produces the same glyph + when rendering on a terminal. + +Various pages + Michael Kerrisk [Geoff Clare] + Use "\(ha" rather than "^" in code + This renders better in PDF. + +Various pages + Mike Frysinger + Drop "coding: UTF-8" header + This header is used inconsistently -- man pages are UTF-8 encoded + but not setting this marker. It's only respected by the man-db + package, and seems a bit anachronistic at this point when UTF-8 + is the standard default nowadays. + +Various pages + Mike Frysinger + Trim leading blank comment line + Very few pages do this, so trim them. + +Various pages + Mike Frysinger + Use standard .\" comment style + The \" comment produces blank lines. Use the .\" that the vast + majority of the codebase uses instead. + +Various pages + Mike Frysinger [G. Branden Robinson] + 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. + + +Changes to individual pages +--------------------------- + +ioctl_tty.2 + Michael Kerrisk + Fix a confusing wording error in description of TIOCSPTLCK + +iopl.2 + Thomas Piekarski [victorm007@yahoo.com] + 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 + +keyctl.2 + Oleksandr Kravchuk + Declare auth_key to fix a compilation error in example code + +lseek.2 + Andrew Price + List gfs2 support for SEEK_HOLE/SEEK_DATA + +mount.2 + Michael Kerrisk + ERRORS: add EINVAL for bind mount of mount namespace inode + +open.2 + Michael Kerrisk + Say a bit more about what happens when 'mode' is wrongly omitted + +pidfd_open.2 + Michael Kerrisk + Add the setns(2) use case for PID file descriptors + Michael Kerrisk + 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. + +prctl.2 + Michael Kerrisk + The parent death signal is cleared on some credential changes + See kernel/cred.c::commit_creds() in the Linux 5.6 source code. + +seccomp.2 + Andy Lutomirski + Improve x32 and nr truncation notes + +send.2 +recv.2 + Alyssa Ross + 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. + +setns.2 + Michael Kerrisk + EXAMPLE: use O_CLOEXEC when opening namespace file descriptor + Michael Kerrisk + It is possible to setns() to the caller's current PID namespace + The page currently incorrectly says that 'fd' must refer to + a descendant PID namespace. However, 'fd' can also refer to + the caller's current PID namespace. Verified by experiment, + and also comments in kernel/pid_namespace.c (Linux 5.8-rc1). + +sync.2 + Jeff Layton + 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. + +syscalls.2 + Michael Kerrisk + Add faccessat2(), added in Linux 5.8 + +sysctl.2 + Michael Kerrisk + glibc removed support for sysctl() starting in version 2.32 + +atoi.3 + Arkadiusz Drabczyk + Explain disadvantages of atoi() + Michael Kerrisk + Relocate BUGS section + Michael Kerrisk + Add NOTES section explaining 0 return value on error + And note that this is not specified by POSIX. + +fread.3 + Arkadiusz Drabczyk + Add example + Arkadiusz Drabczyk + Explain that file position is moved after calling fread()/fwrite() + Corresponding manpage on FreeBSD already contains that + information. + +getpt.3 +posix_openpt.3 +pts.4 + Michael Kerrisk + Use the term "pseudoterminal multiplexor device" for /dev/ptmx + Let's use some consistent terminology for this device. + +posix_memalign.3 + Bruno Haible + Clarify how to free the result of posix_memalign + +pthread_rwlockattr_setkind_np.3 + Carlos O'Donell [Kumar Kartikeya Dwivedi] + Clarify a PTHREAD_RWLOCK_PREFER_WRITER_NP detail + +queue.3 + Alejandro Colomar + Remove wrong code from example + Alejandro Colomar + Comment out text for functions not in glibc (related: 6559169cac) + +pts.4 + Michael Kerrisk + Remove NOTES on BSD pseudoterminals + This information is already covered better in pty(7). No need to + mention it again here. + +hosts.5 + Thomas Bartelsmeier + Clarify capability for IPv6 outside of examples + Resolves https://bugzilla.kernel.org/show_bug.cgi?id=208279 + +proc.5 + Jakub Wilk + 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. + Arkadiusz Drabczyk + Inform that comm in /proc/pid/{stat,status} might also be truncated + pgrep for example searches for a process name in /proc/pid/status + +resolv.conf.5 + Michael Kerrisk [Helge Kreutzmann] + Clarify that ip6-bytestring was removed in 2.25 + +capabilities.7 + Dan Kenigsberg + Clarify that CAP_SYS_NICE relates to *lowering* the nice value + Saikiran Madugula + 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. + Michael Kerrisk [Dan Kenigsberg] + Clarify wording around increasing process nice value + Michael Kerrisk + SEE ALSO: add getpcaps(8) + +cgroups.7 +cpuset.7 + Sven Hoexter + Update kernel cgroup documentation references + cgroups-v1/v2 documentation got moved to the "admin-guide" subfolder + and converted from .txt files to .rst + +ip.7 + Michael Kerrisk [Stephen Hemminger] + Remove mention of ipfw(4) which was in long obsolete ipchains project + +man-pages.7 + Michael Kerrisk + Add some notes on generating optimal glyphs + Getting nice renderings of ^ ` and ~ requires special + steps in the page source. + +pty.7 + Michael Kerrisk + Explicitly mention CONFIG_LEGACY_PTYS + Explicitly mention CONFIG_LEGACY_PTYS, and note that it is disabled + by default since Linux 2.6.30. + Michael Kerrisk + Relocate a paragraph to NOTES + +standards.7 + Michael Kerrisk + Add an entry for POSIX.1-1988 + Michael Kerrisk [Geoff Clare] + Correct various details in the explanation of XPG/POSIX/SUS + +ld.so.8 + Florian Weimer [Michael Kerrisk] + List more places in which dynamic string tokens are expanded + This happens for more than just DT_RPATH/DT_RUNPATH. + Arkadiusz Drabczyk + Explain that empty entry in LD_LIBRARY_PATH means cwd + +zic.8 + Michael Kerrisk + Sync to 2020a tzdb release + From https://www.iana.org/time-zones, version 2020a.