man-pages/Changes

==================== Changes in man-pages-2.80 ====================

Released: 2008-05-08


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

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

Aurelien Gerome <ag@roxor.cx>
Alain Portal <aportal@univ-montp2.fr>
Andries E. Brouwer <Andries.Brouwer@cwi.nl>
Daniel Burr <dburr@topcon.com>
Felix Kater <fkater@googlemail.com>
Folkert van Heusden <folkert@vanheusden.com>
Heikki Orsila <shd@modeemi.fi>
Ingo Molnar <mingo@elte.hu>
Justin Pryzby <justinpryzby@users.sourceforge.net>
Karsten Weiss <K.Weiss@science-computing.de>
Martin Pitt <mpitt@debian.org>
Marty Leisner <leisner@rochester.rr.com>
Nicolas Fran<61>ois <nicolas.francois@trialog.com>
Nick Piggin <npiggin@suse.de>
Petter Reinholdtsen <pere@hungry.com>
Reuben Thomas <rrt@sc3d.org>
Theodoros V. Kalamatianos <thkala@softlab.ece.ntua.gr>
Thomas Huriaux <thomas.huriaux@gmail.com>
Tim Stoakes <tim@stoakes.net>
Timothy Baldwin <T.E.Baldwin99@members.leeds.ac.uk>
Tolga Dalman <tdalman@project-psi.org>

Apologies if I missed anyone!


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

bdflush.2
inotify_add_watch.2
mprotect.2
sigprocmask.2
ctime.3
getusershell.3
setbuf.3
st.4
ip.7
packet.7
    mtk
        Replace "(il)legal" by "(not) permitted" or "(in)valid".

read.2
utime.2
filesystems.5
packet.7
    mtk
        s/time stamp/timestamp/, for consistency with majority use
        in other pages, and in POSIX.1.

madvise.2
mbind.2
mincore.2
mmap.2
mmap2.2
msync.2
remap_file_pages.2
    mtk
        Change name of 'start' argument to 'addr' for consistency
        with:
            * other memory related interfaces
            * POSIX specification (for those interfaces in POSIX)
            * Linux and glibc source code (in at least some cases)

Various pages
    mtk
        s/filesystem/file system/, for consistency with majority use
        in other pages, and in POSIX.1.

Various pages
    mtk
        s/zeroes/zeros/, for consistency with majority use
        in other pages, and in POSIX.1.

abs.3
proc.5
    mtk
        s/builtin/built-in/, for consistency with majority use
        in other pages, and in POSIX.1.

mknod.2
ftw.3
    mtk
        s/normal file/regular file/

Various pages
    mtk
        s/nonempty/non-empty/

Various pages
    mtk
        s/nonzero/non-zero/

Various pages
    mtk
        s/realtime/real-time/, for consistency with majority usage.

Various pages
    mtk
        s/command line/command-line/ when used attributively.

Various pages
    mtk
        Use "run time" when non-attributive, "run-time" when attributive.

Various pages
    mtk
        Various pages that I wrote carried a slightly modified version
        of the "verbatim" license.  In the interests of minimizing
        lincense proliferation, I've reverted the modified form
        so that the license is exactly the same as on other pages
        carrying the verbatim license.

epoll_ctl.2
getitimer.2
getrlimit.2
unix.7
    mtk
        s/since kernel x.y.z/since Linux x.y.z/

wait.2
inotify.7
    mtk
        Reformat kernel version information for flags.

Typographical or grammatical errors have been corrected in several places.
(Special thanks to Nicolas Fran<61>ois.)


New pages
---------

random_r.3
    mtk, after a suggestion by aeb
        Documents random_r(3), srandom_r(3), initstate_r(2), and
        setstate_r(3), which are the reentrant equivalents of
        random(3), srandom(3), initstate(3), and setstate(3).


New links
---------

lutimes.3
    mtk
        Link to futimes.3.

initstate_r.3
setstate_r.3
srandom_r.3
    mtk
        Links to random_r.3.

daylight.3
timezone.3
tzname.3
    mtk
        Links to tzset.3.

isnanf.3
isnanl.3
    mtk
        Links to finite.3.

encrypt_r.3
setkey_r.3
    mtk
        Links to encrypt.3.


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

clone.2
    mtk
        Added note that CLONE_STOPPED (which no-one ever used anyway) is
        now deprecated.

epoll_ctl.2
    mtk
        Added portability note to BUGS text for EPOLL_CTL_DEL.

epoll_wait.2
    mtk
        If the 'sigmask' is NULL, then epoll_pwait() is equivalent
        to epoll_wait().

fork.2
    mtk
        NOTES: since glibc 2.3.3, the glibc NPTL fork() wrapper
        bypasses the fork() system call to invoke clone() with
        flags providing equivalent functionality.

