path: root/Changes

==================== Changes in man-pages-4.08 ====================

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:

Arnaud Gaillard <arnaud.mgaillard@gmail.com>
Bill Pemberton <wfp5p@worldbroken.com>
Carlos O'Donell <carlos@redhat.com>
Christoph Hellwig <hch@lst.de>
David Turner <novalis@novalis.org>
Dr. Tobias Quathamer <toddy@debian.org>
Elliott Hughes <enh@google.com>
Eugene Syromyatnikov <evgsyr@gmail.com>
Heinrich Schuchardt <xypron.glpk@gmx.de>
Hu Keping <hukeping@huawei.com>
Igor Liferenko <igor.liferenko@gmail.com>
Ivan Kharpalev <ivan.kharpalev@gmail.com>
Jakub Wilk <jwilk@jwilk.net>
Jann Horn <jann@thejh.net>
Josh Triplett <josh@joshtriplett.org>
Keno Fischer <keno@juliacomputing.com>
Laurent Georget <laurent.georget@supelec.fr>
Local Lembke <logan@blackhillsinfosec.com>
Mats Wichmann <mats@wichmann.us>
Michael Kerrisk <mtk.manpages@gmail.com>
Mike Crowe <mac@mcrowe.com>
Mike Frysinger <vapier@gentoo.org>
Namhyung Kim <namhyung@gmail.com>
Nikola Forró <nforro@redhat.com>
Patrick McLean <patrickm@gaikai.com>
Peter Wu <peter@lekensteyn.nl>
Petr Cermak <petrcermak@chromium.org>
Quentin Rameau <quinq@fifth.space>
Ray Bellis <ray@isc.org>
Rich Felker <dalias@libc.org>
Ruben Kerkhof <ruben@rubenkerkhof.com>
Sam Varshavchik <mrsam@courier-mta.com>
Sebastian Andrzej Siewior <bigeasy@linutronix.de>
Siward de Groot <siward@wanadoo.nl>
Sloane Bernstein <sloane@cpanel.net>
Stefan Tauner <tauner@technikum-wien.at>
Tim Savannah <kata198@gmail.com>
Ursache Vladimir <f35f22fan@gmail.com>
Zefram <zefram@fysh.org>
王守堰 <wangshouyan@gmail.com>

Apologies if I missed anyone!


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

quotactl.2
    Eugene Syromyatnikov  [Michael Kerrisk]
        Updated information regarding disk quota flags
            Added information regarding DQF_SYS_FILE flag; updated definition
            of V1_DQF_RSQUASH, which has been defined privately and defined
            publicly as DQF_ROOT_SQUASH.
    Eugene Syromyatnikov
        Updated information regarding XFS-specific quotactl subcommands
            Added information regarding structure definitions used for
            XFS-specific subcommands, updated flag constants, added
            information regarding ignored syscall arguments, added notes on
            usage of kernel UAPI header.
    Eugene Syromyatnikov
        Additions regarding project quotas
            Added information regarding presence of project quotas.

bswap.3
    Michael Kerrisk
        New page documenting bswap_16(), bswap_32(), and bswap_64()

cgroups.7
    Michael Kerrisk
       Substantial rewrites, additions, and corrections.


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

readv.2
    Michael Kerrisk
        Document the pwritev2() RWF_SYNC  and RWF_DSYNC flags

proc.5
    Michael Kerrisk
        Document /proc/PID/seccomp
    Jann Horn
        Document /proc/[pid]/task/[tid]/children
            Document the /proc/[pid]/task/[tid]/children interface from
            CRIU, and more importantly, document why it's usually not
            a good interface.


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

bswap_16.3
bswap_32.3
bswap_64.3
        New link to new bswap.3


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

Various pages
    Michael Kerrisk
        Fix section ordering
            Various pages had sections in an order different from
            that prescribed in man-pages(7).

Various pages
    Michael Kerrisk  [Mike Frysinger]
        Consistently use /proc/[pid] (not /proc/PID)

Various pages
    Michael Kerrisk
        Fix order of SEE ALSO entries
            Entries should be ordered first by section, and then alphabetically
            within the section.

Various pages
    Michael Kerrisk
        Order ERRORS alphabetically

Various pages
    Michael Kerrisk
        Remove section number from page self reference
            Fix places where pages refer to the function that they describe
            and include a section number in that reference. Such references
            cause some HTML-rendering tools to create self-references in the
            page.

A few pages
    Michael Kerrisk
        Eliminate groff "cannot adjust line" warnings


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

