getrandom.2: Rework discussion of blocking section on interuption by signals

Reviewed-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

semget.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: Reads from /dev/urandom can block for large request sizes

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: SEE ALSO: add signal(7)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

signal.7: Add getrandom(2) to list of restartable system calls

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: Give the reader a hint about when /dev/urandom is initialized

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: Minor tweaks to Heinrich's text

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: Clarification of open questions

With his last patches for getrandom.2 Michael Kerrisk posed a few
questions and left some comments in the man-page. This patch
seeks to clarify the open issues.

 72 For example, if the call is interrupted by a signal handler,
 73 it may return a partially filled buffer, or fail with the error
 74 .BR EINTR .
 75 .\" Tested with buffer sizes > 256 bytes: both partial reads
 76 .\" and EINTR can occur, with the former being more frequent.
 77 .\"

Michael's observation agrees with the code.
For buffer size > 256: If the buffer is still empty EINTR occurs.
If any number of bytes has been read to the buffer, that number
is returned.  The comment can be removed.

 78 .\" mtk: In the absence of signals, in my testing, even very large reads
 79 .\" return full buffers. I found that reads of up to 33554431 always
 80 .\" returned a filled buffer. Specifying 'buflen' > 33554431 always
 81 .\" returned just 33554431 bytes. (I'm not sure where that number comes
        from.

The maximum number of bytes transferred is limited for
/dev/urandom to:

    nbytes = min_t(size_t, nbytes, INT_MAX >> (ENTROPY_SHIFT + 3));
    // <= 0x1fffff

and for /dev/random to
nbytes = min_t(size_t, nbytes, SEC_XFER_SIZE); // <= 0x200

Lets put this into the NOTES section.

 224 When reading from
 225 .IR /dev/random ,
 226 blocking requests of any size can be interrupted by a signal
 227 (the call fails with the error
 228 .BR EINTR ).

Thats ok.

 82 If the pool has not yet been initialized, then the call blocks, unless
 83 .B GRND_RANDOM
 84 is specified in
 85 .IR flags .
 86 .\" FIXME We need a bit more information here.
 87 .\"       The reader will ask: when is /dev/urandom initialized?
 88 .\"       There should be some text here to explain that.

Entropy is collected from different sources, e.g.
 - time of reaping a thread
 - MAC address of a network interfaces
 - Allwinner security ID
 - ROM content of a firewire device
 - ...

When more than 128 bits have been collected, the pool is set
to initialized.

I suggest that detailed information about the initialization
should be provided on the random.4 page.

I added a paragraph in the NOTES section.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: Enhance discussion of /dev/urandom reads in DESCRIPTION

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: Clarify interaction of GRND_RANDOM and signals

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: NOTES: clarify discussion of EINTR error

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: srcfix: add FIXME

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: Clarify text with respect to GRND_NONBLOCK

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: Clarify sentence on getrandom() and partial GRND_RANDOM reads

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: Reword sentence on blocked getrandom() and interruption by signals

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: Minor wording fixes

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: Rework paragraphs marked with FIXME

The patch clarifies when blocking may occur while calling
getrandom().

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: Mention bug concerning treatment of interrupts

Theodore Ts'o confirmed the bug described in
https://lkml.org/lkml/2014/11/29/16

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: Reword GRND_RANDOM description

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: Reword GRND_NONBLOCK description

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: Add a sentence to clarify the default behavior of getrandom()

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: srcfix: added FIXME

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: Minor wording fixes

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

random.4: SEE ALSO: add getrandom(2)

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

random.3: SEE ALSO: add getrandom(2)

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrandom.2: New page documenting getrandom(2)

Kernel 3.17 introduces a new system call getrandom(2).

The man page in this patch is based on the commit message by
Theodore Ts'o and suggestions by Michael Kerrisk.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

signal.7: Add F_OFD_SETLKW to list of restartable operations

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: srcfix: add mtk to copyright list

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: ERRORS: add some further error cases

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: Edits after Q&A from Vivek Goyal

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: Various additions after feedback from Vivek Goyal

Cowritten-by: Vivek Goyal <vgoyal@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: Better describe EINVAL error when nr_segments exceeds KEXEC_SEGMENT_MAX

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_file_load.2: New link to kexec_load.2

kexec_load.2: Remove crufty statements that constants are not exported to glibc

With the kernel "uapi" changes of a a few releases ago, these
constants are now automatically provided to glibc.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: Move some text from NOTES to DESCRIPTION

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: SEE ALSO: add Documentation/kernel-parameters.txt

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: SEE ALSO: add Documentation/kdump/kdump.txt

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: Edits after review comments by Vivek Goyal

Reviewed-by: Vivek Goyal <vgoyal@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: srcfix: Add Vivek Goyal to copyright notice

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: Note rationale for kexec_file_load()

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: Minor rewording

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: SEE ALSO: add kexec(8)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

reboot.2: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

reboot.2: SEE ALSO: add kexec_load(2)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: Add FIXMEs

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: srcfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: srcfix: remove a FIXME

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: kexec_file_load() requires CONFIG_KEXEC_FILE

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: CONFORMING TO: update for kexec_file_load()

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: Note kernel version for kexec_file_load()

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: Tweaks to Vivek Goyal's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kexec_load.2: Document new kexec_file_load() system call

Signed-off-by: Vivek Goyal <vgoyal@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

iconvconfig.8: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

tcp.7: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

tcp.7: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

socket.7: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthreads.7: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pipe.7: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

namespaces.7: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

ipv6.7: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

epoll.7: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

