path: root/Changes

==================== Changes in man-pages-3.14 ====================

Released: ????-??-??, Bucaramanga


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

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

Andreas Henriksson <andreas@fatal.se>
Bert Wesarg <bert.wesarg@googlemail.com>
Cedric Le Goater <clg@fr.ibm.com>
Chris Heath <chris@heathens.co.nz>
Eric Biederman <ebiederm@xmission.com>
Eugen Dedu <Eugen.Dedu@pu-pm.univ-fcomte.fr>
Ivana Varekova <varekova@redhat.com>
Jen Axboe <jens.axboe@oracle.com>
Jens Axboe <jens.axboe@oracle.com>
Loïc Domaigne <tech@domaigne.com>
Masanari Iida <masanari.iida@hp.com>
Paul Evans <leonerd@leonerd.org.uk>
Pavel Emelyanov <xemul@openvz.org>
Pierre-Paul Paquin <pierrepaulpaquin@gmail.com>
Serge E. Hallyn <serge@hallyn.com>
Stefano Teso <teso@disi.unitn.it>
Stew Benedict <stewb@linux-foundation.org>
Vegard Nossum <vegard.nossum@gmail.com>

Apologies if I missed anyone!


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

CPU_SET.3
    Michael Kerrisk
        New page documenting CPU_* macros
            This page contains material moved out of sched_setscheduler(2).
            It overwrites a previously existing link file with the same name.
    Michael Kerrisk
        Add description of macros for dynamically allocated CPU sets
            Add descriptions of CPU_ALLOC(), CPU_ALLOC_SIZE(), CPU_FREE(),
            CPU_SET_S(), CPU_CLR_S(), CPU_ISSET_S(), CPU_ZERO_S(),
            CPU_COUNT_S(), CPU_AND_S(), CPU_OR_S(), CPU_XOR_S(), and
            CPU_EQUAL_S().
    Michael Kerrisk
        Add documentation of CPU_COUNT()
    Michael Kerrisk
        Add description of CPU_AND(), CPU_OR, CPU_XOR(), and CPU_EQUAL()
            Plus a few other small clean-ups of the text
    Michael Kerrisk
        Various improvements in DESCRIPTION
            After review comments by Bert Wesarg:
            * Explain that cpu_set_t is a bitset, but should be considered
              opaque.
            * A CPU set can be duplicated with memset().
            * Size of a CPU set is rounded up to size of long.
            * CPU_SETSIZE is in bits, but the setsize argument is in bytes.
    Michael Kerrisk
        Document CPU_ALLOC()/CPU_ALLOC_SIZE() bug
            These macros return twice what they should because of thinko
            in glibc 2.8 and earlier.  The bug is fixed for glibc 2.9.
            http://sourceware.org/bugzilla/show_bug.cgi?id=7029
    Michael Kerrisk
        NOTES: Discuss use of types in "prototypes" for these macros
            The SYNOPSIS shows types for arguments and return values, but
            these are really just suggestions: since the interfaces are
            macros, the compiler won't catch all violations of
            the "type rules".  Warn the reader of this.

pthread_attr_setinheritsched.3
    Michael Kerrisk
        New page for pthread_attr_setinheritsched(3) and
        pthread_attr_getinheritsched(3)

pthread_cancel.3
    Michael Kerrisk
        New page for pthread_cancel(3)

pthread_cleanup_push.3
    Michael Kerrisk
        New page for pthread_cleanup_push(3) and pthread_cleanup_pop(3)

pthread_setcancelstate.3
    Michael Kerrisk
        New page for pthread_setcancelstate(3) and pthread_setcanceltype(3)

pthread_testcancel.3
    Michael Kerrisk
        New page for pthread_testcancel(3)


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

