path: root/Changes

==================== Changes in man-pages-4.00 ====================

Released: ????-??-??, 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:

Advait Dixi <advaitdixit@hotmail.com>
Alain Kalker <a.c.kalker@gmail.com>
Andi Kleen <andi@firstfloor.org>
Andreas Gruenbacher <agruenba@redhat.com>
Andreas Heiduk <asheiduk@googlemail.com>
Askar Safin <safinaskar@mail.ru>
Brice Goglin <Brice.Goglin@inria.fr>
Cameron Norman <camerontnorman@gmail.com>
Carlos O'Donell <carlos@redhat.com>
Chris Metcalf <cmetcalf@tilera.com>
Christophe Lohr <Christophe.Lohr@telecom-bretagne.eu>
Christopher Head <chead@chead.ca>
Christoph Hellwig <hch@infradead.org>
David Wilcox <davidvsthegiant@gmail.com>
Denis Du <denisdu@ruggedcom.com>
Egmont Koblinger <egmont@gmail.com>
Filipe Brandenburger <filbranden@gmail.com>
Filipus Klutiero <chealer@gmail.com>
Florian Weimer <fweimer@redhat.com>
Frédéric Maria <frederic.maria@free.fr>
Gleb Fotengauer-Malinovskiy <glebfm@altlinux.org>
Graham Shaw <gdshaw@riscpkg.org>
Gregor Jasny <igjasny@googlemail.com>
Guillem Jover <guillem@hadrons.org>
Guy Harris <guy@alum.mit.edu>
Heinrich Schuchardt <xypron.glpk@gmx.de>
Ian Pilcher <arequipeno@gmail.com>
Jann Horn <jann@thejh.net>
Jason Newton <nevion@gmail.com>
J. Bruce Fields <bfields@fieldses.org>
Jiri Pirko <jpirko@redhat.com>
Joachim Wuttke <j.wuttke@fz-juelich.de>
Joern Heissler <contact@joern.heissler.de>
Jonathan Nieder <jrnieder@gmail.com>
Joonas Salo <salo.joonas@gmail.com>
Jussi Lehtola <jussilehtola@fedoraproject.org>
Kirill A. Shutemov <kirill.shutemov@linux.intel.com>
KOSAKI Motohiro <kosaki.motohiro@jp.fujitsu.com>
Laurence Gonsalves <laurence@xenomachina.com>
Magnus REFTEL <magnus.xm.reftel@stericsson.com>
Michael Kerrisk <mtk.manpages@gmail.com>
NeilBrown <neilb@suse.de>
Regid Ichira <regid23@nt1.in>
Sam Varshavchik <mrsam@courier-mta.com>
Steinar H. Gunderson <sgunderson@bigfoot.com>
Stéphane Aulery <saulery@free.fr>
Stephane Fillod <fillods@users.sf.net>
Tetsuo Handa <from-linux-kernel@i-love.sakura.ne.jp>
Thomas Hood <jdthood@gmail.com>
Urs Thuermann <urs@isnogud.escape.de>
Vasiliy Kulikov <segooon@gmail.com>
Vegard Nossum <vegard.nossum@gmail.com>
Weijie Yang <weijie.yang@samsung.com>
William Woodruff <william@tuffbizz.com>
Zeng Linggang <zenglg.jy@cn.fujitsu.com>

Apologies if I missed anyone!


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

get_phys_pages.3
    William Woodruff
        Document get_phys_pages() and get_avphys_pages()

loop.4
    Urs Thuermann, Michael Kerrisk
        New page documenting the loop device

xattr.7
    Andreas Gruenbacher
        Import attr(5) man page from the 'attr' project
            After discussions with Andreas Gruenbacher, it makes sense to
            move this page into man-pages, since it mostly relates to
            kernel details. Since this is an overview page,
            we'll move it to Section 7.
    Michael Kerrisk
         Rename page
            "xattr" is a more meaningful name than "attr" (it resonates
            with the names of the system calls), so as long as we are
            moving the page to a new section, we'll change the name as well,
            and retain an acl(5) link so that old references remain valid.


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

mmap.2
    Michael Kerrisk  [Andi Kleen]
        Document MAP_HUGE_2MB, MAP_HUGE_1GB, and MAP_HUGE_SHIFT

