path: root/Changes

==================== Changes in man-pages-4.01 ====================

Released: 2015-07-23, Munich


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:

Alexei Starovoitov <ast@plumgrid.com>
Andries E. Brouwer <Andries.Brouwer@cwi.nl>
Arjun Shankar <arjun@redhat.com>
Ashish Sangwan <a.sangwan@samsung.com>
Ben Woodard <woodard@redhat.com>
Carlos O'Donell <carlos@redhat.com>
Christoph Thompson <cjsthompson@gmail.com>
Cortland Setlow <cortland.setlow@gmail.com>
Daniel Borkmann <daniel@iogearbox.net>
David Leppik <dleppik@vocalabs.com>
Dilyan Palauzov <dilyan.palauzov@aegee.org>
Doug Klima <cardoe@gentoo.org>
Eric B Munson <emunson@akamai.com>
Florian Weimer <fweimer@redhat.com>
Hack NDo <hackndo@gmail.com>
Jann Horn <jann@thejh.net>
Jens Axboe <axboe@fb.com>
Jian Wen <wenjianhn@gmail.com>
Joerg Roedel <jroedel@suse.de>
Julian Orth <ju.orth@gmail.com>
Kees Cook <keescook@chromium.org>
Laszlo Ersek <lacos@caesar.elte.hu>
Marko Myllynen <myllynen@redhat.com>
Mehdi Aqadjani Memar <m.aqadjanimemar@student.vu.nl>
Michael Kerrisk <mtk.manpages@gmail.com>
Michal Hocko <mhocko@suse.cz>
Mike Frysinger <vapier@gentoo.org>
Mike Hayward <hayward@loup.net>
Miklos Szeredi <miklos@szeredi.hu>
Namhyung Kim <namhyung@gmail.com>
Namjae Jeon <namjae.jeon@samsung.com>
Nathan Lynch <nathan_lynch@mentor.com>
NeilBrown <neilb@suse.de>
Pádraig Brady <P@draigBrady.com>
Pavel Machek <pavel@ucw.cz>
Peter Hurley <peter@hurleysoftware.com>
Sam Varshavchik <mrsam@courier-mta.com>
Scot Doyle <lkml14@scotdoyle.com>
Stephan Mueller <stephan.mueller@atsec.com>
Tobias Stoeckmann <tobias@stoeckmann.org>
Tulio Magno Quites Machado Filho <tuliom@linux.vnet.ibm.com>
Uwe Kleine-König <uwe+debian@kleine-koenig.org>
Vegard Nossum <vegard.nossum@oracle.com>
Ville Skyttä <ville.skytta@iki.fi>
Vince Weaver <vincent.weaver@maine.edu>
Zeng Linggang <zenglg.jy@cn.fujitsu.com>
文剑 <wenjianhn@gmail.com>

Apologies if I missed anyone!


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

bpf.2
    Alexei Starovoitov, Michael Kerrisk  [Daniel Borkmann]
        New page documenting bpf(2)

__ppc_get_timebase.3
    Tulio Magno Quites Machado Filho
        New page documenting __ppc_get_timebase() and __ppc_get_timebase_freq()
            Glibc 2.16 was released with a new function for the Power
            architecture that can read its Time Base Register.
            Glibc 2.17 adds a function to read the frequency at which the Time
            Base Register of Power processors is updated.

queue.3
    Michael Kerrisk  [David Leppik, Doug Klima]
        Reimport from latest FreeBSD page
            Long ago, Doug Klima noted that many macros were not
            documented in the queue(3) page. Fix by reimporting from
            latest [1] FreeBSD man page.

            [1] Revision 263142, Modified Fri Mar 14 03:07:51 2014 UTC

            This also fixes https://sourceware.org/bugzilla/show_bug.cgi?id=1506

            This time, I'll learn from past mistakes and not convert
            from 'mdoc' to 'man' macros.
    Michael Kerrisk
        Use subsections in DESCRIPTION
    Michael Kerrisk
        Remove SEE ALSO reference to nonexistent tree(3)
    Michael Kerrisk
        Use real hyphens in code samples
    Michael Kerrisk
        Comment out text for functions not in glibc
    Michael Kerrisk
        Replace HISTORY with CONFORMING TO


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

