diff --git a/Changes b/Changes index 00ae284f2..b23eaf747 100644 --- a/Changes +++ b/Changes @@ -10,6 +10,47 @@ 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 +Alexey Budankov +Amir Goldstein +Carlos O'Donell +Dave Martin +David Howells +David Laight +Dmitry V. Levin +Érico Rolim +Florian Weimer +G. Branden Robinson +Hauke Fath +Heinrich Schuchardt +henrik@optoscale.no +Ira Weiny +Jakub Wilk +Jan Kara +Jann Horn +Jing Peng +Jonathan Wakely +Jonny Grant +Konstantin Bukin +Mark Mossberg +Marko Hrastovec +Matthew Bobrowski +Michael Kerrisk +Mike Frysinger +Paul Eggert +Paul Moore +Rich Felker +Samanta Navarro +Serge Hallyn +Simon McVittie +Sridhar Samudrala +Stephen Smalley +Steve Hilder +Thomas Piekarski +Tony May +Tycho Andersen +Yang Xu Apologies if I missed anyone! @@ -17,19 +58,721 @@ Apologies if I missed anyone! New and rewritten pages ----------------------- +circleq.3 + Alejandro Colomar + New page with 'circleq' content extracted from queue(3) + +list.3 + Alejandro Colomar + New page with 'list' content extracted from queue(3) + + +pthread_attr_setsigmask_np.3 + Michael Kerrisk + New page for pthread_attr_setsigmask_np() + pthread_attr_getsigmask_np() + Add a page documenting the pthread_attr_setsigmask_np(3) and + pthread_attr_getsigmask_np(3) functions added in glibc 2.32. + +slist.3 + Alejandro Colomar + New page with 'slist' content extracted from queue(3) + +stailq.3 + Alejandro Colomar + New page with 'stailq' content extracted from queue(3) + +tailq.3 + Alejandro Colomar + New page with 'tailq' content extracted from queue(3) + +system_data_types.7 + Alejandro Colomar, Michael + A new page documenting a wide range of system data types. + +kernel_lockdown.7 + David Howells, Heinrich Schuchardt [Michael Kerrisk] + New page documenting the Kernel Lockdown feature + +queue.7 + Alejandro Colomar + Create summary page for 'queue' APIs + The former queue(3) page was rather unwieldy, as it attempted to + describe too many APIs. After splitting that content out into a + number of smaller pages ( circleq.3, list.3, slist.3, stailq.3, + and tailq.3) move the much-reduced queue(3) page, which is now + essentially a summary of those APIs, from Section 3 to Section 7. + Newly documented interfaces in existing pages --------------------------------------------- +fanotify_init.2 +fanotify.7 + Amir Goldstein [Jan Kara, Matthew Bobrowski] + Document FAN_REPORT_DIR_FID + +fanotify_init.2 +fanotify.7 + Amir Goldstein [Jan Kara, Matthew Bobrowski] + Document FAN_REPORT_NAME + +statx.2 + Ira Weiny + Add STATX_ATTR_DAX + +strerror.3 + Michael Kerrisk + Document strerrorname_np() and strerrordesc_np() + strerrorname_np() and strerrordesc_np() were added in glibc 2.32. + +strsignal.3 + Michael Kerrisk + Document sigabbrev_np() and sigdescr_np(). + sigabbrev_np() and sigdescr_np() were added in glibc 2.32. + +loop.4 + Yang Xu + Document LOOP_CONFIGURE ioctl + Yang Xu + Document LO_FLAGS_DIRECT_IO flag + +capabilities.7 + Michael Kerrisk + Document the CAP_CHECKPOINT_RESTORE capability added in Linux 5.9 + +ip.7 + Stephen Smalley [Paul Moore] + Document IP_PASSSEC for UDP sockets + +ip.7 +socket.7 + Stephen Smalley + Document SO_PEERSEC for AF_INET sockets + Sridhar Samudrala + Document SO_INCOMING_NAPI_ID + +socket.7 +unix.7 + Stephen Smalley [Serge Hallyn, Simon McVittie] + Add initial description for SO_PEERSEC + New and changed links --------------------- +aiocb.3 +clock_t.3 +clockid_t.3 +dev_t.3 +div_t.3 +double_t.3 +fenv_t.3 +fexcept_t.3 +FILE.3 +float_t.3 +gid_t.3 +id_t.3 +imaxdiv_t.3 +int8_t.3 +int16_t.3 +int32_t.3 +int64_t.3 +intN_t.3 +intmax_t.3 +intptr_t.3 +lconv.3 +ldiv_t.3 +lldiv_t.3 +off_t.3 +pid_t.3 +ptrdiff_t.3 +regex_t.3 +regmatch_t.3 +regoff_t.3 +siginfo_t.3 +sigset_t.3 +sigval.3 +size_t.3 +ssize_t.3 +suseconds_t.3 +time_t.3 +timer_t.3 +timespec.3 +timeval.3 +uid_t.3 +uint8_t.3 +uint16_t.3 +uint32_t.3 +uint64_t.3 +uintN_t.3 +uintptr_t.3 +va_list.3 +void.3 + Alejandro Colomar, Michael kerrisk + New links to system_data_types(7) + +CIRCLEQ_ENTRY.3 +CIRCLEQ_HEAD.3 +CIRCLEQ_INIT.3 +CIRCLEQ_INSERT_AFTER.3 +CIRCLEQ_INSERT_BEFORE.3 +CIRCLEQ_INSERT_HEAD.3 +CIRCLEQ_INSERT_TAIL.3 +CIRCLEQ_REMOVE.3 + Alejandro Colomar + Link to the new circleq(3) page instead of queue(3) + +LIST_EMPTY.3 +LIST_ENTRY.3 +LIST_FIRST.3 +LIST_FOREACH.3 +LIST_HEAD.3 +LIST_HEAD_INITIALIZER.3 +LIST_INIT.3 +LIST_INSERT_AFTER.3 +LIST_INSERT_BEFORE.3 +LIST_INSERT_HEAD.3 +LIST_NEXT.3 +LIST_REMOVE.3 + Alejandro Colomar + Link to the new list.3 page instead of queue.3 + +SLIST_EMPTY.3 +SLIST_ENTRY.3 +SLIST_FIRST.3 +SLIST_FOREACH.3 +SLIST_HEAD.3 +SLIST_HEAD_INITIALIZER.3 +SLIST_INIT.3 +SLIST_INSERT_AFTER.3 +SLIST_INSERT_HEAD.3 +SLIST_NEXT.3 +SLIST_REMOVE.3 +SLIST_REMOVE_HEAD.3 + Alejandro Colomar + Link to the new slist(3) page instead of queue(3) + +STAILQ_CONCAT.3 +STAILQ_EMPTY.3 +STAILQ_ENTRY.3 +STAILQ_FIRST.3 +STAILQ_FOREACH.3 +STAILQ_HEAD.3 +STAILQ_HEAD_INITIALIZER.3 +STAILQ_INIT.3 +STAILQ_INSERT_AFTER.3 +STAILQ_INSERT_HEAD.3 +STAILQ_INSERT_TAIL.3 +STAILQ_NEXT.3 +STAILQ_REMOVE.3 +STAILQ_REMOVE_HEAD.3 + Alejandro Colomar + Link to the new stailq(3) page instead of queue(3) + +TAILQ_CONCAT.3 +TAILQ_EMPTY.3 +TAILQ_ENTRY.3 +TAILQ_FIRST.3 +TAILQ_FOREACH.3 +TAILQ_FOREACH_REVERSE.3 +TAILQ_HEAD.3 +TAILQ_HEAD_INITIALIZER.3 +TAILQ_INIT.3 +TAILQ_INSERT_AFTER.3 +TAILQ_INSERT_BEFORE.3 +TAILQ_INSERT_HEAD.3 +TAILQ_INSERT_TAIL.3 +TAILQ_LAST.3 +TAILQ_NEXT.3 +TAILQ_PREV.3 +TAILQ_REMOVE.3 +TAILQ_SWAP.3 + Alejandro Colomar + Link to the new tailq(3) page instead of queue(3) + +getcwd.2 +mq_notify.2 +mq_open.2 +mq_timedreceive.2 +mq_timedsend.2 +mq_unlink.2 + Michael Kerrisk + Reinstate links to section 3 pages that document system calls + Some of the links removed in commit 247c654385128fd0748 should + have been kept, because in some cases there are real system + calls whose wrapper functions are documented in Section 3. + +queue.3 + Alejandro Colomar + Link to queue(7) + +sigabbrev_np.3 + Michael Kerrisk + New link to strsignal.3 + +sigdescr_np.3 + Michael Kerrisk + New link to strsignal.3 + +strerrordesc_np.3 + Michael Kerrisk + New link to strerror(3) + +strerrorname_np.3 + Michael Kerrisk + New link to strerror(3) + +sys_siglist.3 + Michael Kerrisk + New link to strsignal(3) + Global changes -------------- +Various pages + Alejandro Colomar + Use ``sizeof`` consistently through all the examples in the + following way: + + - Use the name of the variable instead of its type as argument for + ``sizeof``. + +Various pages + Alejandro Colomar + Use sizeof() to get buffer size (instead of hardcoding macro name) + +Various pages + Michael Kerrisk + Use \(aq instead of ' inside monospace fonts + Use \(aq to get an unslanted single quote inside monospace code + blocks. Using a simple ' results in a slanted quote inside PDFs. + +Various pages + Michael Kerrisk, Alejandro Colomar + Use C99 style to declare loop counter variables + Rather than: + + sometype x; + + for (x = ....; ...) + + use + + for (sometype x = ...; ...) + + This brings the declaration and use closer together (thus aiding + readability) and also clearly indicates the scope of the loop + counter variable. + +Various pages + Alejandro Colomar + Switch printf() casts to use [u]intmax_t + %ju / %jd + Let's move to the 21st century. Instead of casting system data + types to long/long long/etc. in printf() calls, instead cast to + intmax_t or uintmax_t, the largest available signed/unsigned + integer types. + +Various pages + Alejandro Colomar + Omit 'int' keyword for 'short', 'long' and 'long long' types + +Various pages + Alejandro Colomar + Remove unneeded casts + +Various pages + Alejandro Colomar + In printf(): s/0x%/%#/ except when followed by X instead of x + Use printf()'s '#' flag character to prepend the string "0x". + + However, when the number is printed in uppercase, and the prefix + is in lowercase, the string "0x" needs to be manually written. + +Various pages + Michael Kerrisk + Use C99-style declarations for readability + Rather than writing things such as: + + struct sometype *x; + ... + x = malloc(sizeof(*x)); + + let's use C99 style so that the type info is in the same line as + the allocation: + + struct sometype *x = malloc(sizeof(*x)); + +Various pages + Alejandro Colomar + Cast to 'unsigned long' rather than 'long' when printing with "%lx" + +stdarg.3 + Alejandro Colomar + Declare variables with different types in different lines + In particular, don's mix a variable and a pointer declaration + on the same line: TYPE x, *p; + Changes to individual pages --------------------------- +memusage.1 + Michael Kerrisk + EXAMPLES: remove doubled calculations + The same calculations are repeated in malloc() and printf() calls. + For better readability, do the calculations once. + Michael Kerrisk + Use %zu rather than %zd when printing 'size_t' values + +clock_getres.2 + Alejandro Colomar + EXAMPLES: use 'const' when appropriate + Alejandro Colomar [Jakub Wilk] + Cast 'time_t' to 'int' for printf() and fix the length modifiers + Michael Kerrisk [Tony May] + Fix type and variable name in dynamic clock code example + +clone.2 + Michael Kerrisk + CAP_CHECKPOINT_RESTORE can now be used to employ 'set_tid' + +epoll_ctl.2 + Michael Kerrisk + epoll instances can be nested to a maximum depth of 5 + This limit appears to be an off-by-one count against + EP_MAX_NESTS (4). + Michael Kerrisk + Move some version info from CONFORMING TO to VERSIONS + +eventfd.2 + Alejandro Colomar + Use 'PRIxN' macros when printing C99 fixed-width integer types + +futex.2 + Alejandro Colomar + Use appropriate types + +getdents.2 + Alejandro Colomar + SYNOPSIS: add missing header and feature test macro + +intro.2 +intro.3 +credentials.7 +feature_test_macros.7 +standards.7 + Michael Kerrisk + SEE ALSO: add system_data_types(7) + +ioctl_ns.2 +stat.2 + Alejandro Colomar [Konstantin Bukin] + Fix signedness of printf specifiers + +membarrier.2 + Alejandro Colomar + Note that glibc does not provide a wrapper + +mprotect.2 + Alejandro Colomar + Use "%p" rather than casting to 'long' when printing pointer values + +mq_getsetattr.2 + Alejandro Colomar + Use 'const' when appropriate + +msgop.2 + Yang Xu + Add restriction on ENOSYS error + +open.2 + Michael Kerrisk [henrik@optoscale.no] + ERRORS: add EBUSY + +openat.2 + Alejandro Colomar + SYNOPSIS: return long + The Linux kernel uses long as the return type for this syscall. + As glibc provides no wrapper, use the same type the kernel uses. + +open_by_handle_at.2 + Alejandro Colomar + Use "%u" rather than "%d" when printing 'unsigned int' values + +perf_event_open.2 + Alexey Budankov + Update the man page with CAP_PERFMON related information + +recv.2 +send.2 + Michael Kerrisk + Add cross references to pages with further info about ancillary data + +sched_getattr.2 + Aleksa Sarai + Update to include changed size semantics + +seccomp.2 + Michael Kerrisk [Jann Horn] + Warn reader that SECCOMP_RET_TRACE can be overridden + Highlight to the reader that if another filter returns a + higher-precedence action value, then the ptracer will not + be notified. + Michael Kerrisk [Rich Felker] + Warn against the use of SECCOMP_RET_KILL_THREAD + Killing a thread with SECCOMP_RET_KILL_THREAD is very likely + to leave the rest of the process in a broken state. + Michael Kerrisk [Rich Felker] + EXAMPLES: use SECCOMP_RET_KILL_PROCESS rather than SECCOMP_RET_KILL + Alejandro Colomar + Use ARRAY_SIZE() macro instead of raw sizeof division + +setns.2 + Michael Kerrisk + Correct the version for time namespace support + +sigaction.2 + Michael Kerrisk [Alejandro Colomar] + Use correct POSIX type for siginfo_t.si_value + +syscalls.2 + Michael Kerrisk + Move system calls from discontinued ports out of main syscall list + Various ports that had their own indigenous system calls have + been discontinued. Remove those system calls (none of which had + manual pages!) to a separate part of the page, to avoid + cluttering the main list of system calls. + Michael Kerrisk + Add close_range (Linux 5.9) + +timerfd_create.2 + Alejandro Colomar + Use 'PRIxN' macros when printing C99 fixed-width integer types + +userfaultfd.2 + Michael Kerrisk + Use a better type (uint64_t) for 'len' in EXAMPLES + Alejandro Colomar + Use 'PRIx64' rather than "%llx" when printing 64-bit fixed-width types + +argz_add.3 +envz_add.3 + Michael Kerrisk [Jonny Grant] + Point out that 'error_t' is an integer type + +bsearch.3 + Alejandro Colomar + Fix intermediate type and remove unneeded casts + +bswap.3 + Jakub Wilk + Use strtoull() for parsing 64-bit numbers + +dlopen.3 + Michael Kerrisk + Clarify DT_RUNPATH/DT_RPATH details + It is the DT_RUNPATH/DT_RPATH of the calling object (not the + executable) that is relevant for the library search. Verified + by experiment. + +errno.3 + Michael Kerrisk [Alejandro Colomar] + Note that the pthreads APIs do not set errno + +fopencookie.3 + Alejandro Colomar + printf()'s .* expects an int; cast accordingly + Alejandro Colomar + Fix bugs in example + +fread.3 + Alejandro Colomar + Move ARRAY_SIZE logic into macro + +freeaddrinfo.3 + Marko Hrastovec + Fix memory leaks in freeaddrinfo() examples + +getline.3 + Alejandro Colomar + Use %zd rather than %zu when printing 'ssize_t' values + +lseek64.3 + Michael Kerrisk + Since glibc 2.28. the 'llseek' symbol is no longer available + +mallinfo.3 + Michael Kerrisk + The 'usmblks' field is nowadays always 0 + +offsetof.3 + Alejandro Colomar + Use "%zu" rather than "%zd" when printing 'size_t' values + +perror.3 + Michael Kerrisk + sys_errlist and sys_nerr are no longer exposed by + The change came with the release of glibc 2.32. + +posix_fallocate.3 + Érico Rolim + Add EOPNOTSUPP error code. + +psignal.3 +strsignal.3 + Michael Kerrisk + Consolidate information on 'sys_siglist' in one page (strsignal(3)) + +pthread_attr_init.3 + Michael Kerrisk + SEE ALSO: add pthread_attr_init(3) + +pthread_attr_init.3 +pthread_create.3 +pthread_getattr_np.3 + Michael Kerrisk + Use correct type (size_t) for some variables + +pthread_getattr_np.3 + Alejandro Colomar + Use "%zu" and "%zx" when printing 'size_t' values + +pthread_sigmask.3 + Michael Kerrisk + SEE ALSO: add pthread_attr_setsigmask_np(3) + +qsort.3 + Alejandro Colomar + Fix casts + Alejandro Colomar + SYNOPSIS: move code from queue.3 to stailq.3 + +regex.3 + Alejandro Colomar + Add example program + Alejandro Colomar + Remove unnecessary include + +strsignal.3 + Michael Kerrisk [Hauke Fath] + Note that starting with v2.32, glibc no longer exports 'sys_siglist' + Michael Kerrisk + Further addition on version range for sys_siglist + Michael Kerrisk + Note that 'sys_siglist' is nonstandard + +strtod.3 + Jonathan Wakely + Fix return value for underflow + +strtol.3 + Alejandro Colomar + EXAMPLES: simplify errno checking + Alejandro Colomar + EXAMPLES: as the default base, use special value 0 + Alejandro Colomar + EXAMPLES: delimit output string using "" + +tsearch.3 + Alejandro Colomar + Simplify type usage and remove unneeded casts + Alejandro Colomar + Use size_t for malloc() argument + +loop.4 + Yang Xu + Add some details about lo_flags + +core.5 + Alejandro Colomar + Use adequate type + +locale.5 + Florian Weimer + Decimal points, thousands separators must be one character + +proc.5 + Michael Kerrisk + Update capability requirements for accessing /proc/[pid]/map_files + Jann Horn [Mark Mossberg] + Document inaccurate RSS due to SPLIT_RSS_COUNTING + Michael Kerrisk + Note "open file description" as (better) synonym for "file handle" + +resolv.5 + Florian Weimer + Document the trust-ad option + +aio.7 + Alejandro Colomar + Use perror() directly + +bpf-helpers.7 + Michael Kerrisk [Jakub Wilk] + Resync with current kernel source + +capabilities.7 + Michael Kerrisk + Under CAP_SYS_ADMIN, group "sub-capabilities" together + CAP_BPF, CAP_PERFMON, and CAP_CHECKPOINT_RESTORE have all been + added to split out the power of CAP_SYS_ADMIN into weaker pieces. + Group all of these capabilities together in the list under + CAP_SYS_ADMIN, to make it clear that there is a pattern to these + capabilities. + Michael Kerrisk + CAP_SYS_ADMIN implies CAP_CHECKPOINT_RESTORE + But the latter, weaker capability is preferred. + Michael Kerrisk + Add kernel doc reference for CAP_PERFMON + +fanotify.7 + Alejandro Colomar + Pass array to read(2) directly instead of a pointer to it + +fanotify.7 +fanotify_mark.2 + Amir Goldstein [Jan Kara, Matthew Bobrowski] + Generalize documentation of FAN_REPORT_FID + +feature_test_macros.7 + Jakub Wilk + Update list of macros that inhibit default definitions + +man.7 + Michael Kerrisk [G. Branden Robinson] + Clarify that alternating typeface macros print arguments without spaces + +man-pages.7 + Michael Kerrisk + Add some more requests re code examples + Michael Kerrisk + Soften the statement that ideal programs should be short + +namespaces.7 + Michael Kerrisk + A 'time_for_children' symlink can also pin a namespace + +pid_namespaces.7 + Michael Kerrisk + Update capability requirements for /proc/sys/kernel/ns_last_pid + +pthreads.7 + Michael Kerrisk + Explicitly note that pthreads APIs return an errno-style value on error + +rtld-audit.7 + Florian Weimer [Carlos O'Donell] + Clarify la_version handshake + Returning its argument without further checks is almost always + wrong for la_version. + Alejandro Colomar + Use "%u" rather than "%d" when printing 'unsigned int' values + +sigevent.7 + Michael Kerrisk + Note that 'sigev_notify_thread_id' is Linux-specific + +socket.7 + Michael Kerrisk + SEE ALSO: add ipv6(7)