path: root/Changes

==================== Changes in man-pages-5.06 ====================

Released: ????-??-??, 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 <colomar.6.4.3@gmail.com>
Aleksa Sarai <cyphar@cyphar.com>
Alexander Miller <alex.miller@gmx.de>
Andrea Arcangeli <aarcange@redhat.com>
André Almeida <andrealmeid@collabora.com>
Andrei Vagin <avagin@gmail.com>
Andrew Micallef <andrew.micallef@live.com.au>
Bart Van Assche <bvanassche@acm.org>
Benjamin Peterson <benjamin@python.org>
Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
Christian Brauner <christian@brauner.io>
devi R.K <devi.feb27@gmail.com>
Dmitry Safonov <dima@arista.com>
Eric Biggers <ebiggers@google.com>
Eric Dumazet <eric.dumazet@gmail.com>
Eric Rannaud <e@nanocritical.com>
Eugene Syromyatnikov <evgsyr@gmail.com>
Heinrich Schuchardt <xypron.glpk@gmx.de>
Helge Deller <deller@gmx.de>
Jakub Wilk <jwilk@jwilk.net>
Jorgen Hansen <jhansen@vmware.com>
Julia Suvorova <jusual@mail.ru>
Keno Fischer <keno@juliacomputing.com>
Krzysztof Małysa <varqox@gmail.com>
Marc Lehmann <debian-reportbug@plan9.de>
Matthew Bobrowski <mbobrowski@mbobrowski.org>
Michael Galassi <michael@galassi.us>
Michael Kerrisk <mtk.manpages@gmail.com>
Michal Hocko <mhocko@kernel.org>
Mike Christie <mchristi@redhat.com>
Mike Frysinger <vapier@gentoo.org>
Pablo M. Ronchi <pmronchi@yahoo.com.ar>
Ricardo Biehl Pasquali <pasqualirb@gmail.com>
Stefan Hajnoczi <stefanha@redhat.com>
Stefano Garzarella <sgarzare@redhat.com>
Thomas Gleixner <tglx@linutronix.de>
Walter Harms <wharms@bfs.de>
Zack Weinberg <zackw@panix.com>

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 <sys/select.h>, 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