From e59de0aeb0a52475c689563edbae51a37cb61b67 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Fri, 19 Apr 2013 14:03:08 +0200 Subject: [PATCH] Start of man-pages-3.52: updating Changes and Changes.old --- Changes | 313 ++---------------------------------------------- Changes.old | 334 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 342 insertions(+), 305 deletions(-) diff --git a/Changes b/Changes index 76648421d..6829504a8 100644 --- a/Changes +++ b/Changes @@ -1,6 +1,6 @@ -==================== Changes in man-pages-3.51 ==================== +==================== Changes in man-pages-3.52 ==================== -Released: 2013-04-17, Munich +Released: ????-??-??, Munich Contributors @@ -10,323 +10,26 @@ 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! +New and rewritten pages +----------------------- + + 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 +New and changed links +--------------------- 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 diff --git a/Changes.old b/Changes.old index 98c986e8d..6986642ef 100644 --- a/Changes.old +++ b/Changes.old @@ -26322,3 +26322,337 @@ socket.7 Michael Kerrisk [Florian Weimer] Define _GNU_SOURCE to obtain the definition of 'struct ucred' See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=572210 + + +==================== 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