path: root/Changes

==================== Changes in man-pages-3.42 ====================

Released: ????-??-??, Konolfingen


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:

Aaron Peschel <aaron.peschel@gmail.com>
Adrian Dabrowski <atrox@seclab.tuwien.ac.at>
Akihiro MOTOKI <amotoki@gmail.com>
Alan Curry <pacman@kosh.dhis.org>
Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
Christoph Lameter <cl@linux.com>
Colin McCabe <cmccabe@alumni.cmu.edu>
Daniel Zingaro <daniel.zingaro@utoronto.ca>
David Prévot <taffit@debian.org>
Denys Vlasenko <vda.linux@gmail.com>
Henry Hu <henry.hu.sh@gmail.com>
Herbert Xu <herbert@gondor.apana.org.au>
Jan Engelhardt <jengelh@medozas.de>
Jim Hill <gjthill@gmail.com>
JoonSoo Kim <js1304@gmail.com>
Kalle Olavi Niemitalo <kon@iki.fi>
Martin H <textshell-tSIEzQ@neutronstar.dyndns.org>
Michael Kerrisk <mtk.manpages@gmail.com>
Michael S. Tsirkin <mst@redhat.com>
Rasmus Villemoes <Rasmus.Villemoes@decode.is>
Sami Kerola <kerolasa@iki.fi>
Sam Varshavchik <mrsam@courier-mta.com>
Shawn Landden <shawnlandden@gmail.com>
Simon Paillard <spaillard@debian.org>
Tolga Dalman <tolga.dalman@googlemail.com>
Ulrich Drepper <drepper@gmail.com>
Марк Коренберг <socketpair@gmail.com>

Apologies if I missed anyone!


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

Various pages
    Sami Kerola
        Global fix: use UR macro where applicable
            The syntax .UR http://example.com paired with .UE will create
            links which one can interact, if the pager allows that.  One
            way to see the effect is ask the man(1) command to use browser
            display, e.g.:

                man -H man7/uri.7

            ("\:" is optional groff syntax to permit hyphenless line breaks.)


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

ldd.1
    Michael Kerrisk
        Add security note on untrusted executables
            See also http://www.catonmat.net/blog/ldd-arbitrary-code-execution/
            and
            http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html

clone.2
    Michael Kerrisk
        Rewrite discussion of sys_clone

futex.2
    Марк Коренберг
        Consolidate error descriptions to ERRORS
    Michael Kerrisk
        Various wording fix-ups
    Michael Kerrisk
        Fix description of EINVAL error
            The current text seems incorrect. Replace with a more general
            description.

getdents.2
select_tut.2
atof.3
atoi.3
pthread_create.3
pthread_sigmask.3
rtime.3
setbuf.3
tsearch.3
netlink.7
    Michael Kerrisk  [Jan Engelhardt]
        Remove unneeded casts

get_robust_list.2
get_thread_area.2
getcpu.2
getdents.2
gettid.2
io_cancel.2
io_destroy.2
io_getevents.2
io_setup.2
io_submit.2
ioprio_set.2
kexec_load.2
llseek.2
modify_ldt.2
mq_getsetattr.2
pivot_root.2
readdir.2
rt_sigqueueinfo.2
set_thread_area.2
sgetmask.2
spu_create.2
spu_run.2
subpage_prot.2
sysctl.2
tkill.2
    Michael Kerrisk
        Add note to SYNOPSIS that there is no glibc wrapper for system call
            Reduce the chance that the reader may be misled into thinking
            that there is a wrapper function for this system call by noting
            explicitly in the SYNOPSIS that there is no glibc wrapper and
            pointing the reader to NOTES for further details.

ioprio_set.2
    Colin McCabe
        Clarify the multithreaded behavior of ioprio_set(2)
    Michael Kerrisk  [Марк Коренберг, Kalle Olavi Niemitalo]
        Document who==0 for IOPRIO_WHO_PROCESS and IOPRIO_WHO_PGRP
            For IOPRIO_WHO_PROCESS, who==0 means operate on the caller.
            For IOPRIO_WHO_PGRP, who==0 means operate on the caller's
            process group.

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

migrate_pages.2
    Michael Kerrisk  [Christoph Lameter, JoonSoo Kim]
        Fix description of return value

mount.2
    Michael Kerrisk
        For MS_REMOUNT, source is ignored

mprotect.2
    Michael Kerrisk  [Rasmus Villemoes]
        'addr' argument is not const
            As reported by Rasmus:

                Both my system's man-pages (3.22) and the latest online
                (3.41) show:

                    int mprotect(const void *addr, size_t len, int prot);

                as the prototype for mprotect(2). However, POSIX [1] and the
                actual sys/mman.h (on all the systems I checked) do not have
                the const qualifier on the first argument.

