diff --git a/Changes b/Changes index d364c0128..64c72298a 100644 --- a/Changes +++ b/Changes @@ -10,6 +10,48 @@ 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! @@ -17,19 +59,792 @@ 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