path: root/Changes

==================== Changes in man-pages-3.56 ====================

Released: 2014-01-11, Christchurch

In memory of Doris Church (1939-2013)


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

The following people contributed patches/fixes or (noted in brackets
in the changelog below) reports, notes, and ideas that have been
incorporated in changes in this release:

Andre Majorel <aym-xunil@teaser.fr>
Arif Zaman <arifz@lums.edu.pk>
Bert Wesarg <bert.wesarg@googlemail.com>
Daniel Borkmann <dborkman@redhat.com>
David Malcolm <dmalcolm@redhat.com>
David Prévot <taffit@debian.org>
Dongsheng Song <dongsheng.song@gmail.com>
Elie De Brauwer <eliedebrauwer@gmail.com>
James Smith <james@theta.pw>
Janne Blomqvist <blomqvist.janne@gmail.com>
Joseph S. Myers <joseph@codesourcery.com>
Luke Hutchison <luke.hutch@mit.edu>
Marco Dione <mdione@grulic.org.ar>
Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Mathieu Malaterre <malat@debian.org>
Matthias Klose <doko@debian.org>
Michael Kerrisk <mtk.manpages@gmail.com>
Mike Frysinger <vapier@gentoo.org>
Moritz 'Morty' Strübe <morty@gmx.net>
Nadav Har'El <nyh@math.technion.ac.il>
Ondřej Bílka <neleai@seznam.cz>
Prádraig Brady <P@draigBrady.com>
Peng Haitao <penght@cn.fujitsu.com>
Raphael Geissert <geissert@debian.org>
Shawn Landden <shawn@churchofgit.com>
Simon Paillard <spaillard@debian.org>
Stephen Kell <srk31@srcf.ucam.org>
Sudhanshu Goswami <Sudhanshu.Goswami@emc.com>
Sworddragon2 <sworddragon2@aol.com>
Vince Weaver <vincent.weaver@maine.edu>
Willem de Bruijn <willemb@google.com>
Yuri Kozlov <yuray@komyakino.ru>

Apologies if I missed anyone!


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

fgetc.3
gets.3
    David Malcolm
        Split gets(3) to isolate unsafe gets(3) to a page on its own
            Currently man3/gets.3 documents various safe I/O functions, along
            with the toxic "gets" function.

            At the risk of being melodramatic, this strikes me as akin to
            storing rat poison in a food cabinet, in the same style of
            packaging as the food, but with a post-it note on it saying
            "see warnings below".

            I think such "never use this" functions should be quarantined
            into their own manpages, rather than listing them alongside
            sane functions.

            The attached patch does this for "gets", moving the documentation
            of the good functions from man3/gets.3 into man3/fgetc.3,
            updating the SO links in the relevant functions to point at the
            latter.

            It then rewrites man3/gets.3 to spell out that "gets" is toxic
            and should never be used (with a link to CWE-242 for good
            measure).
    Michael Kerrisk  [Andre Majorel]
        Tweaks to David Malcolm's patch

vdso.7
    Mike Frysinger
        New page documenting the vDSO mapped into each process by the kernel


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

reboot.2
    Elie De Brauwer
        Document LINUX_REBOOT_SW_SUSPEND


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

fgets.3
getc.3
getchar.3
ungetc.3
    Michael Kerrisk
        Adjust links to gets(3) to point to fgetc(3)


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

Various pages
    Michael Kerrisk
        Global fix of "NULL pointer"
            Change "NULL pointer" to "NULL" or null pointer".
            POSIX uses the term "null pointer", not "NULL pointer".

Various pages
    Michael Kerrisk
        Stylistic changes to code example
            For ease of reading, don't embed assignments inside if().

Various pages
    Michael Kerrisk
        Replace uses of "i.e.," in main text with "that is" or similar
            Usual man-pages style is to use "i.e." only within
            parenthetical expressions.

Various pages
    Michael Kerrisk
        Replace uses of "e.g." in main text with "for example" or similar
                Usual man-pages style is to use "e.g." only within
                parenthetical expressions.

Various pages
    Michael Kerrisk
        Add "Program source" subheading under EXAMPLE

Various pages
    Michael Kerrisk
        Add "static" to global variables and functions in example program


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

