man-pages-4.10 is released

[Michael Kerrisk (man-pages)]

The Linux man-pages maintainer proudly announces:

    man-pages-4.10 - man pages for Linux

This release resulted from patches, bug reports, reviews, and comments
from over 40 contributors. The release sees a large number of changes:
over 600 commits changing around 160 pages. The changes include the
addition of 11 pages, significant rewrites of 3 other pages, and
enhancements to many other pages.

Tarball download:
    http://www.kernel.org/doc/man-pages/download.html
Git repository:
    https://git.kernel.org/cgit/docs/man-pages/man-pages.git/
Online changelog:
    http://man7.org/linux/man-pages/changelog.html#release_4.10

A short summary of the release is blogged at:
http://linux-man-pages.blogspot.com/2017/03/man-pages-410-is-released.html

The current version of the pages is browsable at:
http://man7.org/linux/man-pages/

A selection of changes in this release that may be of interest
to readers on LKML is shown below.

Cheers,

Michael

==================== Changes in man-pages-4.10 ====================


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

add_key.2
    Michael Kerrisk  [Eugene Syromyatnikov, David Howells]
        Major improvements and additions
            The page has doubled in length.

ioctl_iflags.2
    Michael Kerrisk
        New page describing inode flags and ioctl() operations

ioctl_ns.2
    Michael Kerrisk
        New page created by splitting ioctl(2) operations out of namespaces(7)

keyctl.2
    Michael Kerrisk, Eugene Syromyatnikov  [David Howells, Mat Martineau]
         A vast number of additions and improvements
             The page has gone from somewhat over 100 lines to well over
             1000 lines and now more or less documents the complete interface
             provided by this system call.

getentropy.3
    Michael Kerrisk
        New page documenting getentropy(3)
            getentropy(3) is added to glibc in version 2.25.

keyrings.7
    David Howells
        New page (written by David Howells) adopted from keyutils
    Michael Kerrisk  [Eugene Syromyatnikov, David Howells]
        Very many additions and improvements

persistent-keyring.7
    Michael Kerrisk
        New page (written by David Howells) adopted from keyutils
            Since this page documents kernel-user-space interfaces,
            it makes sense to have it as part of man-pages, rather
            than the keyutils package.
    Michael Kerrisk
        Various clean-ups and additions

process-keyring.7
    Michael Kerrisk
        New page (written by David Howells) adopted from keyutils
            Since this page documents kernel-user-space interfaces,
            it makes sense to have it as part of man-pages, rather
            than the keyutils package.
    Michael Kerrisk
        Various additions and improvements

request_key.2
    Michael Kerrisk, Eugene Syromyatnikov  [David Howells]
        Very many additions and improvements
             The page is now three times its former length.

session-keyring.7
    Michael Kerrisk
        New page (written by David Howells) adopted from keyutils
    Michael Kerrisk
        Various reworking and additions

signal-safety.7
    Michael Kerrisk
        New page created by migrating the signal-safety discussion from
        signal(7). Along the way some more details got added.
    Michael Kerrisk  [KASAKI Motohiro]
        Note async-signal-safety problems caused by pthread_atfork()
            See https://bugzilla.kernel.org/show_bug.cgi?id=25292
    Michael Kerrisk  [KASAKI Motohiro]
        Note glibc deviations from POSIX requirements
            See https://bugzilla.kernel.org/show_bug.cgi?id=25292

thread-keyring.7
    Michael Kerrisk
        New page (written by David Howells) adopted from keyutils
    Michael Kerrisk
        Various rewordings and additions

user-keyring.7
    Michael Kerrisk
        New page (written by David Howells) adopted from keyutils
    Michael Kerrisk
        Various reworking and improvements

user-session-keyring.7
    Michael Kerrisk
        New page (written by David Howells) adopted from keyutils
    Michael Kerrisk
        Various rewordings and additions


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

bzero.3
    Michael Kerrisk
        Document explicit_bzero() (new in glibc 2.25)
            Also, reword the description of bzero somewhat.

proc.5
    Michael Kerrisk
        Document /proc/sys/vm/user_reserve_kbytes
    Michael Kerrisk
        Document /proc/sys/vm/admin_reserve_kbytes
    Michael Kerrisk
        Document /proc/sys/fs/mount-max
    Michael Kerrisk
        Document /proc/PID/status 'NoNewPrivs' field


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

clone.2
    Michael Kerrisk
        clone() does not execute fork handlers

execve.2
    Michael Kerrisk
        File capabilities can be ignored for the same reasons as set-UID/set-GID
    Michael Kerrisk
        The 'no_new_privs' bit inhibits transformations of the effective IDs

fork.2
    Michael Kerrisk
        cgroup PIDs controller may also be trigger for EAGAIN error

getrlimit.2
    Michael Kerrisk
        Document role of RLIMIT_NOFILE for FD passing over UNIX sockets

link.2
    Michael Kerrisk
        When using linkat() AT_EMPTY_PATH, 'olddirfd' must not be a directory
    Michael Kerrisk
        ERRORS: add EPERM for immutable/append-only files
    Michael Kerrisk
        Note limits where EMLINK is encountered on ext4 and Btrfs

mbind.2
    Krzysztof Kulakowski  [Michael Kerrisk]
        Update MPOL_BIND description
            The behavior of MPOL_BIND changed in Linux 2.6.26.

nanosleep.2
    Michael Kerrisk
        Describe "creeping sleep" problem
            nanosleep() has a problem if used in a program that catches
            signals and those signals are delivered at a very high rate.
            Describe the problem, and note that clock_nanosleep(2)
            provides a solution.

