==================== Changes in man-pages-3.15 ====================

Released: 2008-12-05, Bucaramanga


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

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

Andre Majorel <aym-xunil@teaser.fr>
Andries E. Brouwer <Andries.Brouwer@cwi.nl>
Chris Heath <chris@heathens.co.nz>
Drake Wilson <drake@begriffli.ch>
Mats Wichmann <mats.d.wichmann@intel.com>
Mel Gorman <mel@csn.ul.ie>
Michael Kerrisk <mtk.manpages@gmail.com>
Mike Fedyk <mfedyk@mikefedyk.com>
Pavel Machek <pavel@suse.cz>
Petr Baudis <pasky@suse.cz>
Phil Endecott <phil_vonar_endecott@chezphil.org>
Rob Landley <rob@landley.net>
Sam Varshavchik <mrsam@courier-mta.com>

Apologies if I missed anyone!


New and rewritten pages
-----------------------

makedev.3
    Michael Kerrisk
        New page for makedev(), major(), and minor() macros

pthread_cleanup_push_defer_np.3
    Michael Kerrisk
        New page for pthread_cleanup_push_defer_np(3) and
        pthread_cleanup_pop_restore_np(3)


Newly documented interfaces in existing pages
---------------------------------------------

accept.2
    Michael Kerrisk
        Document accept4() system call, new in Linux 2.6.28

fmemopen.3
    Petr Baudis
        Add description of open_wmemstream(3)

tcp.7
    Michael Kerrisk
        Document MSG_TRUNC flag for TCP sockets

New and changed links
---------------------

accept4.2
    Michael Kerrisk
        New link to accept.2
            accept.2 now documents the new accept4() system call.

open_wmemstream.3
    Petr Baudis
        New link to fmemopen.3
            fmemopen.3 now documents open_wmemstream().
pthread_cleanup_pop_restore_np.3
    Michael Kerrisk
        New link to new pthread_cleanup_push_defer_np.3


Global changes
--------------

accept.2
listen.2
recv.2
getpeername.2
getsockname.2
shutdown.2
socketpair.2
    Michael Kerrisk
        Global fix: SEE ALSO: add socket(7)

bind.2
rcmd.3
capabilities.7
ip.7
    Michael Kerrisk
        Global fix: s/reserved port/privileged port/
            Some pages used one term, some pages the other term;
            make some consistency.

connect.2
getpeername.2
getsockname.2
    Michael Kerrisk
        Use consistent argument names
            Most other sockets pages are using the names 'addr'
            and 'addrlen'; make these pages do the same.

getpeername.2
getsockname.2
getsockopt.2
recv.2
send.2
shutdown.2
sockatmark.3
socket.7
udplite.7
    Michael Kerrisk
        SYNOPSIS: Rename socket file descriptor argument to 'sockfd'
            Many sockets man pages use the name 'sockfd' already.
            For consistency, changes the others to do so as well.

gnu_dev_major.3
gnu_dev_makedev.3
gnu_dev_minor.3
major.3
minor.3
    Michael Kerrisk
        New links to new makedev(3) page


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

_exit.2
    Michael Kerrisk
        Since glibc 2.3, the exit() wrapper function invokes exit_group(2)
            This information is useful to users of strace(1).

accept.2
    Michael Kerrisk
        Clarify details when returned address is truncated
            If the returned address is truncated, the 'addrlen' argument
            indicates the actual size of the address, rather than a count
            of the number of bytes in the truncated buffer.

            Also clarify that if 'addr' argument is NULL, then 'addrlen'
            should is unused, and should also be NULL.
    Michael Kerrisk
        Reorder ERRORS list
            Some errors were listed under a separate "may" heading.
            There's probably no real need to do this; integrate
            those errors into the main list.

exit_group.2
    Michael Kerrisk
        Note that since glibc 2.3, exit(2) invokes exit_group()

futex.2
    Michael Kerrisk
        Mention that glibc provides no wrapper function for futex()

get_thread_area.2
    Michael Kerrisk
        Note that glibc provides no wrapper for this system call

getdomainname.2
    Michael Kerrisk
        Substantial rewrite
            Expand description of setdomainname() and getdomainname().
            Note that getdomainname() is implemented as a library function
            in glibc.
            Note limits on size of domain name.
            Reorganize ERRORS list.

gethostname.2
    Michael Kerrisk
        Various parts rewritten
            Write a paragraph describing sethostname().

            Clarify differences between glibc's gethostbyname() and
            the kernel gethostbyname() system calls.