clock_getres.2
    Michael Kerrisk  [Nadav Har'El]
        Improve description of CLOCK_PROCESS_CPUTIME_ID
            See https://bugzilla.kernel.org/show_bug.cgi?id=67291

close.2
    Michael Kerrisk  [P?draig Brady]
        Note that errors from close() should be used only for diagnosis
            In particular, retrying after EINTR is a bad idea.

            See http://austingroupbugs.net/view.php?id=529

            See http://thread.gmane.org/gmane.comp.lib.glibc.alpha/37702
            Subject: [RFC][BZ #14627] Make linux close errno to EINPROGRESS
                     when interrupted in signal.

execve.2
    Michael Kerrisk  [Marco Dione]
        Add further cases to EFAULT error
            See https://sourceware.org/bugzilla/show_bug.cgi?id=16402

perf_event_open.2
    Vince Weaver  [Sudhanshu Goswami]
        Clarify issues with the disabled bit
            Clarify the perf_event_open behavior with respect to the disabled
            bit and creating event groups.
    Vince Weaver  [Sudhanshu Goswami]
        Clarify issues with the exclusive bit
            Warn that using the perf_event_open "exclusive" bit, while
            it might seem like a good idea, might lead to all 0 results
            in some common usage cases.

reboot.2
    Elie De Brauwer
        Mention RB_POWER_OFF
            The manpage did not mention RB_POWER_OFF which is the glibc
            symbolic name for LINUX_REBOOT_CMD_POWER_OFF.

            $ cd /usr/include
            $ cat x86_64-linux-gnu/sys/reboot.h | grep POWER_OFF
             define RB_POWER_OFF        0x4321fedc
    Elie De Brauwer
        Add "Linux" to kernel version numbers
    Michael Kerrisk
        Add RB_SW_SUSPEND synonym
    Michael Kerrisk
        Add RB_KEXEC synonym

setpgid.2
    Michael Kerrisk  [Joseph S. Myers]
        BSD getpgrp() and setpgrp() go away in glibc 2.19
socket.2
    Michael Kerrisk  [Dongsheng Song]
        Remove crufty statement that AF_INET does not support SOCK_SEQPACKET
            Linux AF_INET supports SOCK_SEQPACKET via SCTP.

syscall.2
    Mike Frysinger
        Fix ia64 registers
            The original list of registers was created by confusing strace
            source code--this is for parsing legacy 32-bit code (which is
            dead and no one cares). Update the list to reflect native ia64
            syscall interface.

syscall.2
syscalls.2
getauxval.3
    Mike Frysinger
        Add references to new vdso(7) page

utimensat.2
    Michael Kerrisk
        Small wording improvement for times!=NULL case

dlopen.3
    Michael Kerrisk  [Mike Frysinger]
        Update remarks on cast needed when assigning dlsym() return value
            POSIX.1-2013 eases life when casting the dlsym() return value to a
            function pointer
    Michael Kerrisk  [Stephen Kell]
        Fix description of dli_sname
            See https://sourceware.org/bugzilla/show_bug.cgi?id=16262

getline.3
    Michael Kerrisk  [Luke Hutchison]
        Correct description of how '*n' is used when '*lineptr' == NULL
            See https://sourceware.org/bugzilla/show_bug.cgi?id=5468
    Michael Kerrisk
        Remove SEE ALSO reference to unsafe gets(3)

mcheck.3
    Simon Paillard  [Raphael Geissert]
        typo in compiler flag
            See http://bugs.debian.org/732464

mkstemp.3
    Michael Kerrisk  [Janne Blomqvist]
        Better describe 'flags' that can be specified for mkostemp()

printf.3
    Michael Kerrisk  [Arif Zaman]
        Fix memory leak in snprintf() example
            See http://stackoverflow.com/questions/19933479/snprintf-man-page-example-memory-leak

pthread_kill.3
    Michael Kerrisk  [Mathieu Desnoyers]
        POSIX.1-2008 removes ESRCH
            POSIX.1-2001 mistakenly documented an ESRCH error, and
            POSIX.1-2008 removes this error. Glibc does return
            this error in cases where it can determine that a thread ID
            is invalid, but equally, the use of an invalid thread ID
            can cause a segmentation fault.

puts.3
    Michael Kerrisk
        SEE ALSO: replace reference to gets(3) with fgets(3)

scanf.3
    Michael Kerrisk  [Ondřej Bílka]
        Improve discussion of obsolete 'a' dynamic allocation modifier

setjmp.3
    Michael Kerrisk  [Joseph S. Myers]
        BSD setjmp() semantics go away in glibc 2.19

sigpause.3
    Michael Kerrisk  [Joseph S. Myers]
        BSD sigpause() goes away in glibc 2.19
    Michael Kerrisk
        Correct feature text macro requirements
    Peng Haitao
        ATTRIBUTES: Note function that is thread-safe
            The function sigpause() is thread safe.

sigqueue.3
    Peng Haitao
        ATTRIBUTES: Note function that is thread-safe
            The function sigqueue() is thread safe.

sigwait.3
    Peng Haitao
        ATTRIBUTES: Note function that is thread-safe
            The function sigwait() is thread safe.

sin.3
    Peng Haitao
        ATTRIBUTES: Note functions that are thread-safe
            The functions sin(), sinf() and sinl() are thread safe.

sincos.3
    Peng Haitao
        ATTRIBUTES: Note functions that are thread-safe
            The functions sincos(), sincosf() and sincosl() are thread safe.

string.3
    Moritz 'Morty' Strübe
        Add short description of the functions
            It is helpful to have a short description about what the different
            functions in string.h do.
    Michael Kerrisk
        Fixes and enhancements to Moritz Strübe's patch

strptime.3
    Michael Kerrisk  [Mathieu Malaterre, Simon Paillard]
        Add number ranges to comments in 'tm' structure
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=729570
    Michael Kerrisk
        Point to ctime(3) for more details on 'tm' structure
    Michael Kerrisk
        Some rewording and reorganization

strsep.3
    Michael Kerrisk
        Clarify description
            The use of "symbols" in the existing description is confusing;
            it's "bytes". Other fixes as well.

strspn.3
    Michael Kerrisk  [Mathieu Malaterre]
        Improve description in NAME
            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=723659

strstr.3
    Michael Kerrisk
        Clarify RETURN VALUE: s/substring/located substring/

sysv_signal.3
    Peng Haitao
        ATTRIBUTES: Note function that is thread-safe
            The function sysv_signal() is thread safe.

tan.3
    Peng Haitao
        ATTRIBUTES: Note functions that are thread-safe
            The functions tan(), tanf() and tanl() are thread safe.

tanh.3
    Peng Haitao
        ATTRIBUTES: Note functions that are thread-safe
            The functions tanh(), tanhf() and tanhl() are thread safe.

toascii.3
    Peng Haitao
        ATTRIBUTES: Note function that is thread-safe
            The function toascii() is thread safe.

toupper.3
    Peng Haitao
        ATTRIBUTES: Note functions that are thread safe with exceptions
            The functions toupper() and tolower() are thread safe with
            exceptions.

towctrans.3
    Peng Haitao
        ATTRIBUTES: Note function that is thread-safe
            The function towctrans() is thread safe.

towlower.3
    Peng Haitao
        ATTRIBUTES: Note function that is thread safe with exceptions
            The function towlower() is thread safe with exceptions.

towupper.3
    Peng Haitao
        ATTRIBUTES: Note function that is thread safe with exceptions
            The function towupper() is thread safe with exceptions.

ualarm.3
    Peng Haitao
        ATTRIBUTES: Note function that is thread-safe
            The function ualarm() is thread safe.

wcpncpy.3
    Peng Haitao
        ATTRIBUTES: Note function that is thread-safe
            The function wcpncpy() is thread safe.

proc.5
    Michael Kerrisk  [Sworddragon2]
        Fix formula for CommitLimit under /proc/meminfo
            See https://bugzilla.kernel.org/show_bug.cgi?id=60991

credentials.7
    Michael Kerrisk
        List APIs that operate on process groups
    Michael Kerrisk
        Add details on controlling terminal and foreground/background jobs

feature_test_macros.7
    Michael Kerrisk
        Document _DEFAULT_SOURCE
    Michael Kerrisk  [Joseph S. Myers]
        From glibc 2.19, _BSD_SOURCE no longer causes __FAVOR_BSD
            Starting with glibc 2.19, _BSD_SOURCE no longer causes BSD
            definitions to be favored in cases where standards conflict.

libc.7
    Mike Frysinger
        SEE ALSO: add various entries

man-pages.7
    Michael Kerrisk  [Mike Frysinger]
        Add STYLE GUIDE section
            Incorporate some of the existing material in the page
            into the STYLE GUIDE, and add a lot more material, mainly
            drawn from the "Global changes" sections in the release
            changelogs.
    Michael Kerrisk
        Add historical note on reason for use of American spelling
    Michael Kerrisk  [Mike Frysinger]
        Various improvements to style guide

packet.7
    Willem de Bruijn  [Daniel Borkmann]
        Document fanout, ring, and auxiliary options
            This patch adds descriptions of the common packet socket options
              PACKET_AUXDATA, PACKET_FANOUT, PACKET_RX_RING, PACKET_STATISTICS,
              PACKET_TX_RING
            and the ring-specific options
              PACKET_LOSS, PACKET_RESERVE, PACKET_TIMESTAMP, PACKET_VERSION
    Michael Kerrisk
        Add kernel version numbers for PACKET_VERSION and PACKET_TIMESTAMP

ld.so.8
    Michael Kerrisk  [Matthias Klose]
        Default output file for D_DEBUG is stderr not stdout
            See https://sourceware.org/bugzilla/show_bug.cgi?id=6874