path: root/Changes

==================== Changes in man-pages-3.20 ====================

Released: 2009-03-31, Christchurch


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

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

Alan Curry <pacman@kosh.dhis.org>
Américo Wang <xiyou.wangcong@gmail.com>
Andi Kleen <andi@firstfloor.org>
Carlos O'Donell <carlos@systemhalted.org>
Chunming Chang <cchang@aerohive.com>
Colin Watson <cjwatson@debian.org>
Eelco Dolstra <dolstra@tudelft.nl>
Jan Engelhardt <jengelh@medozas.de>
Jens Thoms Toerring <jt@toerring.de>
Johannes Stezenbach <js@sig21.net>
Leandro A. F. Pereira <leandro@tia.mat.br>
Martin Gebert <martin.gebert@alpha-bit.de>
Michael Kerrisk <mtk.manpages@gmail.com>
Miike O'Connor <stew@vireo.org>
Mike Frysinger <vapier@gentoo.org>
Nikanth Karthikesan <knikanth@suse.de>
Reuben Thomas <rrt@femur.dyndns.org>
Reuben Thomas <rrt@sc3d.org>
Roland McGrath <roland@redhat.com>
Sam Varshavchik <mrsam@courier-mta.com>
Simon Gomizelj <simongmzlg@gmail.com>
Tanaka Akira <akr@fsij.org>
Teddy Hogeborn <teddy@fukt.bsnet.se>
Walter Jontofsohn <wjontofs@atriumberlin.de>

Apologies if I missed anyone!


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

cpuid.4
    Andi Kleen
        New page for cpuid access device

msr.4
    Andi Kleen
        New page documenting x86 CPU MSR access device


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

proc.5
    Américo Wang
        Document /proc/sys/vm/swappiness
    Michael Kerrisk
        Document /proc/sysrq-trigger


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

timer_create.2
timer_delete.2
timer_getoverrun.2
timer_settime.2
numa.7
    Michael Kerrisk
        Make source layout of 'Link with' text consistent with other pages
            No actual change to formatted output, but this makes the
            page sources more consistent for the purpose of grepping, etc.

mempcpy.3
signbit.3
significand.3
    Michael Kerrisk
        Global fix: acknowledge FSF in copyright
            These pages are heavily based on original material in
            glibc info pages, but the comments in the source of the pages
            did not acknowledge the FRF copyright on the original material.
            Fix that.

accept.2
read.2
recv.2
send.2
write.2
    Michael Kerrisk
        Fix discussion of EAGAIN/EWOULDBLOCK errors
            For a non-blocking socket, POSIX.1-2001/2008 allow either
            EAGAIN or EWOULDBLOCK to be returned in cases where a call
            would have blocked.  Although these constants are defined
            with the same value on most Linux architectures (PA-RISC
            is the exception), POSIX.1 does not require them to have
            the same value.  Therefore, a portable application using
            the sockets API should test for both errors when checking
            this case.

            (NB POSIX.1 only mentions EWOULDBLOCK in the context of
            the sockets interfaces.)

            Change made after a note cross-posted on linux-arch@vger,
            http://thread.gmane.org/gmane.linux.debian.ports.hppa/5615
            and a suggestion for write(2) from Carlos O'Donell

basename.3
getgrent.3
getgrnam.3
getpwent.3
getpwnam.3
readdir.3
    Michael Kerrisk
        Note that returned pointer should not be given to free()

armscii-8.7
cp1251.7
iso_8859-10.7
iso_8859-11.7
iso_8859-13.7
iso_8859-14.7
iso_8859-15.7
iso_8859-16.7
iso_8859-2.7
iso_8859-3.7
iso_8859-4.7
iso_8859-5.7
iso_8859-6.7
iso_8859-7.7
iso_8859-8.7
iso_8859-9.7
koi8-r.7
koi8-u.7
    Michael Kerrisk
        Add explicit character set encoding to first line of source
            Nowadays mandb has provision to understand a character set
            encoding that is explicitly indicated in the first line
            of the source.  As pointed out by Colin Watson, including
            such an explicit indication on pages encoded in anything
            other than ISO 8859-1 or UTF-8 is useful for man-pages
            that aren't shipped in UTF-8.

            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=519209
            and for some other background (responded to by Colin Watson
            in the above report):
            http://thread.gmane.org/gmane.comp.internationalization.linux/6040
            ("man page encoding", 5 Jul 2005)


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