shmget.2
    Michael Kerrisk  [Andi Kleen]
        Document SHM_HUGE_2MB, SHM_HUGE_1GB, and SHM_HUGE_SHIFT

resolver.3
    Michael Kerrisk  [Jonathan Nieder]
        Add descriptions of some other resolver functions
            Add res_ninit(), res_nquery(), res_nsearch(),
            and res_nquerydomain(), res_nmkquery(), res_nsend().

tty_ioctl.4
    Frédéric Maria  [Stephane Fillod, Andreas Heiduk]
        Document TIOCMIWAIT and TIOCGICOUNT
    Michael Kerrisk
        Document TIOCGEXCL
    Michael Kerrisk
        Document TIOGCPKT
    Michael Kerrisk
        Document TIOCSPTLCK
    Michael Kerrisk
        Document TIOCGPTLCK


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

CMSG_DATA.3
    Michael Kerrisk
        New link to cmsg(3)

CMSG_LEN.3
    Michael Kerrisk
        New link to cmsg(3)

dprintf.3
    Michael Kerrisk
        Convert to a link to printf.3

get_avphys_pages.3
    William Woodruff
        New link to new get_phys_pages.3 page

res_ninit.3
res_nmkquery.3
res_nquery.3
res_nquerydomain.3
res_nsearch.3
res_nsend.3
    Michael Kerrisk
        New links to resolver(3) man page

loop-control.4
    Michael Kerrisk
        New link to loop.4

attr.5
    Michael Kerrisk
        New link to xattr(7)


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

chown.2
execve.2
prctl.2
truncate.2
proc.5
capabilities.7
ld.so.8
    Michael Kerrisk
        Tighter wording: 'mode bit' rather than 'permission bit'
            For sticky, set-UID, and set-GID mode bits (as used in POSIX).


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

add_key.2
keyctl.2
request_key.2
    Michael Kerrisk
        SEE ALSO: add keyrings(7)

add_key.2
request_key.2
    Michael Kerrisk
        SEE ALSO: add keyctl(3)

epoll_ctl.2
    Michael Kerrisk
        After EPOLLHUP, EOF will be seen only after all data has been consumed

epoll_wait.2
    Michael Kerrisk
        Clarify that signal mask treatment in epoll_pwait() is per-thread
            s/sigprocmask()/pthread_sigmask()/

fcntl.2
    Michael Kerrisk  [Vegard Nossum]
        Note an F_SETSIG corner case

get_mempolicy.2, set_mempolicy
    Brice Goglin
        Policy is per thread, not per process

getxattr.2
listxattr.2
removexattr.2
setxattr.2
capabilities.7
    Michael Kerrisk
        Adjust "attr(5)" references to "xattr(7)"

ioctl.2
    Michael Kerrisk
        SEE ALSO: add console_ioctl(2) and tty_ioctl(2)

listxattr.2
xattr.7
    Michael Kerrisk
        Describe listxattr(2) E2BIG error and document it as a BUG

mkdir.2
    Michael Kerrisk
        Wording fixes + point reader at stat(2) for explanation of file mode
    Michael Kerrisk  [Andreas Grünbacher]
        Further tweaks to text on S_ISVTX and 'mode' argument

mknod.2
    Michael Kerrisk
        Rewordings + point reader at stat(2) for details of mode bits

mmap.2
    Michael Kerrisk
        Remove text that implies that munmap() syncs MAP_SHARED mapping to file
            The existing text in this page:

                   MAP_SHARED Share  this  mapping.   Updates to the mapping
                              are visible to other processes that  map  this
                              file,  and are carried through to the underly‐
                              ing  file.   The  file  may  not  actually  be
                              updated until msync(2) or munmap() is called.

            implies that munmap() will sync the mapping to the underlying
            file. POSIX doesn't require this, and some light reading of the
            code and some light testing (fsync() after munmap() of a large
            file) also indicates that Linux doesn't do this.

msync.2
    Michael Kerrisk
        Rework text of DESCRIPTION
            Rewrite the text somewhat, for easier comprehension.
            No (intentional) changes to factual content

nfsservctl.2
    Michael Kerrisk  [J. Bruce Fields]
        Note that nfsservctl() was replaced by files in nfsd filesystem

