path: root/Changes

==================== Changes in man-pages-3.11 ====================

Released: 2008-10-07, Munich


Contributors
------------

The following people contributed notes, ideas, or patches that have
been incorporated in changes in this release:

André Goddard Rosa <andre.goddard@gmail.com>
Eugene V. Lyubimkin <jackyf.devel@gmail.com>
Gergely Soos <sogerc1@gmail.com>
Kirill A. Shutemov <kirill@shutemov.name>
Marko Kreen <markokr@gmail.com>
Maxin B. John <maxin.john@ap.sony.com>
Maxin John <maxin.john@gmail.com>
Michael Kerrisk <mtk.manpages@gmail.com>
Nicolas François <nicolas.francois@centraliens.net>
Pavel Heimlich <tropikhajma@seznam.cz>
Ricardo Catalinas Jiménez <jimenezrick@gmail.com>
Sam Varshavchik <mrsam@courier-mta.com>

Apologies if I missed anyone!


New and rewritten 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

        The umount2() material migrated from mount.2 to umount.2


Changes to individual pages
---------------------------

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 <dirent.h>

    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

mq_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.