==================== Changes in man-pages-3.51 ==================== Released: 2013-04-17, 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: Andreas Jaeger Andrew Clayton Brian M. Carlson Changhee Han Cyril Hrubis Damien Grassart David Prévot Denis Barbier Jeff Moyer Krzysztof Konopko Kyle McMartin Mark H Weaver Michael Kerrisk Mike Frysinger Nicolas Hillegeer Pavel Emelyanov Peter Schiffer Radek Pazdera Ralph Loader Simon Paillard The Wanderer Apologies if I missed anyone! Newly documented interfaces in existing pages --------------------------------------------- sched_rr_get_interval.2 Michael Kerrisk Document /proc/sys/kernel/sched_rr_timeslice_ms proc.5 Pavel Emelyanov Document /proc/[pid]/map_files directory This directory was added in Linux v3.3 and provides info about files being mmap-ed in a way very similar to how /proc/[pid]/fd works. v2: Added examples of how links look like and noted dependency on kernel config option CONFIG_CHECKPOINT_RESTORE. Michael Kerrisk Document /proc/sys/kernel/shm_rmid_forced capabilities.7 Michael Kerrisk Document /proc/sys/kernel/cap_last_cap Global changes -------------- Various pages Michael Kerrisk Global fix: fix placement of word "only" Various pages Simon Paillard License headers: consistent format Various pages Michael Kerrisk Global fix: s/since kernel/since Linux/ Various System V IPC pages in Section 2 Michael Kerrisk Add "System V" to .TH line and text Make it clear that these pages relate to System V IPC, not POSIX IPC. Changes to individual pages --------------------------- access.2 Michael Kerrisk [The Wanderer] Clarify RETURN VALUE for F_OK See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=705293 alarm.2 Michael Kerrisk Correct the description of behavior when 'seconds' is 0 clone.2 Michael Kerrisk [Peter Schiffer] Add prototype for syscall to SYNOPSIS And further clarify the distinction between the system call and the wrapper function in the introductory text. Michael Kerrisk Update feature test macro requirements The requirements quietly changed changed in glibc 2.14 See also http://www.sourceware.org/bugzilla/show_bug.cgi?id=4749 Michael Kerrisk [Mike Frysinger] Clarify differences between clone2() syscall and wrapper function Michael Kerrisk [Mike Frysinger] Note those architectures where the sys_clone argument order differs Michael Kerrisk [Mike Frysinger] Add short subsection noting that blackfin, m68k, and sparc are different Michael Kerrisk Move clone2() text to subsection in description The description of ia64 clone2() should follow the discussion of the raw system call interface. Michael Kerrisk Change subhead for ia64 discussion getcpu.2 Michael Kerrisk Recommend that 'tcache' should be specified as NULL nowadays io_cancel.2 Jeff Moyer, Michael Kerrisk [Cyril Hrubis] Improve description io_destroy.2 Jeff Moyer Improve description The description was rather vague, citing a "list of I/O contexts" and stating that it "can" cancel outstanding requests. This update makes things more concrete so that the reader knows exactly what's going on. io_getevents.2 Jeff Moyer The 'timeout' argument is not updated I looked back through the kernel code, and the timeout was never updated in any case. I've submitted a patch upstream to change the comment above io_getevents. io_setup.2 Jeff Moyer Clarify nr_events nr_events is technically the number of completion events that can be stored in the completion ring. The wording of the man page: "capable of receiving at least nr_events" seems dubious to me, only because I worry that folks might interpret that to mean 'nr_events' total, instead of 'nr_events' concurrently. Further, I've added information on where to find the per-user limit on 'nr_events', /proc/sys/fs/aio-max-nr. Let me know if you think that is not relevant. listxattr.2 Michael Kerrisk Explain use of 'size' argument lseek.2 Michael Kerrisk [Andreas Jaeger] _GNU_SOURCE must be defined to get SEEK_DATE and SEEK_HOLE definitions See http://sourceware.org/bugzilla/show_bug.cgi?id=15312 mmap.2 Michael Kerrisk Add pointers to relevant /proc files described in proc(5) posix_fadvise.2 pread.2 readahead.2 sync_file_range.2 truncate.2 Michael Kerrisk Refer to syscall(2) for ABI semantics on certain 32-bit architectures Also: in sync_file_range.2 and posix_fadvise.2 remove description of conventional calling signature as flawed, and in posix_fadvise.2, de-emphasize focus on ARM, and rather phrase as a more general discussion of certain architectures. readdir.2 Michael Kerrisk readdir(2) doesn't exist on x86-64 semop.2 Michael Kerrisk Clarify the discussion of 'semadj' shmctl.2 Michael Kerrisk Refer to proc(5) for description of /proc/sys/kernel/shm_rmid_forced syscall.2 Changhee Han Add notes that caution users when passing arguments to syscall() For example, passing 'long long' on ARM-32 requires special treatment. Mike Frysinger [Michael Kerrisk] Document the exact calling convention for architecture system calls Mike Frysinger [Kyle McMartin] Add PA-RISC details under calling conventions Michael Kerrisk [Mike Frysinger] Refine discussion of ARM and other ABIs syscalls.2 Michael Kerrisk Update kernel version number at start of list umask.2 Michael Kerrisk SEE ALSO: add acl(5) unshare.2 Michael Kerrisk Update feature test macro requirements The requirements quietly changed changed in glibc 2.14 See also http://www.sourceware.org/bugzilla/show_bug.cgi?id=4749 fopencookie.3 Michael Kerrisk [Ralph Loader] Correct definition of cookie_io_functions_t pthread_setname_np.3 Andrew Clayton The thread argument is passed in by value readir.3 seekdir.3 telldir.3 Michael Kerrisk Eliminate the implication that these functions deal with "offsets" The directory position dealt with by the readdir() and friends is not a simple file offset in modern file systems. Typically, it is some kind of cookie value. Add text and make other changes to these pages to eliminate the implication that this is an offset, and warn the reader that directory positions should be treated strictly as opaque values. In the process, rename the 'offset' argument of seekdir(3) to 'loc', and add some text to readdir(3) to note that the 'd_off' field is the same value returned by telldir(3) at the current directory position. See also https://lwn.net/Articles/544298/ scalb.3 Mark H Weaver Fix prototypes for scalbf() and scalbl() sched_getcpu.3 Michael Kerrisk Update feature test macro requirements The requirements quietly changed changed in glibc 2.14 See also http://www.sourceware.org/bugzilla/show_bug.cgi?id=4749 ualarm.3 Michael Kerrisk [Nicolas Hillegeer] Add note on the behavior when 'usecs' is zero POSIX.1-2001 does not specify the behavior in this case and no other system that I checked documented the behavior. Probably, most or all systems do what Linux does in this case: cancel any pending alarm, just as alarm(0) does. Add that info in NOTES. elf.5 Mike Frysinger Add byte positions for all EI_xxx fields When describing e_ident, most of the EI_xxx defines mention the exact byte number. This is useful when manually hacking an ELF with a hex editor. However, the last few fields don't do this, which means you have to count things up yourself. Add a single word to each so you don't have to do that. proc.5 Michael Kerrisk Refer to sched_rr_get_interval(2) for info on sched_rr_timeslice_ms Since Linux 3.9, /proc/sys/kernel/sched_rr_timeslice_ms can be used to change the SCHED_RR quantum. Michael Kerrisk SEE ALSO: Add sysctl(8) Krzysztof Konopko Simplify the example of printing out environ The binutils package contains a very handy utility to print out null-byte delimited strings from a file. This can replace a rather complex expression with cat(1) provided as an example for printing out /proc/[pid]/environ. Michael Kerrisk Update /proc/PID/maps example Update to 64-bit example that includes "[heap]", "[stack], and "[vdso]" Michael Kerrisk Formatting fixes for /proc/PID/maps Mike Frysinger Document the "pathname" field of /proc/PID/maps Michael Kerrisk Add reference to capabilities(7) for /proc/sys/kernel/cap_last_cap Michael Kerrisk /proc/PID/maps: add a reference to mmap(2) ip.7 Radek Pazdera Document IP_MULTICAST_ALL This commit adds documentation for the IP_MULTICAST_ALL socket option. The option was added to the Linux kernel in 2.6.31: Author Nivedita Singhvi Commit f771bef98004d9d141b085d987a77d06669d4f4f The description is based on a previous one [3] posted by the original author of the code -- Nivedita, but it is slightly re-worded. I tested it myself and it works as described. References: [1] http://lxr.free-electrons.com/source/net/ipv4/ip_sockglue.c#L972 [2] http://lxr.free-electrons.com/source/net/ipv4/igmp.c#L2267 [3] http://patchwork.ozlabs.org/patch/28902/ units.7 Brian M. Carlson units should use an actual µ The units(7) man page uses an ASCII u in place of the actual Greek letter mu. Since we're in the twenty-first century, with UTF-8-compatible terminals and terminal emulators, we should use the actual letter µ instead of an ASCII approximation. See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=704787