rename.2
    Michael Kerrisk  [Miklos Szeredi]
        Document RENAME_WHITEOUT
            Heavily based on text by Miklos Szeredi.


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

__ppc_get_timebase_freq.3
    Tulio Magno Quites Machado Filho
        New link to new __ppc_get_timebase(3) page

LIST_EMPTY.3
LIST_FIRST.3
LIST_FOREACH.3
LIST_HEAD_INITIALIZER.3
LIST_INSERT_BEFORE.3
LIST_NEXT.3
SLIST_EMPTY.3
SLIST_ENTRY.3
SLIST_FIRST.3
SLIST_FOREACH.3
SLIST_HEAD.3
SLIST_HEAD_INITIALIZER.3
SLIST_INIT.3
SLIST_INSERT_AFTER.3
SLIST_INSERT_HEAD.3
SLIST_NEXT.3
SLIST_REMOVE.3
SLIST_REMOVE_HEAD.3
STAILQ_CONCAT.3
STAILQ_EMPTY.3
STAILQ_ENTRY.3
STAILQ_FIRST.3
STAILQ_FOREACH.3
STAILQ_HEAD.3
STAILQ_HEAD_INITIALIZER.3
STAILQ_INIT.3
STAILQ_INSERT_AFTER.3
STAILQ_INSERT_HEAD.3
STAILQ_INSERT_TAIL.3
STAILQ_NEXT.3
STAILQ_REMOVE.3
STAILQ_REMOVE_HEAD.3
TAILQ_CONCAT.3
TAILQ_EMPTY.3
TAILQ_FIRST.3
TAILQ_FOREACH.3
TAILQ_FOREACH_REVERSE.3
TAILQ_HEAD_INITIALIZER.3
TAILQ_INSERT_BEFORE.3
TAILQ_LAST.3
TAILQ_NEXT.3
TAILQ_PREV.3
TAILQ_SWAP.3
    Michael Kerrisk
        New links to queue.3


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

Various pages
    Michael Kerrisk  [Andries E. Brouwer]
        Remove "ABI" from "C library/kernel ABI differences" subheadings
            The "ABI" doesn't really convey anything significant in
            the title. These subsections are about describing differences
            between the kernel and (g)libc interfaces.


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

intro.1
    Michael Kerrisk  [Andries E. Brouwer]
        Drop intro paragraph on '$?' shell variable
            As Andries notes, this piece of text is rather out of place in
            a page that was intended to provide a tutorial introduction for
            beginners logging in on a Linux system.

locale.1
    Marko Myllynen
        A minor output format clarification
            A minor clarification for the locale output format which was
            brought up at
            https://sourceware.org/bugzilla/show_bug.cgi?id=18516.

            For reference, see
            https://sourceware.org/bugzilla/show_bug.cgi?id=18516
            http://pubs.opengroup.org/onlinepubs/9699919799/utilities/locale.html

        Add CONFORMING TO section

capget.2
    Julian Orth
        Clarify that hdrp->pid==0 is equivalent gettid() not getpid()

chroot.2
    Jann Horn
        chroot() is not intended for security; document attack
            It is unfortunate that this discourages this use of chroot(2)
            without pointing out alternative solutions - for example,
            OpenSSH and vsftpd both still rely on chroot(2) for security.

            Bind mounts should theoretically be usable as a replacement, but
            currently, they have a similar problem (CVE-2015-2925) that hasn't
            been fixed in ~6 months, so I'd rather not add it to the manpage
            as a solution before a fix lands.

clock_getres.2
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

eventfd.2
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

execve.2
    Michael Kerrisk
        Elaborate on envp/argv as NULL behavior

_exit.2
    Michael Kerrisk
        Open stdio frames are not flushed, temporary files are deleted
            Many years ago, text was added to the page saying that it is
            implementation-dependent whether stdio streams are flushed and
            whether temporary are removed. In part, this change appears to
            be because POSIX.1-2001 added text related to this point.
            However, that seems to have been an error in POSIX, and the
            text was subsequently removed for POSIX.1-2008. See
            https://collaboration.opengroup.org/austin/interps/documents/9984/AI-085.txt
            Austin Group Interpretation reference 1003.1-2001 #085