getgroups.2
    Petter Reinholdtsen
        SEE ALSO: Add getgrouplist(3).
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=479284.

getpriority.2
    mtk, after a note from Ingo Molnar
        Add text in NOTES about the punchier effect of nice values in
        kernel 2.6.23 and later.
        Add Documentation/scheduler/sched-nice-design.txt to SEE ALSO list.

gettid.2
    mtk
        Added VERSIONS section noting that this system call first
        appeared in 2.4.11.

kill.2
    Marty Leisner / mtk
        Add text explicitly noting that sig==0 can be used to check for
        the existence of a PID or PGID.
    mtk
        A few minor rewordings.

mbind.2
    mtk
        The location of the numactl package has changed.

mmap.2
    mtk
        Added some .SS headings to make structure of page a little
        more obvious.
    mtk, with input from Nick Piggin
        MAP_POPULATE supports both file and anonymous mappings.
        Since 2.6.23, MAP_POPULATE supports private mappings.
        Since 2.6.23, MAP_NONBLOCK causes MAP_POPULATE to be a no-op.

mount.2
    mtk
        The MS_REMOUNT changes in 2.4 were at 2.4.10 (not 2.4).
    mtk
        Minor wording change.

msgop.2
    mtk
        Various minor rewordings and restructurings for clarity.
    mtk, after a note from Reuben Thomas
        Remove "msgop" from NAME section.

open.2
    mtk
        Note that O_CLOEXEC should be in the next POSIX.1 revision.

poll.2
    mtk
        If the 'sigmask' is NULL, then ppoll() is equivalent to poll()
        with respect to signal mask manipulations.

posix_fadvise.2
    mtk
        s/posix_madvise (2)/posix_madvise (3)/;
        (The page referred-to page still doesn't exit yet, but hopefully
        will do sometime soon.)

recv.2
    Felix Kater / mtk
        Improve wording for EAGAIN error in discussion of MSG_DONTWAIT.

rmdir.2
    Martin Pitt
        POSIX.1 also allows EEXIST for the ENOTEMPTY error condition.
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=467552.
        
utime.2
    Reuben Thomas
        Remove unnecessary subheading for utimes().
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=477402.

sched_setscheduler.2
    mtk, with input from Ingo Molnar
        Add description of SCHED_IDLE policy (new in 2.6.23).
        Tweak description of SCHED_BATCH.
        Minor rewordings.

select_tut.2
    Justin Pryzby
        Various wording clean-ps.

semop.2
    Aurelien Gerome
        Small fix in example code.

setpgid.2
    mtk / Karsten Weiss
        Clarify description of setpgid() a little.

shmop.2
    mtk, after a note from Reuben Thomas
        Remove "shmop" from NAME section.

signalfd.2
    mtk
        Added BUGS text noting that before kernel 2.6.25, the ssi_int
        and ssi_ptr fields are not set.
        Added comments describing fields in signalfd_siginfo structure.
        Update field names in example program (s/signo/ssi_signo/).
        Various small fixes, and remove duplicated sentence.
        Minor edits to structure definition.

sigqueue.2
    mtk
        Added some comments to code in NOTES.

stat.2
    mtk
        Minor wording change.

syscalls.2
    mtk
        This page is now up to date as at kernel 2.6.25.

syslog.2
    mtk
        Small tidy up of language relating to permissions/capabilities.

timerfd_create.2
    mtk
        Minor change to example program.
        Minor wording change.

utime.2
    mtk
        Change description in NAME line ("or" is not correct: these calls
        always change *both* timestamps).
        CONFORMING TO: utimes() is in POSIX.1-2001.

wait.2
    mtk, after a note by Justin Pryzby
        Add a sentence clarifying that even though the default disposition
        of SIGCHLD is "ignore", explicitly setting the disposition to
        SIG_IGN results in different treatment of zombies.

aio_cancel.3
aio_error.3
aio_fsync.3
aio_read.3
aio_return.3
aio_suspend.3
aio_write.3
    Kevin O'Gorman <kogorman@csc.calpoly.edu>
        Add "Link with -lrt" to SYNOPSIS.

backtrace.3
    Nicolas Fran<61>ois
        s/backtrace_symbols/backtrace-symbols_fd/ in one sentence.
    mtk
        Fix bogus reference to variable 'strings': should be:
	"the array of pointers".

ctime.3
    mtk
        Add warning under NOTES that asctime(), ctime(), gmtime(), and
        localtime() may each overwrite the static object returned by any
        of the other calls.
        Other minor edits.

dlopen.3
    mtk
        Add more detail to the description of the fields in the
        structure returned by dladdr().

