==================== Changes in man-pages-5.06 ==================== Released: 2020-04-11, 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 Aleksa Sarai Alexander Miller Andrea Arcangeli André Almeida Andrei Vagin Andrew Micallef Bart Van Assche Benjamin Peterson Bjarni Ingi Gislason Christian Brauner devi R.K Dmitry Safonov Eric Biggers Eric Dumazet Eric Rannaud Eugene Syromyatnikov Heinrich Schuchardt Helge Deller Jakub Wilk Jorgen Hansen Julia Suvorova Keno Fischer Krzysztof Małysa Marc Lehmann Matthew Bobrowski Michael Galassi Michael Kerrisk Michal Hocko Mike Christie Mike Frysinger Pablo M. Ronchi Ricardo Biehl Pasquali Stefan Hajnoczi Stefano Garzarella Thomas Gleixner Walter Harms Zack Weinberg Apologies if I missed anyone! New and rewritten pages ----------------------- openat2.2 Aleksa Sarai [Michael Kerrisk] Document new openat2(2) syscall pidfd_getfd.2 Michael Kerrisk [Christian Brauner] New manual page documenting the pidfd_getfd() system call select.2 Michael Kerrisk Rewrite DESCRIPTION Improve structure and readability, at the same time incorporating text and details that were formerly in select_tut(2). Also move a few details in other parts of the page into DESCRIPTION. Michael Kerrisk Consolidate the discussion of pselect into a headed subsection Michael Kerrisk Consolidate historical glibc pselect() details under one subhead Michael Kerrisk Consolidate info on usleep() emulation in one place Michael Kerrisk Place the discussion of the self-pipe technique in a headed subsection Michael Kerrisk Note that FD_SET() and FD_CLR() do not return errors Michael Kerrisk Remove details of historical #include requirements The POSIX situation has been the norm for a long time now, and including ancient details overcomplicates the page. Michael Kerrisk Remove some ancient information about pre-POSIX types for 'timeout' select_tut.2 Michael Kerrisk Eliminate duplication of info across select_tut.2 and select2 There was a lot of a duplication of info in SYNOPSIS, DESCRIPTION RETURN VALUE, and SEE ALSO. Move all of the info to one place: the select(2) page. sysvipc.7 Michael Kerrisk Rewrite this page as just a summary of the System V IPC APIs All of the other details in this page have by now been moved into the relevant *ctl(2) pages. time_namespaces.7 Michael Kerrisk [Andrei Vagin, Dmitry Safonov, Thomas Gleixner] New page documenting time namespaces Newly documented interfaces in existing pages --------------------------------------------- arch_prctl.2 Keno Fischer Add ARCH_SET_CPUID subcommand clock_getres.2 Benjamin Peterson Document CLOCK_TAI Michael Kerrisk Add CLOCK_REALTIME_ALARM and CLOCK_BOOTTIME_ALARM prctl.2 Mike Christie [Michal Hocko, Michael Kerrisk, Bart Van Assche] Document PR_SETIO_FLUSHER/GET_IO_FLUSHER setns.2 Michael Kerrisk Document CLONE_NEWTIME statx.2 Eric Biggers Document STATX_ATTR_VERITY unshare.2 Michael Kerrisk Document CLONE_NEWTIME socket.7 Ricardo Biehl Pasquali, Michael Kerrisk Add description of SO_SELECT_ERR_QUEUE Alejandro Colomar [Michael Kerrisk] Document SO_TIMESTAMPNS Global changes -------------- Various pages Michael Kerrisk Remove a few mentions of the ancient "Linux libc" Various pages Michael Kerrisk Global formatting fix: disfavor nonstandard .TP indents In many cases, these don't improve readability, and (when stacked) they sometimes have the side effect of sometimes forcing text to be justified within a narrow column range. Various pages Michael Kerrisk [Christian Brauner] Fix clumsy wording around "nonnegative file descriptors" Changes to individual pages --------------------------- clock_getres.2 Helge Deller [Michael Kerrisk] Consecutive calls for CLOCK_MONOTONIC may return same value Consecutive calls to clock_gettime(CLOCK_MONOTONIC) are guaranteed to return MONOTONIC values, which means that they either return the *SAME* time value like the last call, or a later (higher) time value. Eric Rannaud Dynamic POSIX clock devices can return other errors Michael Kerrisk Improve description of CPU-time clocks Michael Kerrisk Add an example program Michael Kerrisk CLOCK_REALTIME_COARSE is not settable Michael Kerrisk Note that CPU-time clocks are not settable. Explicitly note that CLOCK_PROCESS_CPUTIME_ID and CLOCK_PROCESS_CPUTIME_ID are not settable. Michael Kerrisk Clarify that CLOCK_TAI is nonsettable Michael Kerrisk Clarify that CLOCK_MONOTONIC is system-wide Michael Kerrisk ERRORS: add EINVAL for attempt to set a nonsettable clock Michael Kerrisk Move text in BUGS to NOTES The fact that CLOCK_PROCESS_CPUTIME_ID and CLOCK_PROCESS_CPUTIME_ID are not settable isn't a bug, since POSIX does allow the possibility that these clocks are not settable. Michael Kerrisk SEE ALSO: add time_namespaces(7) clock_nanosleep.2 Michael Kerrisk clock_nanosleep() can also sleep against CLOCK_TAI Michael Kerrisk clock_nanosleep() also supports CLOCK_BOOTTIME Presumably (and from a quick glance at the source code) since Linux 2.6.39, when CLOCK_BOOTTIME was introduced. clock_nanosleep.2 timer_create.2 timerfd_create.2 Michael Kerrisk Add various missing errors Mostly verified by testing and reading the code. There is unfortunately quite a bit of inconsistency across API~s: clock_gettime clock_settime clock_nanosleep timer_create timerfd_create CLOCK_BOOTTIME y n (EINVAL) y y y CLOCK_BOOTTIME_ALARM y n (EINVAL) y [1] y [1] y [1] CLOCK_MONOTONIC y n (EINVAL) y y y CLOCK_MONOTONIC_COARSE y n (EINVAL) n (ENOTSUP) n (ENOTSUP) n (EINVAL) CLOCK_MONOTONIC_RAW y n (EINVAL) n (ENOTSUP) n (ENOTSUP) n (EINVAL) CLOCK_REALTIME y y y y y CLOCK_REALTIME_ALARM y n (EINVAL) y [1] y [1] y [1] CLOCK_REALTIME_COARSE y n (EINVAL) n (ENOTSUP) n (ENOTSUP) n (EINVAL) CLOCK_TAI y n (EINVAL) y y n (EINVAL) CLOCK_PROCESS_CPUTIME_ID y n (EINVAL) y y n (EINVAL) CLOCK_THREAD_CPUTIME_ID y n (EINVAL) n (EINVAL [2]) y n (EINVAL) pthread_getcpuclockid() y n (EINVAL) y y n (EINVAL) [1] The caller must have CAP_WAKE_ALARM, or the error EPERM results. [2] This error is generated in the glibc wrapper. connect.2 Michael Kerrisk [Eric Dumazet] Update the details on AF_UNSPEC Update the details on AF_UNSPEC and circumstances in which socket can be reconnected. dup.2 Michael Kerrisk SEE ALSO: add pidfd_getfd(2) epoll_ctl.2 Michael Kerrisk Various minor additions and clarifications epoll_wait.2 Michael Kerrisk A few minor additions and rewrites execve.2 Michael Kerrisk Add a subhead for the discussion of effect on process attributes Michael Kerrisk Explicitly note that argv[argc] == NULL in the new program Michael Kerrisk ERRORS: ENOENT does not occur for missing shared libraries See http://sourceware.org/bugzilla/show_bug.cgi?id=12241. _exit.2 Michael Kerrisk Clarify that raw _exit() system call terminates only the calling thread inotify_add_watch.2 Michael Kerrisk EXAMPLE: add reference to example in inotify(7) io_submit.2 Julia Suvorova Add IOCB_CMD_POLL opcode lseek.2 Michael Kerrisk ERRORS: ENXIO can also occur SEEK_DATA in middle of hole at end of file madvise.2 Michael Kerrisk [Andrea Arcangeli] Incorporate some (ancient) comments about MADV_HUGEPAGE Back in 2011, a mail from Andrea Arcangeli noted some details that I never got round to incorporating into the manual page. mmap.2 Michael Kerrisk Add a subhead for the 'flags' argument Michael Kerrisk Move some text hidden at the end of DESCRIPTION to NOTES msgctl.2 Michael Kerrisk Add information on permission bits (based on sysvipc(7) text) Michael Kerrisk Copy information on 'msqid_ds' fields from sysvipc(7) open.2 Michael Kerrisk Clarify that O_NOFOLLOW is relevant (only) for basename of 'pathname' Aleksa Sarai Add references to new openat2(2) page Michael Kerrisk Note EINVAL error for invalid character in basename of 'pathname' pidfd_open.2 Michael Kerrisk Mention pidfd_getfd(2) poll.2 Michael Kerrisk Add an example program Michael Kerrisk Mention epoll(7) in the introductory paragraph Michael Kerrisk Improve description of EFAULT error Michael Kerrisk Fix description of ENOMEM error select_tut.2 Michael Kerrisk Adjust header file includes in example Employ , rather than the historical header files. semctl.2 Michael Kerrisk Copy information on 'semid_ds' fields from sysvipc(7) Michael Kerrisk Add a reference to the example in shmop(2) Michael Kerrisk Add information on permission bits (based on sysvipc(7) text) semget.2 Michael Kerrisk EXAMPLE: add an example program semop.2 Michael Kerrisk Add a reference to the semop(2) example in shmop(2) shmctl.2 Michael Kerrisk Add information on permission bits (based on sysvipc(7) text) Michael Kerrisk Note that execute permission is not needed for shmat() SHM_EXEC Michael Kerrisk Copy information on 'shmid_ds' fields from sysvipc(7) Michael Kerrisk Some small improvements to the description of the 'shmid_ds' structure shmget.2 Michael Kerrisk Add a reference to the example in shmop(2) shmop.2 Michael Kerrisk EXAMPLE: add a pair of example programs Add example programs demonstrating usage of shmget(2), shmat(2), semget(2), semctl(2), and semop(2). sigaction.2 signal.7 Zack Weinberg Document kernel bugs in delivery of signals from CPU exceptions stat.2 Michael Kerrisk Clarify definitions of timestamp fields In particular, make it clear that atime and mtime relate to the file *data*. syscalls.2 Michael Kerrisk Add new Linux 5.6 system calls Michael Kerrisk Note that the 5.x series followed 4.20 timer_create.2 Michael Kerrisk timer_create(2) also supports CLOCK_TAI Michael Kerrisk Mention clock_getres(2) for further details on the various clocks timerfd_create.2 Michael Kerrisk [Thomas Gleixner] Note a case where timerfd_settime() can fail with ECANCELED Michael Kerrisk [devi R.K, Thomas Gleixner] Negative changes to CLOCK_REALTIME may cause read() to return 0 Michael Kerrisk Rework text for EINVAL for invalid clock ID Michael Kerrisk Refer reader to clock_getres(2) for further details on the clocks unshare.2 Michael Kerrisk Add CLONE_NEWCGROUP and CLONE_NEWTIME to example program exit.3 Michael Kerrisk [Walter Harms] Small improvement to the discussion of 'status' argument ftok.3 Michael Kerrisk EXAMPLE: add a reference to the example in semget(2) getifaddrs.3 Michael Kerrisk [Michael Galassi] EXAMPLE: remove unneeded loop variable nl_langinfo.3 Eugene Syromyatnikov Document era-related locale elements Eugene Syromyatnikov Add information about AM/PM time format locale elements Eugene Syromyatnikov Mention the respective strftime(3) conversion specifications sem_init.3 Michael Kerrisk Add references to example code in shm_open(3) and sem_wait(3) sem_post.3 Michael Kerrisk Add a reference to code example code in shm_open(3) shm_open.3 Michael Kerrisk EXAMPLE: add some example programs strcmp.3 Michael Kerrisk Add an example program Michael Kerrisk [Andrew Micallef, Walter Harms] Rework text describing return value to be clearer Michael Kerrisk Note that the comparison is done using unsigned char Michael Kerrisk SEE ALSO: add ascii(7) strftime.3 Eugene Syromyatnikov [Michael Kerrisk] Refer to the relevant nl_langinfo(3) items Eugene Syromyatnikov Expand %E and %O description Eugene Syromyatnikov Consistently document fall-back format string proc.5 Mike Frysinger Clarify /proc/[pid]/cmdline mutability cgroups.7 Michael Kerrisk Update list of cgroups v2 controllers Update the list of cgroups v2 controllers (several controllers were missing). Michael Kerrisk Add a subsection on cgroup v2 mount options and include 'nsdelegate' Michael Kerrisk Document the cgroups v2 'memory_localevents' mount option Michael Kerrisk SEE ALSO: add Documentation/admin-guide/cgroup-v2.rst namespaces.7 Michael Kerrisk Add time namespaces information Michael Kerrisk Eliminate some superfluous info from display of /proc/PID/ns links path_resolution.7 Aleksa Sarai Update to mention openat2(2) features socket.7 Michael Kerrisk Note SCM message types for SO_TIMESTAMP and SO_TIMESTAMPNS tcp.7 Michael Kerrisk SEE ALSO: mention Documentation/networking/ip-sysctl.txt time.7 Michael Kerrisk Add small subsection on clocks and time namespaces unix.7 Heinrich Schuchardt Correct example vsock.7 Stefano Garzarella [Jorgen Hansen, Stefan Hajnoczi] Add VMADDR_CID_LOCAL description