fallocate.2
    Namjae Jeon  [Michael Kerrisk]
        Document FALLOC_FL_INSERT_RANGE
    Michael Kerrisk
        Since Linux 4.2, ext4 supports FALLOC_FL_INSERT_RANGE

fcntl.2
    Michael Kerrisk
        OFD locks are proposed for inclusion in the next POSIX revision

getrlimit.2
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

getrusage.2
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

gettid.2
    Michael Kerrisk
        Note that for a thread group leader, gettid() == getpid()

iopl.2
    Michael Kerrisk
        Remove some historical libc5 and glibc 1 details
            These details are ancient, and long ago ceased to be relevant.

ioprio_set.2
    Michael Kerrisk  [Jens Axboe]
        Document meaning of ioprio==0

mlock.2
    Michael Kerrisk  [Mehdi Aqadjani Memar]
        Document another ENOMEM error case
            ENOMEM can occur if locking/unlocking in the middle of a region
            would increase the number of VMAs beyond the system limit (64k).

mmap.2
    Michal Hocko  [Eric B Munson]
        Clarify MAP_POPULATE
            David Rientjes has noticed that MAP_POPULATE wording might promise
            much more than the kernel actually provides and intends to provide.
            The primary usage of the flag is to pre-fault the range. There is
            no guarantee that no major faults will happen later on. The pages
            might have been reclaimed by the time the process tries to access
            them.
    Michal Hocko  [Eric B Munson]
        Clarify MAP_LOCKED semantics
            MAP_LOCKED had a subtly different semantic from mmap(2)+mlock(2)
            since it has been introduced.
            mlock(2) fails if the memory range cannot get populated to
            guarantee that no future major faults will happen on the range.
            mmap(MAP_LOCKED) on the other hand silently succeeds even if
            the range was populated only partially.

            Fixing this subtle difference in the kernel is rather awkward
            because the memory population happens after mm locks have been
            dropped and so the cleanup before returning failure (munlock)
            could operate on something else than the originally mapped area.

            E.g. speculative userspace page fault handler catching SEGV and
            doing mmap(fault_addr, MAP_FIXED|MAP_LOCKED) might discard portion
            of a racing mmap and lead to lost data. Although it is not clear
            whether such a usage would be valid, mmap page doesn't explicitly
            describe requirements for threaded applications so we cannot
            exclude this possibility.

            This patch makes the semantic of MAP_LOCKED explicit and suggests
            using mmap + mlock as the only way to guarantee no later major
            page faults.
    Michael Kerrisk
        ERRORS: point out that ENOMEM can occur even for munmap()

mprotect.2
    Michael Kerrisk
        Note ENOMEM error that can occur when we reach limit on maximum VMAs

open.2
read.2
write.2
    Michael Kerrisk  [Mike Hayward]
        Clarify that O_NONBLOCK is a no-op for regular files and block devices

perf_event_open.2
    Vince Weaver  [Joerg Roedel]
        Exclude_host/exclude_guest clarification
            This patch relates to the exclude_host and exclude_guest bits added
            by the following commit:

               exclude_host, exclude_guest; Linux 3.2
                    commit a240f76165e6255384d4bdb8139895fac7988799
                    Author: Joerg Roedel <joerg.roedel@amd.com>
                    Date:   Wed Oct 5 14:01:16 2011 +0200

                        perf, core: Introduce attrs to count in either host or guest mode

            The updated manpage text clarifies that the "exclude_host" and
            "exclude_guest" perf_event_open() attr bits only apply in the
            context of a KVM environment and are currently x86 only.
    Vince Weaver
        Document PERF_SAMPLE_REGS_INTR
            This patch relates to the addition of PERF_SAMPLE_REGS_INTR
            support added in the following commit:

                perf_sample_regs_intr; Linux 3.19
                commit 60e2364e60e86e81bc6377f49779779e6120977f
                Author: Stephane Eranian <eranian@google.com>

                        perf: Add ability to sample machine state on interrupt

            The primary difference between PERF_SAMPLE_REGS_INTR and the
            existing PERF_SAMPLE_REGS_USER is that the new support will
            return kernel register values.  Also if precise_ip is
            set higher than 0 then the PEBS register state will be returned
            rather than the saved interrupt state.

            This patch incorporates feedback from Stephane Eranian and
            Andi Kleen.