bootparam.7: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

repertoiremap.5: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

proc.5: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

st.4: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

rtc.4: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

mem.4: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

statfs.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

shmctl.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

setns.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

select_tut.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

perf_event_open.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

ioprio_set.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

execve.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

close.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

memusage.1: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

strcmp.3: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

fmemopen.3: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pow.3: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

fclose.3: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

addseverity.3: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

fflush.3: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

fflush.3: srcfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

fflush.3: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

fflush.3: POSIX.1-2008 specifies the behavior when flushing input streams

POSIX.1-2001 did not have a specification for input streams,
but POSIX.1-2008 added one.

Reported-by: Sergey V. Zubkov <cubbi@cubbi.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

fflush.3: Clarify that flushing of input streams occurs only for seekable files

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

Reported-by: Sergey V. Zubkov <cubbi@cubbi.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

locale.1: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

prctl.2: Unused arguments of PR_MPX_(EN,DIS}ABLE_MANAGEMENT must be zero

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

perf_event_open.2: srcfix: add git commit references

I noticed you were adding git commit references to the various
Linux version markers.

This adds git commit references for all Linux kernel version
notes in perf_event_open.2

mtk: I backed out two pieces of Vince's patch that were not
source comments. They can be dealt with as separate commits.

Signed-off-by: Vince Weaver <vincent.weaver@maine.edu>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

tzset.3: Clarify that first timezone format does not contain spaces

Reported-by: J William Piggott <elseifthen@gmx.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

tzset.3: Correct system timezone file path

The manual incorrectly states the system timezone
path as /usr/share/zoneinfo/localtime. Glibc does
not use that file for anything, it uses
$(prefix)/etc/localtime.

There is an ambiguous reference in the man-page to
/etc/localtime, but it does not indicate that it
will be used. It states clearly that
/usr/share/zoneinfo/localtime is used.

A comment in the glibc Makeconfig even says that
file should not exist:

> ... relative to $(zonedir).  It is a good idea
> to put this somewhere other than there, so the
> zoneinfo directory contains only universal data,
> localizing the configuration data elsewhere.

Furthermore, the man page does not indicate the
reason this file is being used; which is because
it is the configured system timezone.

A later patch in this series addresses the
possibility that /etc/localtime could be changed
during glibc's compilation. The language changed
in this patch points to the FILE section which is
where the explanation will be. There is no reason
to repeat that information multiple times
throughout the man-page.

EVIDENCE:

glibc/Makeconfig:256: sysconfdir = $(prefix)/etc
glibc/Makeconfig:272: localtime-file = $(sysconfdir)/localtime

FROM INFO LIBC:
C.2 Installing the C Library
============================
   To configure the locally used timezone, set the `TZ' environment
variable.  The script `tzselect' helps you to select the right value.
As an example, for Germany, `tzselect' would tell you to use
`TZ='Europe/Berlin''.  For a system wide installation (the given paths
are for an installation with `--prefix=/usr'), link the timezone file
which is in `/usr/share/zoneinfo' to the file `/etc/localtime'.  For
Germany, you might execute `ln -s /usr/share/zoneinfo/Europe/Berlin
/etc/localtime'.

STEPS TO REPRODUCE:

cd /usr/share/zoneinfo/
cp Antarctica/South_Pole localtime
cp /US/Eastern /etc/localtime
cd
date
Sun Jan 18 12:06:36 EST 2015
TZ=:/usr/share/zoneinfo/localtime date
Mon Jan 19 06:06:54 NZDT 2015
rm /etc/localtime
date
Sun Jan 18 17:08:37 UTC 2015
TZ=:/usr/share/zoneinfo/localtime date
Mon Jan 19 06:08:41 NZDT 2015

Signed-off-by: J William Piggott <elseifthen@gmx.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

tzset.3: Document behavior when TZ filespec omits the colon

If the TZ filespec omits the leading colon, glibc will parse
it for any valid format, i.e., it will still work.

STEPS TO REPRODUCE:
TZ=:Europe/Kiev date
Sun Jan 18 20:19:13 EET 2015
TZ=Europe/Kiev date
Sun Jan 18 20:19:20 EET 2015

Signed-off-by: J William Piggott <elseifthen@gmx.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

tzset.3: Filespec omitted incorrect

Paragraph three of the DESCRIPTION section says
that when TZ is set, but empty, then UTC is used.

Later it says if the TZ filespec is omitted then the file
/usr/share/zoneinfo/localtime is used.  This is incorrect,
it will use UTC in that case as well.

Steps to reproduce:

cd /usr/share/zoneinfo/
cp Antarctica/South_Pole localtime
cd
date
Sun Jan 18 10:59:50 EST 2015
TZ=:Hongkong date
Sun Jan 18 23:59:56 HKT 2015
TZ=:/usr/share/zoneinfo/localtime date
Mon Jan 19 05:00:03 NZDT 2015
TZ=: date
Sun Jan 18 16:00:11 UTC 2015
TZ=":" date
Sun Jan 18 16:00:18 UTC 2015
TZ=':' date
Sun Jan 18 16:00:24 UTC 2015
TZ=:/ date
Sun Jan 18 16:00:34  2015
TZ=":/" date
Sun Jan 18 16:00:40  2015
TZ="" date
Sun Jan 18 16:00:45 UTC 2015

Signed-off-by: J William Piggott <elseifthen@gmx.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

Changes.old: tfix in 3.78 changelog

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

Start of man-pages-3.79: updating Changes and Changes.old

Start of man-pages-3.79: updating .Announce and .lsm files