path: root/Changes

==================== Changes in man-pages-5.12 ====================

Released: ????-??-??, Christchurch


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:

Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Akihiro Motoki <amotoki@gmail.com>
Alejandro Colomar <alx.manpages@gmail.com>
Alyssa Ross <hi@alyssa.is>
Aurelien Aptel <aaptel@suse.com>
Borislav Petkov <bp@suse.de>
Bruce Merry <bmerry@ska.ac.za>
Chris Keilbart <keilbartchris@gmail.com>
Christian Brauner <christian@brauner.io>
Christoph Anton Mitterer <calestyo@scientia.net>
dann frazier <dann.frazier@canonical.com>
Dmitry V. Levin <ldv@altlinux.org>
Florian Weimer <fw@deneb.enyo.de>
Huang Ying <ying.huang@intel.com>
Jakub Wilk <jwilk@jwilk.net>
James O. D. Hunt <jamesodhunt@gmail.com>
Jann Horn <jannh@google.com>
Johannes Berg <johannes@sipsolutions.net>
Jon Murphy <jonmurphy1618@gmail.com>
Josh Triplett <josh@joshtriplett.org>
Katsuhiro Numata <byakkomon@gmail.com>
Kees Cook <keescook@chromium.org>
Mark Kettenis <kettenis@openbsd.org>
Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Michael Kerrisk <mtk.manpages@gmail.com>
Mike Rapoport <rppt@linux.vnet.ibm.com>
Peter Xu <peterx@redhat.com>
Sargun Dhillon <sargun@sargun.me>
Stefan Puiu <stefan.puiu@gmail.com>
Štěpán Němec <stepnem@gmail.com>
thomasavoss <thomasavoss@protonmail.com>
Topi Miettinen <toiwoton@gmail.com>
Tycho Andersen <tycho@tycho.pizza>
Utkarsh Singh <utkarsh190601@gmail.com>
Vishwajith K <vishuvikas1996@gmail.com>
Walter Harms <wharms@bfs.de>
Yang Xu <xuyang2018.jy@fujitsu.com>
Zhiheng Li <phoenix_lzh@sina.com>
наб <nabijaczleweli@nabijaczleweli.xyz>

Apologies if I missed anyone!


New and rewritten pages
-----------------------

seccomp_unotify.2
    Michael Kerrisk  [Tycho Andersen, Jann Horn, Kees Cook, Christian Brauner
                      Sargun Dhillon]
        New page documenting the seccomp user-space notification mechanism

MAX.3
    Alejandro Colomar
        New page to document MAX() and MIN()


Newly documented interfaces in existing pages
---------------------------------------------

seccomp.2
    Tycho Andersen  [MichaelKerrisk]
        Document SECCOMP_GET_NOTIF_SIZES
    Tycho Andersen
        Document SECCOMP_FILTER_FLAG_NEW_LISTENER   [Michael Kerrisk]
    Tycho Andersen
        Document SECCOMP_RET_USER_NOTIF  [Michael Kerrisk]

set_mempolicy.2
    Huang Ying  [Alejandro Colomar, "Huang, Ying"]
        Add mode flag MPOL_F_NUMA_BALANCING

userfaultfd.2
    Peter Xu  [Alejandro Colomar, Mike Rapoport]
        Add UFFD_FEATURE_THREAD_ID docs
    Peter Xu  [Alejandro Colomar, Mike Rapoport]
        Add write-protect mode docs
    Peter Xu  [Alejandro Colomar, Mike Rapoport]
        Add UFFD_FEATURE_THREAD_ID docs

proc.5
    Michael Kerrisk
        Document /proc/sys/vm/sysctl_hugetlb_shm_group

system_data_types.7
    Alejandro Colomar
        Add 'blksize_t'
    Alejandro Colomar
        Add 'blkcnt_t'
    Alejandro Colomar
        Add 'mode_t'
    Alejandro Colomar
        Add 'struct sockaddr'
    Alejandro Colomar
        Add 'cc_t'
    Alejandro Colomar
        Add 'socklen_t'


