==================== Changes in man-pages-3.82 ==================== Released: ????-??-??, Paris Eric W. Biederman Heinrich Schuchardt Jakub Wilk Jann Horn Jason Vas Dias Josh Triplett J William Piggott Kees Cook Konstantin Shemyak Ma Shimiao Matt Turner Michael Kerrisk Michael Witten Mikael Pettersson Namhyung Kim Nicolas FRANCOIS Paul E Condon Peter Adkins Scot Doyle Shawn Landden Stéphane Aulery Stephen Smalley Taisuke Yamada Torvald Riegel Vincent Lefevre Yuri Kozlov 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: Alban Crequy Andy Lutomirski Bert Wesarg Bill Pemberton Chris Delozier David Madore Dmitry Deshevoy Eric W. Biederman Heinrich Schuchardt Jakub Wilk Jann Horn Jason Vas Dias Josh Triplett J William Piggott Kees Cook Konstantin Shemyak Ma Shimiao Matt Turner Michael Kerrisk Michael Witten Mikael Pettersson Namhyung Kim Nicolas FRANCOIS Paul E Condon Peter Adkins Scot Doyle Shawn Landden Stéphane Aulery Stephen Smalley Taisuke Yamada Torvald Riegel Vincent Lefevre Yuri Kozlov Apologies if I missed anyone! New and rewritten pages ----------------------- nptl.7 Michael Kerrisk New page with details of the NPTL POSIX threads implementation Newly documented interfaces in existing pages --------------------------------------------- user_namespaces.7 Eric W. Biederman [Michael Kerrisk] Document /proc/[pid]/setgroups Changes to individual pages --------------------------- intro.1 Stéphane Aulery Prompt is not % but $ Stéphane Aulery Various improvements - Add reference to other common shells dash(1), ksh(1) - Add a reference to stdout(3) - Separate cp and mv descriptions - Add examples of special cases of cd - Add su(1) and shutdown(8) references for section Logout and poweroff - Move Control-D to section Logout and poweroff - Fix some little formatting errors Stéphane Aulery Add cross references cited Stéphane Aulery Order SEE ALSO section clone.2 Josh Triplett Document that clone() silently ignores CLONE_PID and CLONE_STOPPED Normally, system calls return EINVAL for flags they don't support. Explicitly document that clone does *not* produce an error for these two obsolete flags. Michael Kerrisk Small rewording of explanation of clone() wrt threads Clone has so many effects that it's an oversimplification to say that the *main* use of clone is to create a thread. (In fact, the use of clone() to create new processes may well be more common, since glibc's fork() is a wrapper that calls clone().) getgroups.2 Michael Kerrisk [Shawn Landden] Add discussion of NPTL credential-changing mechanism At the kernel level, credentials (UIDs and GIDs) are a per-thread attribute. NPTL uses a signal-based mechanism to ensure that when one thread changes its credentials, all other threads change credentials to the same values. By this means, the NPTL implementation conforms to the POSIX requirement that the threads in a process share credentials. Michael Kerrisk ERRORS: add EPERM for the case where /proc/PID/setgroups is "deny" Michael Kerrisk Note capability associated with EPERM error for setgroups(2) Michael Kerrisk Refer reader to user_namespaces(7) for discussion of /proc/PID/setgroups The discussion of /proc/PID/setgroups has moved from proc(5) to user_namespaces(7). getpid.2 Michael Kerrisk Note that getppid() returns 0 if parent is in different PID namespace getsockopt.2 Konstantin Shemyak Note RETURN VALUE details when netfilter is involved ioctl_list.2 Heinrich Schuchardt SEE ALSO ioctl_fat.2 Add FAT_IOCTL_GET_VOLUME_ID SEE ALSO ioctl_fat.2 Heinrich Schuchardt include/linux/ext2_fs.h Include linux/ext2_fs.h does not contain any ioctl definitions anymore. Request codes EXT2_IOC* have been replaced by FS_IOC* in linux/fs.h. Some definitions of FS_IOC_* use long* but the actual code expects int* (see fs/ext2/ioctl.c). msgop.2 Bill Pemberton Remove EAGAIN as msgrcv() errno The list of errnos for msgrcv() lists both EAGAIN and ENOMSG as the errno for no message available with the IPC_NOWAIT flag. ENOMSG is the errno that will be set. Bill Pemberton Add an example program open.2 Michael Kerrisk [Jason Vas Dias] Mention blocking semantics for FIFO opens See https://bugzilla.kernel.org/show_bug.cgi?id=95191 seccomp.2 Jann Horn [Kees Cook, Mikael Pettersson, Andy Lutomirski] Add note about alarm(2) not being sufficient to limit runtime Jann Horn Explain blacklisting problems, expand example Michael Kerrisk [Kees Cook] Add mention of libseccomp setgid.2 Michael Kerrisk Clarify that setgid() changes all GIDs when caller has CAP_SETGID Michael Kerrisk [Shawn Landden] Add discussion of NPTL credential-changing mechanism At the kernel level, credentials (UIDs and GIDs) are a per-thread attribute. NPTL uses a signal-based mechanism to ensure that when one thread changes its credentials, all other threads change credentials to the same values. By this means, the NPTL implementation conforms to the POSIX requirement that the threads in a process share credentials. setresuid.2 Michael Kerrisk [Shawn Landden] Add discussion of NPTL credential-changing mechanism At the kernel level, credentials (UIDs and GIDs) are a per-thread attribute. NPTL uses a signal-based mechanism to ensure that when one thread changes its credentials, all other threads change credentials to the same values. By this means, the NPTL implementation conforms to the POSIX requirement that the threads in a process share credentials. setreuid.2 Michael Kerrisk [Shawn Landden] Add discussion of NPTL credential-changing mechanism At the kernel level, credentials (UIDs and GIDs) are a per-thread attribute. NPTL uses a signal-based mechanism to ensure that when one thread changes its credentials, all other threads change credentials to the same values. By this means, the NPTL implementation conforms to the POSIX requirement that the threads in a process share credentials. Michael Kerrisk SEE ALSO: add credentials(7) setuid.2 Michael Kerrisk Clarify that setuid() changes all UIDs when caller has CAP_SETUID Michael Kerrisk [Shawn Landden] Add discussion of NPTL credential-changing mechanism At the kernel level, credentials (UIDs and GIDs) are a per-thread attribute. NPTL uses a signal-based mechanism to ensure that when one thread changes its credentials, all other threads change credentials to the same values. By this means, the NPTL implementation conforms to the POSIX requirement that the threads in a process share credentials. sigaction.2 Michael Kerrisk Add discussion of rt_sigaction(2) Michael Kerrisk Note treatment of signals used internally by NPTL The glibc wrapper gives an EINVAL error on attempts to change the disposition of either of the two real-time signals used by NPTL. sigpending.2 Michael Kerrisk Add discussion of rt_sigpending(2) sigprocmask.2 Michael Kerrisk Add discussion of rt_sigprocmask(2) Michael Kerrisk Note treatment of signals used internally by NPTL The glibc wrapper silently ignores attempts to block the two real-time signals used by NPTL. sigreturn.2 Michael Kerrisk Add discussion of rt_sigreturn(2) sigsuspend.2 Michael Kerrisk Add discussion of rt_sigsuspend(2) sigwaitinfo.2 Michael Kerrisk Note treatment of signals used internally by NPTL The glibc wrappers silently ignore attempts to wait for signals used by NPTL. Michael Kerrisk Add discussion of rt_sigtimedwait(2) socket.2 Heinrich Schuchardt SEE ALSO close(2) The description mentions close(2). Hence it should also be referenced in the SEE ALSO section. syscall.2 Jann Horn Add x32 ABI umount.2 Eric W. Biederman Document the effect of shared subtrees on umount(2) Eric W. Biederman Correct the description of MNT_DETACH I recently realized that I had been reasoning improperly about what umount(MNT_DETACH) did based on an insufficient description in the umount.2 man page, that matched my intuition but not the implementation. When there are no submounts, MNT_DETACH is essentially harmless to applications. Where there are submounts, MNT_DETACH changes what is visible to applications using the detach directories. Michael Kerrisk Move "shared mount + umount" text to a subsection in NOTES aio_return.3 Stéphane Aulery Document the return value on error Reported by Alexander Holler clock.3 Stéphane Aulery CLOCKS_PER_SEC = 1000000 is required by XSI, not POSIX Debian Bug #728213 reported by Tanaka Akira See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=728213 dlopen.3 Michael Kerrisk Amend error in description of dlclose() behavior The current text says that unloading depends on whether the reference count falls to zero *and no other libraries are using symbols in this library*. That latter text has been there since man-pages-1.29, but it seems rather dubious. How could the implementation know whether other libraries are still using symbols in this library? Furthermore, no other implementation's man page mentions this point. Seems best to drop this point. Michael Kerrisk Add some details for RTLD_DEFAULT Michael Kerrisk Add some details on RTLD_NEXT and preloading Michael Kerrisk RTLD_NEXT works for symbols generally, not just functions The common use case is for functions, but RTLD_NEXT also applies to variable symbols. Michael Kerrisk dlclose() recursively closes dependent libraries Note that dlclose() recursively closes dependent libraries that were loaded by dlopen() Michael Kerrisk Rename second dlopen() argument from "flag" to "flags" This is more consistent with other such arguments Michael Kerrisk Reformat text on RTLD_DEFAULT and RTLD_NEXT fmemopen.3 Ma Shimiao ATTRIBUTES: Note functions that are thread-safe The markings match glibc markings. fpathconf.3 Ma Shimiao ATTRIBUTES: Note functions that are thread-safe The marking matches glibc marking. fputwc.3 Ma Shimiao ATTRIBUTES: Note functions that are thread-safe The marking matches glibc marking. fputws.3 Ma Shimiao ATTRIBUTES: Note function that is thread-safe The marking matches glibc marking. fseek.3 Ma Shimiao ATTRIBUTES: Note functions that are thread-safe The markings match glibc markings. fseeko.3 Ma Shimiao ATTRIBUTES: Note functions that are thread-safe The markings match glibc markings. gcvt.3 Ma Shimiao ATTRIBUTES: Note function that is thread-safe The marking matches glibc marking. getline.3 Ma Shimiao ATTRIBUTES: Note functions that are thread-safe The marking matches glibc marking. getwchar.3 Ma Shimiao ATTRIBUTES: Note function that is thread-safe The marking matches glibc marking. hypot.3 Ma Shimiao ATTRIBUTES: Note functions that are thread-safe The markings match glibc markings. iconv_open.3 Ma Shimiao ATTRIBUTES: Note function that is thread-safe The marking matches glibc marking. if_nameindex.3 Ma Shimiao ATTRIBUTES: Note functions that are thread-safe The markings match glibc markings. initgroups.3 Ma Shimiao ATTRIBUTES: Note function that is thread-safe The markings match glibc markings. mq_open.3 Torvald Riegel Add EINVAL error case for invalid name This behavior is implementation-defined by POSIX. If the name doesn't start with a '/', glibc returns EINVAL without attempting the syscall. popen.3 Ma Shimiao ATTRIBUTES: Note functions that are thread-safe The marking matches glibc marking. pthread_kill.3 Michael Kerrisk Note treatment of signals used internally by NPTL The glibc pthread_kill() function gives an error on attempts to send either of the real-time signals used by NPTL. pthread_sigmask.3 Michael Kerrisk Note treatment of signals used internally by NPTL The glibc implementation silently ignores attempts to block the two real-time signals used by NPTL. pthread_sigqueue.3 Michael Kerrisk Note treatment of signals used internally by NPTL The glibc pthread_sigqueue() function gives an error on attempts to send either of the real-time signals used by NPTL. resolver.3 Stéphane Aulery [Jakub Wilk] Document missing options used by _res structure indicate defaults Missing options: RES_INSECURE1, RES_INSECURE2, RES_NOALIASES, USE_INET6, ROTATE, NOCHECKNAME, RES_KEEPTSIG, BLAST, USEBSTRING, NOIP6DOTINT, USE_EDNS0, SNGLKUP, SNGLKUPREOP, RES_USE_DNSSEC, NOTLDQUERY, DEFAULT Written from the glibc source and resolv.conf.5. See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=527136 Stéphane Aulery RES_IGNTC is implemented rint.3 Matt Turner Document that halfway cases are rounded to even Per IEEE-754 rounding rules. The round(3) page describes the behavior of rint and nearbyint in the halfway cases by saying: These functions round x to the nearest integer, but round halfway cases away from zero [...], instead of to the nearest even integer like rint(3) sigqueue.3 Michael Kerrisk NOTES: add "C library/kernel ABI differences" subheading Michael Kerrisk Clarify version info (mention rt_sigqueueinfo()) sigsetops.3 Michael Kerrisk Note treatment of signals used internally by NPTL The glibc sigfillset() function excludes the two real-time signals used by NPTL. sigwait.3 Michael Kerrisk Note treatment of signals used internally by NPTL The glibc sigwait() silently ignore attempts to wait for signals used by NPTL. strcoll.3 Ma Shimiao ATTRIBUTES: Note function that is thread-safe The markings match glibc markings. strdup.3 Ma Shimiao ATTRIBUTES: Note functions that are thread-safe The marking matches glibc marking. tzset.3 J William Piggott Add 'std' quoting information ulimit.3 Ma Shimiao ATTRIBUTES: Note function that is thread-safe The marking matches glibc marking. wcstombs.3 Ma Shimiao ATTRIBUTES: Note function that is thread-safe The marking matches glibc marking. wctob.3 Ma Shimiao ATTRIBUTES: Note function that is thread-safe The marking matches glibc marking. xdr.3 Taisuke Yamada Clarified incompatibility and correct usage of XDR API See http://bugs.debian.org/628099 console_codes.4 Scot Doyle Add Console Private CSI sequence 15 An undocumented escape sequence in drivers/tty/vt/vt.c brings the previously accessed virtual terminal to the foreground. mtk: Patch misattributed to Taisuke Yamada in Git commit because of a muck up on my part. Michael Kerrisk Add kernel version number for CSI sequence 15 random.4 Michael Kerrisk Fix permissions shown for the devices These days, the devices are RW for everyone. filesystems.5 Michael Kerrisk Remove dubious claim about comparative performance of ext2 Perhaps it was the best filesystem performance-wise in the 20th century, when that text was written. That probably ceased to be true quite a long time ago, though. Stéphane Aulery Add cross references for ext filesystems Stéphane Aulery Specifies the scope of this list and its limits. host.conf.5 hosts.5 resolv.conf.5 Stéphane Aulery [Paul E Condon] Cross references of these pages. See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=298259 host.conf.5 Stéphane Aulery Rework discussion of nospoof, spoofalert, spoof and RESOLV_SPOOF_CHECK The keywords and environment variables "nospoof", "spoofalert", "spoof" and RESOLV_SPOOF_CHECK were added to glibc 2.0.7 but never implemented Move descriptions to historical section and reorder it for clarity See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=773443 hosts.5 Stéphane Aulery [Vincent Lefevre] Mention 127.0.1.1 for FQDN and IPv6 examples See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=562890 proc.5 Taisuke Yamada Document /proc/PID/status VmPin field See https://bugs.launchpad.net/bugs/1071746 Michael Kerrisk Document (the obsolete) /proc/PID/seccomp Michael Kerrisk Replace description of 'uid_map' with a reference to user_namespaces(7) All of the information in proc(5) was also present in user_namespaces(7), but the latter was more detailed and up to date. Taisuke Yamada Fix SELinux /proc/pid/attr/current example Since the /proc/pid/attr API was added to the kernel, there have been a couple of changes to the SELinux handling of /proc/pid/attr/current. Fix the SELinux /proc/pid/attr/current example text to reflect these changes and note which kernel versions first included the changes. securetty.5 Stéphane Aulery [Nicolas FRANCOIS] Note that the pam_securetty module also uses this file See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=528015 This patch is a modified version of the one proposed without parts specific to Debian. boot.7 Michael Witten Copy edit While a lot of the changes are issues of presentation, there are also issues of grammar and punctuation. Michael Witten Mention `systemd(1)' and its related `bootup(7)' It's important that the reader receive contemporary information. credentials.7 Michael Kerrisk SEE ALSO: add pthreads(7) Michael Kerrisk Add reference to nptl(7) feature_test_macros.7 Michael Kerrisk Update discussion of _FORTIFY_SOURCE Since the initial implementation a lot more checks were added. Describe all the checks would be too verbose (and would soon fall out of date as more checks are added). So instead, describe the kinds of checks that are done more generally. Also a few other minor edits to the text. hier.7 Stéphane Aulery First patch of a series to achieve compliance with FHS 2.3 Stéphane Aulery SGML and XML directories are separated in FHS 2.3 Stéphane Aulery Add missing directories defined by FHS 2.3 Stéphane Aulery Identify which directories are optional Stéphane Aulery Document /initrd, /lost+found and /sys Ubuntu Bug #70094 reported by Brian Beck https://bugs.launchpad.net/ubuntu/+source/manpages/+bug/70094 Stéphane Aulery Explain YP, which is not obvious ipv6.7 Stéphane Aulery [David Madore] SOL_IPV6 and other SOL_* options socket are not portable See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=472447 man-pages.7 Michael Kerrisk [Bill Pemberton] Add indent(1) command that produces desired formatting for example code Stéphane Aulery Improve description of sections in accordance with intro pages packet.7 Michael Kerrisk Rework description of fanout algorithms as list Michael Kerrisk Remove mention of needing UID 0 to create packet socket The existing text makes no sense. The check is based purely on a capability check. (Kernel function net/packet/af_packet.c::packet_create() Michael Kerrisk Remove text about ancient glibc not defining SOL_PACKET This was fixed in glibc 2.1.1, which is a long while ago. And in any case, there is nothing special about this case; it's just one of those times when glibc lags. Michael Kerrisk Rework description of 'sockaddr_ll' fields as a list Michael Kerrisk Various minor edits pthreads.7 Michael Kerrisk Add references to nptl(7) raw.7 Michael Kerrisk Rephrase "Linux 2.2" language to "Linux 2.2 or later" The man page was written in the LInux 2.2 timeframe, and some phrasing was not future-proof. signal.7 Michael Kerrisk Note when Linux added realtime signals Michael Kerrisk Correct the range of realtime signals Michael Kerrisk Summarize 2.2 system call changes that resulted from larger signal sets Michael Kerrisk SEE ALSO: add nptl(7) tcp.7 Peter Adkins Document removal of TCP_SYNQ_HSIZE Looking over the man page for 'tcp' I came across a reference to tuning the 'TCP_SYNQ_HSIZE' parameter when increasing 'tcp_max_syn_backlog' above 1024. However, this static sizing was removed back in Linux 2.6.20 in favor of dynamic scaling - as part of commit 72a3effaf633bcae9034b7e176bdbd78d64a71db. user_namespaces.7 Eric W. Biederman Update the documentation to reflect the fixes for negative groups Files with access permissions such as rwx---rwx give fewer permissions to their group then they do to everyone else. Which means dropping groups with setgroups(0, NULL) actually grants a process privileges. The unprivileged setting of gid_map turned out not to be safe after this change. Privileged setting of gid_map can be interpreted as meaning yes it is ok to drop groups. [ Eric additionally noted: Setting of gid_map with privilege has been clarified to mean that dropping groups is ok. This allows existing programs that set gid_map with privilege to work without changes. That is, newgidmap(1) continues to work unchanged.] To prevent this problem and future problems, user namespaces were changed in such a way as to guarantee a user can not obtain credentials without privilege that they could not obtain without the help of user namespaces. This meant testing the effective user ID and not the filesystem user ID, as setresuid(2) and setregid(2) allow setting any process UID or GID (except the supplementary groups) to the effective ID. Furthermore, to preserve in some form the useful applications that have been setting gid_map without privilege, the file /proc/[pid]/setgroups was added to allow disabling setgroups(2). With setgroups(2) permanently disabled in a user namespace, it again becomes safe to allow writes to gid_map without privilege. Michael Kerrisk Rework some text describing permission rules for updating map files No (intentional) change to the facts, but this restructuring should make the meaning easier to grasp. Michael Kerrisk Update kernel version associated with 5-line limit for map files As at Linux 3.18, the limit is still five lines, so mention the more recent kernel version in the text. Michael Kerrisk [Alban Crequy] Handle /proc/PID/setgroups in the example program Michael Kerrisk Rework text describing restrictions on updating /proc/PID/setgroups No (intentional) changes to factual description, but the restructured text is hopefully easier to grasp. Michael Kerrisk Explain why the /proc/PID/setgroups file was added ldconfig.8 Michael Kerrisk Note use of /lib64 and /usr/lib64 on some 64-bit architectures ld.so.8 Michael Kerrisk Note the use of /lib64 and /usr/lib64 on some 64-bit architectures