man-pages-3.56 released

Gidday,

The Linux man-pages maintainer proudly announces:

man-pages-3.56 - man pages for Linux

Tarball download:
http://www.kernel.org/doc/man-pages/download.html
Git repository:
https://git.kernel.org/cgit/docs/man-pages/man-pages.git/
Online changelog:

    http://man7.org/linux/man-pages/changelog.html#release_3.56

A short summary of the release is blogged at:
http://linux-man-pages.blogspot.com/2014/01/man-pages-356-is-released.html

The current version of the pages is browsable at:
http://man7.org/linux/man-pages/

You are receiving this message either because:

a) You contributed to the content of this release.

b) You are subscribed to linux-man-u79uwXL29TaiAVqoAR/[email protected]

c) I have information (possibly inaccurate) that you are the maintainer of a translation of the manual pages, or are the maintainer of the manual pages set in a particular distribution, or have expressed interest in helping with man-pages maintenance, or have otherwise expressed interest in being notified about man-pages releases. If you don't want to receive such messages from me, or you know of some other translator or maintainer who may want to receive such notifications, send me a message.

Cheers,

Michael

==================== 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-Bi/[email protected]> Arif Zaman <[email protected]>
Bert Wesarg <bert.wesarg-gM/[email protected]> Daniel Borkmann <[email protected]> David Malcolm <[email protected]> David Prévot <[email protected]> Dongsheng Song <[email protected]> Elie De Brauwer <[email protected]> James Smith <[email protected]>
Janne Blomqvist <[email protected]> Joseph S. Myers <[email protected]> Luke Hutchison <[email protected]>
Marco Dione <[email protected]> Mathieu Desnoyers <mathieu.desnoyers-vg+e7yoeK/dWk0Htik3J/[email protected]> Mathieu Malaterre <[email protected]> Matthias Klose <[email protected]> Michael Kerrisk <[email protected]> Mike Frysinger <[email protected]> Moritz 'Morty' Strübe <[email protected]>
Nadav Har'El <nyh-TS7m/[email protected]> Ondřej Bílka <[email protected]> Prádraig Brady <[email protected]>
Peng Haitao <[email protected]> Raphael Geissert <[email protected]> Shawn Landden <shawn-01I/[email protected]> Simon Paillard <[email protected]> Stephen Kell <[email protected]> Sudhanshu Goswami <[email protected]> Sworddragon2 <[email protected]>
Vince Weaver <[email protected]> Willem de Bruijn <[email protected]> Yuri Kozlov <[email protected]>

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

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

hi,
i send a few new pages and one fix that is missing here at 08.10.2013 any particular reason why they are not included ?

re,
wh

Am 11.01.2014 19:36, schrieb Michael Kerrisk (man-pages):

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html