From 18e408ec5fcd21960a62448c6eaeeb3e8825e7ef Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Mon, 22 Mar 2021 11:19:38 +0100 Subject: [PATCH] Start of man-pages-5.12: updating Changes and Changes.old --- Changes | 819 +------------------------------------------------- Changes.old | 852 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 854 insertions(+), 817 deletions(-) diff --git a/Changes b/Changes index e767b0329..24ceb67e2 100644 --- a/Changes +++ b/Changes @@ -1,6 +1,6 @@ -==================== Changes in man-pages-5.11 ==================== +==================== Changes in man-pages-5.12 ==================== -Released: 2021-03-21, Munich +Released: ????-??-??, Munich Contributors @@ -10,48 +10,6 @@ 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 -Alessandro Bono -Alyssa Ross -Bastien Roucariès -Bruno Haible -Christian Brauner -Ciprian Dorin Craciun -Dmitry V. Levin -Dmitry Vorobev -edef -Enke Chen -Gabriel Krisman Bertazi -Ganimedes Colomar -Jakub Wilk -Jan Kara -Jens Axboe -Johannes Pfister -Johannes Wellhöfer -John Morris -Jonathan Wakely -Jonny Grant -Manfred Spraul -Michael Kerrisk -Michal Hocko -Minchan Kim -Pádraig Brady -Pali Rohár -Palmer Dabbelt -Paran Lee -Peter H. Froehlich -Philipp Schuster -Stephen Kitt -Steve Grubb -Suren Baghdasaryan -Szunti -Valentin Kettner -Vincent Lefevre -Walter Franzini -Walter Harms -Willem de Bruijn -Yang Xu -Zack Weinberg Apologies if I missed anyone! @@ -59,792 +17,19 @@ Apologies if I missed anyone! New and rewritten pages ----------------------- -close_range.2 - Stephen Kitt, Michael Kerrisk [Christian Brauner] - New page documenting close_range(2) - -process_madvise.2 - Suren Baghdasaryan, Minchan Kim [Michal Hocko, Alejandro Colomar, - Michael Kerrisk] - Document process_madvise(2) - -fileno.3 - Michael Kerrisk - Split fileno(3) content out of ferror(3) into new page - fileno(3) differs from the other functions in various ways. - For example, it is governed by different standards, - and can set 'errno'. Conversely, the other functions - are about examining the status of a stream, while - fileno(3) simply obtains the underlying file descriptor. - Furthermore, splitting this function out allows - for some cleaner upcoming changes in ferror(3). - Newly documented interfaces in existing pages --------------------------------------------- -epoll_wait.2 - Willem de Bruijn [Dmitry V. Levin] - Add documentation of epoll_pwait2() - Expand the epoll_wait() page with epoll_pwait2(), an epoll_wait() - variant that takes a struct timespec to enable nanosecond - resolution timeout. - -fanotify_init.2 -fanotify.7 - Jan Kara [Steve Grubb] - Document FAN_AUDIT flag and FAN_ENABLE_AUDIT - -madvise.2 - Michael Kerrisk - Add descriptions of MADV_COLD and MADV_PAGEOUT - Taken from process_madvise(2). - -openat2.2 - Jens Axboe - Add RESOLVE_CACHED - -prctl.2 - Gabriel Krisman Bertazi - Document Syscall User Dispatch - -mallinfo.3 - Michael Kerrisk - Document mallinfo2() and note that mallinfo() is deprecated - Document the mallinfo2() function added in glibc 2.33. - Update example program to use mallinfo2() - -system_data_types.7 - Alejandro Colomar - Add off64_t to system_data_types(7) - -ld.so.8 - Michael Kerrisk - Document the --argv0 option added in glibc 2.33 - New and changed links --------------------- -epoll_pwait2.2 - Dmitry V. Levin - New link to epoll_wait(2) - -mallinfo2.3 - Michael Kerrisk - New link to mallinfo(3) - -off64_t.3 - Alejandro Colomar - New link to system_data_types(7) - Global changes -------------- -Various pages - Alejandro Colomar - SYNOPSIS: Use 'restrict' in prototypes - This change has been completed for *all* relevant pages - (around 135 pages in total). - -Various pages - Alejandro Colomar [Zack Weinberg] - Remove unused - The manual pages are already inconsistent in which headers need - to be included. Right now, not all of the types used by a - function have their required header included in the SYNOPSIS. - - If we were to add the headers required by all of the types used by - functions, the SYNOPSIS would grow too much. Not only it would - grow too much, but the information there would be less precise. - - Having system_data_types(7) document each type with all the - information about required includes is much more precise, and the - info is centralized so that it's much easier to maintain. - - So let's document only the include required for the function - prototype, and also the ones required for the macros needed to - call the function. - - only defines types, not functions or constants, so - it doesn't belong to man[23] (function) pages at all. - - I ignore if some old systems had headers that required you to - include *before* them (incomplete headers), but if - so, those implementations would be broken, and those headers - should probably provide some kind of warning. I hope this is not - the case. - - [mtk: Already in 2001, POSIX.1 removed the requirement to - include for many APIs, so this patch seems - well past due.] - -A few pages - Alejandro Colomar - Add notes about missing glibc wrappers - -_exit.2 -abort.3 -err.3 -exit.3 -pthread_exit.3 -setjmp.3 - Alejandro Colomar - SYNOPSIS: Use 'noreturn' in prototypes - Use standard C11 'noreturn' in these manual page for - functions that do not return. - -Various pages - Ganimedes Colomar [Alejandro Colomar] - Normalize SYNOPSIS notes about nonexistent glibc wrappers - To easily distinguish documentation about glibc wrappers from - documentation about kernel syscalls, let's have a normalized - 'Note' in the SYNOPSIS, and a further explanation in the page body - (NOTES in most of them), as already happened in many (but not all) - of the manual pages for syscalls without a wrapper. Furthermore, - let's normalize the messages, following membarrier.2 (because it's - already quite extended), so that it's easy to use grep to find - those pages. - Normalize NOTES about nonexistent glibc wrappers - This commit normalizes texts under sections other than SYNOPSIS - (most of them in NOTES). - - -Global changes (formatting fixes and minor edits) -------------------------------------------------- - -Various pages - Michael Kerrisk - ERRORS: remove redundant statement that 'errno' is set - This is implied in every other manual page. There is no need to - state it explicitly in these pages. - -Various pages - Michael Kerrisk - Use periods more consistently inside code comments - In general, complete sentences in free-standing comments - should be terminated by periods. - -A few pages - Michael Kerrisk - Better table formatting - In particular, allow for rendering in widths different from - (especially less than) 80 columns. - -Various pages - Michael Kerrisk - Consistency fix-up in FTMs - Generally, place '||' at start of a line, rather than the end of - the previous line. - - Rationale: this placement clearly indicates that that each piece - is an alternative. - -Various pages - Michael Kerrisk [Alejandro Colomar] - Bring more whitespace consistency in SYNOPSIS - The use of vertical white space in the SYNOPSIS sections - is rather inconsistent. Make it more consistent, subject to the - following heuristics: - - * Prefer no blank lines between function signatures by default. - * Where many functions are defined in the SYNOPSIS, add blank - lines where needed to improve readability, possibly by using - blank lines to separate logical groups of functions. - -Various pages - Alejandro Colomar - Consistently use 'unsigned int' - Most pages use 'unsigned int' (and the kernel too). - Make them all do so. - -Various pages - Michael Kerrisk - Various improvements in wording in RETURN VALUE - -Various pages - Michael Kerrisk - s/Glibc versions . - -clone.2 - Valentin Kettner - Fix types in clone_args - A file descriptor is an int so it should be stored through an int - pointer while parent_tid should have the same type as child_tid - which is pid_t pointer. - -close.2 - Michael Kerrisk - SEE ALSO: add close_range(2) - -copy_file_range.2 - Alejandro Colomar - Document glibc wrapper instead of kernel syscall - Glibc uses 'off64_t' instead of 'loff_t'. - -delete_module.2 - Alejandro Colomar - SYNOPSIS: Fix prototype parameter types - The Linux kernel uses 'unsigned int' instead of 'int' for the - 'flags' parameter. As glibc provides no wrapper, use the same - type the kernel uses. - -epoll_create.2 - Michael Kerrisk - CONFORMING TO: mention that epoll_create1() is Linux-specific - -epoll_wait.2 - Michael Kerrisk - CONFORMING TO: mention that epoll_pwait() is Linux-specific - -execve.2 - Palmer Dabbelt - Correct the versions of Linux that don't have ARG_MAX argv/envp size - -execveat.2 - Alejandro Colomar - Fix prototype - It's been 6 years since execveat(2) was added to the kernel, - and there's still no glibc wrapper. Let's document the kernel - syscall prototype. - -getcpu.2 - Michael Kerrisk [Alejandro Colomar] - Rewrite page to describe glibc wrapper function - Since glibc 2.29, there is a wrapper for getcpu(2). - The wrapper has only 2 arguments, omitting the unused - third system call argument. Rework the manual page - to reflect this. - -getgid.2 -getuid.2 - Michael Kerrisk - Note that these interfaces never modify 'errno' - See https://www.austingroupbugs.net/view.php?id=511 - and the POSIX.1-2008 specifications of the interfaces. - -gethostname.2 - Michael Kerrisk - Update FTM requirements for gethostname() - -getpagesize.2 -getdtablesize.3 - Michael Kerrisk - Update/correct FTM requirements - -getrusage.2 - Michael Kerrisk - Starting in 2.33, glibc no longer provides vtimes() - -ioctl_tty.2 - Michael Kerrisk - Reformat argument type information - The current mark-up renders poorly. To resolve this, move - the type information into a separate line. - -ipc.2 - Alejandro Colomar - Fix prototype parameter types - -kcmp.2 - Michael Kerrisk - Since Linux 5.12, kcmp() availability is unconditional - kcmp() is no longer dependent on CONFIG_CHECKPOINT_RESTORE. - -keyctl.2 - Alejandro Colomar - SYNOPSIS: Fix prototype parameter types - The Linux kernel uses 'unsigned long'. - There's no reason to use the typedef '__kernel_ulong_t'. - -lookup_dcookie.2 - Alejandro Colomar - Use standard types: u64 -> uint64_t - -madvise.2 - Michael Kerrisk - SEE ALSO: add process_madvise(2) - -mlock.2 - Alejandro Colomar - mlock2(): Fix prototype parameter types - The documented prototype for mlock2() was a mix of the - glibc wrapper prototype and the kernel syscall prototype. - Let's document the glibc wrapper prototype, which is shown below. - Michael Kerrisk - CONFORMING TO: note more explicitly which APIs are in the standards - -mmap2.2 - Alejandro Colomar - Fix prototype parameter types - There are many slightly different prototypes for this syscall, - but none of them is like the documented one. - Of all the different prototypes, - let's document the asm-generic one. - -mount.2 - Michael Kerrisk - Note that the 'data' argument can be NULL - -move_pages.2 - Alejandro Colomar - Add notes about missing glibc wrappers - -open.2 -rename.2 - Alyssa Ross - Refer to tmpfs rather than shmem - If I'm understanding correctly, tmpfs is a filesystem built on - shmem, so I think it's more correct (and probably much more - widely understandable) to refer to tmpfs here. - -pciconfig_read.2 - Alejandro Colomar - SYNOPSIS: Fix prototype parameter types - Use the glibc prototypes instead of the kernel ones. - Exception: use 'int' instead of 'enum'. - -pidfd_open.2 - Michael Kerrisk - Note the process_madvise(2) use case for PID file descriptors - -readlink.2 - Michael Kerrisk [Jonny Grant] - Emphasize that the returned buffer is not null-terminated - -s390_pci_mmio_write.2 - Alejandro Colomar - SYNOPSIS: Add 'const' qualifier - s390_pci_mmio_write() uses 'const void *' instead of 'void *'. - -sched_setattr.2 - Alejandro Colomar - Add note about missing glibc wrappers - -semctl.2 - Yang Xu [Alejandro Colomar, Manfred Spraul] - Correct SEM_STAT_ANY description - -socketcall.2 - Alejandro Colomar - Add note about missing glibc wrapper - -splice.2 - Alejandro Colomar - Use 'off64_t' instead of 'loff_t' - The kernel syscall uses 'loff_t', but the glibc wrapper uses 'off64_t'. - Let's document the wrapper prototype, as in other pages. - -spu_create.2 - Alejandro Colomar - SYNOPSIS: Fix prototype parameter type - The 'flags' parameter of spu_create() uses 'unsigned int'. - -spu_run.2 - Alejandro Colomar - SYNOPSIS: Fix prototype parameter types - The 2nd and 3rd parameters of spu_run() use 'uint32_t *'. - -stat.2 - Jonathan Wakely [Alejandro Colomar] - Remove from SYNOPSIS - There seems to be no reason is shown here, so remove it. - Michael Kerrisk - Move the obsolete _BSD_SOURCE FTM to the end of the FTM info - -syscall.2 - Peter H. Froehlich - Update superh syscall convention - -syscalls.2 - Michael Kerrisk - Add epoll_pwait2() - -tkill.2 - Alejandro Colomar - SYNOPSIS: Fix prototype parameter types - All but the last parameters of t[g]kill() use 'pid_t', - both in the kernel and glibc. - -vmsplice.2 - Alejandro Colomar - SYNOPSIS: Fix prototype parameter type - The 3rd parameter of vmsplice() uses 'size_t' in glibc. - -bstring.3 - Michael Kerrisk - SEE ALSO: add string(3) - -circleq.3 -list.3 -slist.3 -stailq.3 -tailq.3 - Alejandro Colomar - Improve readability, especially in SYNOPSIS - -circleq.3 - Alejandro Colomar - Fix CIRCLEQ_LOOP_*() return type - -crypt.3 - Michael Kerrisk - Reformat FTM info (in preparation for next patch) - Michael Kerrisk - Update crypt() FTM requirements to note glibc 2.28 changes - -ecvt.3 -gcvt.3 - Michael Kerrisk - Update FTM requirements - -error.3 - Michael Kerrisk [Alejandro Colomar, Walter Harms] - Clarify the meaning of 'status==0' for error(3) - -ferror.3 - Michael Kerrisk - Remove fileno(3) content that was migrated to new fileno(3) page - Michael Kerrisk - Add a RETURN VALUE section - Michael Kerrisk - POSIX.1-2008: these functions won't change 'errno' if 'stream' is valid - See https://www.austingroupbugs.net/view.php?id=401. - -fread.3 - Alessandro Bono - EXAMPLES: swap size and nmemb params - It works both ways, but this one feels more right. We are reading - four elements sizeof(*buffer) bytes each. - -fseeko.3 - Michael Kerrisk - Move info about obsolete FTM from SYNOPSIS to NOTES - This makes the SYNOPSIS more consistent with other pages. - -ftime.3 - Michael Kerrisk - glibc 2.33 has removed ftime() - -ftw.3 - Alejandro Colomar - SYNOPSIS: Remove duplicate header - -gethostbyname.3 - Michael Kerrisk - Move mention of from SYNOPSIS to DESCRIPTION - The functions are all declared in . is only - needed for the AF_* constants. - -gethostid.3 - Michael Kerrisk - Update FTM requirements for gethostid() - -get_phys_pages.3 - Alejandro Colomar [Jakub Wilk] - glibc gets the info from sysinfo(2) since 2.23 - -grantpt.3 -ptsname.3 -unlockpt.3 - Michael Kerrisk - Remove mention of _XOPEN_SOURCE_EXTENDED FTM - This rather ancient FTM is not mentioned in other pages for - reasons discussed in feature_test_macros(7). Remove this FTM - from the three pages where it does appear. - -malloc.3 - Alejandro Colomar [Johannes Pfister] - Document that realloc(p, 0) is specific to glibc and nonportable - -malloc_hook.3 - Alejandro Colomar - SYNOPSIS: Use 'volatile' in prototypes - -malloc_trim.3 - Dmitry Vorobev - Remove mention of free() call - 'malloc_trim' was and is never called from the 'free' function. - -pthread_create.3 - Michael Kerrisk [Paran Lee] - Fix undeclared variable error in example program - Michael Kerrisk - Fix a signedness error in the example code - -puts.3 - Michael Kerrisk - Reorder functions more logically (group related functions together) - -qecvt.3 - Michael Kerrisk - Update feature test macro requirements - -setbuf.3 - Michael Kerrisk - POSIX doesn't require errno to be unchanged after successful setbuf() - See https://www.austingroupbugs.net/view.php?id=397#c799 - -setlocale.3 - Michael Kerrisk [Alejandro Colomar, Bruno Haible] - Restructure a particularly difficult sentence - -simpleq.3 -stailq.3 -queue.7 -SIMPLEQ_*.3 - Alejandro Colomar - Document SIMPLEQ_*() as an alias to STAILQ_*() macros - -strerror.3 - Alejandro Colomar - strerrorname_np() and strerrordesc_np() first appeared on glibc 2.32 - -string.3 - Michael Kerrisk - SEE ALSO: add bstring(3) - -system.3 - Alejandro Colomar [Ciprian Dorin Craciun] - Document bug and workaround when the command name starts with a hyphen - -environ.7 - Bastien Roucariès - Reorder the text - Move the the text describing how to set environment variable before - the list(s) of variables in order to improve readability. - Bastien Roucariès - Document convention of string in environ - Document the name=value system and that nul byte is forbidden. - Bastien Roucariès - Document that HOME, LOGNAME, SHELL, USER are set at login time - and point to the su(1) manual page. - Bastien Roucariès - Add see also ld.so(8) for LD_ variables - Michael Kerrisk [Bastien Roucariès] - Improve the description of PATH - Add more details of how PATH is used, and mention the legacy - use of an empty prefix. - Bastien Roucariès [Alejandro Colomar, Bastien Roucaries, Vincent Lefevre] - Document valid values of pathnames for SHELL, PAGER and EDITOR/VISUAL - Michael Kerrisk [Bastien Roucariès] - Note the default if PAGER is not defined - Michael Kerrisk - Be a little more precise when discussing 'exec' - Say "execve(2)" instead of "exec(3)", and note that this step - starts a new program (not a new process!). - Michael Kerrisk [Bastien Roucariès] - Relocate and reword the mention of _GNU_SOURCE - -man-pages.7 - Michael Kerrisk - Document "acknowledgement" as the preferred spelling - Michael Kerrisk - Add some notes on comments in example code - Michael Kerrisk - Add a FORMATTING AND WORDING CONVENTIONS section - In man-pages-5.11, a large number of pages were edited to achieve - greater consistency in the SYNOPIS, RETURN VALUE and ATTRIBUTES - sections. To avoid future inconsistencies, try to capture some of - the preferred conventions in text in man-pages(7). - Michael Kerrisk - Note some rationale for the use of real minus signs - -netdevice.7 - Pali Rohár [Alejandro Colomar] - Update documentation for SIOCGIFADDR SIOCSIFADDR SIOCDIFADDR - -netlink.7 - Pali Rohár [Alejandro Colomar] - Fix minimal Linux version for NETLINK_CAP_ACK - NETLINK_CAP_ACK option was introduced in commit 0a6a3a23ea6e which first - appeared in Linux version 4.3 and not 4.2. - Pali Rohár [Alejandro Colomar] - Remove IPv4 from description - rtnetlink is not only used for IPv4 - Philipp Schuster - Clarify details of netlink error responses - Make it clear that netlink error responses (i.e., messages with - type NLMSG_ERROR (0x2)), can be longer than sizeof(struct - nlmsgerr). In certain circumstances, the payload can be longer. - -shm_overview.7 - Michael Kerrisk - SEE ALSO: add memfd_create(2) - -sock_diag.7 - Pali Rohár [Alejandro Colomar] - Fix recvmsg() usage in the example - -tcp.7 - Enke Chen - Documentation revision for TCP_USER_TIMEOUT - -uri.7 - Michael Kerrisk - Note that 'logical' quoting is the norm in Europe diff --git a/Changes.old b/Changes.old index 891e9b2a5..f863583b1 100644 --- a/Changes.old +++ b/Changes.old @@ -53339,3 +53339,855 @@ tcp.7 tcp_syncookies: It is now an integer [0, 2] Since Linux kernel 3.12, tcp_syncookies can have the value 2, which sends out cookies unconditionally. + + +==================== Changes in man-pages-5.11 ==================== + +Released: 2021-03-21, 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 +Alessandro Bono +Alyssa Ross +Bastien Roucariès +Bruno Haible +Christian Brauner +Ciprian Dorin Craciun +Dmitry V. Levin +Dmitry Vorobev +edef +Enke Chen +Gabriel Krisman Bertazi +Ganimedes Colomar +Jakub Wilk +Jan Kara +Jens Axboe +Johannes Pfister +Johannes Wellhöfer +John Morris +Jonathan Wakely +Jonny Grant +Manfred Spraul +Michael Kerrisk +Michal Hocko +Minchan Kim +Pádraig Brady +Pali Rohár +Palmer Dabbelt +Paran Lee +Peter H. Froehlich +Philipp Schuster +Stephen Kitt +Steve Grubb +Suren Baghdasaryan +Szunti +Valentin Kettner +Vincent Lefevre +Walter Franzini +Walter Harms +Willem de Bruijn +Yang Xu +Zack Weinberg + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +close_range.2 + Stephen Kitt, Michael Kerrisk [Christian Brauner] + New page documenting close_range(2) + +process_madvise.2 + Suren Baghdasaryan, Minchan Kim [Michal Hocko, Alejandro Colomar, + Michael Kerrisk] + Document process_madvise(2) + +fileno.3 + Michael Kerrisk + Split fileno(3) content out of ferror(3) into new page + fileno(3) differs from the other functions in various ways. + For example, it is governed by different standards, + and can set 'errno'. Conversely, the other functions + are about examining the status of a stream, while + fileno(3) simply obtains the underlying file descriptor. + Furthermore, splitting this function out allows + for some cleaner upcoming changes in ferror(3). + + +Newly documented interfaces in existing pages +--------------------------------------------- + +epoll_wait.2 + Willem de Bruijn [Dmitry V. Levin] + Add documentation of epoll_pwait2() + Expand the epoll_wait() page with epoll_pwait2(), an epoll_wait() + variant that takes a struct timespec to enable nanosecond + resolution timeout. + +fanotify_init.2 +fanotify.7 + Jan Kara [Steve Grubb] + Document FAN_AUDIT flag and FAN_ENABLE_AUDIT + +madvise.2 + Michael Kerrisk + Add descriptions of MADV_COLD and MADV_PAGEOUT + Taken from process_madvise(2). + +openat2.2 + Jens Axboe + Add RESOLVE_CACHED + +prctl.2 + Gabriel Krisman Bertazi + Document Syscall User Dispatch + +mallinfo.3 + Michael Kerrisk + Document mallinfo2() and note that mallinfo() is deprecated + Document the mallinfo2() function added in glibc 2.33. + Update example program to use mallinfo2() + +system_data_types.7 + Alejandro Colomar + Add off64_t to system_data_types(7) + +ld.so.8 + Michael Kerrisk + Document the --argv0 option added in glibc 2.33 + + +New and changed links +--------------------- + +epoll_pwait2.2 + Dmitry V. Levin + New link to epoll_wait(2) + +mallinfo2.3 + Michael Kerrisk + New link to mallinfo(3) + +off64_t.3 + Alejandro Colomar + New link to system_data_types(7) + + +Global changes +-------------- + +Various pages + Alejandro Colomar + SYNOPSIS: Use 'restrict' in prototypes + This change has been completed for *all* relevant pages + (around 135 pages in total). + +Various pages + Alejandro Colomar [Zack Weinberg] + Remove unused + The manual pages are already inconsistent in which headers need + to be included. Right now, not all of the types used by a + function have their required header included in the SYNOPSIS. + + If we were to add the headers required by all of the types used by + functions, the SYNOPSIS would grow too much. Not only it would + grow too much, but the information there would be less precise. + + Having system_data_types(7) document each type with all the + information about required includes is much more precise, and the + info is centralized so that it's much easier to maintain. + + So let's document only the include required for the function + prototype, and also the ones required for the macros needed to + call the function. + + only defines types, not functions or constants, so + it doesn't belong to man[23] (function) pages at all. + + I ignore if some old systems had headers that required you to + include *before* them (incomplete headers), but if + so, those implementations would be broken, and those headers + should probably provide some kind of warning. I hope this is not + the case. + + [mtk: Already in 2001, POSIX.1 removed the requirement to + include for many APIs, so this patch seems + well past due.] + +A few pages + Alejandro Colomar + Add notes about missing glibc wrappers + +_exit.2 +abort.3 +err.3 +exit.3 +pthread_exit.3 +setjmp.3 + Alejandro Colomar + SYNOPSIS: Use 'noreturn' in prototypes + Use standard C11 'noreturn' in these manual page for + functions that do not return. + +Various pages + Ganimedes Colomar [Alejandro Colomar] + Normalize SYNOPSIS notes about nonexistent glibc wrappers + To easily distinguish documentation about glibc wrappers from + documentation about kernel syscalls, let's have a normalized + 'Note' in the SYNOPSIS, and a further explanation in the page body + (NOTES in most of them), as already happened in many (but not all) + of the manual pages for syscalls without a wrapper. Furthermore, + let's normalize the messages, following membarrier.2 (because it's + already quite extended), so that it's easy to use grep to find + those pages. + Normalize NOTES about nonexistent glibc wrappers + This commit normalizes texts under sections other than SYNOPSIS + (most of them in NOTES). + + +Global changes (formatting fixes and minor edits) +------------------------------------------------- + +Various pages + Michael Kerrisk + ERRORS: remove redundant statement that 'errno' is set + This is implied in every other manual page. There is no need to + state it explicitly in these pages. + +Various pages + Michael Kerrisk + Use periods more consistently inside code comments + In general, complete sentences in free-standing comments + should be terminated by periods. + +A few pages + Michael Kerrisk + Better table formatting + In particular, allow for rendering in widths different from + (especially less than) 80 columns. + +Various pages + Michael Kerrisk + Consistency fix-up in FTMs + Generally, place '||' at start of a line, rather than the end of + the previous line. + + Rationale: this placement clearly indicates that that each piece + is an alternative. + +Various pages + Michael Kerrisk [Alejandro Colomar] + Bring more whitespace consistency in SYNOPSIS + The use of vertical white space in the SYNOPSIS sections + is rather inconsistent. Make it more consistent, subject to the + following heuristics: + + * Prefer no blank lines between function signatures by default. + * Where many functions are defined in the SYNOPSIS, add blank + lines where needed to improve readability, possibly by using + blank lines to separate logical groups of functions. + +Various pages + Alejandro Colomar + Consistently use 'unsigned int' + Most pages use 'unsigned int' (and the kernel too). + Make them all do so. + +Various pages + Michael Kerrisk + Various improvements in wording in RETURN VALUE + +Various pages + Michael Kerrisk + s/Glibc versions . + +clone.2 + Valentin Kettner + Fix types in clone_args + A file descriptor is an int so it should be stored through an int + pointer while parent_tid should have the same type as child_tid + which is pid_t pointer. + +close.2 + Michael Kerrisk + SEE ALSO: add close_range(2) + +copy_file_range.2 + Alejandro Colomar + Document glibc wrapper instead of kernel syscall + Glibc uses 'off64_t' instead of 'loff_t'. + +delete_module.2 + Alejandro Colomar + SYNOPSIS: Fix prototype parameter types + The Linux kernel uses 'unsigned int' instead of 'int' for the + 'flags' parameter. As glibc provides no wrapper, use the same + type the kernel uses. + +epoll_create.2 + Michael Kerrisk + CONFORMING TO: mention that epoll_create1() is Linux-specific + +epoll_wait.2 + Michael Kerrisk + CONFORMING TO: mention that epoll_pwait() is Linux-specific + +execve.2 + Palmer Dabbelt + Correct the versions of Linux that don't have ARG_MAX argv/envp size + +execveat.2 + Alejandro Colomar + Fix prototype + It's been 6 years since execveat(2) was added to the kernel, + and there's still no glibc wrapper. Let's document the kernel + syscall prototype. + +getcpu.2 + Michael Kerrisk [Alejandro Colomar] + Rewrite page to describe glibc wrapper function + Since glibc 2.29, there is a wrapper for getcpu(2). + The wrapper has only 2 arguments, omitting the unused + third system call argument. Rework the manual page + to reflect this. + +getgid.2 +getuid.2 + Michael Kerrisk + Note that these interfaces never modify 'errno' + See https://www.austingroupbugs.net/view.php?id=511 + and the POSIX.1-2008 specifications of the interfaces. + +gethostname.2 + Michael Kerrisk + Update FTM requirements for gethostname() + +getpagesize.2 +getdtablesize.3 + Michael Kerrisk + Update/correct FTM requirements + +getrusage.2 + Michael Kerrisk + Starting in 2.33, glibc no longer provides vtimes() + +ioctl_tty.2 + Michael Kerrisk + Reformat argument type information + The current mark-up renders poorly. To resolve this, move + the type information into a separate line. + +ipc.2 + Alejandro Colomar + Fix prototype parameter types + +kcmp.2 + Michael Kerrisk + Since Linux 5.12, kcmp() availability is unconditional + kcmp() is no longer dependent on CONFIG_CHECKPOINT_RESTORE. + +keyctl.2 + Alejandro Colomar + SYNOPSIS: Fix prototype parameter types + The Linux kernel uses 'unsigned long'. + There's no reason to use the typedef '__kernel_ulong_t'. + +lookup_dcookie.2 + Alejandro Colomar + Use standard types: u64 -> uint64_t + +madvise.2 + Michael Kerrisk + SEE ALSO: add process_madvise(2) + +mlock.2 + Alejandro Colomar + mlock2(): Fix prototype parameter types + The documented prototype for mlock2() was a mix of the + glibc wrapper prototype and the kernel syscall prototype. + Let's document the glibc wrapper prototype, which is shown below. + Michael Kerrisk + CONFORMING TO: note more explicitly which APIs are in the standards + +mmap2.2 + Alejandro Colomar + Fix prototype parameter types + There are many slightly different prototypes for this syscall, + but none of them is like the documented one. + Of all the different prototypes, + let's document the asm-generic one. + +mount.2 + Michael Kerrisk + Note that the 'data' argument can be NULL + +move_pages.2 + Alejandro Colomar + Add notes about missing glibc wrappers + +open.2 +rename.2 + Alyssa Ross + Refer to tmpfs rather than shmem + If I'm understanding correctly, tmpfs is a filesystem built on + shmem, so I think it's more correct (and probably much more + widely understandable) to refer to tmpfs here. + +pciconfig_read.2 + Alejandro Colomar + SYNOPSIS: Fix prototype parameter types + Use the glibc prototypes instead of the kernel ones. + Exception: use 'int' instead of 'enum'. + +pidfd_open.2 + Michael Kerrisk + Note the process_madvise(2) use case for PID file descriptors + +readlink.2 + Michael Kerrisk [Jonny Grant] + Emphasize that the returned buffer is not null-terminated + +s390_pci_mmio_write.2 + Alejandro Colomar + SYNOPSIS: Add 'const' qualifier + s390_pci_mmio_write() uses 'const void *' instead of 'void *'. + +sched_setattr.2 + Alejandro Colomar + Add note about missing glibc wrappers + +semctl.2 + Yang Xu [Alejandro Colomar, Manfred Spraul] + Correct SEM_STAT_ANY description + +socketcall.2 + Alejandro Colomar + Add note about missing glibc wrapper + +splice.2 + Alejandro Colomar + Use 'off64_t' instead of 'loff_t' + The kernel syscall uses 'loff_t', but the glibc wrapper uses 'off64_t'. + Let's document the wrapper prototype, as in other pages. + +spu_create.2 + Alejandro Colomar + SYNOPSIS: Fix prototype parameter type + The 'flags' parameter of spu_create() uses 'unsigned int'. + +spu_run.2 + Alejandro Colomar + SYNOPSIS: Fix prototype parameter types + The 2nd and 3rd parameters of spu_run() use 'uint32_t *'. + +stat.2 + Jonathan Wakely [Alejandro Colomar] + Remove from SYNOPSIS + There seems to be no reason is shown here, so remove it. + Michael Kerrisk + Move the obsolete _BSD_SOURCE FTM to the end of the FTM info + +syscall.2 + Peter H. Froehlich + Update superh syscall convention + +syscalls.2 + Michael Kerrisk + Add epoll_pwait2() + +tkill.2 + Alejandro Colomar + SYNOPSIS: Fix prototype parameter types + All but the last parameters of t[g]kill() use 'pid_t', + both in the kernel and glibc. + +vmsplice.2 + Alejandro Colomar + SYNOPSIS: Fix prototype parameter type + The 3rd parameter of vmsplice() uses 'size_t' in glibc. + +bstring.3 + Michael Kerrisk + SEE ALSO: add string(3) + +circleq.3 +list.3 +slist.3 +stailq.3 +tailq.3 + Alejandro Colomar + Improve readability, especially in SYNOPSIS + +circleq.3 + Alejandro Colomar + Fix CIRCLEQ_LOOP_*() return type + +crypt.3 + Michael Kerrisk + Reformat FTM info (in preparation for next patch) + Michael Kerrisk + Update crypt() FTM requirements to note glibc 2.28 changes + +ecvt.3 +gcvt.3 + Michael Kerrisk + Update FTM requirements + +error.3 + Michael Kerrisk [Alejandro Colomar, Walter Harms] + Clarify the meaning of 'status==0' for error(3) + +ferror.3 + Michael Kerrisk + Remove fileno(3) content that was migrated to new fileno(3) page + Michael Kerrisk + Add a RETURN VALUE section + Michael Kerrisk + POSIX.1-2008: these functions won't change 'errno' if 'stream' is valid + See https://www.austingroupbugs.net/view.php?id=401. + +fread.3 + Alessandro Bono + EXAMPLES: swap size and nmemb params + It works both ways, but this one feels more right. We are reading + four elements sizeof(*buffer) bytes each. + +fseeko.3 + Michael Kerrisk + Move info about obsolete FTM from SYNOPSIS to NOTES + This makes the SYNOPSIS more consistent with other pages. + +ftime.3 + Michael Kerrisk + glibc 2.33 has removed ftime() + +ftw.3 + Alejandro Colomar + SYNOPSIS: Remove duplicate header + +gethostbyname.3 + Michael Kerrisk + Move mention of from SYNOPSIS to DESCRIPTION + The functions are all declared in . is only + needed for the AF_* constants. + +gethostid.3 + Michael Kerrisk + Update FTM requirements for gethostid() + +get_phys_pages.3 + Alejandro Colomar [Jakub Wilk] + glibc gets the info from sysinfo(2) since 2.23 + +grantpt.3 +ptsname.3 +unlockpt.3 + Michael Kerrisk + Remove mention of _XOPEN_SOURCE_EXTENDED FTM + This rather ancient FTM is not mentioned in other pages for + reasons discussed in feature_test_macros(7). Remove this FTM + from the three pages where it does appear. + +malloc.3 + Alejandro Colomar [Johannes Pfister] + Document that realloc(p, 0) is specific to glibc and nonportable + +malloc_hook.3 + Alejandro Colomar + SYNOPSIS: Use 'volatile' in prototypes + +malloc_trim.3 + Dmitry Vorobev + Remove mention of free() call + 'malloc_trim' was and is never called from the 'free' function. + +pthread_create.3 + Michael Kerrisk [Paran Lee] + Fix undeclared variable error in example program + Michael Kerrisk + Fix a signedness error in the example code + +puts.3 + Michael Kerrisk + Reorder functions more logically (group related functions together) + +qecvt.3 + Michael Kerrisk + Update feature test macro requirements + +setbuf.3 + Michael Kerrisk + POSIX doesn't require errno to be unchanged after successful setbuf() + See https://www.austingroupbugs.net/view.php?id=397#c799 + +setlocale.3 + Michael Kerrisk [Alejandro Colomar, Bruno Haible] + Restructure a particularly difficult sentence + +simpleq.3 +stailq.3 +queue.7 +SIMPLEQ_*.3 + Alejandro Colomar + Document SIMPLEQ_*() as an alias to STAILQ_*() macros + +strerror.3 + Alejandro Colomar + strerrorname_np() and strerrordesc_np() first appeared on glibc 2.32 + +string.3 + Michael Kerrisk + SEE ALSO: add bstring(3) + +system.3 + Alejandro Colomar [Ciprian Dorin Craciun] + Document bug and workaround when the command name starts with a hyphen + +environ.7 + Bastien Roucariès + Reorder the text + Move the the text describing how to set environment variable before + the list(s) of variables in order to improve readability. + Bastien Roucariès + Document convention of string in environ + Document the name=value system and that nul byte is forbidden. + Bastien Roucariès + Document that HOME, LOGNAME, SHELL, USER are set at login time + and point to the su(1) manual page. + Bastien Roucariès + Add see also ld.so(8) for LD_ variables + Michael Kerrisk [Bastien Roucariès] + Improve the description of PATH + Add more details of how PATH is used, and mention the legacy + use of an empty prefix. + Bastien Roucariès [Alejandro Colomar, Bastien Roucaries, Vincent Lefevre] + Document valid values of pathnames for SHELL, PAGER and EDITOR/VISUAL + Michael Kerrisk [Bastien Roucariès] + Note the default if PAGER is not defined + Michael Kerrisk + Be a little more precise when discussing 'exec' + Say "execve(2)" instead of "exec(3)", and note that this step + starts a new program (not a new process!). + Michael Kerrisk [Bastien Roucariès] + Relocate and reword the mention of _GNU_SOURCE + +man-pages.7 + Michael Kerrisk + Document "acknowledgement" as the preferred spelling + Michael Kerrisk + Add some notes on comments in example code + Michael Kerrisk + Add a FORMATTING AND WORDING CONVENTIONS section + In man-pages-5.11, a large number of pages were edited to achieve + greater consistency in the SYNOPIS, RETURN VALUE and ATTRIBUTES + sections. To avoid future inconsistencies, try to capture some of + the preferred conventions in text in man-pages(7). + Michael Kerrisk + Note some rationale for the use of real minus signs + +netdevice.7 + Pali Rohár [Alejandro Colomar] + Update documentation for SIOCGIFADDR SIOCSIFADDR SIOCDIFADDR + +netlink.7 + Pali Rohár [Alejandro Colomar] + Fix minimal Linux version for NETLINK_CAP_ACK + NETLINK_CAP_ACK option was introduced in commit 0a6a3a23ea6e which first + appeared in Linux version 4.3 and not 4.2. + Pali Rohár [Alejandro Colomar] + Remove IPv4 from description + rtnetlink is not only used for IPv4 + Philipp Schuster + Clarify details of netlink error responses + Make it clear that netlink error responses (i.e., messages with + type NLMSG_ERROR (0x2)), can be longer than sizeof(struct + nlmsgerr). In certain circumstances, the payload can be longer. + +shm_overview.7 + Michael Kerrisk + SEE ALSO: add memfd_create(2) + +sock_diag.7 + Pali Rohár [Alejandro Colomar] + Fix recvmsg() usage in the example + +tcp.7 + Enke Chen + Documentation revision for TCP_USER_TIMEOUT + +uri.7 + Michael Kerrisk + Note that 'logical' quoting is the norm in Europe