open.2
    Michael Kerrisk  [Andreas Gruenbacher]
        open() honors the S_ISVTX, S_ISUID, and S_ISGID bits in 'mode'
    Michael Kerrisk
        Tighten wording: use 'mode bit' rather than 'permission bit'
    Michael Kerrisk  [NeilBrown]
        BUGS: O_CREAT | O_DIRECTORY succeeds if pathname does not exist

poll.2
    Michael Kerrisk  [Ian Pilcher]
        Clarify that signal mask treatment in ppoll() is per-thread
            s/sigprocmask()/pthread_sigmask()/
    Michael Kerrisk  [Sam Varshavchik]
        After POLLHUP, EOF will be seen only after all data has been consumed
    Michael Kerrisk
        Make it clearer which bits are ignored in 'events'

prctl.2
    Michael Kerrisk  [David Wilcox, Filipe Brandenburger]
        Note that "parent" for purposes of PR_SET_DEATHSIG is a *thread*
            See https://bugzilla.kernel.org/show_bug.cgi?id=43300

sendfile.2
    Michael Kerrisk  [Jason Newton]
        Note that sendfile does not support O_APPEND for 'out_fd'
            See https://bugzilla.kernel.org/show_bug.cgi?id=82841
    Michael Kerrisk  [Gregor Jasny]
        RETURN VALUE: note the possibility of "short sends"
            See https://bugzilla.kernel.org/show_bug.cgi?id=97491
    Michael Kerrisk  [Askar Safin]
        Clarify text on 'out_fd' and regular files in Linux 2.4
            See https://bugzilla.kernel.org/show_bug.cgi?id=86001

shutdown.2
    Michael Kerrisk  [Stéphane Aulery]
        BUGS: UNIX domain sockets now detect invalid 'how' values
            Bug fixed in Linux 3.7.
            See https://bugzilla.kernel.org/show_bug.cgi?id=47111

sigaction.2
    Michael Kerrisk
        Refer the reader to fcntl(2) F_SETSIG for further details on si_fd

stat.2
    Jann Horn
        Add note about stat() being racy
    Andreas Gruenbacher
        Improve description of some mode constants
    Michael Kerrisk  [Andreas Grünbacher]
        Remove excessive leading zeros on some constants
    Michael Kerrisk
        Add text on POSIX terms "file mode bits" and "file permission bits"
            Recent changes to various pages employ this distinction.
    Michael Kerrisk
        Tighten wording: use 'mode bit' rather than 'permission bit'
            According to POSIX, the the 9 UGO*RWX bits are permissions, and
            'mode' is used to refer to collectively to those bits plus sticky,
            set-UID, and set_GID bits.

syslog.2
    Michael Kerrisk
        SEE ALSO: add dmesg(1)

umask.2
open.2
mknod.2
mkdir.2
    Andreas Gruenbacher
        Explain what default ACLs do
            Explain the effect that default ACLs have (instead of the umask)
            in umask.2.  Mention that default ACLs can have an affect in
            open.2, mknod.2, and mkdir.2.

unshare.2
    Michael Kerrisk  [Florian Weimer]
        Give the reader a hint that unshare() works on processes or threads
            See https://bugzilla.kernel.org/show_bug.cgi?id=59281

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

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

cmsg.3
    Michael Kerrisk  [Christopher Head]
        Fix error in SCM_RIGHTS code sample
            Remove erroneous second initialization of msg.msg_controllen
            in the example code for SCM_RIGHTS.
            See https://bugzilla.kernel.org/show_bug.cgi?id=15952

CPU_SET.3
    Chris Metcalf
        Clarify language about "available" cpus
            The CPU_SET.3 man page uses the adjective "available" when
            explaining what the argument to CPU_SET() means.  This is
            confusing, since "available" isn't well-defined.  The kernel
            has a set of adjectives (possible, present, online, and active)
            that qualify cpus, but normally none of these are what the
            cpu_set_t bit index means: it's just "which cpu", using the
            kernel's internal numbering system, even if that cpu isn't
            possible or present.

            This change removes the word "available" and adds a sentence
            warning that cpu sets may not be contiguous due to dynamic
            cpu hotplug, etc.

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

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