fallocate.2
    Michael Kerrisk
        VERSIONS: glibc support is provided since version 2.10

fcntl.2
    Michael Kerrisk
        Remove mention of EWOULDBLOCK from discussion of mandatory locking
            In the kernel, the error on encountering a mandatory lock is
            EAGAIN.  Although EAGAIN and EWOULDBLOCK are the same on
            most Linux architectures, on some they are not, so don't
            mention EWOULDBLOCK as it is misleading.  (Mea culpa.)

getcontext.2
    Michael Kerrisk
        Note that POSIX.1-2008 removes the specification of getcontext()

getitimer.2
    Michael Kerrisk
        Note that POSIX.1-2008 recommends POSIX timers API instead of this API

gettimeofday.2
    Michael Kerrisk
        Note that POSIX.1-2008 recommends clock_gettime() instead of this API

ptrace.2
    Michael Kerrisk
        Note use of 'data' for PTRACE_SYS{CALL,EMU} and PTRACE_*_SINGLESTEP
            These operations use the 'data' argument as a signal number,
            like PTRACE_CONT.

ptrace.2
    Mike Frysinger
        only reference <sys/user.h>
            The kernel no longer installs linux/user.h, so update
            references to sys/user.h.

recv.2
    Michael Kerrisk
        Add 'iovec' defn to defn of 'msghdr' structure
            The 'msghdr' structure includes a field of type 'iovec',
            so show the definition of that structure in this page.

rename.2
    Michael Kerrisk
        Make ENOENT description consistent with POSIX.1-2008

timerfd_create.2
    Michael Kerrisk
        ERRORS: add EINVAL for invalid 'flags' for timer_settime()

truncate.2
    Michael Kerrisk
        SYNOPSIS: Fix description of feature test macro requirements
            After a report by Arvid Norlander.

bcopy.3
    Michael Kerrisk
        Note that POSIX.1-2008 removes specification of bcopy()

bsd_signal.3
    Michael Kerrisk
        Note that POSIX.1-2008 recommends sigaction(2) instead of this API

ctime.3
    Michael Kerrisk
        Note that POSIX.1-2008 recommends strftime(3) instead of these functions

ecvt.3
    Michael Kerrisk
        Note that POSIX.1-2008 recommends sprintf(3) instead of these functions

gcvt.3
    Michael Kerrisk
        Note that POSIX.1-2008 recommends sprintf(3) instead of this function

getcwd.3
    Michael Kerrisk
        Note that getcwd() should be used instead of the obsolete getwd()

getgrent.3
    Michael Kerrisk
        Returned buffer may be statically allocated and overwritten by
        later calls

gethostbyname.3
    Michael Kerrisk
        POSIX.1-2008 recommends getaddrinfo(3) and getnameinfo(3) instead

getnetent_r.3
    Michael Kerrisk
        Fix function name in text: s/getnetbynumber_r/getnetbyaddr_r/
            The SYNOPSIS showed the right function name (getnetbyaddr_r),
            but the text repeatedly used the wrong name (getnetbynumber_r).
            Probably, this was a cut-and-paste error.

getpwent.3
    Michael Kerrisk
        Returned buffer may be statically allocated and overwritten by
        later calls

index.3
    Michael Kerrisk
        Note that POSIX.1-2008 recommends strchr(3) and strrchr(3) instead

isalpha.3
    Michael Kerrisk
        Explain why POSIX.1-2008 marks isascii(3) obsolete

lockf.3
    Nikanth Karthikesan
        Update pointer to documentation in kernel source

makecontext.3
    Michael Kerrisk
        Note that POSIX.1-2008 recommends the use of POSIX threads instead

mq_notify.3
    Michael Kerrisk
        Document the POSIX.1-2008 optional EINVAL error
            POSIX.1-2008 allows an optional EINVAL error if
            notification==NULL and the caller is not currently
            registered to receive notifications.

posix_fallocate.3
    Michael Kerrisk
        Clarify that EINVAL also occurs of 'len' *equals* zero
            See http://bugzilla.kernel.org/show_bug.cgi?id=12919

posix_fallocate.3
    Michael Kerrisk
        Document POSIX.1-2001 and POSIX.1-2008 specifications for EINVAL error
            See http://bugzilla.kernel.org/show_bug.cgi?id=12919