fexecve.3
    mtk
        Clean up SYNOPSIS after work by cut-and-paste-Pete:
        the necessary header file is <unistd.h> not <sys/time.h>!

futimes.3
    mtk
        Add documentation of lutimes(), which appeared in glibc 2.6.
    mtk
        Change description in NAME line ("or" is not correct: these calls
        always change *both* timestamps).
        CONFORMING TO: futimes() did not come from 4.2BSD.  (It came from
        FreeBSD; see the FreeBSD man page.)

getenv.3
    mtk
        Noted that caller must not modify returned value string.
        Noted that getenv() is not reentrant: the buffer may be statically
        allocated and overwritten by later calls to getenv(), putenv(),
        setenv(), or unsetenv().
        Other minor rewrites.

getgrent.3
    Petter Reinholdtsen
        SEE ALSO: Add getgrouplist(3).
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=479284.

gethostbyname.3
    mtk
        Add 'h_errno' to NAME list.

getopt.3
    mtk
        Add 'optarg', 'optind', 'opterr', and 'optopt' to NAME section.
        Add subheading for getopt_long() and getopt_long_only()
        description.

getpt.3
    mtk
        Point out that this function should be avoided in favour of
        posix_openpt().

getsubopt.3
    Daniel Burr
        SYNOPSIS: Fix declaration of valuep.
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=476672.

malloc.3
    mtk
        RETURN VALUE: Note circumstances in which successful malloc() and
        calloc() can return NULL.

mq_open.3
    mtk, after a note by Marty Leisner
        Note that <fcntl.h> is needed for O_* constants and <sys/stat.h>
        is needed for 'mode' constants.

opendir.3
    mtk
        Describe treatment of close-on-exec flag by opendir() and
        fdopendir().

openpty.3
    mtk
        SEE ALSO: add ttyname(3).

raise.3
    mtk / Timothy Baldwin
        Clarify semantics of raise() when called from a multithreaded
        program.
        as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=476484.
    mtk
        Rewrites and additions to various parts of the page.

rand.3
    Tolga Dalman / aeb / mtk
        Remove outdated warning in NOTES; encourage the use of
        random(3) instead.
    Folkert van Heusden
        Clarify wording describing range of values returned by rand().

random.3
    aeb / mtk / Tolga Dalman
        Recommend use or random_r(3) for multithreaded applications
        that need independent, reproducible sequences of random numbers.

        Move references to "The Art of Computer Programming" and
        "Numerical Recipes", formerly in rand(3), to this page.

        Add drand48(93) to SEE ALSO list.

regex.3
    Heikki Orsila
        Clarify description of 'rm_eo' field.

sem_post.3
    mtk
        Added pointer to example in sem_wait(3).

sem_open.3
    mtk, after a note by Marty Leisner
        Note that <fcntl.h> is needed for O_* constants and <sys/stat.h> is
        needed for 'mode' constants.

sem_close.3
sem_destroy.3
sem_getvalue.3
sem_init.3
sem_open.3
sem_post.3
sem_unlink.3
sem_wait.3
    mtk, after a note from Marty Leisner
        Add text to SYNOPSIS noting the need to link with "-lrt" or
        "-pthread".

setenv.3
    mtk
        setenv() copies 'name' and 'value' (contrast with putenv()).
        unsetenv() of a nonexistent variable does nothing and is
        considered successful.
        Noted that setenv() and unsetenv() need not be reentrant.

shm_open.3
    mtk, after a note by Marty Leisner
        Note that <fcntl.h> is needed for O_* constants and <sys/stat.h> is
        needed for 'mode' constants.

undocumented.3
    mtk
        initstate_r(3), setkey_r(3), setstate_r(3) are now documented.

utmp.5
    Nicolas Fran<61>ois
        Small rewording.

resolv.conf.5
    Nicolas Fran<61>ois
        gethostname is in Section 2, not section 3.

charsets.7
    Nicolas Fran<61>ois
        s/unicode.com/unicode.org/

credentials.7
    mtk
        NOTES: Pthreads requires that all threads share the same UIDs and
        GIDs.  But the Linux kernel maintains separate UIDs and GIDs for
        every thread.  NPTL does some work to ensure that credential
        changes by any thread are carried through to all POSIX threads in
        a process.

inotify.7
    mtk
        Document SIGIO feature (new in 2.6.25) for inotify file descriptors.
    mtk
        Note that select()/poll()/epoll_wait() indicate a ready inotify
        file descriptor as readable.
    mtk
        Document IN_ATTRIB in a little more detail.

pthreads.7
    Justin Pryzby
        Grammar fix, plus fix typo in script.
    mtk
        Add list of thread-safe functions.

standards.7
    mtk
        Add a section on the upcoming POSIX revision.

ld.so.8
    Justin Pryzby / mtk
        Various wording improvements.