==================== Changes in man-pages-4.00 ==================== Released: 2015-05-07, 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: Advait Dixi Alain Kalker Andi Kleen Andreas Gruenbacher Andreas Heiduk Askar Safin Brice Goglin Cameron Norman Carlos O'Donell Chris Metcalf Christophe Lohr Christopher Head Christoph Hellwig David Wilcox Denis Du Egmont Koblinger Filipe Brandenburger Filipus Klutiero Florian Weimer Frédéric Maria Gleb Fotengauer-Malinovskiy Graham Shaw Gregor Jasny Guillem Jover Guy Harris Heinrich Schuchardt Ian Pilcher Jann Horn Jason Newton J. Bruce Fields Jiri Pirko Joachim Wuttke Joern Heissler Jonathan Nieder Joonas Salo Jussi Lehtola Kirill A. Shutemov KOSAKI Motohiro Laurence Gonsalves Magnus REFTEL Michael Kerrisk NeilBrown Regid Ichira Sam Varshavchik Steinar H. Gunderson Stéphane Aulery Stephane Fillod Tetsuo Handa Thomas Hood Urs Thuermann Vasiliy Kulikov Vegard Nossum Weijie Yang William Woodruff Zeng Linggang Apologies if I missed anyone! New and rewritten pages ----------------------- get_phys_pages.3 William Woodruff Document get_phys_pages() and get_avphys_pages() loop.4 Urs Thuermann, Michael Kerrisk New page documenting the loop device xattr.7 Andreas Gruenbacher Import attr(5) man page from the 'attr' project After discussions with Andreas Gruenbacher, it makes sense to move this page into man-pages, since it mostly relates to kernel details. Since this is an overview page, we'll move it to Section 7. Michael Kerrisk Rename page "xattr" is a more meaningful name than "attr" (it resonates with the names of the system calls), so as long as we are moving the page to a new section, we'll change the name as well, and retain an acl(5) link so that old references remain valid. Newly documented interfaces in existing pages --------------------------------------------- mmap.2 Michael Kerrisk [Andi Kleen] Document MAP_HUGE_2MB, MAP_HUGE_1GB, and MAP_HUGE_SHIFT shmget.2 Michael Kerrisk [Andi Kleen] Document SHM_HUGE_2MB, SHM_HUGE_1GB, and SHM_HUGE_SHIFT resolver.3 Michael Kerrisk [Jonathan Nieder] Add descriptions of some other resolver functions Add res_ninit(), res_nquery(), res_nsearch(), and res_nquerydomain(), res_nmkquery(), res_nsend(). tty_ioctl.4 Frédéric Maria [Stephane Fillod, Andreas Heiduk] Document TIOCMIWAIT and TIOCGICOUNT Michael Kerrisk Document TIOCGEXCL Michael Kerrisk Document TIOGCPKT Michael Kerrisk Document TIOCSPTLCK Michael Kerrisk Document TIOCGPTLCK New and changed links --------------------- CMSG_DATA.3 Michael Kerrisk New link to cmsg(3) CMSG_LEN.3 Michael Kerrisk New link to cmsg(3) dprintf.3 Michael Kerrisk Convert to a link to printf.3 get_avphys_pages.3 William Woodruff New link to new get_phys_pages.3 page res_ninit.3 res_nmkquery.3 res_nquery.3 res_nquerydomain.3 res_nsearch.3 res_nsend.3 Michael Kerrisk New links to resolver(3) man page loop-control.4 Michael Kerrisk New link to loop.4 attr.5 Michael Kerrisk New link to xattr(7) Global changes -------------- chown.2 execve.2 prctl.2 truncate.2 proc.5 capabilities.7 ld.so.8 Michael Kerrisk Tighter wording: 'mode bit' rather than 'permission bit' For sticky, set-UID, and set-GID mode bits (as used in POSIX). Changes to individual pages --------------------------- add_key.2 keyctl.2 request_key.2 Michael Kerrisk SEE ALSO: add keyrings(7) add_key.2 request_key.2 Michael Kerrisk SEE ALSO: add keyctl(3) epoll_ctl.2 Michael Kerrisk After EPOLLHUP, EOF will be seen only after all data has been consumed epoll_wait.2 Michael Kerrisk Clarify that signal mask treatment in epoll_pwait() is per-thread s/sigprocmask()/pthread_sigmask()/ fcntl.2 Michael Kerrisk [Vegard Nossum] Note an F_SETSIG corner case get_mempolicy.2, set_mempolicy Brice Goglin Policy is per thread, not per process getxattr.2 listxattr.2 removexattr.2 setxattr.2 capabilities.7 Michael Kerrisk Adjust "attr(5)" references to "xattr(7)" ioctl.2 Michael Kerrisk SEE ALSO: add console_ioctl(2) and tty_ioctl(2) listxattr.2 xattr.7 Michael Kerrisk Describe listxattr(2) E2BIG error and document it as a BUG mkdir.2 Michael Kerrisk Wording fixes + point reader at stat(2) for explanation of file mode Michael Kerrisk [Andreas Grünbacher] Further tweaks to text on S_ISVTX and 'mode' argument mknod.2 Michael Kerrisk Rewordings + point reader at stat(2) for details of mode bits mmap.2 Michael Kerrisk Remove text that implies that munmap() syncs MAP_SHARED mapping to file The existing text in this page: MAP_SHARED Share this mapping. Updates to the mapping are visible to other processes that map this file, and are carried through to the underly‐ ing file. The file may not actually be updated until msync(2) or munmap() is called. implies that munmap() will sync the mapping to the underlying file. POSIX doesn't require this, and some light reading of the code and some light testing (fsync() after munmap() of a large file) also indicates that Linux doesn't do this. msync.2 Michael Kerrisk Rework text of DESCRIPTION Rewrite the text somewhat, for easier comprehension. No (intentional) changes to factual content nfsservctl.2 Michael Kerrisk [J. Bruce Fields] Note that nfsservctl() was replaced by files in nfsd filesystem open.2 Michael Kerrisk [Andreas Gruenbacher] open() honors the S_ISVTX, S_ISUID, and S_ISGID bits in 'mode' Michael Kerrisk Tighten wording: use 'mode bit' rather than 'permission bit' Michael Kerrisk [NeilBrown] BUGS: O_CREAT | O_DIRECTORY succeeds if pathname does not exist poll.2 Michael Kerrisk [Ian Pilcher] Clarify that signal mask treatment in ppoll() is per-thread s/sigprocmask()/pthread_sigmask()/ Michael Kerrisk [Sam Varshavchik] After POLLHUP, EOF will be seen only after all data has been consumed Michael Kerrisk Make it clearer which bits are ignored in 'events' prctl.2 Michael Kerrisk [David Wilcox, Filipe Brandenburger] Note that "parent" for purposes of PR_SET_DEATHSIG is a *thread* See https://bugzilla.kernel.org/show_bug.cgi?id=43300 sendfile.2 Michael Kerrisk [Jason Newton] Note that sendfile does not support O_APPEND for 'out_fd' See https://bugzilla.kernel.org/show_bug.cgi?id=82841 Michael Kerrisk [Gregor Jasny] RETURN VALUE: note the possibility of "short sends" See https://bugzilla.kernel.org/show_bug.cgi?id=97491 Michael Kerrisk [Askar Safin] Clarify text on 'out_fd' and regular files in Linux 2.4 See https://bugzilla.kernel.org/show_bug.cgi?id=86001 shutdown.2 Michael Kerrisk [Stéphane Aulery] BUGS: UNIX domain sockets now detect invalid 'how' values Bug fixed in Linux 3.7. See https://bugzilla.kernel.org/show_bug.cgi?id=47111 sigaction.2 Michael Kerrisk Refer the reader to fcntl(2) F_SETSIG for further details on si_fd stat.2 Jann Horn Add note about stat() being racy Andreas Gruenbacher Improve description of some mode constants Michael Kerrisk [Andreas Grünbacher] Remove excessive leading zeros on some constants Michael Kerrisk Add text on POSIX terms "file mode bits" and "file permission bits" Recent changes to various pages employ this distinction. Michael Kerrisk Tighten wording: use 'mode bit' rather than 'permission bit' According to POSIX, the the 9 UGO*RWX bits are permissions, and 'mode' is used to refer to collectively to those bits plus sticky, set-UID, and set_GID bits. syslog.2 Michael Kerrisk SEE ALSO: add dmesg(1) umask.2 open.2 mknod.2 mkdir.2 Andreas Gruenbacher Explain what default ACLs do Explain the effect that default ACLs have (instead of the umask) in umask.2. Mention that default ACLs can have an affect in open.2, mknod.2, and mkdir.2. unshare.2 Michael Kerrisk [Florian Weimer] Give the reader a hint that unshare() works on processes or threads See https://bugzilla.kernel.org/show_bug.cgi?id=59281 atexit.3 Zeng Linggang ATTRIBUTES: Note function that is thread-safe bsearch.3 Zeng Linggang ATTRIBUTES: Note function that is thread-safe cmsg.3 Michael Kerrisk [Christopher Head] Fix error in SCM_RIGHTS code sample Remove erroneous second initialization of msg.msg_controllen in the example code for SCM_RIGHTS. See https://bugzilla.kernel.org/show_bug.cgi?id=15952 CPU_SET.3 Chris Metcalf Clarify language about "available" cpus The CPU_SET.3 man page uses the adjective "available" when explaining what the argument to CPU_SET() means. This is confusing, since "available" isn't well-defined. The kernel has a set of adjectives (possible, present, online, and active) that qualify cpus, but normally none of these are what the cpu_set_t bit index means: it's just "which cpu", using the kernel's internal numbering system, even if that cpu isn't possible or present. This change removes the word "available" and adds a sentence warning that cpu sets may not be contiguous due to dynamic cpu hotplug, etc. err.3 Zeng Linggang ATTRIBUTES: Note functions that are thread-safe ftw.3 Zeng Linggang ATTRIBUTES: Note functions that are thread-safe gethostbyname.3 Carlos O'Donell NSS plugins searched first Carlos O'Donell "order" is obsolete gethostid.3 Zeng Linggang ATTRIBUTES: Note functions that are/aren't thread-safe getmntent.3 Zeng Linggang ATTRIBUTES: Note functions that are/aren't thread-safe get_nprocs_conf.3 Michael Kerrisk Use exit() rather than return in main() getopt.3 Michael Kerrisk [Guy Harris] Remove crufty BUGS section See https://bugzilla.kernel.org/show_bug.cgi?id=90261 iconv_close.3 Zeng Linggang ATTRIBUTES: Note function that is thread-safe inet_ntop.3 Zeng Linggang ATTRIBUTES: Note function that is thread-safe longjmp.3 Zeng Linggang ATTRIBUTES: Note functions that are thread-safe lsearch.3 Zeng Linggang ATTRIBUTES: Note functions that are thread-safe mcheck.3 Zeng Linggang ATTRIBUTES: Note functions that aren't thread-safe on_exit.3 Zeng Linggang ATTRIBUTES: Note function that is thread-safe printf.3 Michael Kerrisk [Egmont Koblinger] Merge dprintf() and vdprintf() discussion into this page Michael Kerrisk SEE ALSO: add puts(3) Michael Kerrisk Move return value discussion to proper RETURN VALUE section putpwent.3 Zeng Linggang ATTRIBUTES: Note function that is thread-safe qsort.3 Zeng Linggang ATTRIBUTES: Note functions that are thread-safe regex.3 Michael Kerrisk [Laurence Gonsalves] Fix error in description of 'cflags' 'cflags' is a bit mask of *zero* (not one) or more flags. resolver.3 Stéphane Aulery Add info about RES_INSECURE1 and RES_INSECURE2 option in debug mode scanf.3 Joern Heissler Improve description of %n specifier setjmp.3 Zeng Linggang ATTRIBUTES: Note functions that are thread-safe setlocale.3 Zeng Linggang ATTRIBUTES: Note function that isn't thread-safe setlogmask.3 Zeng Linggang ATTRIBUTES: Note function that isn't thread-safe sleep.3 Zeng Linggang ATTRIBUTES: Note function that isn't thread-safe strsignal.3 Zeng Linggang ATTRIBUTES: Note function that isn't thread-safe sysconf.3 Zeng Linggang ATTRIBUTES: Note function that is thread-safe undocumented.3 William Woodruff Remove documented functions tty_ioctl.4 Michael Kerrisk [Denis Du] Fix error in code example proc.5 Michael Kerrisk [Cameron Norman, Vasiliy Kulikov] Document /proc mount options Document the 'hidepid' and 'gid' mount options that were added in Linux 3.3. See https://bugzilla.kernel.org/show_bug.cgi?id=90641 Based on text by Vasiliy Kulikov in Documentation/filesystems/proc.txt. Michael Kerrisk [Kirill A. Shutemov] Improve description of /proc/PID/status Guillem Jover Document /proc/PID/exe behaviour on unlinked pathnames Michael Kerrisk [Weijie Yang] Document /proc/PID/status VmPMD resolv.conf.5 Stéphane Aulery [Thomas Hood] Document use-vc option added to glibc 2.14 Fix Ubuntu bug #1110781: https://bugs.launchpad.net/ubuntu/+source/manpages/+bug/1110781 Stéphane Aulery [Thomas Hood] Document RES_SNGLKUPREOP Fix Ubuntu bug #1110781: https://bugs.launchpad.net/ubuntu/+source/manpages/+bug/1110781 tzfile.5 Sam Varshavchik Add various details on version 2 format aio.7 Michael Kerrisk Add details and update URL for OLS 2003 paper on AIO xattr.7 Michael Kerrisk Document EA limits for Btrfs Document VFS-imposed limits on EAs VFS imposes a 255-byte limit on EA names, and a 64kB limit on EA values. Michael Kerrisk The ext[234] block limitation applies to sum of all EAs It is not a per-EA limit. Michael Kerrisk Clarify permissions required to work with 'user' EAs Michael Kerrisk ext2 and ext3 no longer need mounting with 'user_xattr' for user EAs Michael Kerrisk Add various relevant pages to SEE ALSO Michael Kerrisk Add CONFORMING TO section Michael Kerrisk Modify headings to man-pages norms Michael Kerrisk Btrfs also supports extended attributes Michael Kerrisk File capabilities are implemented using *security* attributes Not *system* attributes Michael Kerrisk Describe limit on EA values for JFS, XFS, and Reiserfs bootparam.7 Michael Kerrisk [Alain Kalker] Update discussion of 'debug' option See https://bugzilla.kernel.org/show_bug.cgi?id=97161 Michael Kerrisk Summary of multiple changes: remove cruft from this page. Much of the detail on hardware specifics in this page dates from the 20th century. (The last major update to this page was in man-pages-1.14!) It's hugely out of date now (many of these devices disappeared from the kernel years ago.) So, I've taken a large scythe to the page to remove anything that looks seriously dated. In the process, the page has shrunk to less than 50% of its previous size. Michael Kerrisk Remove "buff=" details This seems to have gone away in Linux 2.2. Michael Kerrisk Remove crufty "Mouse drivers" options Michael Kerrisk Remove crufty "General non-device-specific boot arguments" options Michael Kerrisk Remove crufty "Hard disks" options Michael Kerrisk Remove crufty "mem=" details Michael Kerrisk Remove crufty details on IBM MCA bus devices Michael Kerrisk Remove 'swap=" details This seems to have gone away in Linux 2.2, Michael Kerrisk Remove crufty floppy disk driver options In the specific case of floppy drives: the drivers still exist, but it's been a while since most of saw these devices in the wild. So, just refer the reader to the kernel source file for details. (The detail in this man page was after all originally drawn from that file.) Remove crufty "ISDN drivers" options Michael Kerrisk Remove crufty "line printer driver" options Michael Kerrisk Remove crufty "Serial port drivers" options Michael Kerrisk Remove crufty reference to CONFIG_BUGi386 That option disappeared in Linux 2.4. Michael Kerrisk Remove crufty text "bootsetups array" dates from Linux 2.0. Michael Kerrisk Remove crufty "Video hardware" options Michael Kerrisk Remove crufty SCSI device driver options fanotify.7 Michael Kerrisk [Heinrich Schuchardt] Since Linux 3.19, fallocate(2) generates FAN_MODIFY events inotify.7 Michael Kerrisk [Heinrich Schuchardt] Since Linux 3.19, fallocate(2) generates IN_MODIFY events ip.7 Michael Kerrisk Explain how IP_ADD_MEMBERSHIP determines its argument type Michael Kerrisk [Jiri Pirko, Magnus REFTEL] Clarify details of the IP_MULTICAST_IF socket option Michael Kerrisk [Advait Dixi] Remove dubious text that says that SO_PRIORITY set IP TOS See https://bugzilla.kernel.org/show_bug.cgi?id=35852 Michael Kerrisk Relocate misplaced text describing ENOPROTOOPT error packet.7 Graham Shaw Add sll_protocol to list of required fields for outbound packets pthreads.7 Michael Kerrisk [KOSAKI Motohiro] Using thread IDs whose lifetime has expired gives undefined behavior See https://bugzilla.kernel.org/show_bug.cgi?id=53061 raw.7 Michael Kerrisk [Tetsuo Handa] For incoming datagrams, sin_port is set to zero Michael Kerrisk Mention sendto(), recvfrom(), and so on when discussing address format This gives the reader a little context for the following discussion of 'sin_port'. Michael Kerrisk Remove crufty reference to Michael Kerrisk Replace reference to RFC 1700 with pointer to IANA protocol number list signal.7 Michael Kerrisk [Steinar H. Gunderson] Clarify that I/O operations on disks are not interrupted by signals See https://bugzilla.kernel.org/show_bug.cgi?id=97721 unix.7 Michael Kerrisk [Christophe Lohr] Remove mention of UNIX_PATH_MAX This kernel constant is not exposed to user space. Michael Kerrisk Note the 108 bytes for sun_path is how things are done on Linux And refer the reader to NOTES for discussion of portability. xattr.7 Michael Kerrisk Explicitly mention some of the xattr system calls in DESCRIPTION Naming the system calls helps to orient the reader nscd.8 Michael Kerrisk Add mention of 'services' and 'netgroup' databases This makes the page consistent with nscd.conf(5).