==================== 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