posix_fadvise.2
    Michael Kerrisk
        Mention /proc/sys/vm/drop_caches
            It may be helpful for the reader of this page to know about
            /proc/sys/vm/drop_caches.
    Michael Kerrisk
        One can use open(2) + mmap(2) + mincore(2) as a 'fincore'
            Note that open(2) + mmap(2) + mincore(2) can be used to get a view
            of which pages of a file are currently cached.
    Michael Kerrisk  [Maik Zumstrull]
        Note that POSIX_FADV_DONTNEED *may* try to write back dirty pages

read.2
    Michael Kerrisk  [Steven Luo]
        Remove crufty text about EINTR and partial read
            Remove bogus text saying that POSIX permits partial read
            to return -1/EINTR on interrupt by a signal handler.
            That statement already ceased to be true in SUSv1 (1995)!

            See https://bugzilla.kernel.org/show_bug.cgi?id=193111

remap_file_pages.2
    Michael Kerrisk
        remap_file_pages() has been replaced by a slower in-kernel emulation

setxattr.2
    Michael Kerrisk
        ERRORS: add EPERM for immutable/append-only files

signalfd.2
    Michael Kerrisk
        signalfd() doesn't play well with helper programs spawned by libraries
            See https://lwn.net/Articles/415684/.
    Michael Kerrisk
        signalfd can't be used to receive synchronously generated signals
            Signals such as the SIGSEGV that results from an invalid
            memory access can be caught only with a handler.


syscall.2
    Mike Frysinger
        Add endian details with 64-bit splitting
            Architectures that split 64-bit values across register pairs
            usually do so according to their C ABI calling convention (which
            means endianness).  Add some notes to that effect, and change the
            readahead example to show a little endian example (since that is
            way more common than big endian).

            Also start a new list of syscalls that this issue does not apply
            to.
    Mike Frysinger
        Note parisc handling of aligned register pairs
            While parisc would normally have the same behavior as ARM/PowerPC,
            they decide to write shim syscall stubs to unpack/realign rather
            than expose the padding to userspace.

vfork.2
    Michael Kerrisk
        Note some caveats re the use of vfork()
            Inspired by Rich Felker's post at http://ewontfix.com/7/.
            See also https://sourceware.org/bugzilla/show_bug.cgi?id=14749 and
            See also https://sourceware.org/bugzilla/show_bug.cgi?id=14750.

write.2
    Michael Kerrisk  [Kai NODA]
        Alert the reader that there is a limit on 'count'
            See https://bugzilla.kernel.org/show_bug.cgi?id=86061

exec.3
    Michael Kerrisk
        execl() and execle() were not async-signal-safe before glibc 2.24

sem_wait.3
    Michael Kerrisk  [Fabjan Sukalia]
        Remove statement that SA_RESTART does not cause restarting
            This has not been true since Linux 2.6.22. The description
            of EINTR maintains a reference to signal(7), which explains
            the historical details.

            See https://bugzilla.kernel.org/show_bug.cgi?id=192071

core.5
    Michael Kerrisk
        Clarify that dumping program's initial CWD is root directory
    Michael Kerrisk
        The target of core dump piping can also be a script

proc.5
    Mike Frysinger  [Michael Kerrisk]
        Clarify /proc/pid/environ behavior
            /proc/pid/environ reflects process environment at
            *start* of program execution; it is set at time of execve(2)

capabilities.7
    Michael Kerrisk  [Casey Schaufler]
        Add subsection with notes to kernel developers
            Provide some notes to kernel developers considering how to choose
            which capability should govern a new kernel feature.
    Michael Kerrisk
        Further enhance the recommendation against new uses of CAP_SYS_ADMIN

inotify.7
    Michael Kerrisk
        Point out that inotify monitoring is inode based

mount_namespaces.7
    Michael Kerrisk  [Rob Landley]
        Rework the discussion of defaults for mount propagation types
            Add rather more detail. In particular, note the cases where the
            default propagation type is MS_PRIVATE vs MS_SHARED.

netlink.7
    Michael Kerrisk
        NETLINK_IP6_FW went away in Linux 3.5
    Michael Kerrisk
        NETLINK_W1 went away in Linux 2.6.18
    Michael Kerrisk
        NETLINK_FIREWALL was removed in Linux 3.5
    Michael Kerrisk
        NETLINK_NFLOG was removed in Linux 3.17

pid_namespaces.7
    Keno Fischer
        CLONE_SIGHAND|CLONE_VM|CLONE_NEWPID is no longer disallowed

pipe.7
    Michael Kerrisk
        Since Linux 4.9, pipe-max-size is ceiling for the default pipe capacity
    Michael Kerrisk
        Clarify that default pipe capacity is 16 pages
            The statement that the default pipe capacity is 65536 bytes
            is accurate only on systems where the page size is 4096B.
            See the use of PIPE_DEF_BUFFERS in the kernel source.

unix.7
    Michael Kerrisk  [Willy Tarreau]
        Document ETOOMANYREFS for SCM_RIGHTS send exceeding RLIMIT_NOFILE limit

ld.so.8
    Michael Kerrisk
        LD_BIND_NOT has effect only for function symbols
    Michael Kerrisk
        Describe use of LD_DEBUG with LD_BIND_NOT
    Michael Kerrisk
        In secure mode, LD_AUDIT restricts the libraries that it will load
    Michael Kerrisk
        LD_AUDIT understands $ORIGIN, $LIB, and $PLATFORM


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/