prctl.2
seccomp.2
    Michael Kerrisk
        Clarify that SECCOMP_SET_MODE_STRICT disallows exit_group(2)
            These days, glibc implements _exit() as a wrapper around
            exit_group(2). (When seccomp was originally introduced, this was
            not the case.) Give the reader a clue that, despite what glibc is
            doing, what SECCOMP_SET_MODE_STRICT permits is the true _exit(2)
            system call, and not exit_group(2).

pread.2
read.2
readv.2
sendfile.2
write.2
    Michael Kerrisk
        Clarify that Linux limits transfers to a maximum of 0x7ffff000 bytes
            See https://bugs.debian.org/629994 and
            https://bugs.debian.org/630029.

pread.2
    Michael Kerrisk
        Rewrite RETURN VALUE section
            (Also drop the text on pwrite() returning zero; that seems bogus.)

ptrace.2
    Michael Kerrisk  [Vegard Nossum]
        PTRACE_O_TRACEEXIT clarification

readv.2
    Michael Kerrisk
        Remove BUGS heading
            The text on mixinf I/O syscalls and stdio is a general point
            of behavior. It's not a bug as such.

recv.2
send.2
    Michael Kerrisk
        Explain some subtleties of MSG_DONTWAIT versus O_NONBLOCK

rename.2
    Michael Kerrisk
    Michael Kerrisk
        Note that RENAME_NOREPLACE can't be employed with RENAME_EXCHANGE

sched_setaffinity.2
    Michael Kerrisk
        Add an example program
    Michael Kerrisk  [Florian Weimer]
        Explain how to deal with 1024-CPU limitation of glibc's cpu_set_t type
    Michael Kerrisk
        Mention the use of the 'isolcpus' kernel boot option

sched_setattr.2
    Julian Orth
        Remove a const attribute
            The attr argument of sched_setattr was documented as const but the
            kernel will modify the size field of this struct if it contains an
            invalid value. See the documentation of the size field for details.

seccomp.2
    Michael Kerrisk
        SEE ALSO: add bpf(2)

send.2
    Michael Kerrisk
        Expand on subtleties of MSG_NOSIGNAL versus ignoring SIGPIPE

sigaltstack.2
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

socket.2
    Stephan Mueller
        Update documentation reference for AF_ALG

truncate.2
    Michael Kerrisk
        ERRORS: ftruncate() can fail if the file descriptor is not writable

utimensat.2
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe
            After research, We think utimensat() and futimens() are thread-safe.
            But, there are not markings of utimensat() and futimens() in glibc
            document.

clearenv.3
    Zeng Linggang
        ATTRIBUTES: Note function that is not thread-safe

dl_iterate_phdr.3
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

error.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are/aren't thread-safe

fexecve.3
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

fpurge.3
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

fread.3
    Andries E. Brouwer
        Clarify terminology
            In the "RETURN VALUE" section the word item is in italics
            as if it were one of the function parameters. But the word
            "item" occurs here for the first time, earlier the text
            uses "element". [Patch improves this.]

fts.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are/aren't thread-safe

getaddrinfo.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

getaddrinfo_a.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

getauxval.3
    Michael Kerrisk
        File capabilities also trigger AT_SECURE
    Michael Kerrisk
        (Briefly) document AT_HWCAP2

getgrent_r.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are/aren't thread-safe

gethostbyname.3
    Michael Kerrisk  [Laszlo Ersek]
        Remove mention of IPv6 addresses, which are not supported
            As reported by Laszlo Ersek:

                gethostbyname(3) fails to resolve the IPv6 address "::1",
                but the manual page says: "If name is an IPv4 or IPv6 address,
                no lookup is performed and gethostbyname() simply copies name
                into the h_name field [...]".

                Debian bug report:
                http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=455762

                glibc bug report:
                http://sourceware.org/bugzilla/show_bug.cgi?id=5479

                SUSv3 link for gethostbyname(3):
                http://www.opengroup.org/onlinepubs/000095399/functions/gethostbyname.html

                It seems that the glibc behavior is conformant, and the manual
                page is in error.