msgctl.2
semctl.2
shmctl.2
svipc.7
    Michael Kerrisk
        Don't mention that ipc_perm is defined in <sys/ipc.h>
            There's no need to mention that the 'ipc_perm' structure
            is defined in <sys/ipc.h>. That's an implementation detail,
            and furthermore <sys/ipc.h> is itself included by the other
            System V IPC header files. The current text might lead the
            reader to conclude that they must include <sys/ipc.h>, which
            is not the case (it is required neither on Linux, nor by the
            standards).

msgctl.2
msgget.2
msgop.2
semctl.2
semget.2
semop.2
shmctl.2
shmget.2
    Michael Kerrisk
        NOTES: <sys/types.h> and <sys/ipc.h> aren't strictly needed
            Add text to NOTES to say that the <sys/types.h> and <sys/ipc.h>
            header files aren't required by Linux or the standards, but may
            be needed for portability to old systems.

ptrace.2
    Denys Vlasenko
        Explain WNOHANG behavior and EINTR bug
            I didn't like ithe "SIGKILL operates similarly, with exceptions"
            phrase (if it's different, then it's not "similar", right?),
            and now I got around to changing it. Now it says simply:
            "SIGKILL does not generate signal-delivery-stop and therefore
            the tracer can't suppress it."

            Replaced "why WNOHANG is not reliable" example with a more
            realistic one (the one which actually inspired to add this
            information to man page in the first place): we got
            ESRCH - process is gone! - but waitpid(WNOHANG) can still
            confusingly return 0 "no processes to wait for".

            Replaced "This means that unneeded trailing arguments may
            be omitted" part with a much better recommendation
            to never do that and to supply zero arguments instead.
            (The part about "undocumentedness" of gcc behavior was bogus,
            btw - deleted).

            Expanded BUGS section with the explanation and an example
            of visible strace behavior on the buggy syscalls which
            exit with EINTR on ptrace attach. I hope this will lead
            to people submitting better bug reports to lkml about
            such syscalls.

seteuid.2
    Michael Kerrisk
        Note glibc version where setegid() implementation changed
            In glibc 2.2/2.3, setegid() switched from setregid() to setresgid().

set_tid_address.2
    Michael Kerrisk
        Rename 'ctid' argument for consistency with clone(2) page
    Michael Kerrisk
        Some rewordings and minor clarifications

sigwaitinfo.2
    Michael Kerrisk  [Daniel Zingaro]
        Some wording clarifications
            Mainly rewording things like "is delivered" to "becomes pending",
            which is more accurate terminology.

syscall.2
    Michael Kerrisk
        Add some more details to the description of syscall(2)
            And add another example of using syscall() to the program example.

syscalls.2
    Michael Kerrisk
        Add kcmp(2)
    Michael Kerrisk
        Move discussion of set_zone_reclaim(2) out of main table
            This system call was never visible to user space, so it makes
            sense to move it out of the main table of system calls into
            the notes below the table.

getifaddrs.3
    Michael Kerrisk  [Adrian Dabrowski]
        Note that ifa_addr and ifa_netmask can be NULL

readdir.3
    Michael Kerrisk  [Jan Engelhardt]
        Handle -1 error from pathconf() in example code snippet
            Improve the example demonstrating allocation of a buffer
            for readdir_r() to handle -1 error return from pathconf().
            Otherwise, naive readers may think that pathconf() return
            value can be used without checking.

realpath.3
    Shawn Landden
        Use past tense with ancient history (libc4, libc5)

regex.3
    Michael Kerrisk
        Correct SEE ALSO reference to glibc manual "regex" section

rtime.3
    Michael Kerrisk  [Jan Engelhardt]
        Fix broken pointer cast in example code

sem_close.3
sem_destroy.3
sem_getvalue.3
sem_init.3
sem_open.3
sem_post.3
sem_unlink.3
sem_wait.3
sem_overview.7
    Michael Kerrisk
        Note that "cc -pthread" is required; "-lrt" no longer works
            See https://bugs.launchpad.net/ubuntu/+source/manpages/+bug/874418

sigwait.3
    Michael Kerrisk
        Reword "is delivered" to "becomes pending"

strcat.3
    Michael Kerrisk
        Add some text to emphasize the dangers of buffer overruns
    Michael Kerrisk
        NOTES: Add discussion of strlcat()

strcpy.3
    Michael Kerrisk
        Note that info is lost when strncpy() doesn't null terminate
    Michael Kerrisk
        Add some text to emphasize possibility of buffer runs with strcpy()
    Michael Kerrisk
        NOTES: Add a discussion of strlcpy()
            Inspired by https://lwn.net/Articles/506530/
    Michael Kerrisk
        Fix description of the null-byte padding performed by strncpy()

