diff --git a/Changes b/Changes index 297006159..90a95a6f0 100644 --- a/Changes +++ b/Changes @@ -1,4 +1,4 @@ -==================== Changes in man-pages-3.11 ==================== +==================== Changes in man-pages-3.?? ==================== Released: ????-??-??, Munich @@ -9,30 +9,400 @@ Contributors The following people contributed notes, ideas, or patches that have been incorporated in changes in this release: - +André Goddard Rosa +Eugene V. Lyubimkin +Gergely Soos +Kirill A. Shutemov +Marko Kreen +Maxin B. John +Maxin John +Michael Kerrisk +Nicolas François +Pavel Heimlich +Ricardo Catalinas Jiménez +Sam Varshavchik Apologies if I missed anyone! New and rewritten pages ----------------------- - -Newly documented interfaces in existing pages ---------------------------------------------- +umount.2 + Michael Kerrisk + Create a new page for umount() and umount2() by extracting + existing material from mount.2 page. New and changed links --------------------- +umount2.2 + Michael Kerrisk + umount2.2: Change link to point to new umount.2 -Global changes --------------- + The umount2() material migrated from mount.2 to umount.2 Changes to individual pages --------------------------- -syscalls.2 - mtk +execve.2 + Michael Kerrisk + execve.2: _SC_ARG_MAX is no longer necessarily constant + + POSIX.1-2001 says that the values returned by sysconf() + are constant for the life of the process. + But the fact that, since Linux 2.6.23, ARG_MAX is settable + via RLIMIT_STACK means _SC_ARG_MAX is no longer constant, + since it can change at each execve(). + + Michael Kerrisk + execve.2: Linux now imposes a floor on the ARG_MAX limit + + Starting with Linux 2.6.23, the ARG_MAX limit became settable via + (1/4 of) RLIMIT_STACK. This broke ABI compatibility if RLIMIT_STACK + was set such that ARG_MAX was < 32 pages. Document the fact that + since 2.6.25 Linux imposes a floor on ARG_MAX, so that the old limit + of 32 pages is guaranteed. + + For some background on the changes to ARG_MAX in kernels 2.6.23 and + 2.6.25, see: + http://sourceware.org/bugzilla/show_bug.cgi?id=5786 + http://bugzilla.kernel.org/show_bug.cgi?id=10095 + http://thread.gmane.org/gmane.linux.kernel/646709/focus=648101, + checked into 2.6.25 as commit a64e715fc74b1a7dcc5944f848acc38b2c4d4ee2. + + Also some reordering/rewording of the discussion of ARG_MAX. + +fallocate.2 + Michael Kerrisk + fallocate.2: Note lack of glibc wrapper; caller must use syscall(2) + + Glibc doesn't (and quite probably won't) include a wrapper for this + system call. Therefore, point out that potential callers will need + to use syscall(2), and rewrite the RETURN VALUE text to show things + as they would be if syscall() is used. + + Michael Kerrisk + fallocate: Refer reader to posix_fallocate(3) for portable interface + + Add a para to start of page that points out that this is the + low-level, Linux-specific API, and point the reader to posix_fallocate(3) + for the portable API. + +getdents.2, readdir.3 + Michael Kerrisk + getdents.2, readdir.3: d_type is currently only supported on ext[234] + + As at kernel 2.6.27, only ext[234] support d_type. + On other file systems, d_type is always set to DT_UNKNOWN (0). + +getdents.2 + Michael Kerrisk + getdents.2: Add an example program + Michael Kerrisk + getdents.2: comment out linux_dirent fields with varying location + + The location of the fields faster d_name varies according to + the size of d_name. We can't properly declare them in C; + therefore, put those fields inside a comment. + + Michael Kerrisk + getdents.2: The DT_* constants are defined in + + Michael Kerrisk + getdents.2: remove header files from SYNOPSIS + + None of the header files provides what is needed. + Calls are made via syscall(2). + + Michael Kerrisk + getdents.2: The programmer must define the linux_dirent structure + + Point out that this structure is not defined in glibc headers. + + Michael Kerrisk + getdents.2: s/dirent/linux_dirent/ + + The structure isn't currently defined in glibc headers, and the kernel + name of the structure is 'linux_dirent' (as was already used in some, + but not all, places in this page). + +getrlimit.2 + Michael Kerrisk + getrlimit.2: Reword/relocate discussion of BSD's historical RLIMIT_OFILE + + The old sentence sat on its own in an odd place, and anyway the + modern BSDs use the name RLIMIT_NOFILE. + + Michael Kerrisk + getrlimit.2: refer to execve(2) for RLIMIT_STACK's effect on ARG_MAX + + Refer the reader to new text in execve(2) that describes how + (since Linux 2.6.23) RLIMIT_STACK determines the value of ARG_MAX. + +getrusage.2 + Michael Kerrisk + getrusage.2: rusage measures are preserved across execve(2) + +mlock.2 + Maxin John + mlock.2: add EAGAIN error. + +move_pages.2 + Nicolas François + move_pages.2: Make a detail of EPERM error more precise + +mount.2 + Michael Kerrisk + mount.2: Add description of namespace + + Describe per-process namespaces, including discussion + of clone() and unshare CLONE_NEWNS, and /proc/PID/mounts. + + Michael Kerrisk + mount.2: List a few other file systems that we may see in /proc/filesystems + + Add some modern file systems to that list (xfs, jfs, ext3, reiserfs). + + Michael Kerrisk + mount.2: Document MS_SILENT (and MS_VERBOSE) + +mount.2, umount.2 + Michael Kerrisk + mount.2, umount.2: split umoun*() out into a separate page + + The length of this page means that it's becoming difficult to parse + which info is specific to mount() versus umount()/umount2(), so split + the umount material out into its own page. + +pause.2 + Michael Kerrisk + pause.2: remove mention of words "library function" + + This really is a system call. + +readdir.2 + Michael Kerrisk + readdir.2: The programmer must declare the old_linux_dirent structure + + Glibc does not provide a definition of this structure. + + Michael Kerrisk + readdir.2: s/dirent/old_linux_dirent/ + + Nowadays, this is the name of the structure in the kernel sources. + + Michael Kerrisk + readdir.2: remove words "which may change" + + These words are slightly bogus: although the interface is obsolete, + for ABI-compatibility reasons, the kernel folk should never be changing + this interface. + + Michael Kerrisk + readdir.2: remove header files from SYNOPSIS + + glibc doesn't provide any support for readdir(2), + so remove these header files (which otherwise suggest + that glibc does provide the required pieces). + +recv.2 + Nicolas François + recv.2: Move kernel version number to first mention to MSG_ERRQUEUE. + +semop.2 + Kirill A. Shutemov + semop.2: fix typo in example + + (The '&' before sop in the semop() call is unneeded.) + +send.2 + Michael Kerrisk + send.2: make kernel version for MSG_CONFIRM more precise + + s/2.3+ only/Since Linux 2.3.15/ + +sigaction.2 + Michael Kerrisk + sigaction.2: refer reader to signal(7) for an overview of signals + sigaction.2: explain semantics of signal disposition during fork() and execve() + sigaction.2: refer to signal(7) for more details on signal mask. + +sigaltstack.2 + Michael Kerrisk + sigaltstack.2: explain inheritance of alternate signal stack across fork(2) + +sigwaitinfo.2 + Michael Kerrisk + sigwaitinfo.2: distinguish per-thread and process-wide signals + + A sentence clarifying that pending signal set is union of + per-thread and process-wide pending signal sets. + + Michael Kerrisk + sigwaitinfo.2: these interfaces have per-thread semantics + + The page was previously fuzzy about whether the these interfaces + have process-wide or per-thread semantics. (E.g., now the + page states that the calling *thread* (not process) is suspended + until the signal is delivered.) + +sigpending.2 + Michael Kerrisk + sigpending.2: explain effect of fork() and execve() for pending signal set + + Michael Kerrisk + sigpending.2: explain how thread's pending signal set is defined + + The pending set is the union of per-thread pending signals and process-wide + pending signals. + +sigprocmask.2 + Michael Kerrisk + sigprocmask.2: explain effects of fork() and execve() for signal mask + +splice.2 + Michael Kerrisk + splice.2: note that SPLICE_F_MOVE is a no-op since kernel 2.6.21 + +syscall.2 + Michael Kerrisk + syscall.2: Add more detail about wrapper functions + Add a few more details about work generally done by wrapper functions. Note that syscall(2) performs the same steps. + +tkill.2 + Michael Kerrisk + tkill.2: EINVAL error can also occur for invalid TGID + + The EINVAL error on an invalid TGID for tgkill() was + not documented; this change documents it. + +utimensat.2 + Michael Kerrisk + utimensat.2: POSIX.1-2008 revision will likely affect FTMs for futimens() + + Make it clear that the POSIX.1 revision that is likely + to affect the feature test macro requirements for futimens() is + POSIX.1-2008. + + Nicolas François + utimensat.2: Make various wordings a little more precise. + + The times argument point to *an array of* structures, and the + man-page should say that consistently. + +wait4.2 + Michael Kerrisk + wait4.2: wait3() is a library function layered on wait4(). + + On Linux wait3() is a library function implemented on top of wait4(). + (Knowing this is useful when using strace(2), for example.) + +atan2.3 + Nicolas François + atan2.3: Fix error in description of range or return value + + In recent changes to the man page, mtk accidentally changed + the description of the return value range to -pi/2..pi/2; + the correct range is -pi..pi. + +cmsg.3 + Nicolas François + cmsg.3: Add parentheses after macro names. + +ctime.3 + Michael Kerrisk + ctime.3: clarify mktime()'s use of tm_isdst + + Describe use of tm_isdst for input to mktime(); + explain how mktime() modifies this field. + (This field is left unchanged in case of error.) + + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=500178 + + Michael Kerrisk + Clarify wording for ctime_r() and asctime_r() to indicate that + the buffer must be at least 26 *bytes*. + + Michael Kerrisk + ctime.3: minor rewording of mktime() description. + +floor.3 + Nicolas François + floor.3: Fix error in description: s/smallest/largest/ + +hsearch.3 + André Goddard Rosa + hsearch.3: Call hdestroy() after using hash table created by hcreate(), for the sake of completeness + +mg_getattr.3 + Michael Kerrisk + mg_getattr.3: mq_getattr() and mq_setattr() are layered on mq_getsetattr(2) + + mq_getattr() and mq_setattr() are library functions layered on + top of the mq_getsetattr(2) system call. + (This is useful info for users of strace(1).) + +mq_receive.3 + Michael Kerrisk + mq_receive.3: mq_send() is a library function layered on mq_timedreceive() syscall + + This info is useful for users of strace(1). + +mq_send.3 + Michael Kerrisk + mq_send.3: mq_send() is a library function layered on mq_timedsend() syscall + + This info is useful for users of strace(1). + +nextafter.3 + Nicolas François + nextafter.3: Make description more precise: s/next/largest/ + +readdir.3 + Michael Kerrisk + readdir.3: SEE ALSO: add getdents(2) + + Because readdir() is implemented on top of getdents(2). + +realpath.3 + Michael Kerrisk + realpath.3: clarify that returned pathname is NULL terminated + + Also clarify that null-byte is included in PATH_MAX limit. + +proc.5 + Michael Kerrisk + proc.5: rewrite and simplify description of /proc/mounts + + Most of the relevant discussion is now under /proc/PID/mounts; + all that needs to be here is a mention of the pre-2.4.19 + system-wide namespace situation, and a reference to the + discussion under /proc/PID/mounts. + + Michael Kerrisk + proc.5: Add description of /proc/PID/mounts + + Largely cribbed from existing /proc/mounts discussion, which is + about to be rewritten. + +mq_overview.7 + Michael Kerrisk + mq_overview.7: add mq_notify() to list of lib. functions and syscalls in MQ API + +signal.7 + Michael Kerrisk + signal.7: improve description in NAME section + signal.7: Add mention of sigaltstack(2). + signal.7: Describe syscalls that synchronously wait for a signal, + signal.7: Give overview of syscalls that block until a signal is caught + signal.7: Add overview of interfaces for sending signals. + + Michael Kerrisk + signal.7: describe semantics w.r.t. fork() and execve() + + Include text describing semantics of fork() and execve() for + signal dispositions, signal mask, and pending signal set.