From 480d8858617dc3cc3ad808fc628acd85766923d4 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Thu, 9 May 2019 09:46:26 +0200 Subject: [PATCH] Start of man-pages-5.02: updating Changes and Changes.old --- Changes | 230 ++---------------------------------------------- Changes.old | 249 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 258 insertions(+), 221 deletions(-) diff --git a/Changes b/Changes index 14231a61ac..464579ad9f 100644 --- a/Changes +++ b/Changes @@ -1,6 +1,6 @@ -==================== Changes in man-pages-5.01 ==================== +==================== Changes in man-pages-5.02 ==================== -Released: 2019-05-09, Munich +Released: ????-??-??, Munich Contributors @@ -10,238 +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: -Abhinav Upadhyay -Andreas Korb -Anisse Astier -Brice Goglin -Carlos O'Donell -Dr. Jürgen Sauermann -Egmont Koblinger -Elias Benali -Elliot Hughes -Florian Weimer -Hugues Evrard -Jakub Nowak -Jakub Wilk -Keegan Saunders -Lucas Werkmeister -Marcus Huewe -Michael Kerrisk -Michael Witten -Seth Troisi -Slavomir Kaslev -Vincent Lefevre -Wladimir Mutel Apologies if I missed anyone! +New and rewritten pages +----------------------- + + Newly documented interfaces in existing pages --------------------------------------------- -tsearch.3 - Florian Weimer [Michael Kerrisk] - Document the twalk_r() function added in glibc 2.30 - New and changed links --------------------- -twalk_r.3 - Michael Kerrisk - New link to twalk(3) page + +Global changes +-------------- Changes to individual pages --------------------------- -accept.2 - Michael Kerrisk - Note that 'addrlen' is left unchanged in the event of an error - See http://austingroupbugs.net/view.php?id=836. - -bpf.2 - Michael Kerrisk - Update kernel version info for JIT compiler - -clone.2 - Michael Kerrisk [Jakub Nowak] - CLONE_CHILD_SETTID has effect before clone() returns *in the child* - CLONE_CHILD_SETTID may not have had effect by the time clone() - returns in the parent, which could be relevant if the - CLONE_VM flag is employed. The relevant kernel code is in - schedule_tail(), which is called in ret_from_fork() - in the child. - - See https://bugzilla.kernel.org/show_bug.cgi?id=203105 - -execve.2 -exec.3 - Michael Kerrisk [Dr. Jürgen Sauermann] - Consistently use the term 'pathname' (not 'path') - -execve.2 - Michael Kerrisk - Note that stack+environ size is also limited to 3/4 of _STK_LIM - In fs/exec.c::prepare_arg_pages(), we have: - - limit = _STK_LIM / 4 * 3; - limit = min(limit, bprm->rlim_stack.rlim_cur / 4); - Michael Kerrisk [Dr. Jürgen Sauermann] - SEE ALSO: refer to exec(3) (rather than execl(3)) - -pipe.2 - Michael Kerrisk - Note that 'pipefd' is left unchanged in the event of an error - See http://austingroupbugs.net/view.php?id=467. - -sched_setaffinity.2 - Michael Kerrisk [Brice Goglin] - Correct details of return value of sched_getaffinity() syscall - Things changed a little with: - - commit cd3d8031eb4311e516329aee03c79a08333141f1 - Author: KOSAKI Motohiro - Date: Fri Mar 12 16:15:36 2010 +0900 - -setfsgid.2 - Michael Kerrisk - Rewrite for improved clarity and defer to setfsuid() for details - Rewrite for improved clarity and defer to setfsuid(2) for the - rationale of the fsGID rather than repeating the same details - in this page. - -setfsuid.2 - Michael Kerrisk - Rewrite for improved clarity and to hint history more explicitly - The current text reads somewhat clumsily. Rewrite it to introduce - the eUID and fsUID in parallel, and more clearly hint at the the - historical rationale for the fsUID, which is detailed lower in - the page. - -socketpair.2 - Michael Kerrisk - Clarify that 'sv' is left unchanged in the event of an error - See also http://austingroupbugs.net/view.php?id=483. - -splice.2 - Slavomir Kaslev - EAGAIN can occur when called on nonblocking file descriptors - -syscalls.2 - Michael Kerrisk [Andreas Korb] - Remove crufty text about i386 syscall dispatch table - The removed text long ago ceased to be accurate. Nowadays, the - dispatch table is autogenerated when building the kernel (via - the kernel makefile, arch/x86/entry/syscalls/Makefile). - -tee.2 - Slavomir Kaslev - EAGAIN can occur when called on nonblocking file descriptors - -fopen.3 - Elliot Hughes - Explain BSD vs glibc "a+" difference - Where is the initial read position for an "a+" stream? - - POSIX leaves this unspecified. Most BSD man pages are silent, and - MacOS has the ambiguous "The stream is positioned at the end of - the file", not differentiating between reads and writes other than - to say that fseek(3) does not affect writes. glibc's documentation - explicitly specifies that the initial read position is the - beginning of the file. - - My new wording is based on the BSD implementations, so you may - prefer to replace the non-glibc section with "unspecified", or - indeed remove all claims about the initial read position. - -mallinfo.3 - Elliott Hughes - Further discourage use of mallinfo() - The BUGS section already explains why you need to be cautious - about using mallinfo, but given the number of bug reports we see - on Android, it seems not many people are reading that far. Call it - out up front. - -malloc_trim.3 - Carlos O'Donell - Update trimming information - Since glibc 2.8, commit 68631c8eb92, the malloc_trim function has - iterated over all arenas and free'd back to the OS all page runs - that were free. This allows an application to call malloc_trim to - consolidate fragmented chunks and free back any pages it can to - potentially reduce RSS usage. - -posix_memalign.3 - Elliot Hughes - Some functions set errno - True of bionic, glibc, and musl. (I didn't check elsewhere.) - -resolver.3 - Michael Kerrisk [Wladimir Mutel] - Mention that some functions set 'h_errno' - -stdarg.3 - Michael Kerrisk [Vincent Lefevre] - Remove the NOTES section describing the ancient varargs macros - stdarg.h is now 30 years old, and gcc long ago (2004) ceased to - implement . There seems little value in keeping this - text. - - See https://bugzilla.kernel.org/show_bug.cgi?id=202907 - Michael Kerrisk [Egmont Koblinger] - Add a note that "..." in function signature means a variadic function - Egmont suggested adding this, because the string "..." appears - at several other points in the page, but just to indicate that - some text is omitted from example code. - -strerror.3 - Jakub Wilk - Don't discuss buffer size for strerror_l() - Unlike strerror_r(), strerror_l() doesn't take buffer length as an - argument. - -strtol.3 -strtoul.3 - Jakub Wilk - SEE ALSO: add strtoimax(3), strtoumax(3) - -sysconf.3 - Michael Kerrisk [Hugues Evrard] - Clearly note that _SC_PAGESIZE and _SC_PAGE_SIZE are synonyms - -tsearch.3 - Florian Weimer - Do not use const arguments in twalk() callback - The const specifier is not part of the prototype (it only applies - to the implementation), so showing it here confuses the reader. - Michael Kerrisk - SYNOPSIS: add missing definition of 'VISIT' type - Michael Kerrisk - Reformat twalk() and twalk_r() prototypes for easier readability - -console_codes.4 - Jakub Wilk - Document that \e[1;n] and \e[2;n] support 16 colors - Source: setterm_command() in drivers/tty/vt/vt.c - -elf.5 - Michael Kerrisk [Keegan Saunders] - A data segment does not have PF_X - -proc.5 - Michael Witten [Anisse Astier] - Add missing Inode field to /proc/net/unix - -hostname.7 - Florian Weimer - HOSTALIASES/search path processing is DNS-specific - Other NSS modules do not necessarily honor these settings. - -inode.7 - Michael Kerrisk - Note that timestamp fields measure time starting at the Epoch - Michael Kerrisk - Timestamp fields are structures that include a nanosecond component - Michael Kerrisk - Add references to execve(2) to describe set-UID/set-GID behaviors diff --git a/Changes.old b/Changes.old index 3504f7f94b..62768279e2 100644 --- a/Changes.old +++ b/Changes.old @@ -49191,3 +49191,252 @@ zdump.8 zic.8 Paul Eggert Sync from tzdb upstream + + +==================== Changes in man-pages-5.01 ==================== + +Released: 2019-05-09, 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: + +Abhinav Upadhyay +Andreas Korb +Anisse Astier +Brice Goglin +Carlos O'Donell +Dr. Jürgen Sauermann +Egmont Koblinger +Elias Benali +Elliot Hughes +Florian Weimer +Hugues Evrard +Jakub Nowak +Jakub Wilk +Keegan Saunders +Lucas Werkmeister +Marcus Huewe +Michael Kerrisk +Michael Witten +Seth Troisi +Slavomir Kaslev +Vincent Lefevre +Wladimir Mutel + +Apologies if I missed anyone! + + +Newly documented interfaces in existing pages +--------------------------------------------- + +tsearch.3 + Florian Weimer [Michael Kerrisk] + Document the twalk_r() function added in glibc 2.30 + + +New and changed links +--------------------- + +twalk_r.3 + Michael Kerrisk + New link to twalk(3) page + + +Changes to individual pages +--------------------------- + +accept.2 + Michael Kerrisk + Note that 'addrlen' is left unchanged in the event of an error + See http://austingroupbugs.net/view.php?id=836. + +bpf.2 + Michael Kerrisk + Update kernel version info for JIT compiler + +clone.2 + Michael Kerrisk [Jakub Nowak] + CLONE_CHILD_SETTID has effect before clone() returns *in the child* + CLONE_CHILD_SETTID may not have had effect by the time clone() + returns in the parent, which could be relevant if the + CLONE_VM flag is employed. The relevant kernel code is in + schedule_tail(), which is called in ret_from_fork() + in the child. + + See https://bugzilla.kernel.org/show_bug.cgi?id=203105 + +execve.2 +exec.3 + Michael Kerrisk [Dr. Jürgen Sauermann] + Consistently use the term 'pathname' (not 'path') + +execve.2 + Michael Kerrisk + Note that stack+environ size is also limited to 3/4 of _STK_LIM + In fs/exec.c::prepare_arg_pages(), we have: + + limit = _STK_LIM / 4 * 3; + limit = min(limit, bprm->rlim_stack.rlim_cur / 4); + Michael Kerrisk [Dr. Jürgen Sauermann] + SEE ALSO: refer to exec(3) (rather than execl(3)) + +pipe.2 + Michael Kerrisk + Note that 'pipefd' is left unchanged in the event of an error + See http://austingroupbugs.net/view.php?id=467. + +sched_setaffinity.2 + Michael Kerrisk [Brice Goglin] + Correct details of return value of sched_getaffinity() syscall + Things changed a little with: + + commit cd3d8031eb4311e516329aee03c79a08333141f1 + Author: KOSAKI Motohiro + Date: Fri Mar 12 16:15:36 2010 +0900 + +setfsgid.2 + Michael Kerrisk + Rewrite for improved clarity and defer to setfsuid() for details + Rewrite for improved clarity and defer to setfsuid(2) for the + rationale of the fsGID rather than repeating the same details + in this page. + +setfsuid.2 + Michael Kerrisk + Rewrite for improved clarity and to hint history more explicitly + The current text reads somewhat clumsily. Rewrite it to introduce + the eUID and fsUID in parallel, and more clearly hint at the the + historical rationale for the fsUID, which is detailed lower in + the page. + +socketpair.2 + Michael Kerrisk + Clarify that 'sv' is left unchanged in the event of an error + See also http://austingroupbugs.net/view.php?id=483. + +splice.2 + Slavomir Kaslev + EAGAIN can occur when called on nonblocking file descriptors + +syscalls.2 + Michael Kerrisk [Andreas Korb] + Remove crufty text about i386 syscall dispatch table + The removed text long ago ceased to be accurate. Nowadays, the + dispatch table is autogenerated when building the kernel (via + the kernel makefile, arch/x86/entry/syscalls/Makefile). + +tee.2 + Slavomir Kaslev + EAGAIN can occur when called on nonblocking file descriptors + +fopen.3 + Elliot Hughes + Explain BSD vs glibc "a+" difference + Where is the initial read position for an "a+" stream? + + POSIX leaves this unspecified. Most BSD man pages are silent, and + MacOS has the ambiguous "The stream is positioned at the end of + the file", not differentiating between reads and writes other than + to say that fseek(3) does not affect writes. glibc's documentation + explicitly specifies that the initial read position is the + beginning of the file. + + My new wording is based on the BSD implementations, so you may + prefer to replace the non-glibc section with "unspecified", or + indeed remove all claims about the initial read position. + +mallinfo.3 + Elliott Hughes + Further discourage use of mallinfo() + The BUGS section already explains why you need to be cautious + about using mallinfo, but given the number of bug reports we see + on Android, it seems not many people are reading that far. Call it + out up front. + +malloc_trim.3 + Carlos O'Donell + Update trimming information + Since glibc 2.8, commit 68631c8eb92, the malloc_trim function has + iterated over all arenas and free'd back to the OS all page runs + that were free. This allows an application to call malloc_trim to + consolidate fragmented chunks and free back any pages it can to + potentially reduce RSS usage. + +posix_memalign.3 + Elliot Hughes + Some functions set errno + True of bionic, glibc, and musl. (I didn't check elsewhere.) + +resolver.3 + Michael Kerrisk [Wladimir Mutel] + Mention that some functions set 'h_errno' + +stdarg.3 + Michael Kerrisk [Vincent Lefevre] + Remove the NOTES section describing the ancient varargs macros + stdarg.h is now 30 years old, and gcc long ago (2004) ceased to + implement . There seems little value in keeping this + text. + + See https://bugzilla.kernel.org/show_bug.cgi?id=202907 + Michael Kerrisk [Egmont Koblinger] + Add a note that "..." in function signature means a variadic function + Egmont suggested adding this, because the string "..." appears + at several other points in the page, but just to indicate that + some text is omitted from example code. + +strerror.3 + Jakub Wilk + Don't discuss buffer size for strerror_l() + Unlike strerror_r(), strerror_l() doesn't take buffer length as an + argument. + +strtol.3 +strtoul.3 + Jakub Wilk + SEE ALSO: add strtoimax(3), strtoumax(3) + +sysconf.3 + Michael Kerrisk [Hugues Evrard] + Clearly note that _SC_PAGESIZE and _SC_PAGE_SIZE are synonyms + +tsearch.3 + Florian Weimer + Do not use const arguments in twalk() callback + The const specifier is not part of the prototype (it only applies + to the implementation), so showing it here confuses the reader. + Michael Kerrisk + SYNOPSIS: add missing definition of 'VISIT' type + Michael Kerrisk + Reformat twalk() and twalk_r() prototypes for easier readability + +console_codes.4 + Jakub Wilk + Document that \e[1;n] and \e[2;n] support 16 colors + Source: setterm_command() in drivers/tty/vt/vt.c + +elf.5 + Michael Kerrisk [Keegan Saunders] + A data segment does not have PF_X + +proc.5 + Michael Witten [Anisse Astier] + Add missing Inode field to /proc/net/unix + +hostname.7 + Florian Weimer + HOSTALIASES/search path processing is DNS-specific + Other NSS modules do not necessarily honor these settings. + +inode.7 + Michael Kerrisk + Note that timestamp fields measure time starting at the Epoch + Michael Kerrisk + Timestamp fields are structures that include a nanosecond component + Michael Kerrisk + Add references to execve(2) to describe set-UID/set-GID behaviors -- 2.47.3