New and changed links
---------------------

blkcnt_t.3
    Alejandro Colomar
        New link to system_data_types(7)

blksize_t.3
    Alejandro Colomar
        New link to system_data_types(7)

cc_t.3
    Alejandro Colomar
        New link to system_data_types(7)

MIN.3
    Michael Kerrisk
        New link to MIN.3

mode_t.3
    Alejandro Colomar
        New link to system_data_types(7)

sockaddr.3
    Alejandro Colomar
        New link to system_data_types(7)

socklen_t.3
    Alejandro Colomar
        New link to system_data_types(7)


Global changes
--------------

Many pages
    Alejandro Colomar
        SYNOPSIS: Use syscall(SYS_...); for system calls without a wrapper

Many pages
    Alejandro Colomar
        SYNOPSIS: Document why each header is required

Many pages
    Alejandro Colomar
        SYNOPSIS: Remove unused includes

Many pages
    Alejandro Colomar
        Make clear why exactly is each header needed

Various pages
    Alejandro Colomar
        Add note about the use of syscall(2)

Various pages
    Alejandro Colomar
        SYNOPSIS: Miscellaneous fixes to includes

A few pages
    Alejandro Colomar
        SYNOPSIS: Add missing 'const'


Changes to individual pages
---------------------------

dup.2
    Michael Kerrisk
        Rewrite the description of dup() somewhat
            As can be seen by any number of StackOverflow questions, people
            persistently misunderstand what dup() does, and the existing manual
            page text, which talks of "copying" a file descriptor doesn't help.
            Rewrite the text a little to try to prevent some of these
            misunderstandings, in particular noting at the start that dup()
            allocates a new file descriptor.
    Michael Kerrisk
        Clarify what silent closing means
    Alejandro Colomar
        SYNOPSIS: Use consistent comments through pages

epoll_wait.2
    Alejandro Colomar
        Move misplaced subsection to NOTES from BUGS

execveat.2
    Michael Kerrisk
        Library support has been added in glibc 2.34

_exit.2
    Michael Kerrisk
        Add a little more detail on the raw _exit() system cal

exit_group.2
    Alejandro Colomar
        Use 'noreturn' in prototypes

flock.2
    Aurelien Aptel  [Alejandro Colomar]
        Add CIFS details
            CIFS flock() locks behave differently than the standard.
            Give an overview of those differences.

ioperm.2
    Alejandro Colomar
        Remove obvious comment

memfd_create.2
mmap.2
shmget.2
    Michael Kerrisk  [Yang Xu]
        Document the EPERM error for huge page allocations
            This error can occur if the caller is does not have CAP_IPC_LOCK
            and is not a member of the sysctl_hugetlb_shm_group.

mmap.2
    Bruce Merry
        Clarify that MAP_POPULATE is best-effort

mount.2
    Topi Miettinen
        Document SELinux use of MS_NOSUID mount flag