clone.2
    Jens Axboe
        Document CLONE_IO (new in Linux 2.6.25)
            Some text also by mtk.
    Michael Kerrisk
        Document CLONE_NEWNET
    Michael Kerrisk
        Document CLONE_NEWUTS (new in Linux 2.6.19)
    Michael Kerrisk
        Document CLONE_NEWIPC flag (new in Linux 2.6.19)
    Michael Kerrisk
        Document CLONE_NEWPID flag (new in Linux 2.6.24)

mmap.2
    Michael Kerrisk
        Document MAP_STACK flag (new in Linux 2.6.27)

arp.7
    Michael Kerrisk
        Document /proc file retrans_time_ms (new in Linux 2.6.12)
    Michael Kerrisk
        Document /proc file base_reachable_time_ms (new in Linux 2.6.12)

icmp.7
    Michael Kerrisk
        Document icmp_ignore_bogus_error_responses (new in Linux 2.2)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document icmp_ratelimit and icmp_ratemask (new in Linux 2.4.10)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document icmp_echo_ignore_broadcasts (new in Linux 2.6.12)
            Text taken from Documentation/networking/ip-sysctl.txt

tcp.7
    Michael Kerrisk
        Document /proc file tcp_slow_start_after_idle (new in Linux 2.6.18)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_base_mss (new in Linux 2.6.17)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_frto_response (new in Linux 2.6.22)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_moderate_rcvbuf (new in Linux 2.4.17/2.6.7)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_congestion_control (new in Linux 2.4.13)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_no_metrics_save (new in Linux 2.6.6)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_mtu_probing (new in Linux 2.6.17)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_dma_copybreak (new in Linux 2.6.24)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_tso_win_divisor (new in Linux 2.6.9)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_allowed_congestion_control (new in Linux 2.4.20)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_workaround_signed_windows (new in Linux 2.6.26)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_available_congestion_control (new in Linux 2.4.20)
            Text taken from Documentation/networking/ip-sysctl.txt
    Michael Kerrisk
        Document /proc file tcp_abc (new in Linux 2.6.15)
            Text taken from Documentation/networking/ip-sysctl.txt

udp.7
    Michael Kerrisk
        Document /proc files udp_mem, udp_rmem_min, and udp_wmem_min
            All of these are new in Linux 2.6.25


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

CPU_ALLOC.3
CPU_ALLOC_SIZE.3
CPU_AND.3
CPU_AND_S.3
CPU_CLR_S.3
CPU_COUNT.3
CPU_COUNT_S.3
CPU_EQUAL.3
CPU_EQUAL_S.3
CPU_FREE.3
CPU_ISSET_S.3
CPU_OR.3
CPU_OR_S.3
CPU_SET_S.3
CPU_XOR.3
CPU_XOR_S.3
CPU_ZERO_S.3
    Michael Kerrisk
        New link to new CPU_SET.3

CPU_CLR.3
CPU_ISSET.3
CPU_ZERO.3
    Michael Kerrisk
        Update links to point to CPU_SET.3
            The documentation of the CPU_* macros migrated to a new
            location: CPU_SET.3.

pthread_attr_getinheritsched.3
    Michael Kerrisk
        New link to new pthread_attr_setinheritsched.3

pthread_cleanup_pop.3
    Michael Kerrisk
        New link to new pthread_cleanup_push.3

pthread_setcanceltype.3
    Michael Kerrisk
        New link to new pthread_setcancelstate.3


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

clone.2
mount.2
unshare.2
proc.5
path_resolution.7
    Michael Kerrisk
        Global fix: s/namespace/mount-point namespace/, as appropriate
            In recent times, a number of other namespace flags have been
            added to clone(2).  As such, it is no longer clear to use
            the generic term "namespace" to refer to the particular
            namespace controlled by CLONE_NEWNS; instead, use the
            term "mount-point namespace".
    Michael Kerrisk
        Global fix: s/mount-point namespace/mount namespace/
            This is more consistent with the term "mounts namespace"
            used in the 2008 ACM SIGOPS paper, "Virtual servers
            and and checkpoint/restart in mainstream Linux".
            (I avoided the "s", because using the plural strikes me
            as klunky English, and anyway we don't talk about
            the "PIDs namespace" or the "networks namespace", etc..)