posix_memalign.3
    Michael Kerrisk
        Document handling of size==0 case for posix_memalign()

pthread_exit.3
    Michael Kerrisk
        Fix error in DESCRIPTION: s/pthread_create/pthread_exit/

realpath.3
    Michael Kerrisk
        Rework resolved_path==NULL discussion w.r.t. POSIX.1-200[18]
            Although the page already mentioned the resolved_path==NULL
            feature, and that this feature was added in POSIX.1-2008, there
            was still some crufty text in BUGS that hadn't been updated to
            reflect the POSIX.1-2008 changes.

            Also, some other minor wording and grammar fixes.

scalb.3
    Michael Kerrisk
        Note that POSIX.1-2008 recommends scalbln*(3) instead

seekdir.3
    Michael Kerrisk
        SYNOPSIS: Fix type of 'offset' argument: s/off_t/long/
            And add a NOTES section pointing out that 'off_t'
            was indeed used in glibc 2.1.1 and earlier.
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=519230

sem_post.3
    Michael Kerrisk
        Document EOVERFLOW error

shm_open.3
    Michael Kerrisk
        Recast discussion on name length to exclude terminating NULL byte
            Probably it's clearer to describe the length of the IPC object
            name as a count that excludes the null terminator.

siginterrupt.3
    Michael Kerrisk
        Note that POSIX.1-2008 recommends sigaction() instead

sigset.3
    Michael Kerrisk
        Note APIs that POSIX.1-2008 recommends instead of these obsolete APIs

strftime.3
    Michael Kerrisk
        Small fix to description of %G
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=516677

strftime.3
    Michael Kerrisk
        Add details on ISO 8601 week-based dates
            ISO 8602 week-based dates are relevant for %G, %g, and %V,
            and the existing details on these dates are a little thin.

strftime.3
    Michael Kerrisk
        Remove mention of year from ISO 8601 standard
            The text mentioned the 1988 8601 standard, but there have
            already been two revisions of the standard since then, so
            simply remove mention of the year.

telldir.3
    Michael Kerrisk
        SYNOPSIS: Fix return type: s/off_t/long/
            And add a NOTES section pointing out that 'off_t'
            was indeed used in glibc 2.1.1 and earlier.
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=519230

timeradd.3
    Michael Kerrisk
        Note that on some systems, <=, >=, == don't work for timercmp()

timeradd.3
    Michael Kerrisk
        SYNOPSIS: Fix return types of timerisset() and timercmp()

toascii.3
    Michael Kerrisk
        Note why POSIX.1-2008 marks this function obsolete

console_ioctl.4
    Alan Curry
        Fix 'argp' type for KDGETLED description
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=517485

group.5
    Michael Kerrisk
        Various minor rewordings and improvements

resolv.conf.5
    Michael Kerrisk
        Document 'ip6-bytestring' option

resolv.conf.5
    Michael Kerrisk
        Document 'edns0' option

resolv.conf.5
    Michael Kerrisk
        Document 'ip6-dotint' / 'no-ip6-dotint' option

resolv.conf.5
    Michael Kerrisk
        Note that maximum value of 'ndots' option is capped to 15

resolv.conf.5
    Michael Kerrisk
        Note that maximum value of 'timeout' option is capped to 30

hier.7
    Michael Kerrisk
        Add description of /srv
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=520904

ip.7
    Michael Kerrisk
        Fix type used to declare sin6_port
            The page should use the type specified by POSIX,
            rather than the (equivalent) type used in the kernel

ipv6.7
    Teddy Hogeborn
        Fix types used to declare sin6_family and sin6_port
            The page should use the types specified by POSIX,
            rather than the (equivalent) types used in the kernel.

            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=517074

mq_overview.7
    Michael Kerrisk
        Recast discussion on name length to exclude terminating NULL byte
            Probably it's clearer to describe the length of the IPC object
            name as a count that excludes the null terminator.

rtld-audit.7
    Michael Kerrisk
        Note that multiple libraries in LD_AUDIT doesn't work
            This is reportedly fixed in glibc 2.10.
            See http://sourceware.org/bugzilla/show_bug.cgi?id=9733

sem_overview.7
    Michael Kerrisk
        Fix discussion of length of semaphore names
            Because of the "sem." prefix added by glibc to a semaphore
            name, the limit on the length of the name (excluding the
            terminating null byte) is 251 characters.