gethostbyname.3
    Carlos O'Donell
        NSS plugins searched first
    Carlos O'Donell
        "order" is obsolete

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

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

get_nprocs_conf.3
    Michael Kerrisk
        Use exit() rather than return in main()

getopt.3
    Michael Kerrisk  [Guy Harris]
        Remove crufty BUGS section
            See https://bugzilla.kernel.org/show_bug.cgi?id=90261

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

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

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

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

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

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

printf.3
    Michael Kerrisk  [Egmont Koblinger]
        Merge dprintf() and vdprintf() discussion into this page
    Michael Kerrisk
        SEE ALSO: add puts(3)
    Michael Kerrisk
        Move return value discussion to proper RETURN VALUE section

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

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

regex.3
    Michael Kerrisk  [Laurence Gonsalves]
        Fix error in description of 'cflags'
            'cflags' is a bit mask of *zero* (not one) or more flags.

resolver.3
    Stéphane Aulery
        Add info about RES_INSECURE1 and RES_INSECURE2 option in debug mode

scanf.3
    Joern Heissler
        Improve description of %n specifier

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

setlocale.3
    Zeng Linggang
        ATTRIBUTES: Note function that isn't thread-safe

setlogmask.3
    Zeng Linggang
        ATTRIBUTES: Note function that isn't thread-safe

sleep.3
    Zeng Linggang
        ATTRIBUTES: Note function that isn't thread-safe

strsignal.3
    Zeng Linggang
        ATTRIBUTES: Note function that isn't thread-safe

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

undocumented.3
    William Woodruff
        Remove documented functions

tty_ioctl.4
    Michael Kerrisk  [Denis Du]
        Fix error in code example

proc.5
    Michael Kerrisk  [Cameron Norman, Vasiliy Kulikov]
        Document /proc mount options
            Document the 'hidepid' and 'gid' mount options that were added in
            Linux 3.3.  See https://bugzilla.kernel.org/show_bug.cgi?id=90641
            Based on text by Vasiliy Kulikov in
            Documentation/filesystems/proc.txt.
    Michael Kerrisk  [Kirill A. Shutemov]
        Improve description of /proc/PID/status
    Guillem Jover
        Document /proc/PID/exe behaviour on unlinked pathnames
    Michael Kerrisk  [Weijie Yang]
        Document /proc/PID/status VmPMD

resolv.conf.5
    Stéphane Aulery  [Thomas Hood]
        Document use-vc option added to glibc 2.14
            Fix Ubuntu bug #1110781:
            https://bugs.launchpad.net/ubuntu/+source/manpages/+bug/1110781
    Stéphane Aulery  [Thomas Hood]
        Document RES_SNGLKUPREOP
            Fix Ubuntu bug #1110781:
            https://bugs.launchpad.net/ubuntu/+source/manpages/+bug/1110781

tzfile.5
    Sam Varshavchik
        Add various details on version 2 format

aio.7
    Michael Kerrisk
        Add details and update URL for OLS 2003 paper on AIO

xattr.7
    Michael Kerrisk
        Document EA limits for Btrfs
        Document VFS-imposed limits on EAs
            VFS imposes a 255-byte limit on EA names, and a 64kB limit on
            EA values.
    Michael Kerrisk
        The ext[234] block limitation applies to sum of all EAs
            It is not a per-EA limit.
    Michael Kerrisk
        Clarify permissions required to work with 'user' EAs
    Michael Kerrisk
        ext2 and ext3 no longer need mounting with 'user_xattr' for user EAs
    Michael Kerrisk
        Add various relevant pages to SEE ALSO
    Michael Kerrisk
        Add CONFORMING TO section
    Michael Kerrisk
        Modify headings to man-pages norms
    Michael Kerrisk
        Btrfs also supports extended attributes
    Michael Kerrisk
        File capabilities are implemented using *security* attributes
            Not *system* attributes
    Michael Kerrisk
        Describe limit on EA values for JFS, XFS, and Reiserfs