connect.2
listen.2
send.2
uname.2
cmsg.3
proc.5
arp.7
ddp.7
icmp.7
ip.7
raw.7
socket.7
tcp.7
udp.7
    Michael Kerrisk
        Global fix: eliminate mention of the obsolete sysctl(2) interface
            Many pages still mention use of the obsolete sysctl(2) system
            call, or used the term "sysctls"; rewrite these mentions to
            instead be in terms of /proc interfaces.

fcntl.2
signal.2
mbsnrtowcs.3
mbsrtowcs.3
mbtowc.3
wcrtomb.3
wcsnrtombs.3
wcsrtombs.3
wctomb.3
    Michael Kerrisk
        Global fix: s/multi-thread/multithread/

getdents.2
pthread_attr_init.3
pthread_create.3
pthread_getattr_np.3
pthread_setaffinity_np.3
pthread_setschedparam.3
pthread_tryjoin_np.3
    Michael Kerrisk
        Use consistent error-handling function names
            Many older pages use a handle_error() macro to do simple
            error handling from system and library function calls.
            Switch these pages to do similar.


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

time.1
    Michael Kerrisk
        Note that some shells have a 'time' built-in command
            Therefore, to access the functionality described on this page,
            it may be necessary to specify the full pathname.

clone.2
    Michael Kerrisk
        Place list of CLONE_* flags in alphabetical order
            (No content changes.)
fsync.2
    Michael Kerrisk
        Update feature test macro requirements for fsync()
            Since glibc 2.8, the fsync() declaration is also exposed if
            _POSIX_C_SOURCE >= 200112L

sched_setaffinity.2
    Michael Kerrisk
        Add note on system-imposed restrictions on CPUs actually used
            After Loic Domaigne's suggestion for pthread_setaffinity_np(3), add
            similar text to this page noting that the system silently
            limits the set of CPUs on which the process actually runs to
            the set of CPUs physically present and the limits imposed by
            cpuset(7).

sched_setaffinity.2
    Michael Kerrisk
        Removed discussion of CPU_* macros()
            These macros are now moving to a separate page.
    Michael Kerrisk
        Refer reader to pthread_setaffinity_np(3)
            pthread_setaffinity_np() is preferable for setting
            thread CPU affinity if using the POSIX threads API.

sysctl.2
    Michael Kerrisk
        Add prominent warning against using this system call
            This was already stated under NOTES, but make it even more
            prominent by adding a sentence at the start of the DESCRIPTION.

uname.2
    Michael Kerrisk
        Add C comments describing fields in utsname structure

atan2.3
    Stefano Teso
        Fix description of range of function value return
            The range is not [-pi/2, pi/2], but [-pi, pi].

            (mtk: This error was reported by Nicolas Francois, and
            should have been fixed in 3.11, but somewhere along the way,
            the fix got lost.)

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

bindresvport.3
    Michael Kerrisk
        Since glibc 2.8, EPFNOSUPPORT error is now EAFNOSUPPORT
            Glibc switched to using a POSIX-specified error code for
            this error case.

            http://bugs.linuxbase.org/show_bug.cgi?id=2375

clock_getres.3
    Michael Kerrisk
        CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID not settable
            According to POSIX.1-2001, the CLOCK_PROCESS_CPUTIME_ID and
            CLOCK_THREAD_CPUTIME_ID clocks should be settable, but
            currently they are not.

getgrnam.3
    Michael Kerrisk
        Clarify and add more detail in RETURN VALUE description
            The page was a bit fuzzy in describing the return values for
            various cases.  In particular, it needed to be more explicit
            in describing what happens for the "not found" case.

            This is an analogous change to the change for
            getpwnam.3, made after Andreas Henriksson's report.
            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504787
    Michael Kerrisk
        Rename arguments to getgrnam_r() and getgrgid_r()
            s/gbuf/grp/ and s/gbufp/result/, for consistency
            with POSIX.1 argument names.
    Michael Kerrisk
        Clarify RETURN VALUE description
            The page was a bit fuzzy in describing the return values for
            various cases.  In particular, it needed to be more explicit
            in describing what happens for the "not found" case.

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