pldd.1
    Michael Kerrisk  [Carlos O'Donell]
        Note gdb(1) command that can be used as a replacement for pldd
            Taken from Carlos O'Donnell's suggestion in
            https://sourceware.org/bugzilla/show_bug.cgi?id=18035#c2
    Michael Kerrisk
        BUGS: pldd has not worked since glibc 2.19

accept.2
    Michael Kerrisk
        Mention epoll(7) alongside poll()/select()
    Michael Kerrisk
        Demote discussion of DECNet to NOTES
            DECNet ceased to be important long ago...

adjtimex.2
    Nikola Forró
        Fix kernel version references

chroot.2
    Michael Kerrisk
        Note user namespace requirements for CAP_SYS_CHROOT

clone.2
    Keno Fischer  [Josh Triplett]
        Adjust syscall prototype and expand CLONE_SETTLS description
    Michael Kerrisk  [Josh Triplett, Josh Triplett]
        Document raw syscall interfaces on various other architectures
    Michael Kerrisk
        Change types for 'ptid' and 'ctid' in syscall prototypes
            These types changed from 'void *' to 'int *' back in Linux 3.8.
    Michael Kerrisk
        EINVAL is generated by glibc wrapper for NULL 'fn' or 'child_stack'
            Clarify that this error is produced by the wrapper function, not
            the underlying system call. In particular, the point is that the
            raw system call can accommodate a NULL pointer for 'child_stack'.
    Michael Kerrisk  [Elliott Hughes]
        Make the implications of CLONE_FILES more explicit
            If CLONE_FILES is not set, the duplicated FDs nevertheless share
            file offset and status flags via the open file description.
    Michael Kerrisk
        Mention kcmp() under notes

close.2
    Michael Kerrisk
        Add mention of the close-on-exec flag
    Michael Kerrisk
        Clarify discussion noting that close() does not flush buffer cache

epoll_wait.2
    Mike Crowe
        Clarify that the timeout is measured against CLOCK_MONOTONIC

execve.2
    Michael Kerrisk
        Mention use of 'environ' to access environment list
    Michael Kerrisk
        Note that real UID, real GID, and supplementary GIDs are unchanged

fanotify_init.2
    Heinrich Schuchardt
        Update BUGS information

fcntl.2
    Michael Kerrisk
        Note an important detail of F_SETOWN permission rules for signals
            F_SETOWN records the caller's credentials at the time of
            the fcntl() call, and it is these saved credentials that
            are used for subsequent permission checks.
    Michael Kerrisk
        Make the description of the effect of close-on-exec a little clearer
    Michael Kerrisk
        Clarify that F_GETFD and F_GETFL return flags via the function result

fork.2
    Michael Kerrisk
        PID of new process also does not match any existing session ID

fsync.2
    Michael Kerrisk
        SEE ALSO: add pwritev(2)
            Since Linux 4.7, pwritev() has flags related to I/O
            integrity completion.

getdomainname.2
    Michael Kerrisk
        Note user namespace requirements for CAP_SYS_ADMIN

getgroups.2
    Michael Kerrisk
        Note user namespace requirements for CAP_SETGID

gethostname.2
    Michael Kerrisk
        Note user namespace requirements for CAP_SYS_ADMIN

getrlimit.2
    Michael Kerrisk
        Note user namespace semantics for CAP_SYS_RESOURCE

getsid.2
    Michael Kerrisk
        Rework description to be somewhat clearer
    Michael Kerrisk
        Correct the definition of "session ID"

getunwind.2
    Michael Kerrisk
        Simplify text referring to vdso(7)
            The detail given here is redundant, since this info is also
            in vdso(7).

kcmp.2
    Michael Kerrisk
        Add an example program

kill.2
    Michael Kerrisk
        Note the user namespace requirement for CAP_KILL

killpg.2
    Michael Kerrisk
        Refer reader to kill(2) for signal permission rules

mlock.2
    Sebastian Andrzej Siewior
        Document that fork() after mlock() may be a bad idea in a RT process

mmap.2
    Jann Horn
        Describe treatment of 'offset' for MAP_ANONYMOUS
    Michael Kerrisk  [Siward de Groot]
        Small improvement to description of MAP_SHARED
            See https://sourceware.org/bugzilla/show_bug.cgi?id=6887

msgctl.2
msgget.2
msgop.2
semctl.2
semget.2
semop.2
shmctl.2
shmget.2
shmop.2
    Michael Kerrisk
        Note the user namespace requirements for CAP_IPC_OWNER

open.2
    Michael Kerrisk
        Clarify user namespace capability requirements for O_NOATIME
    Michael Kerrisk
        NOTES: kcmp() can be used to test if two FDs refer to the same OFD
    Michael Kerrisk
        F2FS support for O_TMPFILE was added in Linux 3.16
    Michael Kerrisk
        Clarify the rules about how the group ID of a new file is determined

prctl.2
    Michael Kerrisk
        Refer to proc(5) for effects of dumpability on ownership of /proc/PID/*
    Michael Kerrisk
        ERRORS: Add EACCES error for PR_SET_SECCOMP-SECCOMP_MODE_FILTER
    Michael Kerrisk
        Simplify list of cases where "dumpable" attribute is reset
    Michael Kerrisk
        Note user namespace requirements for PR_CAPBSET_DROP CAP_SETPCAP

readlink.2
    Michael Kerrisk  [Ursache Vladimir]
        Make example program handle links that report a size of zero
            Some "magic" symlinks created by the kernel (e.g., those under
            /proc and /sys) report 'st_size' as zero. Modify the example
            program to handle that possibility.
    Michael Kerrisk
        Emphasize that truncation of returned buffer generates no error

readv.2
    Michael Kerrisk  [Christoph Hellwig]
        Clarify that RWF_DSYNC and RWF_SYNC apply only to data being written
    Michael Kerrisk
        Add preadv2() and pwritev2() to NAME line

reboot.2
    Michael Kerrisk
        Note user namespace requirements around CAP_SYS_BOOT

rename.2
    Michael Kerrisk  [Tim Savannah]
        Clarify that ERRORS may cause rename to fail (not to be nonatomic)

sched_setaffinity.2
    Michael Kerrisk
        Note user namespace requirements for CAP_SYS_NICE

seccomp.2
    Michael Kerrisk
        CAP_SYS_ADMIN is required only in caller's user namespace

select_tut.2
    Peter Wu
        Fix various issues in example program

seteuid.2
    Michael Kerrisk
        Note user namespace requirements for CAP_SETUID and CAP_SETGID

setgid.2
    Michael Kerrisk
        Note user namespace requirements for CAP_SETGID

setpgid.2
    Michael Kerrisk
        Add a reference to credentials(7)

setpgid.2
setsid.2
    Michael Kerrisk
        Relocate some text on sessions and sessions leaders
            Some text that was in setpgid(2) is better placed in setsid(2).

setresuid.2
    Michael Kerrisk
        Note user namespace requirements for CAP_SETUID

setreuid.2
    Michael Kerrisk
        Note user namespace requirements for CAP_SETUID and CAP_SETGID

setsid.2
    Michael Kerrisk
        Refer to credentials(7) for details for details on controlling terminal
            Refer to credentials(7) for details of how a session obtains
            a controlling terminal.

set_thread_area.2
    Michael Kerrisk
        Add get_thread_area() to NAME

setuid.2
    Michael Kerrisk
        Note user namespace requirements for CAP_SETUID

sigprocmask.2
    Keno Fischer
        Expand/clarify libc/kernel sigset_t difference

stat.2
    Michael Kerrisk  [Ursache Vladimir, Mats Wichmann]
        Improve discussion of 'st_size' for /proc and /sys files
    Michael Kerrisk
        _BSD_SOURCE and _SVID_SOURCE no longer expose nanosecond timestamps

umask.2
    Michael Kerrisk
        Provide a rationale for the existence of /proc/PID/status 'Umask' field

wait.2
    Michael Kerrisk
        Remove erroneous statement that waitpid() is implemented via wait4()
            There is a fallback to wait4(), but only if the kernel does
            not provide a waitpid() system call.

bindresvport.3
rcmd.3
ip.7
    Michael Kerrisk
        Note user namespace requirements for CAP_NET_BIND_SERVICE

byteorder.3
    Michael Kerrisk
        SEE ALSO: add bswap(3)

dlopen.3
    Michael Kerrisk
        dlmopen() is still broken in glibc 2.24

endian.3
    Michael Kerrisk
        SEE ALSO: add bswap(3)

ffs.3
    Michael Kerrisk  [Stefan Tauner]
        Correct feature test macro requirements

fmemopen.3
    Michael Kerrisk  [Rich Felker]
        Remove bogus suggestion to use setbuffer()

getlogin.3
    Michael Kerrisk
        Update feature test macro requirements for cuserid()

getumask.3
    Michael Kerrisk
        Note that getumask() is still unavailable in glibc 2.24
    Michael Kerrisk
        Point to umask(2) for a thread-safe way to discover process's umask

mkstemp.3
    Quentin Rameau
        Fix _POSIX_C_SOURCE value for mkstemp()
            The correct _POSIX_C_SOURCE value has always been 200809L,
            not 200112L.

pthread_join.3
    Michael Kerrisk  [Mats Wichmann]
        Note that the caller might do clean up after joining with a thread
    Michael Kerrisk  [王守堰]
        Clarify use of 'retval' pointer

resolver.3
    Ray Bellis
        Correct arguments to res_ninit(res_state statep)

strverscmp.3
    Michael Kerrisk
        Add an example program

wcstombs.3
    Michael Kerrisk  [Igor Liferenko]
        wcsrtombs() does not provide thread-safe interface to same functionality
            See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=741360

core.5
    Mike Frysinger  [Michael Kerrisk]
       Add more details for output paths and the crash handler
            People sometimes assume that the crash handler runs in the same
            context as the crashing process.  They would be incorrect :).

proc.5
    Mike Frysinger
        Clarify the root symlink and mount namespaces
            If the target process is in a different mount namespace, the root
            symlink actually shows that view of the filesystem.
    Michael Kerrisk  [Mike Frysinger]
        Expand discussion of /proc/[pid]/root
            Add a shell example showing that /proc/[pid]/root is more
            than a symlink. Based on an example provided by Mike Frysinger
            in an earlier commit message.
    Michael Kerrisk
        Explain rules determining ownership of /proc/PID/* files
            Describe the effect of the "dumpable" attribute on ownership
            of /proc/PID files.
    Michael Kerrisk
        Note effect of 'suid_dumpable' on ownership of /proc/PID files
    Michael Kerrisk
        Refer to ptrace(2) for info on effect of suid_dumpable on ptraceability
    Michael Kerrisk
        Add reference to core(5) in discussion of 'suid_dumpable'
    Michael Kerrisk
        Note that 'suid_dumpable' mode 1 is insecure
    Michael Kerrisk
        Document /proc/meminfo '+ShmemHugePages' and 'ShmemPmdMapped' fields
    Michael Kerrisk
        Document /proc/PID/status 'RssAnon', 'RssFile', and 'RssShmem' fields
    Michael Kerrisk
        Document /proc/PID/status 'HugetlbPages' field
    Michael Kerrisk  [Zefram]
        Clarify that /proc/PID/statm 'shared' field counts *resident* pages
            See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=741360
    Michael Kerrisk
        Add reference to umask(2) in discussion of /proc/PID/status 'Umask'
    Michael Kerrisk
        Clarify user namespace requirements for /proc/sys/fs/protected_hardlinks
    Michael Kerrisk
        Note changes to config option governing /proc/[pid]/task/[tid]/children
    Michael Kerrisk
        Clarify description of /proc/PID/statm 'lib' and 'dt' fields
            These fields are always zero since Linux 2.6.
    Namhyung Kim  [Petr Cermak]
        Add description of CLEAR_REFS_MM_HIWATER_RSS
    Michael Kerrisk
        Update example VM values in /proc/PID/status

capabilities.7
    Michael Kerrisk
        Add note about nosuid to file capabilities section
    Michael Kerrisk
        SEE ALSO: add proc(5)
    Michael Kerrisk
        SEE ALSO: add setsid(2) and setpgid(2)

glob.7
    Michael Kerrisk  [Arnaud Gaillard]
        Clarify that syntactically incorrect patterns are left unchanged

packet.7
    Michael Kerrisk
        Clarify user namespace requirements for CAP_NET_RAW

pipe.7
    Michael Kerrisk  [Patrick McLean]
        Document FIONREAD

raw.7
    Michael Kerrisk
        Clarify user namespace requirements for CAP_NET_RAW
            Also remove mention of UID 0 as a method or creating
            a raw socket. As far as I can tell from reading the
            kernel source (net/ipv4/af_inet.c), this is not true.

socket.7
    Michael Kerrisk
        SIOCSPGRP: refer to fcntl(2) F_SETOWN for correct permission rules
            The permission rules described for SIOCCPGRP are wrong. Rather
            than repeat the rules here, just refer the reader to fcntl(2),
            where the rules are described for F_SETOWN.

unix.7
    Michael Kerrisk  [Laurent Georget, Ivan Kharpalev]
        Remove mention of recvmsg() from discussion of EPIPE error
            See https://bugzilla.kernel.org/show_bug.cgi?id=137351

ld.so.8
    Michael Kerrisk
        Expand description of LD_DEBUG
            Provide a list of the categories, and note that multiple
            categories can be specified.
    Michael Kerrisk
        Add glibc version for LD_USE_LOAD_BIAS
    Michael Kerrisk
        Clarify text describing whether secure-mode programs preload libraries
    Michael Kerrisk
        Remove discussion of environment variables understood by libc5
            libc5 disappeared long ago, so cease cluttering up this page
            with those ancient details. Thus, remove discussion of the
            following environment variables: LD_AOUT_LIBRARY_PATH,
            LD_AOUT_PRELOAD, LD_KEEPDIR, LD_NOWARN, and LDD_ARGV0.
    Michael Kerrisk
        Remove text with ancient libc4 and Linux libc details
    Michael Kerrisk
        Remove mention of "ELF only"
            Drawing a distinction between ELF-only features versus a,out
            ceased to be relevant long ago, so cluttering the page
            with "ELF-only" serves no purpose.