bootparam.7
    Michael Kerrisk  [Alain Kalker]
        Update discussion of 'debug' option
            See https://bugzilla.kernel.org/show_bug.cgi?id=97161
    Michael Kerrisk
        Summary of multiple changes: remove cruft from this page.
            Much of the detail on hardware specifics in this page dates
            from the 20th century. (The last major update to this page was in
            man-pages-1.14!) It's hugely out of date now (many of these
            devices disappeared from the kernel years ago.) So, I've taken
            a large scythe to the page to remove anything that looks
            seriously dated. In the process, the page has shrunk to less
            than 50% of its previous size.
    Michael Kerrisk
        Remove "buff=" details
            This seems to have gone away in Linux 2.2.
    Michael Kerrisk
        Remove crufty "Mouse drivers" options
    Michael Kerrisk
        Remove crufty "General non-device-specific boot arguments" options
    Michael Kerrisk
        Remove crufty "Hard disks" options
    Michael Kerrisk
        Remove crufty "mem=" details
    Michael Kerrisk
        Remove crufty details on IBM MCA bus devices
    Michael Kerrisk
        Remove 'swap=" details
            This seems to have gone away in Linux 2.2,
    Michael Kerrisk
        Remove crufty floppy disk driver options
            In the specific case of floppy drives: the drivers still
            exist, but it's been a while since most of saw these devices
            in the wild. So, just refer the reader to the kernel source
            file for details. (The detail in this man page was after all
            originally drawn from that file.)
        Remove crufty "ISDN drivers" options
    Michael Kerrisk
        Remove crufty "line printer driver" options
    Michael Kerrisk
        Remove crufty "Serial port drivers" options
    Michael Kerrisk
        Remove crufty reference to CONFIG_BUGi386
            That option disappeared in Linux 2.4.
    Michael Kerrisk
        Remove crufty text
            "bootsetups array" dates from Linux 2.0.
    Michael Kerrisk
        Remove crufty "Video hardware" options
    Michael Kerrisk
        Remove crufty SCSI device driver options

fanotify.7
    Michael Kerrisk  [Heinrich Schuchardt]
        Since Linux 3.19, fallocate(2) generates FAN_MODIFY events

inotify.7
    Michael Kerrisk  [Heinrich Schuchardt]
        Since Linux 3.19, fallocate(2) generates IN_MODIFY events

ip.7
    Michael Kerrisk
        Explain how IP_ADD_MEMBERSHIP determines its argument type
    Michael Kerrisk  [Jiri Pirko, Magnus REFTEL]
        Clarify details of the IP_MULTICAST_IF socket option
    Michael Kerrisk  [Advait Dixi]
        Remove dubious text that says that SO_PRIORITY set IP TOS
            See https://bugzilla.kernel.org/show_bug.cgi?id=35852
    Michael Kerrisk
        Relocate misplaced text describing ENOPROTOOPT error

packet.7
    Graham Shaw
        Add sll_protocol to list of required fields for outbound packets

pthreads.7
    Michael Kerrisk  [KOSAKI Motohiro]
        Using thread IDs whose lifetime has expired gives undefined behavior
            See https://bugzilla.kernel.org/show_bug.cgi?id=53061

raw.7
    Michael Kerrisk  [Tetsuo Handa]
        For incoming datagrams, sin_port is set to zero
    Michael Kerrisk
        Mention sendto(), recvfrom(), and so on when discussing address format
            This gives the reader a little context for the following
            discussion of 'sin_port'.
    Michael Kerrisk
        Remove crufty reference to <netinet/in.h>
    Michael Kerrisk
        Replace reference to RFC 1700 with pointer to IANA protocol number list

signal.7
    Michael Kerrisk  [Steinar H. Gunderson]
        Clarify that I/O operations on disks are not interrupted by signals
            See https://bugzilla.kernel.org/show_bug.cgi?id=97721

unix.7
    Michael Kerrisk  [Christophe Lohr]
        Remove mention of UNIX_PATH_MAX
            This kernel constant is not exposed to user space.
    Michael Kerrisk
        Note the 108 bytes for sun_path is how things are done on Linux
            And refer the reader to NOTES for discussion of portability.


xattr.7
    Michael Kerrisk
        Explicitly mention some of the xattr system calls in DESCRIPTION
            Naming the system calls helps to orient the reader

nscd.8
    Michael Kerrisk
        Add mention of 'services' and 'netgroup' databases
            This makes the page consistent with nscd.conf(5).