getpwnam.3
    Michael Kerrisk
        Rename arguments to getpwnam_r() and getpwuid_r()
            s/pwbuf/pwd/ and s/pwbufp/result/, for consistency
            with POSIX.1 argument names.
    Michael Kerrisk
        Clarify and add more detail in RETURN VALUE description
            The page was a bit fuzzy in describing the return values for
            various cases.  In particular, it needed to be more explicit
            in describing what happens for the "not found" case.

            http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504787
    Michael Kerrisk
        Add an EXAMPLE program for getpwnam_r()

inet_ntop.3
    Michael Kerrisk
        Rename 'cnt' argument to 'size'
            This is consistent with POSIX.1, and also a more sensible name.
    Michael Kerrisk
        Rework text describing 'size' argument
            (After a suggestion by Vegard Nossum.)
            Also made a few other small rewordings to in the initial
            paragraph.

makecontext.3
    Michael Kerrisk
        Add text on use of pointer arguments to makecontext()
            Passing pointer arguments to makecontext() is possible,
            but only on some architectures, and with no guarantees
            of portability.

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

pthread_attr_setaffinity_np.3
    Michael Kerrisk
        Various fixes after review by Loic Domaigne
            Reviewed-by: Loic Domaigne <tech@domaigne.com>

pthread_attr_setaffinity_np.3
pthread_setaffinity_np.3
    Michael Kerrisk
        Update to reflect new location of CPU_*() documentation
            The CPU_*() macros are now documented in CPU_SET.3;
            update to reflect that fact.
    Michael Kerrisk
        Remove redundant text relating to CPU sets
            Information about CPU_SETSIZE can be found in CPU_SET.3, so
            remove discussion of it here.

pthread_attr_setschedparam.3
pthread_setschedparam.3
    Michael Kerrisk
        Remove text saying that only sched_priority is required by POSIX.1
            Loic Domaigne points out that if a system implements
            SCHED_SPORADIC (which Linux does not), then other
            fields are also specified in sched_param.  The simple
            solution is just to remove that phrase from the man
            page.

pthread_cancel.3
pthread_detach.3
pthread_join.3
pthread_setaffinity_np.3
    Michael Kerrisk
        Make text of ESRCH error consistent

pthread_setaffinity_np.3
    Michael Kerrisk
        Add text to EINVAL error mentioning cpuset(7)
    Michael Kerrisk
        Various improvements after review by Loïc Domaigne
            Various fix-ups after Loïc's review.

            Reviewed-by: Loïc Domaigne <tech@domaigne.com>

pthread_setschedparam.3
    Michael Kerrisk
        PTHREAD_INHERIT_SCHED is default for inherit scheduler attribute
            In EXAMPLE, note that PTHREAD_INHERIT_SCHED is the default for
            the inherit scheduler attribute attribute.

syslog.3
    Masanari Iida
        LOG_KERN messages can't be generated from user processes
            Masanari notes that this is an FAQ for logger(1) and that
            Solaris and FreeBSD document this point in syslog(3).
            The glibc info page also hides this comment in its source:

                Internally, there is also LOG_KERN, but LOG_KERN == 0,
                which means if you try to use it here, just selects default.

proc.5
    Ivana Varekova
        Fix reference to kernel source file
            Use relative reference to Documentation/mtrr.txt.

arp.7
    Michael Kerrisk
        Add kernel version numbers for /proc interfaces

cpuset.7
    Michael Kerrisk
        SEE ALSO: add CPU_SET(3)

epoll.7
    Michael Kerrisk
        Note glibc version that added epoll support