getifaddrs.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

getnameinfo.3
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

getnetent_r.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

getprotoent.3
    Zeng Linggang
        ATTRIBUTES: Note functions that aren't thread-safe

getprotoent_r.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

getpw.3
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

getpwent_r.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are/aren't thread-safe

getrpcent.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are/aren't thread-safe

getrpcent_r.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

getrpcport.3
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

getservent.3
    Zeng Linggang
        ATTRIBUTES: Note functions that aren't thread-safe

getservent_r.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

gsignal.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

key_setsecret.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

malloc_get_state.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

malloc_info.3
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

malloc_stats.3
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

malloc_trim.3
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

MB_LEN_MAX.3
    Michael Kerrisk
        Clarify meaning of MB_LEN_MAX
    Michael Kerrisk  [Pádraig Brady]
        MB_LEN_MAX is 16 in modern glibc versions

memcpy.3
    Michael Kerrisk
        NOTES: describe the glibc 2.13 changes that revealed buggy applications
            Adding a note on this point seems worthwhile as a way of
            emphasizing the point that the buffers must not overlap.

mq_notify.3
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

perror.3
    Michael Kerrisk
        Some wording improvements and clarifications

profil.3
    Zeng Linggang
        ATTRIBUTES: Note function that is not thread-safe

psignal.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

pthread_attr_init.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe
    Michael Kerrisk
        Use "%zd" for printing size_t in example code

pthread_attr_setaffinity_np.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

pthread_cancel.3
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

pthread_cleanup_push.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

pthread_create.3
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

pthread_detach.3
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

pthread_getattr_np.3
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

pthread_join.3
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

pthread_setname_np.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

pthread_tryjoin_np.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

putgrent.3
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

rcmd.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are/aren't thread-safe

resolver.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

rpc.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

rpmatch.3
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

sem_close.3
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

sem_open.3
    Zeng Linggang
        ATTRIBUTES: Note function that is thread-safe

setaliasent.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are/aren't thread-safe

setlocale.3
    Marko Myllynen
        Update CONFORMING TO
            http://pubs.opengroup.org/onlinepubs/9699919799/functions/setlocale.html

setlocale.3
    Marko Myllynen
        Tweak C/POSIX locale portability description
            As discussed earlier, the current description might be a little
            bit too stringent, let's avoid the issue by describing the
            portability aspect on a slightly higher level.

            References:

            http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap06.html
            http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html
            http://pubs.opengroup.org/onlinepubs/9699919799/functions/setlocale.html

shm_open.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

strfmon.3
    Marko Myllynen
        Document strfmon_l(3)
            Describe strfmon_l(3).

            http://pubs.opengroup.org/onlinepubs/9699919799/functions/strfmon.html
    Marko Myllynen
        Fix CONFORMING TO
            AFAICS strfmon(3) is now defined in POSIX and the glibc
            implementation is as specified there.

            http://pubs.opengroup.org/onlinepubs/9699919799/functions/strfmon.html
    Marko Myllynen
        Rewrite the example
            I think the example is more accurate when we use the exact
            locale names and also the Euro sign where appropriate.

xcrypt.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

xdr.3
    Zeng Linggang
        ATTRIBUTES: Note functions that are thread-safe

console_codes.4
    Scot Doyle  [Pavel Machek, Michael Kerrisk]
        Add CSI sequence for cursor blink interval
            Add a Console Private CSI sequence to specify the current
            console's cursor blink interval. The interval is specified
            as a number of milliseconds until the next cursor display
            state toggle, from 50 to 65535.

null.4
    Michael Kerrisk
        Note that reads from /dev/zero are interruptible since Linux 2.6.31

core.5
    Michael Kerrisk
        Mention 'coredump_filter' boot option