tsearch.3
    Michael Kerrisk
        NOTES: remove redundant discussion of unorthodox use of term "postorder"
            This point is already covered at greater length in the main
            text of the page (See the piece "More commonly, ...").
    Michael Kerrisk
        Clarify use for first argument to the twalk() 'action' function
            There's a number of details in POSIX that are omitted in
            the current version of this page.
    Michael Kerrisk
        Some wording fixes

core.5
    Michael Kerrisk
        Note effect of madvise(2) MADV_DONTDUMP flag

capabilities.7
    Michael Kerrisk
        Document CAP_BLOCK_SUSPEND

glob.7
    Bjarni Ingi Gislason
        Change 8 bit characters to 7 bit representation
            Fixes rendering errors for accented 'a' characters.
    Michael Kerrisk  [Aaron Peschel]
        Update bash(1) command used to obtain classical globbing behavior
            The man page formerly noted the bash(1) v1 command to do this.

iso_8859-1.7
    Bjarni Ingi Gislason
        Explanation of SOFT HYPHEN and the code for it
            <groff: iso_8859-2.7>:89: warning: can't find special character `shc'

            This is the only "iso_8859-*.7" file that has this (now)
            undefined character.  The code in column four in "iso_8859-1.7" is
            "0x2D" ("HYPHEN, MINUS SIGN" or "HYPHEN-MINUS") instead of "0xAD".
            See Debian bug 156154 (or package "manpages").

            There should be an explanation for this graphic character and the
            code should be 0xAD in iso_8859-1.7 (as in all others), even
            though "[gn]roff" does not display a "HYPHEN" in that position of
            the table.

            The line with "SOFT HYPHEN" gets a footnote and a short
            explanation.

mdoc.7
    Bjarni Ingi Gislason
        Fixing a warning and a table
            Fis warning from "groff -ww ..." (or "man --warnings=w ..."):

                <groff: mdoc.7>:294: warning:
                tab character in unquoted macro argument

            In one table the distance between columns is too small in the
            "ps" output.  (Bug in the groff "doc.tmac" macro?)

mdoc.samples.7
    Bjarni Ingi Gislason
        Fix warnings from [ng]roff, corrections
            From "man -ww ..." (groff -ww ...):

                <standard input>:541: warning:
                tab character in unquoted macro argument
                [+3 similar warnings]
                <standard input>:813: warning: macro `Pu' not defined
                Usage: .Rv -std in sections 2 and 3 only (#1669)
                mdoc warning: A .Bl directive has no matching .El (#1821)

            String "Pu" defined as a row of punctuation characters.
            ".Bl" and ".El" fixed.
            Some arguments, that start with a period or are the name of a
            macro, protected with "\&".
            Variable name for macro ".Rv" corrected.

netdevice.7
    Bjarni Ingi Gislason
        Line in table too long
            Fix warning from "man ..." ("nroff -ww ..."):

                nroff: netdevice.7: warning: around line 98:
                table wider than line width

            Fix: No right adjustment in text blocks in tables.

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

netlink.7
    Bjarni Ingi Gislason
        Line in table is too long
            Fix warning from "man ..." ("nroff -ww ..."):

                nroff: netlink.7: warning: around line 195:
                table wider than line width

            Horizontal line incorporated into table.
            No right adjustment of text blocks in tables.

            See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=673875
    Simon Paillard  [Herbert Xu]
        Change description of "*_pid" fields to "Port ID"
            As reported by Herbert Xu, these should not be considered as PIDs.

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

rtnetlink.7
    Bjarni Ingi Gislason
        Line in table too long
            Fix warning from "man ..." ("nroff -ww ..."):

                nroff: rtnetlink.7: warning: around line 415:
                table wider than line width

            Column gutter reduced to fit line length.
            Right adjustment in text blocks removed in tables.
            Some header made centered in tables.
            One table put on same page.

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

socket.7
    Martin H
        Document SO_MARK socket option
            Commit 4a19ec5800fc3bb64e2d87c4d9fdd9e636086fe0 in Jan 2008 added
            the new SO_MARK socket option.

            This patch is based on text from the commit message.

            See https://bugzilla.kernel.org/show_bug.cgi?id=16461.

svipc.7
    Michael Kerrisk
        SYNOPSIS: Remove include of <sys/types.h> and <sys/ipc.h>
            Including <sys/types.h> and <sys/ipc.h> isn't needed on Linux
            and isn't really relevant for the explanation on this page.