open.2
    Alejandro Colomar  [Walter Harms]
        Fix bug in linkat(2) call example
            AT_EMPTY_PATH works with empty strings (""), but not with NULL
            (or at least it's not obvious).
    Michael Kerrisk
        Make it clearer that an FD is an index into the process's FD table
            Sometimes people are confused, thinking a file descriptor is just a
            number....

perfmonctl.2
    Michael Kerrisk
        This system call was removed in Linux 5.10

pipe.2
    Alejandro Colomar
        SYNOPSIS: Fix incorrect prototype
    Michael Kerrisk
        Rearrange SYNOPSIS so that minority version pipe() is at end

ptrace.2
    Dmitry V. Levin  [Alejandro Colomar, Mathieu Desnoyers]
        Mention PTRACE_GET_SYSCALL_INFO in RETURN VALUE section

seccomp.2
    Michael Kerrisk
        Reorder list of SECCOMP_SET_MODE_FILTER flags alphabetically
            (No content changes.)
    Michael Kerrisk
        SEE ALSO: add seccomp_unotify(2)

select.2
    Michael Kerrisk
        Strengthen the warning regarding the low value of FD_SETSIZE
            All modern code should avoid select(2) in favor of poll(2)
            or epoll(7).
    Michael Kerrisk
        Relocate sentence about the fd_set value-result arguments to BUGS

syscalls.2
    Michael Kerrisk
        perfmonctl(2) was removed in Linux 5.10

bswap.3
    Alejandro Colomar
        bswap_*() are implemented using functions
            Even though it's true that they are macros,
            it's transparent to the user.

            The user will see their results casted to unsigned types
            after the conversion due to the underlying functions,
            so it's better to document these as the underlying functions,
            specifying the types.

cmsg.3
unix.7
    Michael Kerrisk
        Refer to seccomp_unotify(2) for an example of SCM_RIGHTS usage

cpow.3
    Alejandro Colomar
        Use 'complex' after the type consistently

ctime.3
    Michael Kerrisk  [Katsuhiro Numata]
        Restore documentation of 'tm_gmtoff' field

errno.3
    Alejandro Colomar  [Florian Weimer, Mark Kettenis]
        Fix ENODATA text
            ENODATA is an XSI STREAMS extension (not base POSIX).

exec.3
    Josh Triplett  [Alejandro Colomar]
        Clarify that execvpe() uses PATH from the caller, not envp
    Josh Triplett  [Alejandro Colomar]
        Fix description of 'e' variants
            The envp argument specifies the environment of the new process
            image, not "the environment of the caller".

fflush.3
    Alejandro Colomar
        SEE ALSO: Add fpurge(3)

getline.3
    наб  [Ahelenia Ziemiańska, Alejandro Colomar]
        !*lineptr is sufficient
            No implementation or spec requires *n to be 0 to allocate
            a new buffer.

getopt.3
    James O. D. Hunt  [Alejandro Colomar]
        Clarify behaviour

printf.3
    Utkarsh Singh  [Alejandro Colomar]
        Add overall structure of format string

pthread_attr_setinheritsched.3
pthread_attr_setschedparam.3
    Alejandro Colomar
        SYNOPSIS: Use 'restrict' in prototypes

pthread_mutexattr_setrobust.3
    Michael Kerrisk
        Note that the *_np() APIs are deprecated since glibc 2.34
    Alejandro Colomar
        SYNOPSIS: Remove incorrect 'const'

pthread_mutex_consistent.3
    Michael Kerrisk
        Note that pthread_mutexattr_setrobust() is now deprecated

pthread_yield.3
    Michael Kerrisk
        Note that this function is deprecated since glibc 2.34

rpc.3
    Alejandro Colomar
        SYNOPSIS: Fix prototypes (misc.)

scanf.3
    Alyssa Ross  [Alejandro Colomar]
        Clarify that %n supports type modifiers

xdr.3
    Alejandro Colomar
        SYNOPSIS: Fix prototype types
            Use the same types glibc uses, and add a missing 'const'.

capabilities.7
    Michael Kerrisk
        CAP_IPC_LOCK also governs memory allocation using huge pages

environ.7
    Josh Triplett  [Alejandro Colomar]
        Remove obsolete admonishment of the GZIP environment variable

kernel_lockdown.7
    dann frazier  [Alejandro Colomar]
        Remove description of lifting via SysRq (not upstream)
            The patch that implemented lockdown lifting via SysRq ended up
            getting dropped[*] before the feature was merged upstream. Having
            the feature documented but unsupported has caused some confusion
            for our users.

mount_namespaces.7
namespaces.7
    Michael Kerrisk
        Relocate reference to pam_namespace(8) from namespaces.7 to
        mount_namespaces.7.

signal.7
    Michael Kerrisk
        Add reference to seccomp_unotify(2)
            The seccomp user-space notification feature can cause changes in
            the semantics of SA_RESTART with respect to system calls that
            would never normally be restarted. Point the reader to the page
            that provide further details.

vsock.7
    Alyssa Ross
        ioctls are on /dev/vsock, not sockets