-==================== Changes in man-pages-3.53 ====================
+==================== Changes in man-pages-3.54 ====================
-Released: 2013-07-31, Munich
+Released: 2013-09-17, Munich
Contributors
in the changelog below) reports, notes, and ideas that have been
incorporated in changes in this release:
-Al Viro <viro@ZenIV.linux.org.uk>
-Andrey Vagin <avagin@openvz.org>
-Benjamin Poirier <bpoirier@suse.de>
-Chris Heath <chris@heathens.co.nz>
-Chuck Coffing <clc@alum.mit.edu>
+A. Costa <agcosta@gis.net>
+Akihiro MOTOKI <amotoki@gmail.com>
+Andreas Wiese <aw-lkml@instandbesetzt.net>
+Andrew Hunter <andrewhhunter@gmail.com>
+Chen Gang <gang.chen@asianux.com>
+Christopher Hall <chall0@gmail.com>
+Christos Tsopokis <christos@tsopokis.gr>
David Prévot <taffit@debian.org>
-Denys Vlasenko <dvlasenk@redhat.com>
-Dmitry V. Levin <ldv@altlinux.org>
-Felix_Schulte@McAfee.com
-graud@gmx.com
+D. Barbier <bouzim@gmail.com>
+Doug Goldstein <cardoe@cardoe.com>
+Elie De Brauwer <eliedebrauwer@gmail.com>
+Eugen Dedu <Eugen.Dedu@pu-pm.univ-fcomte.fr>
+Felix Janda <felix.janda@posteo.de>
+G.raud <graud@gmx.com>
+Hannes Landeholm <hannes@jumpstarter.io>
+J. Bruce Fields <bfields@fieldses.org>
+J. Bruce Fields <bfields@redhat.com>
+Johan Erlandsson <jeoerl@gmail.com>
+Jon Grant <jg@jguk.org>
+Magnus Reftel <magnus.reftel@gmail.com>
+Marko Myllynen <myllynen@redhat.com>
Michael Kerrisk <mtk.manpages@gmail.com>
Oleg Nesterov <oleg@redhat.com>
Peng Haitao <penght@cn.fujitsu.com>
Peter Schiffer <pschiffe@redhat.com>
+Robert Harris <robert.harris@fixnetix.com>
+Rodrigo Campos <rodrigo@sdfg.com.ar>
Simon Paillard <spaillard@debian.org>
+Stas <stas.grumbler@gmail.com>
Vince Weaver <vincent.weaver@maine.edu>
+Will Newton <will.newton@linaro.org>
+Zdenek Pavlas <zpavlas@redhat.com>
+Zsbán Ambrus <ambrus@math.bme.hu>
Apologies if I missed anyone!
-New and rewritten pages
------------------------
-
-restart_syscall.2
- Michael Kerrisk
- New page for restart_syscall(2) system call
-
Newly documented interfaces in existing pages
---------------------------------------------
-fchownat.2
- Michael Kerrisk
- Document AT_EMPTY_PATH
+ioctl_list.2
+ Zsbán Ambrus
+ Document FAT_IOCTL_GET_ATTRIBUTES
+ The attached patch adds four ioctls from linux/msdos_fs.h to the
+ ioctl_list(2) manpage.
-fstatat.2
- Michael Kerrisk
- Document AT_EMPTY_PATH
+ The ioctl FAT_IOCTL_GET_ATTRIBUTES reads FAT attributes of a
+ file a mounted vfat file system. I tested this on Linux
+ 2.6.33, an example script can be found at
+ http://www.perlmonks.com/?node_id=832623
-linkat.2
- Michael Kerrisk
- Document AT_EMPTY_PATH
-open.2
- Michael Kerrisk [Al Viro]
- Document O_PATH
- See also https://bugzilla.redhat.com/show_bug.cgi?id=885740
+Global changes
+--------------
+
+Various pages
+ Michael Kerrisk
+ Global fix: s/file system/filesystem/
+ Notwithstanding 24d01c530c5a3f75217543d02bf6712395e5f90c,
+ "filesystem" is the form used by the great majority of man pages
+ outside the man-pages project and in a number of other sources,
+ so let's go with that.
Changes to individual pages
---------------------------
-clock_nanosleep.2
+access.2
+ J. Bruce Fields
+ Fix outdated NFS information
+ Note that NFS versions since version 3 support an "access" call
+ so that the client doesn't have to guess permissions or ID
+ mapping on its own.
+
+ (See RFC 1813 sections 1.7 and 3.3.4.)
+
+adjtimex.2
+ Michael Kerrisk
+ SEE ALSO: Add adjtimex(8)
+
+clock_getres.2
+ Michael Kerrisk [Rodrigo Campos]
+ Note circumstances in which "SMP" note applies.
+ Michael Kerrisk
+ Add kernel version for CLOCK_*_CPUTIME_ID
+ CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID
+ appeared in 2.6.12.
+ Michael Kerrisk
+ Add VERSIONS section
+
futex.2
-nanosleep.2
-poll.2
-sigaction.2
-sigreturn.2
-signal.7
Michael Kerrisk
- SEE ALSO: add restart_syscall(2)
+ The 'timeout' can be rounded upwards by clock granularity and also overrun
+
+kill.2
+ Michael Kerrisk
+ Small improvements to text on historical rules for permissions
+
+nfsservctl.2
+ Michael Kerrisk
+ Note commands that were only in Linux 2.4.x and earlier
open.2
- Michael Kerrisk [Geoffrey Thomas]
- Remove warning that O_DIRECTORY is only for use with opendir(3)
- O_DIRECTORY can also be used with, for example, O_PATH.
+ Robert Harris
+ Add mmap(2) to list of calls that fail when given an O_PATH descriptor
+ Doug Goldstein
+ Add EINVAL to errors list
+ EINVAL can be returned by open(2) when the underlying filesystem
+ doesn't support O_DIRECT. It is documented in the NOTES section
+ but this patch adds it to the list of possible errors.
perf_event_open.2
Vince Weaver
- Improve PERF_SAMPLE_BRANCH_STACK documentation
- Vince Weaver
- Fix indentation of the MMAP layout section
- The indentation of the MMAP layout section wasn't quite right.
- I think this improves things but I admit I'm not an expert at the
- low-level indentation directives.
- Vince Weaver
- Update PERF_IOC_FLAG_GROUP info
- It turns out PERF_IOC_FLAG_GROUP was broken from 75f937f24bd9
- (in Linux 2.6.31, the initial perf_event release) until
- 724b6daa1 (Linux 3.4).
+ PERF_SAMPLE_BRANCH_STACK updates
+ This started out as just adding the new perf_event_open features
+ from Linux 3.11 (which was the addition of transactional memory
+ defines for PERF_SAMPLE_BRANCH_STACK samples) but turned into a
+ general cleanup of the PERF_SAMPLE_BRANCH_STACK documentation.
+
+ The main clarification is that at least one of the non-privilege
+ values must be set or else perf_event_open() will return an EINVAL
+ error.
+ Michael Kerrisk
+ Reorder text describing fields of 'perf_event_header' structure
+ Place the fields with the shorter descriptions first, to make the
+ information easier to read.
- I've done some extensive kernel source code digging plus
- running tests of various kernels and I hope the info
- presented is accurate now.
+poll.2
+ Michael Kerrisk
+ Clarify wording of 'timeout' as a "minimum" interval
- (Patch edited somewhat by mtk.)
- Vince Weaver
- Improve sysfs files documentation
- This improves the documentation of the various
- perf_event_open()-related sysfs files.
+sched_setaffinity.2
+ Michael Kerrisk [Christos Tsopokis]
+ Clarify that these system calls affect a per-thread attribute
-ptrace.2
- Denys Vlasenko [Oleg Nesterov, Dmitry V. Levin]
- If SEIZE was used, initial auto-attach stop is EVENT_STOP
- For every PTRACE_O_TRACEfoo option, mention that old-style SIGSTOP
- is replaced by PTRACE_EVENT_STOP if PTRACE_SEIZE attach was used.
+sched_setparam.2
+ Michael Kerrisk
+ Clarify that this system call applies to threads (not processes)
- Mention the same thing again in the description of
- PTRACE_EVENT_STOP.
- Denys Vlasenko [Oleg Nesterov, Dmitry V. Levin]
- Mention that PTRACE_PEEK* libc API and kernel API are different
- Denys Vlasenko [Oleg Nesterov, Dmitry V. Levin]
- Clarify PTRACE_INTERRUPT, PTRACE_LISTEN, and group-stop behavior
+sched_setscheduler.2
+ Michael Kerrisk
+ Clarify that this system call applies to threads (not processes)
+
+select.2
+ Michael Kerrisk [G.raud]
+ Clarify wording of 'timeout' as a "minimum" interval
-readlink.2
+setfsgid.2
+ Michael Kerrisk [Oleg Nesterov]
+ Clarify description of return value
+ More clearly describe the weirdness in the return value of this
+ system call, and note the problems it creates in in BUGS
+ Michael Kerrisk
+ Correct header file in SYNOPSIS
+ Michael Kerrisk
+ Refer to setfsuid(2) for an explanation of why setfsgid() is obsolete
+ Michael Kerrisk
+ Wording improvements
+
+setfsuid.2
+ Michael Kerrisk [Oleg Nesterov]
+ Clarify description of return value
+ More clearly describe the weirdness in the return value of this
+ system call, and ote the problems it creates in in BUGS
+ Michael Kerrisk [Chen Gang]
+ Clarify historical details and note that setfsuid() is obsolete
Michael Kerrisk
- Document use of empty 'pathname' argument
+ Wording improvements
Michael Kerrisk
- Change error check in example program from "< 0" to "== -1"
+ Correct header file in SYNOPSIS
-setpgid.2
- Michael Kerrisk [graud@gmx.com]
- s/SIGTSTP/SIGTTIN/ when discussing reads from terminal
- See https://bugzilla.kernel.org/show_bug.cgi?id=60504
+sigwaitinfo.2
+ Michael Kerrisk
+ Clarify wording of 'timeout' as a "minimum" interval
+
+syscall.2
+ Johan Erlandsson
+ Add missing argument in example
+ Johan Erlandsson
+ Correct registers for arm/EABI
+ Registers was off by one.
+
+ Reference:
+ http://www.arm.linux.org.uk/developer/patches/viewpatch.php?id=3105/4
+
+ See also:
+ http://peterdn.com/post/e28098Hello-World!e28099-in-ARM-assembly.aspx
+ https://wiki.debian.org/ArmEabiPort
+ http://en.wikipedia.org/wiki/Calling_convention#ARM
+
+wait.2
+ Michael Kerrisk [Hannes Landeholm]
+ Add details on the fifth argument provided by raw waitid() system call
+ See https://bugzilla.kernel.org/show_bug.cgi?id=60744
-clog2.3
+clock.3
Michael Kerrisk
- Note that these functions are still not present in glibc 2.17
+ clock() switched from using times(2) to clock_gettime() in glibc 2.18
-dirfd.3
+drand48_r.3
Peng Haitao
- ATTRIBUTES: Note function that is thread-safe
- The function dirfd() is thread safe.
+ ATTRIBUTES: Note functions that are thread-safe
+ The functions drand48_r(), erand48_r(), lrand48_r(),
+ nrand48_r(), mrand48_r(), jrand48_r(), srand48_r(), seed48_r(),
+ and lcong48_r() are thread safe.
-div.3
+fma.3
Peng Haitao
ATTRIBUTES: Note functions that are thread-safe
- The functions div(), ldiv(), lldiv() and imaxdiv() are thread
- safe.
+ The functions fma(), fmaf() and fmal() are thread safe.
-fabs.3
+fmax.3
Peng Haitao
ATTRIBUTES: Note functions that are thread-safe
- The functions fabs(), fabsf() and fabsl() are thread safe.
+ The functions fmax(), fmaxf() and fmaxl() are thread safe.
-fdim.3
+fmin.3
Peng Haitao
ATTRIBUTES: Note functions that are thread-safe
- The functions fdim(), fdimf() and fdiml() are thread safe.
+ The functions fmin(), fminf() and fminl() are thread safe.
-fflush.3
+fpclassify.3
Peng Haitao
- ATTRIBUTES: Note function that is thread-safe
- The function fflush() is thread safe.
+ ATTRIBUTES: Note functions that are thread-safe
+ The functions fpclassify(), isfinite(), isnormal(), isnan(), and
+ isinf() are thread safe.
-finite.3
+frexp.3
Peng Haitao
ATTRIBUTES: Note functions that are thread-safe
- The functions finite(), finitef(), finitel(), isinf(), isinff(),
- isinfl(), isnan(), isnanf() and isnanl() are thread safe.
+ The functions frexp(), frexpf() and frexpl() are thread safe.
-flockfile.3
+gethostbyname.3
+ Michael Kerrisk [Jon Grant]
+ gai_strerror() is the modern replacement for herror() and hstrerror()
+ Michael Kerrisk
+ Update feature test macro requirements for herror() and hstrerror()
+ Michael Kerrisk
+ Add feature test macro requirements for h_errno
+
+ilogb.3
Peng Haitao
ATTRIBUTES: Note functions that are thread-safe
- The functions flockfile(), ftrylockfile() and funlockfile() are
- thread safe.
+ The functions ilogb(), ilogbf() and ilogbl() are thread safe.
-floor.3
+ldexp.3
Peng Haitao
ATTRIBUTES: Note functions that are thread-safe
- The functions floor(), floorf() and floorl() are thread safe.
+ The functions ldexp(), ldexpf() and ldexpl() are thread safe.
-resolv.conf.5
- Simon Paillard
- Explain how to set empty domain
- See http://bugs.debian.org/463575
+lrint.3
+ Peng Haitao
+ ATTRIBUTES: Note functions that are thread-safe
+ The functions lrint(), lrintf(), lrintl(), llrint(), llrintf(),
+ and llrintl() are thread safe.
-capabilities.7
- Michael Kerrisk
- Add open_by_handle_at(2) under CAP_DAC_READ_SEARCH
+lround.3
+ Peng Haitao
+ ATTRIBUTES: Note functions that are thread-safe
+ The functions lround(), lroundf(), lroundl(), llround(),
+ llroundf() and llroundl() are thread safe.
-inotify.7
- Michael Kerrisk [Felix_Schulte@McAfee.com]
- Clarify description of IN_MOVED_FROM and IN_MOVED_TO
+lseek64.3
+ Peng Haitao
+ ATTRIBUTES: Note function that is thread-safe
+ The function lseek64() is thread safe.
-man-pages.7
- Michael Kerrisk
- DESCRIPTION should note versions for new interface features or behavior
+mbsinit.3
+ Peng Haitao
+ ATTRIBUTES: Note function that is thread-safe
+ The function mbsinit() is thread safe.
+
+nextafter.3
+ Peng Haitao
+ ATTRIBUTES: Note functions that are thread-safe
+ The functions nextafter(), nextafterf(), nextafterl(),
+ nexttoward(), nexttowardf() and nexttowardl() are thread safe.
-udp.7
- Benjamin Poirier
- Add missing #include directive
- Using the UDP_CORK socket option documented in udp.7 requires
- including <netinet/udp.h>.
+posix_memalign.3
+ Michael Kerrisk [Will Newton]
+ 'errno" is indeterminate after a call to posix_memalign()
+ Michael Kerrisk [Will Newton]
+ Clarify wording on "return value" when size==0
-ld.so.8
- Michael Kerrisk
- Rework rpath token expansion text
- Michael Kerrisk
- Describe $PLATFORM rpath token
+printf.3
+ Christopher Hall
+ Correctly describe the meaning of a negative precision
+ The printf(3) manpage says that a negative precision is taken to
+ be zero, whereas printf(3p) says that a negative precision is
+ taken as if the precision were omitted. glibc agrees with the
+ latter (POSIX) specification.
+
+ Test code:
+
+ printf("%f\n",42.0); // "42.000000"
+ printf("%.*f\n",0,42.0); // "42"
+ printf("%.*f\n",-1,42.0); // "42.000000"
+
+ This patch corrects the explanation to match what actually happens.
+
+rewinddir.3
+ Peng Haitao
+ ATTRIBUTES: Note function that is thread-safe
+ The function rewinddir() is thread safe.
+
+rint.3
+ Peng Haitao
+ ATTRIBUTES: Note functions that are thread-safe
+ The functions nearbyint(), nearbyintf(), nearbyintl(), rint(),
+ rintf() and rintl() are thread safe.
+
+seekdir.3
+ Peng Haitao
+ ATTRIBUTES: Note function that is thread-safe
+ The function seekdir() is thread safe.
+
+telldir.3
+ Peng Haitao
+ ATTRIBUTES: Note function that is thread-safe
+ The function telldir() is thread safe.
+
+wctomb.3
+ Peng Haitao
+ ATTRIBUTES: Note function that is not thread-safe
+ The function wctomb() is not thread safe.
+
+wavelan.4
+ Michael Kerrisk [Elie De Brauwer]
+ This driver disappeared in 2.56.35
+
+dir_colors.5
+ Michael Kerrisk [Stas]
+ Add various synonyms
+ See http://bugs.debian.org/553477
+ Simon Paillard [Stas]
+ Add keywords SUID, SGID, STICKY, STICKY_OTHER_WRITABLE, OTHER_WRITABLE
+ See http://bugs.debian.org/553477
+ See ls.c and dircolors.c in coreutils
+
+proc.5
+ Peter Schiffer
+ Document /proc/[pid]/io file
+ Attempt to document fields in the /proc/[pid]/io file, based on
+ the Documentation/filesystems/proc.txt. The text will probably
+ need some grammar corrections.
+ Michael Kerrisk [Marko Myllynen]
+ /proc/sys/fs/inode-max went away in Linux 2.4
+ Also, the 'preshrink' field in /proc/sys/fs/inode-state became
+ a dummy value in Linux 2.4.
+
+ See https://bugzilla.kernel.org/show_bug.cgi?id=60836
+ Michael Kerrisk [A. Costa]
+ Note block size used by /proc/partitions
+ See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=666972
Michael Kerrisk
- Describe $LIB rpath token
+ Add rationale on drop_caches and note that it can hurt performance
+ See also http://lwn.net/Articles/562211/
+
+bootparam.7
+ Michael Kerrisk [Eugen Dedu]
+ Remove "lilo" entries from SEE ALSO
+ See http://bugs.debian.org/604019
+
+inotify.7
Michael Kerrisk
- Document LD_BIND_NOT
- Michael Kerrisk [Simon Paillard]
- Add reference to pthreads(7) in discussion of LD_ASSUME_KERNEL
+ SEE ALSO: add inotifywait(1) and inotifywatch(1)
-readlink.2
- Chuck Coffing
- Fix possible race condition in readlink.2 example
- I noticed that the example in the readlink.2 man pages does error
- checking for a race condition that would cause the value of the
- symbolic link to get larger. However, it doesn't handle the
- opposite case, in which the value gets shorter. (The NULL
- terminator is always set at the old, longer offset.) This could
- cause the program to operate on uninitialized data.
+ip.7
+ Simon Paillard
+ IP_MULTICAST_IF setsockopt recognizes struct mreq (compatibility)
+ Kernel added compatibility only recently in
+ 3a084ddb4bf299a6e898a9a07c89f3917f0713f7
+ See: http://bugs.debian.org/607979
+
+standards.7
+ Michael Kerrisk
+ Add mention of SUSv4-TC1 (POSIX.1-2013)