gethostname.2
    Michael Kerrisk
        Note that HOST_NAME_MAX is 64 on Linux
            Also note that in pre-1.0 days, the limit on hostnames
            was 8 bytes.

getpeername.2
    Michael Kerrisk
        Note that returned address may be truncated if buffer is too small

getsid.2
    Michael Kerrisk
        Simplified version information and moved to a new VERSIONS section

getsockname.2
    Michael Kerrisk
        Note that returned address is truncated if buffer is too small

mknod.2
    Michael Kerrisk
        Refer reader to makedev(3) to build a device ID

mmap.2
    Michael Kerrisk
        Loosen language around how 'addr' hint is interpreted
            Mel Gorman reported that in Linux 2.6.27, 'addr' is rounded
            down to a page boundary.

            Before kernel 2.6.26, if 'addr' was taken as a hint, it was
            rounded up to the next page boundary.  Since Linux 2.6.24,
            it is rounded down.  Therefore, loosen the description of
            this point to say that the address is rounded to "a nearby
            page boundary".

open.2
    Michael Kerrisk
        EFBIG error is now EOVERFLOW (since Linux 2.6.24)
            When a 32-bit app opens a file whose size is too big to be
            represented in 31-bits, POSIX.1 specifies the error EOVERFLOW.
            Linux used to give EFBIG for this case, but 2.6.24 fixed this.

            Also, add some text to describe the error scenario in
            more detail.

pread.2
    Michael Kerrisk
        Note that glibc emulation for these calls uses lseek(2)
            (This makes it clearer that the emulated calls are not atomic.)

recv.2
send.2
    Michael Kerrisk
        Make names of "address" and "address length" args more consistent
            Make the names of these arguments more consistent with other
            sockets man pages.

recv.2
    Michael Kerrisk
        Clarify details when returned address is truncated
            If the recvfrom() returned address is truncated, the 'fromlen'
            argument indicates the actual size of the address, rather than
            a count of the number of bytes in the truncated buffer.

            Also clarify that the 'from' argument can be NULL, in which
            case 'fromlen' should is unused, and should also be NULL.
    Michael Kerrisk
        Internet datagram and netlink sockets support MSG_TRUNC for recv(2)
            Internet datagram (since Linux 2.4.27/2.6.8),
            and netlink (since Linux 2.6.22) sockets support
            the MSG_TRUNC flag for recv(2).

select.2
    Michael Kerrisk
        Rewrote text describing feature test macros requirement for pselect()

select_tut.2
    Michael Kerrisk
        Fix SHUT_FD* macros in example program
            Add "do {} while (0)"

set_thread_area.2
    Michael Kerrisk
        Note that glibc provides no wrapper for this system call

setfsgid.2
setfsuid.2
    Michael Kerrisk
        Simplify version information and move to a VERSIONS section

setsid.2
    Michael Kerrisk
        Rework RETURN VALUE section; add an ERRORS section

setup.2
    Michael Kerrisk
        Relocate some CONFORMING TO text to VERSIONS and NOTES

stat.2
    Michael Kerrisk
        Document EOVERFLOW error
    Michael Kerrisk
        Refer reader to major() and minor() to decompose a device ID

syscalls.2
    Michael Kerrisk
        Fix version numbers for a few system calls
            Some 2.6 system calls were wrongly mentioned as also being
            backported into a 2.4.x kernel.

uname.2
    Michael Kerrisk
        DESCRIPTION: Point reader at NOTES for further info on field lengths

atan.3
    Andries E. Brouwer
        Fix return value description
            The correct range for the return value is [-pi/2,pi/2].
            (mtk's fix in the last change to the return value text was
            a botch-up of a (correct) suggestion by Nicolas Francois.)

atexit.3
    Michael Kerrisk
        atexit() and on_exit(3) register functions on the same list
    Michael Kerrisk
        Terminating registered function using longjmp() is undefined
            According to POSIX.1, using longjmp() to terminate execution of
            a function registered using atexit() produces undefined results.
    Michael Kerrisk
        Calling exit(3) more than once produces undefined results
            If an exit handler itself calls exit(3), the results are
            undefined (see the POSIX.1-2001 specification of exit(3)).
    Michael Kerrisk
        The same exit handler may be registered multiple times
    Michael Kerrisk
        Calling _exit(2) terminates processing of exit handlers
    Michael Kerrisk
        Terminating registered function using longjmp() is undefined
            According to POSIX.1, using longjmp() to terminate execution of
            a function registered using atexit() produces undefined results.

