From 994ef54be900efb95a69fe3f247385baf4b09f36 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Fri, 12 May 2006 18:12:51 +0000 Subject: [PATCH] Ready for 2.32 --- Changes | 323 +++++++++------------------------------- Changes.old | 298 ++++++++++++++++++++++++++++++++++++ HOWTOHELP | 28 ++-- man-pages-2.32.Announce | 2 +- man-pages-2.32.lsm | 4 +- 5 files changed, 386 insertions(+), 269 deletions(-) diff --git a/Changes b/Changes index d6e318bb6..dd6468150 100644 --- a/Changes +++ b/Changes @@ -1,6 +1,6 @@ -==================== Changes in man-pages-2.31 ==================== +==================== Changes in man-pages-2.32 ==================== -Released: 2006-05-02 +Released: 2006-05-13 Contributors ------------ @@ -8,289 +8,114 @@ Contributors The following people contributed notes, ideas, or patches that have been incorporated in changes in this release: -Joshua Kwan +Andries Brouwer +Johannes Weiner Justin Pryzby Karel Kulhavy -Mark Glines -Martin (Joey) Schulze -Nishanth Aravamudan -Reuben Thomas -Ryan S. Arnold -Ulrich Drepper +Paul Brook +Pavel Heimlich Apologies if I missed anyone! -Page renamings --------------- - -The following pages have been relocated into section 7, since -that is their more natural home. SEE ALSO references in various -other pages have been adjusted. - -epoll.4 -fifo.4 -futex.4 -complex.5 -environ.5 (many pages outside man-pages actually *expect* - 'environ' to be in Section 7.) -ipc.5 renamed to svipc.7 - -".so" link files have been created to link the old file locations to the -new file locations. These links are added just to ensure that cross -references from any other (non-man-pages) pages will remain valid; -eventually these links will be removed. - - New pages --------- -fstatat.2 +faccessat.2 mtk - New page for fstatat(2), new in 2.6.16. + New page for faccessat(2), new in 2.6.16. -adjtime.3 +fchmodat.2 mtk - New page for adjtime(3). - -error.3 - Justin Pryzby / mtk - New page describing error() and error_at_line() - Fixes Debian bug 186307. + New page for fchmodat(2), new in 2.6.16. -error_at_line.3 -error_message_count.3 -error_on_per_line.3 -error_print_progname.3 +fchownat.2 mtk - New links to new error.3. + New page for fchownat(2), new in 2.6.16. -program_invocation_name.3 +futimesat.2 mtk - New page describing program_invocation_name and - program_invocation_short_name variables. - -program_invocation_short_name.3 - mtk - New link to new program_invocation_name.3. - -sockatmark.3 - mtk - New page for sockatmark(3). - -ftm.7 - mtk - New page describing feature test macros. - -time.7 - mtk - New page giving an overview of "time" on Linux systems. - - -Global changes --------------- - -getgroups.2 -wait4.2 -chown.2 -chdir.2 -gettimeofday.2 -initgroups.3 -dirfd.3 - mtk - Simplified wording around requirement for _BSD_SOURCE - feature test macro. - -times.2 -time.2 -gettimeofday.2 -getitimer.2 -nanosleep.2 -ctime.3 -rtc.4 - mtk - Added SEE ALSO referring to new time.7. - -err.3 -errno.3 -perror.3 -strerror.3 - Justin Pryzby / mtk - Add SEE ALSO referring to new error.3. - -getdate.3 -printf.3 -scanf.3 - mtk - Added SEE ALSO entry referring to setlocale.3. + New page for futimesat(2), new in 2.6.16. Changes to individual pages --------------------------- -accept.2 - Mark Glines - Remove mention of SOCK_RDM from this page, since this socket - type does not support accept()ing connections. - -adjtimex.2 +access.2 mtk - Modified text referring to adjtime(); added SEE ALSO for new - adjtime.3 page. + Add SEE ALSO reference pointing to new faccessat.2 page. + +capget.2 + mtk + Reworded to reflect that capabilities are per-thread. -fsync.2 - mtk, after a note by Karel Kulhavy - Rewrote most of the DESCRIPTION, as well as some other parts - the page, to clarify use and operation of, and rationale for, - fsync(2) and fdatasync(2). - -getitimer.2 - mtk - Updated discussion of maximum timer value to reflect the fact - that the default jiffy is now 4 milliseconds. - - Added text to note that current incorrect behaviour of - normalising tv_usec >= 1000000 will be repaired in a future - kernel; applications should be fixed now. - -gettimeofday.2 - Karel Kulhavy - Point out more explicitly that 'tz' argument should - normally be NULL. +chmod.2 mtk - Various other minor edits and formatting fixes. + Add SEE ALSO reference pointing to new fchmodat.2 page. -mount.2 +chown.2 mtk - Since kernel 2.6.16, MS_NOATIME and MS_NODIRATIME are settable - on a per-mount basis. - Detail exactly which mount flags can be changed on MS_REMOUNT. - -nanosleep.2 - mtk / Karel Kulhavy - Clarify RETURN VALUE discussion. + Add SEE ALSO reference pointing to new fchownat.2 page. + +mmap.2 + mtk + Updated discussion of MAP_NORESERVE since it is no longer + restricted to MAP_PRIVATE mappings. + Add reference to discussion of /proc/sys/vm/overcommit_memory + in proc.5. openat.2 mtk - Add SEE ALSO reference pointing to new fstatat.2. + Add SEE ALSO reference pointing to new faccessat.2, fchmodat.2, + fchownat.2, futimesat.2 pages. -recv.2 - mtk - Added SEE ALSO for new sockatmark.3. - -rmdir.2 - Joshua Kwan / Martin (Joey) Schulze / mtk - Correct wording of EBUSY case. - mtk - Add ".." case to ENOTEMPTY error - -select.2 - Karel Kulhavy - Note more clearly that fd_set arguments can be NULL. - mtk / Karel Kulhavy - Improve opening paragraph describing purpose of select(). - mtk - Various other minor edits and formatting fixes. - -semget.2 - mtk / Nishanth Aravamudan - Add text to noting that the initial values of semaphores - in a new set are indeterminate. - shmget.2 mtk - Add text noting that contents of newly created segment are zero - values. - -sigwaitinfo.2 - mtk - Noted that all threads should block signal being waited for. - -stat.2 - Nishanth Aravamudan / mtk - Added NOTE that st_size is always returned as zero for most - /proc files. - mtk - Add SEE ALSO reference pointing to new fstatat.2. - -syscall.2 - Justin Pryzby / mtk - Remove bogus BUGS text. + Document SHM_NORESERVE flag, new in 2.6.15. +truncate.2 + Paul Brook / mtk + Expand text noting that ftruncate()/truncate() may fail if + asked to extend a file beyond its current length. + Add EPERM error. + utime.2 mtk - Various minor changes. + Add SEE ALSO reference pointing to new futimesat.2 page. -confstr.3 +fopen.3 + Justin Pryzby / mtk + Document 'm' (mmap) flag. + Debian bug 365754. mtk - Rewrote RETURN VALUE discussion. - Updated CONFORMING TO. - Removed BUGS. - -ctanh.3 - Martin (Joey) Schulze / mtk - Fix errors in DESCRIPTION + Document 'c' (notcancel) flag. + +futimes.3 + mtk + Add SEE ALSO reference pointing to new futimesat.2 page. + +qsort.3 + Johannes Weiner + Add missing "const" qualifies to cast in EXAMPLE. + mtk + Slight rewording of comments in EXAMPLE. + +termios.3 + Karel Kulhavy + Clarify meaning of IXANY. + Clarify relationship of MIN with VMIN and TIME with VTIME. + mtk + Noted that CIBAUD, OFDEL, and DELECHO are not implemented + on Linux. + Added explanatory paragraph for phrases "not in POSIX" and + "XSI". -ctime.3 +capabilities.7 mtk - The range of tm_sec is 0..60 (not 0..61). - -fmemopen.3 - mtk / Ryan S. Arnold - Add text noting that explicitly controlling output buffering - may be useful to catch errors on output operations on an - fmemopen() stream. - -getline.3 - Justin Pryzby - Add SEE ALSO pointing to getline.3. - See Debian bug 364772 - -strtod.3 -strtoul.3 - mtk - Describe correct handling of errno in order to - distinguish error from success after the call. - - Added EXAMPLE section which points to strtol.3 which provides - an example of the use of the analogous strtol(3). - -strtol.3 - mtk / Justin Pryzby - Add an example program. - mtk - Describe correct handling or errno in order to - distinguish error from success after the call. - -tmpfile.3 - Reuben Thomas - DESCRIPTION does not need to say "temporary file name" - just "temporary file", since the name is in any case - unavailable to the user. - See Debian bug 363518 - mtk - In DESCRIPTION: - Change /automatically deleted when the program terminates normally/ - to /automatically deleted when the program terminates/ - since deletion occurs on both normal and abnormal termination. - -ip.7 - Karel Kulhavy / mtk - Various wording improvements and clarifications. - -signal.7 - mtk / Ulrich Drepper - Add text noting that a signal's disposition is process-wide, - shared by all threads. - mtk - Add text on changing signal dispositions. - Add text on "signal mask and pending signals". - Other minor edits. - -time.7 - mtk - Added SEE ALSO for new adjtime.3. - -ld.so.8 - Justin Pryzby - Remove bogus duplicate line. + Reworded to reflect that capabilities are per-thread. + Add ioprio_set() to list of operations permitted by + CAP_SYS_NICE. + Add ioprio_set() IOPRIO_CLASS_RT and IOPRIO_CLASS_IDLE + scheduling classes to list op operations permitted by + CAP_SYS_ADMIN. + Note effects of CAP_SYS_NICE for migrate_pages(). diff --git a/Changes.old b/Changes.old index 8bac54a17..96535c349 100644 --- a/Changes.old +++ b/Changes.old @@ -3718,3 +3718,301 @@ core.5 PID in the core filename. mtk / Stefan Puiu Eliminate some accidentally duplicated text. + + +==================== Changes in man-pages-2.31 ==================== + +Released: 2006-05-02 + +Contributors +------------ + +The following people contributed notes, ideas, or patches that have +been incorporated in changes in this release: + +Joshua Kwan +Justin Pryzby +Karel Kulhavy +Mark Glines +Martin (Joey) Schulze +Nishanth Aravamudan +Reuben Thomas +Ryan S. Arnold +Ulrich Drepper + +Apologies if I missed anyone! + + +Page renamings +-------------- + +The following pages have been relocated into section 7, since +that is their more natural home. SEE ALSO references in various +other pages have been adjusted. + +epoll.4 +fifo.4 +futex.4 +complex.5 +environ.5 (many pages outside man-pages actually *expect* + 'environ' to be in Section 7.) +ipc.5 renamed to svipc.7 + +".so" link files have been created to link the old file locations to the +new file locations. These links are added just to ensure that cross +references from any other (non-man-pages) pages will remain valid; +eventually these links will be removed. + + +New pages +--------- + +fstatat.2 + mtk + New page for fstatat(2), new in 2.6.16. + +adjtime.3 + mtk + New page for adjtime(3). + +error.3 + Justin Pryzby / mtk + New page describing error() and error_at_line() + Fixes Debian bug 186307. + +error_at_line.3 +error_message_count.3 +error_on_per_line.3 +error_print_progname.3 + mtk + New links to new error.3. + +program_invocation_name.3 + mtk + New page describing program_invocation_name and + program_invocation_short_name variables. + +program_invocation_short_name.3 + mtk + New link to new program_invocation_name.3. + +sockatmark.3 + mtk + New page for sockatmark(3). + +ftm.7 + mtk + New page describing feature test macros. + +time.7 + mtk + New page giving an overview of "time" on Linux systems. + + +Global changes +-------------- + +getgroups.2 +wait4.2 +chown.2 +chdir.2 +gettimeofday.2 +initgroups.3 +dirfd.3 + mtk + Simplified wording around requirement for _BSD_SOURCE + feature test macro. + +times.2 +time.2 +gettimeofday.2 +getitimer.2 +nanosleep.2 +ctime.3 +rtc.4 + mtk + Added SEE ALSO referring to new time.7. + +err.3 +errno.3 +perror.3 +strerror.3 + Justin Pryzby / mtk + Add SEE ALSO referring to new error.3. + +getdate.3 +printf.3 +scanf.3 + mtk + Added SEE ALSO entry referring to setlocale.3. + + +Changes to individual pages +--------------------------- + +accept.2 + Mark Glines + Remove mention of SOCK_RDM from this page, since this socket + type does not support accept()ing connections. + +adjtimex.2 + mtk + Modified text referring to adjtime(); added SEE ALSO for new + adjtime.3 page. + +fsync.2 + mtk, after a note by Karel Kulhavy + Rewrote most of the DESCRIPTION, as well as some other parts + the page, to clarify use and operation of, and rationale for, + fsync(2) and fdatasync(2). + +getitimer.2 + mtk + Updated discussion of maximum timer value to reflect the fact + that the default jiffy is now 4 milliseconds. + + Added text to note that current incorrect behaviour of + normalising tv_usec >= 1000000 will be repaired in a future + kernel; applications should be fixed now. + +gettimeofday.2 + Karel Kulhavy + Point out more explicitly that 'tz' argument should + normally be NULL. + mtk + Various other minor edits and formatting fixes. + +mount.2 + mtk + Since kernel 2.6.16, MS_NOATIME and MS_NODIRATIME are settable + on a per-mount basis. + Detail exactly which mount flags can be changed on MS_REMOUNT. + +nanosleep.2 + mtk / Karel Kulhavy + Clarify RETURN VALUE discussion. + +openat.2 + mtk + Add SEE ALSO reference pointing to new fstatat.2. + +recv.2 + mtk + Added SEE ALSO for new sockatmark.3. + +rmdir.2 + Joshua Kwan / Martin (Joey) Schulze / mtk + Correct wording of EBUSY case. + mtk + Add ".." case to ENOTEMPTY error + +select.2 + Karel Kulhavy + Note more clearly that fd_set arguments can be NULL. + mtk / Karel Kulhavy + Improve opening paragraph describing purpose of select(). + mtk + Various other minor edits and formatting fixes. + +semget.2 + mtk / Nishanth Aravamudan + Add text to noting that the initial values of semaphores + in a new set are indeterminate. + +shmget.2 + mtk + Add text noting that contents of newly created segment are zero + values. + +sigwaitinfo.2 + mtk + Noted that all threads should block signal being waited for. + +stat.2 + Nishanth Aravamudan / mtk + Added NOTE that st_size is always returned as zero for most + /proc files. + mtk + Add SEE ALSO reference pointing to new fstatat.2. + +syscall.2 + Justin Pryzby / mtk + Remove bogus BUGS text. + +utime.2 + mtk + Various minor changes. + +confstr.3 + mtk + Rewrote RETURN VALUE discussion. + Updated CONFORMING TO. + Removed BUGS. + +ctanh.3 + Martin (Joey) Schulze / mtk + Fix errors in DESCRIPTION. + +ctime.3 + mtk + The range of tm_sec is 0..60 (not 0..61). + +fmemopen.3 + mtk / Ryan S. Arnold + Add text noting that explicitly controlling output buffering + may be useful to catch errors on output operations on an + fmemopen() stream. + +getline.3 + Justin Pryzby + Add SEE ALSO pointing to getline.3. + See Debian bug 364772. + +strtod.3 +strtoul.3 + mtk + Describe correct handling of errno in order to + distinguish error from success after the call. + + Added EXAMPLE section which points to strtol.3 which provides + an example of the use of the analogous strtol(3). + +strtol.3 + mtk / Justin Pryzby + Add an example program. + mtk + Describe correct handling or errno in order to + distinguish error from success after the call. + +tmpfile.3 + Reuben Thomas + DESCRIPTION does not need to say "temporary file name" + just "temporary file", since the name is in any case + unavailable to the user. + See Debian bug 363518. + mtk + In DESCRIPTION: + Change /automatically deleted when the program terminates normally/ + to /automatically deleted when the program terminates/ + since deletion occurs on both normal and abnormal termination. + +ip.7 + Karel Kulhavy / mtk + Various wording improvements and clarifications. + +signal.7 + mtk / Ulrich Drepper + Add text noting that a signal's disposition is process-wide, + shared by all threads. + mtk + Add text on changing signal dispositions. + Add text on "signal mask and pending signals". + Other minor edits. + +time.7 + mtk + Added SEE ALSO for new adjtime.3. + +ld.so.8 + Justin Pryzby + Remove bogus duplicate line. diff --git a/HOWTOHELP b/HOWTOHELP index f2d5d798b..570760ee9 100644 --- a/HOWTOHELP +++ b/HOWTOHELP @@ -81,6 +81,12 @@ When you submit a patch, please note the following: [patch] shmop.2: add "(void *)" cast to RETURN VALUE +-- If editing a page, and you find one or two white spaces at the end + of an existing line, DON'T bother removing them. The reason is + that in a "diff -u" this will make it look like there is a change + when in fact nothing has changed. In most cases, these extra white + spaces do no harm, so just leave them be. + MANUAL PAGES IN OTHER PACKAGES ============================== @@ -220,7 +226,10 @@ If you are thinking of writing one or more of these pages, then: -- You need to have a reasonably high degree of understanding of the topic, or be prepared to invest the time (e.g., reading source code, - writing test programs) to gain that understanding. + writing test programs) to gain that understanding. Writing test + programs is important; quite a few kernel and glibs bugs have been + uncovered while writing test programs during the preparation of + manual pages. -- Follow the existing formatting conventions for manual pages. Some information about formatting is provided in the "man(7)" @@ -261,24 +270,9 @@ request_key(2) (new in kernel 2.6.10) See: Documentation/keys.txt Documentation/keys-request-key.txt - Requires CONFIG_KEYS (and optionally COFIG_KEYS_DEBUG_PROC_KEYS) + Requires CONFIG_KEYS (and optionally COFIG_KEYS_DEBUG_PROC_KEYS) under "Security options" - -ioprio_get(2) (new in kernel 2.6.13) -ioprio_set(2) (new in kernel 2.6.13) - See: - Documentation/block/ioprio.txt - The following may also be useful: - http://marc.theaimsgroup.com/?t=106829609100002&r=1&w=2 - Subject: [PATCH] cfq + io priorities - Date: 2003-11-08 12:47:58 - - http://marc.theaimsgroup.com/?l=linux-kernel&m=110364047432467&w=2 - Subject: [PATCH][CFT] time sliced cfq ver18 - From: Jens Axboe - Date: 2004-12-21 14:40:50 - restart_syscall(2) (new in kernel 2.6) kexec_load(2) (new in kernel 2.6.13) diff --git a/man-pages-2.32.Announce b/man-pages-2.32.Announce index 856283b1e..fbc53c8b1 100644 --- a/man-pages-2.32.Announce +++ b/man-pages-2.32.Announce @@ -1,7 +1,7 @@ RELEASE The Linux man page maintainer proudly announces. . . - man-pages-2.31.tar.gz - man pages for Linux + man-pages-2.32.tar.gz - man pages for Linux Differences from the previous manual pages release are listed in the file "Changes". diff --git a/man-pages-2.32.lsm b/man-pages-2.32.lsm index e3d8b238d..bbf834125 100644 --- a/man-pages-2.32.lsm +++ b/man-pages-2.32.lsm @@ -1,7 +1,7 @@ Begin3 Title: Section 2, 3, 4, 5 and 7 man pages for Linux -Version: 2.31 -Entered-date: 2006-05-02 +Version: 2.32 +Entered-date: 2006-05-13 Description: Linux and POSIX manual pages Keywords: man pages Author: several