icmp.7
    Michael Kerrisk
        Add kernel version numbers to /proc file descriptions

inotify.7
    Vegard Nossum
        Fix description of max_user_watches
            It seems that inotify(7) is wrong here:

            "/proc/sys/fs/inotify/max_user_watches
                This specifies a limit on the number of watches that can be
                associated with each inotify instance."

            On my system, the default value for this variable is 8192. But I
            cannot create more than 8192 watches in total for the same UID
            even when they are on different inotify instances. So I suggest
            to rephrase this as: "This specifies an upper limit on the
            number of watches that can be created per real user ID."

ip.7
    Michael Kerrisk
        Reorder socket options alphabetically
    Michael Kerrisk
        Added kernel version numbers for IP_* socket options
    Michael Kerrisk
        Relocate kernel version information for IP_PMTUDISC_PROBE
    Michael Kerrisk
        Add kernel version numbers for /proc/sys/net/ipv4/ip_* files
    Michael Kerrisk
        Remove mention of kernel header from description of IP_RECVERR
            Looks like glibc has had this definition since about version 2.1.
    Michael Kerrisk
        Relocate kernel version information for ip_mreqn structure
    Michael Kerrisk
        Relocate info about Linux-specific sockopts to NOTES
            Also add some source comments about non-standard Linux-specific
            options that are not yet documented.

netlink.7
    Vegard Nossum
        Fix incorrect variable names in example code
            s/snl/sa/ * 2

pthreads.7
    Michael Kerrisk
        Add section on cancellation points
            This section includes a list of the functions that must and
            may be cancellation points.
    Michael Kerrisk
        Rework, and fix small error in, thread-safe function list
            Integrate the changes that occurred in POSIX.1-2008 into the
            main list (to be consistent with the list, elsewhere on this
            page, of functions that are cancellation points).

            Also, fix an error that said that strerror() was added to
            the list in POSIX.1-2008.  It was strsignal() that was
            added.  (strerror() was already in the list in POSIX.1-2001.)
    Michael Kerrisk
        Tweak text on sigpause() cancellation point
            In POSIX.1-2009, this function moves from the "must be"
            to the "may be" list.
    Michael Kerrisk
        Add ref to signal(7) for further info on use of real-time signals
            signal(7) provides some further details on the use of real-time
            signals by the two Linux threading implementations.
    Michael Kerrisk
        SEE ALSO: add pthread_attr_init() and pthread_cancel()

tcp.7
    Michael Kerrisk
        Update description of tcp_rmem defaults for Linux 2.6
    Michael Kerrisk
        Add kernel version numbers for TCP_* socket options
            Note kernel version were each socket option first appeared.
    Michael Kerrisk
        The tcp_bic* proc files disappeared in Linux 2.6.13
    Michael Kerrisk
        tcp_vegas_cong_avoid disappeared in Linux 2.6.13
    Michael Kerrisk
        Add mention of RFC 4138 for 'tcp_frto' /proc file
    Michael Kerrisk
        Remove mention of /proc in VERSIONS
            This information is not indicated for each /proc interface
    Michael Kerrisk
        Clarify that tcp_mem measures in units of the system page size
    Michael Kerrisk
        Update tcp_frto description for 2.6.22 changes
            Linux 2.6.22 added a mode value 2 ("Enable SACK-enhanced
            F-RTO if flow uses SACK").
    Michael Kerrisk
        Fix alphabetical order in /proc file list
            A few entries were slightly out of order.
    Michael Kerrisk
        Remove obsolete statement about /proc from VERSIONS
            Much of the text has been updated to 2.6.27 or so,
            so this statement no longer applies.
    Michael Kerrisk
        Add kernel version numbers for each /proc interface
            Note kernel version where each /proc interface first appeared
    Michael Kerrisk
        tcp_westwood /proc file disappeared in Linux 2.6.13
    Michael Kerrisk
        Update description of tcp_wmem defaults for Linux 2.6