bindresvport.3
    Mats Wichmann
        SYNOPSIS: s/\*\*/*/ in prototype
    Michael Kerrisk
        Fix errors regarding port used, plus other rewrites
            Glibc's bindresvport() takes no notice of sin->sin_port:
            it always returns an arbitrary reserved port in the
            anonymous range (512-1023).  (Reported by Mats Wichmann.)

            Also:
            * Add EADDRINUSE and EACCES errors.
            * Mention use of getsockname(2).
            * Other minor rewrites and reorderings of the text.
            * Explicitly note that glib's bindresvport() ignores
              sin->sin_port.
            * Change license There's now virtually no text remaining from
              the 1.70 version of this page.

            Reviewed-by: Mats Wichmann <mats.d.wichmann@intel.com>
            Reviewed-by: Petr Baudis <pasky@suse.cz>

dlopen.3
    Petr Baudis
        Describe confusing dladdr() behavior
            dladdr() will act unexpectedly if called from non-pic code on a
            compile-time-generated function pointer.

fmemopen.3
    Michael Kerrisk
        Add VERSIONS section
    Petr Baudis
        SEE OPEN: Add fopencookie(3)
            fopencookie(3) is used to implement fmemopen().

fopen.3
    Petr Baudis
        SEE ALSO: Add fmemopen(3) and fopencookie(3)

fopencookie.3
    Petr Baudis
        fopencookie() needs _GNU_SOURCE feature test macro

getaddrinfo.3
    Petr Baudis
        Document results ordering and /etc/gai.conf
            This patch documents the order of the getaddrinfo(3) results
            (RFC 3484), how should the application deal with that,
            mentions the extremely common cause of having multiple
            results per query (both IPv4 and IPv6 addresses available)
            and mentions /etc/gai.conf.

            (mtk: Minor tweaks, and note glibc version for /etc/gai.conf)

isatty.3
    Michael Kerrisk
        Complete rewrite of this page, with rather more detail

memmem.3
    Michael Kerrisk
        Remove sentence saying that libc 5.0.9 is still widely used
            That was a *long* time ago.

on_exit.3
    Michael Kerrisk
        Document handling of registrations on fork(2) and execve(2)
            Treatment in these cases is the same as for atexit(3).
    Michael Kerrisk
        Arg given to registered function is status from *last* call to exit()
            It's a subtle point, but if a registered function itself
            calls exit(3), then subsequent functions that were registered
            with on_exit(3) will see the exit status given to the more
            recent exit(3) call.
    Michael Kerrisk
        Note that same function may be registered multiple times

setlocale.3
locale.7
    Michael Kerrisk
        Clean up the description of LANGUAGE environment variable
            Clean up the $LANGUAGE description, by removing bogus comments
            from setlocale(3) and expanding the mention in locale(7).

            Maybe you will decide that a more detailed description
            should be left to the gettext(3) documentation, but I
            actually care about the invisible part of the patch more
            since the comments have put me off the track initially
            ($LANGUAGE has nothing to do with setlocale(3) and is
             completely isolated to gettext, as obvious from the
             glibc sources).

proc.5
    Michael Kerrisk
        /proc/stat: s/minor/disk_idx/ in description of /proc/stat
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=225619

capabilities.7
    Drake Wilson
        Various minor fixes as per Debian bug 471029
            The relevant pieces of
            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=471029 are:

              - Delete duplicate subentry for KEYCTL_CHOWN/KEYCTL_SETPERM
                operations in the CAP_SYS_ADMIN entry.  (It feels like that
                capability entry should be converted to a list, but I've
                left it in semicolon-delimited form for now.)

              - Remove text about ENFILE from the text about the
                /proc/sys/fs/file-max limit in the CAP_SYS_ADMIN entry, since
                this is already described in the man pages for the relevant
                ofile-creating system calls.

              - Correct or clarify a few other bits of grammar and such;
                see the diff file itself for details.

socket.7
    Michael Kerrisk
        SEE ALSO: add tcp(7) and udp(7)

tcp.7
    Michael Kerrisk
        Relocate out-of-band data discussion
            Move to a new subsection entitled "Sockets API".
    Michael Kerrisk
        Note that MSG_PEEK can be used on out-of-band data

time.7
    Michael Kerrisk
        SEE ALSO: add clock_gettime(3)

unix.7
    Michael Kerrisk
        Unix domain sockets don't support the recv() MSG_TRUNC flag
    Michael Kerrisk
        Retitled subsection "(Un)supported features" to "Sockets API"
            This is consistent with the recent change in tcp(7).