host.conf.5
    Michael Kerrisk
        Wording fix: s/resolv+/the resolver library/
            The term "resolv+" seems to be historical cruft.

hosts.equiv.5
    Carlos O'Donell
        Fix format, clarify IdM needs, and provide examples.
            In some recent work with a Red Hat customer I had the opportunity
            to discuss the fine nuances of the ruserok() function and related
            API which are used to implement rlogin and rsh.

            It came to my attention after working with QE on some automated
            internal testing that there were no good examples in the hosts.equiv
            manual page showing how the format was supposed to work for this
            file and for ~/.rhosts, worse the "format" line showed that there
            should be spaces between arguments when that would clearly lead
            to incorrect behaviour. In addition some things that the format
            allows you to write are just wrong like "-host -user" which makes
            no sense since the host is already rejected, and should be written
            as "host -user" instead. I added notes in the example to make it
            clear that "-host -user" is invalid.

            I fixed three things:

            (a) The format line.
            - Either +, or [-]hostname, or +@netgrp or -@netgrp.
            - Either +, or [-]username, or +@netgrp or -@netgrp.
            - You must specify something in the hostname portion so remove
              optional brackets.

            (b) Clarify language around credentials
            - If the host is not trusted you must provide credentials to
              the login system and that could be anything really and it
              depends on your configuration e.g. PAM or whatever IdM you have.

            (c) Provide real-world examples
            - Provide several real world examples and some corner case
              examples for how you would write something. Hopefully others
              can add examples as they see fit.
    Michael Kerrisk  [Carlos O'Donell, Arjun Shankar]
        Improve explanation in EXAMPLE

locale.5
    Marko Myllynen
        Document map to_inpunct, map to_outpunct
            See e.g. fa_IR for reference.
    Marko Myllynen
        Document class in LC_CTYPE
            See e.g. the locale zh_CN and

            http://en.cppreference.com/w/cpp/string/wide/towctrans
            http://en.cppreference.com/w/cpp/string/wide/wctrans
    Marko Myllynen
        Add iconv(1) reference
    Marko Myllynen
        Document character transliteration
            See e.g. da_DK for reference.

            (Not sure should we actually provide an example here?)
    Marko Myllynen
        Document era keywords
            This patch completes the LC_TIME section - since these era
            keywords are so tightly coupled, I'm providing them as a
            single patch.

            Based on
            http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap07.html
            http://www.open-std.org/jtc1/SC22/WG20/docs/n972-14652ft.pdf
    Marko Myllynen
        Document default_missing
    Marko Myllynen
        Document outdigit and alt_digits
            See e.g. fa_IR for reference.
    Marko Myllynen
        Refer to locale(7) more prominently
            It's probably a good idea to refer to locale(7) so that a reader
            can check what a category is about before describing them in
            detail.
    Marko Myllynen
        Document charclass and charconv
            See e.g. the locales ja_JP and ko_KR and

            http://en.cppreference.com/w/cpp/string/wide/towctrans
            http://en.cppreference.com/w/cpp/string/wide/wctrans
    Marko Myllynen
        Copy is not exclusive in LC_CTYPE and LC_COLLATE
            See e.g. da_DK for reference.
    Marko Myllynen
        Remove the FIXME for timezone
            The timezone of LC_TIME is not in POSIX, only 6 (out of ~300)
            glibc locales define it, the glibc code comment below from
            glibc.git/programs/ld-time.c seems to suggest it's not a good
            idea, and there's been a proposal in upstream [1] to remove the
            existing timezone definitions from glibc locales so I think
            it's actually better to leave this one undocumented:

            /* XXX We don't perform any tests on the timezone value since this is
               simply useless, stupid $&$!@...  */

            1) https://sourceware.org/ml/libc-alpha/2015-06/msg00098.html

            Move the remaining LC_COLLATE FIXMEs together while at it.
    Marko Myllynen
        Fix country_isbn format
            Both plain numbers and Unicode code points are used in
            glibc locales but checking the code reveals that country_isbn
            is handled like the rest of its category expect for country_num
            which was clarified earlier.
    Marko Myllynen
        Sort according to the standard
            Sort the options so that those defined in POSIX are listed first,
            then followed by those defined in ISO/IEC TR 14652 in the order
            of common convention in many widely used glibc locales.

            Actual descriptions are unchanged.

            http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html
    Marko Myllynen
        Refer to strftime(3) where appropriate
            The relationship between the locale time format syntax
            and strftime() cannot be considered as obvious.
    Marko Myllynen
        Document map "totitle"
            See e.g. locales/i18n for reference.
    Michael Kerrisk  [Marko Myllynen]
        Remove BUGS section saying man page is not complete
            To some degree, this is true of many pages. And anyway, this
            page is much better after recent work by Marko.

