==================== Changes in man-pages-3.76 ==================== 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: Adam Jiang Andrea Balboni Andreas Schwab Bernhard Walle Carlos O'Donell David Wragg Florian Westphal Heinrich Schuchardt Huxiaoxiang Jan Chaloupka Jonathan Wakely Jonny Grant Josh Triplett Kamezawa Hiroyuki Laurent Georget Manuel López-Ibáñez Marko Myllynen Ma Shimiao Mel Gorman Michael Gehring Michael Haardt Michael Kerrisk Mike Frysinger Rasmus Villemoes Richard Weinberger Rich Felker Scott Harvey Siddhesh Poyarekar Simon Newton Simon Paillard Sven Hoexter Tobias Werth Weijie Yang Will Newton Yuri Kozlov 刘湃 尹杰 Apologies if I missed anyone! New and rewritten pages ----------------------- adjtimex.2 Laurent Georget Add fields in struct timex description This patch updates the man page with the new fields added in struct timex since last edition of the man page. Laurent Georget [Michael Kerrisk] Document ADJ_TAI Michael Kerrisk Improve description of ADJ_OFFSET_SINGLESHOT Michael Kerrisk Add brief documentation of ADJ_MICRO and ADJ_NANO Michael Kerrisk Reformat return value list And remove numeric values, since they're not needed Michael Kerrisk Other 'modes' bits are ignored on ADJ_OFFSET_* Other bits in 'modes' are ignored if modes contains ADJ_OFFSET_SINGLESHOT or ADJ_OFFSET_SS_READ. Michael Kerrisk Add nanosecond details Fixes https://bugzilla.kernel.org/show_bug.cgi?id=61171. Michael Kerrisk Document ADJ_OFFSET_SS_READ Michael Kerrisk Reformat 'times' flags as list And remove numeric values, since they're not needed. Michael Kerrisk Note effect of ADJ_NANO for ADJ_SETOFFSET Michael Kerrisk Add comment noting that timex structure contains padding bytes Michael Kerrisk Add more details to description of 'tai' field Michael Kerrisk Note meaning of "PLL" abbreviation Michael Kerrisk Clarify which 'timex' field is used by each 'modes' bit Michael Kerrisk Document timex 'status' bits Michael Kerrisk Clarify treatment of other 'modes' bits for ADJ_OFFSET_* Michael Kerrisk Update RFC number: RFC 5905 obsoletes RFC 1305 Michael Kerrisk Briefly document ADJ_SETOFFSET Michael Kerrisk Note PPS (pulse per second) fields in timex structure sigreturn.2 Michael Kerrisk Add (a lot) more detail on the signal trampoline And rewrite much of the page. Newly documented interfaces in existing pages --------------------------------------------- proc.5 Bernhard Walle Document /proc/thread-self /proc/thread-self has been introduced in Linux 3.17 with commit 0097875bd41528922fb3bb5f348c53f17e00e2fd. Sven Hoexter [Michael Kerrisk, Kamezawa Hiroyuki] Document "VmSwap" field of /proc/[pid]/status Florian Westphal Document /proc/net/netfilter/nfnetlink_queue Changes to individual pages --------------------------- localedef.1 Marko Myllynen Mention default path for compiled files clock_nanosleep.2 Michael Kerrisk Note that 'clock_id' can also be a CPU clock ID epoll_ctl.2 Michael Kerrisk Regular files and directories can't be monitored with epoll_ctl() ioctl.2 Heinrich Schuchardt Rename 'd' argument to 'fd' in text In most other manpages file descriptors are called 'fd'. This patches renames attribute 'd' to 'fd'. madvise.2 Michael Kerrisk VERSIONS: Support for madvise() is now configurable Support for this system call now depends on the CONFIG_ADVISE_SYSCALLS configuration option. open.2 Michael Kerrisk Enhance rationale discussion for openat() and friends posix_fadvise.2 Mel Gorman Document the behavior of partial page discard requests It is not obvious from the interface that partial page discard' requests are ignored. It should be spelled out. Michael Kerrisk [Weijie Yang] ERRORS: Since 2.6.16, the kernel correctly deals with the ESPIPE case Michael Kerrisk Support for fadvise64() is now configurable Support for this system call now depends on the CONFIG_ADVISE_SYSCALLS configuration option. prctl.2 Andreas Schwab Correct description of null-termination in PR_GET_NAME and PR_SET_NAME The size of the process name has always been at most 16 byte _including_ the null terminator. This also means that the name returned by PR_GET_NAME is always null-terminated. Michael Kerrisk PR_SET_NAME silently truncates strings that exceed 16 bytes restart_syscall.2 Michael Kerrisk Add some text explaining why restart_syscall() exists sched_setaffinity.2 Michael Kerrisk NOTES: Add paragraph on how to discover set of CPUs available on system Michael Kerrisk SEE ALSO: add nproc(1) and lscpu(1) select.2 Michael Kerrisk SEE ALSO: add restart_syscall(2) semop.2 Michael Kerrisk Add note that interrupted semtimedop() returns 'timeout' unchanged Michael Kerrisk Remove information about semtimedop() EAGAIN that is repeated elsewhere Michael Kerrisk Add subsection head for semtimedop() setsid.2 Michael Kerrisk Rewrite some pieces and add some details Among other changes, add an explanation of why setsid() can't be called from a process group leader sgetmask.2 Michael Kerrisk Since 3.16, support for these system call is configurable Support for these calls is now dependent on the setting of the CONFIG_SGETMASK_SYSCALL option. sigaction.2 Michael Kerrisk Document SA_RESTORER Michael Kerrisk Add some detail on the sa_restorer field Michael Kerrisk SEE ALSO: add sigreturn(2) splice.2 Michael Kerrisk Reformat description of 'fd_in' and 'off_in' to improve readability syscall.2 Michael Kerrisk SEE ALSO: add errno(3) syscalls.2 Michael Kerrisk SEE ALSO: add errno(3) Michael Kerrisk 3.19 adds execveat() Michael Kerrisk Add bpf(2) to list tee.2 Michael Kerrisk Add shell session demonstrating use of the example program tkill.2 Michael Kerrisk [Rich Felker] Remove bogus text saying tgid==-1 makes tgkill() equivalent to tkill() abort.3 Michael Kerrisk Note that SIGABRT is raised as though raise(3) is called Also note that abort is POSIX.1-2008 compliant. cmsg.3 David Wragg ensure buf is suitably aligned in sending example Inspection of the definition of CMSG_FIRSTHDR (both in glibc and the suggested definition in RFC3542) shows that it yields the msg_control field. So when sending, the pointer placed in msg_control should be suitably aligned as a struct cmsghdr. In the sending example, buf was declared as a bare char array, and so is not necessarily suitably aligned. The solution here involves placing buf inside a union, and is based on the sockets/scm_rights_send.c sample from The Linux Programming Interface "dist" source code collection. exp10.3 Michael Kerrisk Before glibc 2.19, exp() did not give ERANGE error on underflow http://sources.redhat.com/bugzilla/show_bug.cgi?id=6787 ftw.3 Michael Kerrisk FTW_CHDIR has no effect on the 'fpath' argument passed to fn() getopt.3 Michael Kerrisk [Jonny Grant] Ensure that 'nsecs' is used ilogb.3 Michael Kerrisk [Will Newton] Since glibc 2.16, ilogb() does correctly diagnose domain errors memcmp.3 Michael Haardt Document return value for n==0 case Michael Haardt Warn against use of memcmp() for comparing security-critical data mq_open.3 Michael Kerrisk Document the O_CLOEXEC flag Michael Kerrisk Place 'flags' constants in alphabetical order pow.3 Manuel López-Ibáñez Add note on performance characteristics of pow() pthread_setschedparam.3 Simon Newton Fix logic error in example program The example program will crash if -A is used, since 'attr' is uninitialized. $ ./a.out -A *** Error in `./a.out': free(): invalid pointer: 0xb779c3c4 *** Aborted (core dumped) 刘湃 Small fixes to example program sigvec.3 Michael Kerrisk Starting with version 2.21, glibc no longer exports sigvec() sysconf.3 Josh Triplett Document _SC_NGROUPS_MAX Already documented in getgroups(2), but not in sysconf(3). termios.3 Michael Kerrisk SEE ALSO: add tset(1) tgamma.3 Michael Kerrisk Since glibc 2.18, errno is correctly set to EDOM when (x == -infinity)) wordexp.3 Carlos O'Donell Make it clear that WRDE_NOCMD prevents command substitution The use of WRDE_NOCMD prevents command substitution. If the flag WRDE_NOCMD is set then no command substitution shall occur and the error WRDE_CMDSUB will be returned if such substitution is requested when processing the words. The manual page as-is makes it seem like the command substitution occurs, and an error is returned *after* the substitution. This patch clarifies that. locale.5 Marko Myllynen Describe the formats of values locale(5) describes what a locale should define but doesn't spell out how (in what format). The patch attempts to address this, it also has few trivial additional enhancements. * Reference to locale(7) for category descriptions. * Clarify first_workday in NOTES a bit. * Add upstream BZ reference for two missing LC_ADDRESS fields. Marko Myllynen Fix miscoded character resolv.conf.5 Jan Chaloupka Add missing no-tld-query option Based on commit [1], the no-tld-query option exists for resolv.conf configuration file. Description of this option is provided in [2]. This patch just copies this option into resolv.conf.5 man page. Plus changes 'a' member into 'an' before 'unqualified name as if it ...' on the third line of [2]. Based on [3], this option was added in glibc 2.14 as solving [4] bug. [1] https://sourceware.org/git/?p=glibc.git;a=commitdiff;h=f87dfb1f11c01f2ccdc40d81e134cd06b32e28e8 [2] http://www.daemon-systems.org/man/resolv.conf.5.html man page. [3] https://sourceware.org/git/?p=glibc.git;a=blob;f=NEWS;h=952f32af17e7fb49c4c1a305de673a13075bfaf5;hb=f87dfb1f11c01f2ccdc40d81e134cd06b32e28e8 [4] https://sourceware.org/bugzilla/show_bug.cgi?id=12734 credentials.7 Josh Triplett Cross-reference getgroups(2) Since credentials.7 discusses supplementary GIDs, it should reference getgroups(2). fanotify.7 Heinrich Schuchardt Allow relative paths in example The current example code requires passing an absolute path to the mount to be watched. By passing AT_FDCWD to fanotify_mark it can use both absolute and relative paths. Heinrich Schuchardt fallocate(2) creates no events fallocate(2) should create FAN_MODIFY events but does not. Heinrich Schuchardt [Michael Kerrisk] fanotify notifies only events generated on the same mount Unfortunately, fanotify does not inform listeners for all paths under which a touched filesystem object is visible, but only the listener using the same path as the process touching the filesystem object. Heinrich Schuchardt Update BUGS to note bugs still not fixed in 3.17 I bumped the Linux version number in the BUGS section to 3.17. inotify.7 Heinrich Schuchardt fallocate(2) does not trigger inotify events Calling fallocate(2) does not result in inotify events. locale.7 Marko Myllynen Improve LOCPATH description LOCPATH is ignored by privileged programs. Add locale archive references. Add FILES section. man-pages.7 Michael Kerrisk [Laurent Georget] Clarify that SEE ALSO entries may refer to pages from other projects signal.7 Michael Kerrisk Mention other "slow devices" Reads from eventfd(2), signalfd(2), timerfd(2), inotify(7), and fanotify(7) file descriptors are also slow operations that are restartable. Michael Kerrisk Fix SO_RECVTIMEO/ SO_SENDTIMEO confusion in text Michael Kerrisk Since Linux 3.8, reads on inotify(7) file descriptors are restartable Michael Kerrisk inotify(7) reads no longer show the odd EINTR error after SIGCONT Since kernel 3.7, reads from inotify(7) file descriptors no longer show the (Linux oddity) behavior of failing with EINTR when the process resumes after a stop signal + SIGCONT. Michael Kerrisk SEE ALSO: add sigreturn(2) unix.7 Michael Kerrisk [Scott Harvey] Fix buglet in code snippet in BUGS section ld.so.8 Carlos O'Donell Add --inhibit-cache option The dynamic loader has 6 options, only 5 are documented. This patch documents the sixth option i.e. `--inhibit-cache`. Jonathan Wakely [Siddhesh Poyarekar] Correct documentation of $ORIGIN As noted by Siddhesh: The ld.so man page says: $ORIGIN (or equivalently ${ORIGIN}) This expands to the directory containing the application executable. Thus, an application located in somedir/app could be compiled with This is incorrect since it expands to the directory containing the DSO and not the application executable. This seems like deliberate behaviour in dl-object.c, so it needs to be fixed in the man page. See http://stackoverflow.com/questions/26280738/what-is-the-equivalent-of-loader-path-for-rpath-specification-on-linux/26281226#26281226