==================== Changes in man-pages-4.08 ==================== Released: 2016-10-08, 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 Bill Pemberton Carlos O'Donell Christoph Hellwig David Turner Dr. Tobias Quathamer Elliott Hughes Eugene Syromyatnikov Heinrich Schuchardt Hu Keping Igor Liferenko Ivan Kharpalev Jakub Wilk Jann Horn Josh Triplett Keno Fischer Laurent Georget Local Lembke Mats Wichmann Michael Kerrisk Mike Crowe Mike Frysinger Namhyung Kim Nikola Forró Patrick McLean Peter Wu Petr Cermak Quentin Rameau Ray Bellis Rich Felker Ruben Kerkhof Sam Varshavchik Sebastian Andrzej Siewior Siward de Groot Sloane Bernstein Stefan Tauner Tim Savannah Ursache Vladimir Zefram 王守堰 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.