proc.5
    Michael Kerrisk
        List /proc/vmstat fields
    Michael Kerrisk
        Tweak /proc/vmstat text
    Michael Kerrisk
        Add /proc/crypto entry with a pointer to further information
    Michael Kerrisk  [Kees Cook]
        Document /proc/sys/kernel/sysctl_writes_strict
            Based on text in Documentation/sysctl/kernel.txt.
    Michael Kerrisk
        Move misordered /proc/[pid]/timers entry
    Michael Kerrisk
        Refer to bpf(2) for explanation of /proc/sys/net/core/bpf_jit_enable

repertoiremap.5
    Marko Myllynen
        Symbolic names AKA mnemonics
            A long time ago in glibc, repertoire maps were used (but they
            were removed already in 2000), those mapping files were named
            as mnemonics, so "mnemonic" is a term that would almost
            certainly come up if somebody studies glibc side (perhaps even
            the related standards like ISO 9945 [which I don't have access
            to]) so I thought it's worth to mention to term in the man page
            to make sure we're talking about the same thing, otherwise
            someone might wonder is that something different or not.

            IOW, symbolic names and mnemonics are often used interchangeably,
            let's mention the other often used term in the page, too.

capabilities.7
    Michael Kerrisk
        CAP_SYS_ADMIN allows calling bpf(2)

locale.7
    Marko Myllynen
        LC_CTYPE determines transliteration rules on glibc systems

packet.7
    文剑  [Cortland Setlow]
        Fix description of binding a packet socket to an interface

pty.7
    NeilBrown  [Peter Hurley]
        Clarify asynchronous nature of PTY I/O
            A PTY is not like a pipe - there may be delayed between data
            being written at one end and it being available at the other.

            This became particularly apparent after
                 commit f95499c3030f
                ("n_tty: Don't wait for buffer work in read() loop")
            in Linux 3.12

            See also the mail thread at https://lkml.org/lkml/2015/5/1/35
                Date    Mon, 04 May 2015 12:32:04 -0400
                From    Peter Hurley <>
                Subject Re: [PATCH bisected regression] input_available_p()
                            sometimes says 'no' when it should say 'yes'

rtld-audit.7
    Ben Woodard
        Use correct printf() specifier for pointer types
            In the example code you used %x rather than %p in the example
            code for an audit library. The problem is that it truncates the
            pointers on 64b platforms. So you get something like:

            la_symbind64(): symname = strrchr sym->st_value = 0x7f4b8a3f8960
            ndx = 222 flags = 0x0 refcook = 8b53e5c8 defcook = 8b537e30

            rather than:

            la_symbind64(): symname = fclose sym->st_value = 0x7fa452dd49b0
            ndx = 1135 flags = 0x0 refcook = 0x7fa453f395c8 defcook = 0x7fa453f32e30

            This has bitten me a handful of times when playing around with
            audit test libraries to investigate its behavior.

sched.7
    Michael Kerrisk
        Remove ancient, wildly optimistic prediction about future of RT patches
            It seems the patches were not merged by 2.6.30...

socket.7
    Michael Kerrisk
        SEE ALSO: add bpf(2)

vdso.7
    Nathan Lynch  [Mike Frysinger]
        Update for ARM
            The 32-bit ARM architecture in Linux has gained a vDSO as of the
            4.1 release.  (I was the primary author.)

            Document the symbols exported by the ARM VDSO.

            Accepted kernel submission:
            http://lists.infradead.org/pipermail/linux-arm-kernel/2015-March/332573.html