Michael Kerrisk [Thu, 17 Dec 2015 08:36:37 +0000 (09:36 +0100)]
random_r.3: Clarify need to use initstate_r()
As noted by Archie Cobbs:
I was trying to use srandom_() and initstate_r() and fell into
the exact same trap this this fellow did:
http://stackoverflow.com/questions/18569523/segfault-at-srandom-r,
resulting in a segfault.
The man page is really unclear here. It leads one to believe
(falsely) that invoking setrandom_r() is sufficient to initialize
a struct random_data, but this is not the case. In fact
srandom_r() is not like srandom() at all in this respect.
Reported-by: Archie Cobbs <archie.cobbs@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Wed, 16 Dec 2015 15:35:30 +0000 (16:35 +0100)]
futex.2: Clarify "total ordering" a little
Comments from Davidlohr:
So there are two things here regarding ordering. One is the
most obvious which is ordered due to the taking/dropping the
hb spinlock. Secondly, its the cases which Peter brought up
a while ago that involves atomic futex ops futex_atomic_*(),
which do not have clearly defined semantics, and you get
inconsistencies with certain archs (tile being the worst
iirc).
But anyway, the important thing users need to know about is
that the atomic futex operation must be totally ordered wrt
any other user tasks that are trying to access that address.
This is not necessarily the case for kernel ops. Peter
illustrates this nicely with lock stealing example; (see
https://lkml.org/lkml/2015/8/26/596).
Internally, I believe we decided that making it fully ordered
(as opposed to making use of implicit barriers for
ACQUIRE/RELEASE), so you'd end up having an MB ll/sc MB kind of
setup.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> Reported-by: Davidlohr Bueso <dave@stgolabs.net>
Laurent Georget [Fri, 11 Dec 2015 20:10:04 +0000 (21:10 +0100)]
sendfile.2: Document more ERRORS
sendfile(2) can return more error codes than are
documented in sendfile(2). This patch adds some details:
- EINVAL can be returned if count is negative; from function
rw_verify_area in fs/read_write.c, called from do_sendfile,
called from sys_sendfile.
- EOVERFLOW can be returned if count is too large; from
rw_verify_area, called from do_sendfile, called from
sys_sendfile, or directly from do_sendfile in one case
(pos + count > max size of either in_fd or out_fd).
- ESPIPE can be returned if offset is not a NULL pointer but
the input file does not support FMODE_PREAD;
from do_sendfile, called from sys_sendfile.
Signed-off-by: Laurent Georget <laurent.georget@supelec.fr> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Carlos O'Donell [Thu, 10 Dec 2015 22:05:02 +0000 (17:05 -0500)]
tzset.3: Clarify "daylight" and remove erroneous note
When tzset is run the value of daylight is computed
by looking at all available rules for the application
of daylight savings. This includes reading the tzdata
files to determine if there is a transition or not for
the current timezone. It also includes parsing TZ env
to see if it specifies custom rules which are used in
precedence to any tzdata rules. Therefore daylight is
going to be set if there is a daylight saving rule past,
present, or future that indicates a transition. We clarify
that in the man page.
Lastly, the note about tz_dsttime is not correct and is
removed. The earlier paragraph about daylight makes it
clear that it doesn't mean "daylight saving rule applies
now", and the interaction with tz_dsttime is not correct
for glibc on Linux (as outlined in my gettimeofday.3 patch
sent here: http://marc.info/?l=linux-man&m=144977768703615&w=2).
Signed-off-by: Carlos O'Donell <carlos@redhat.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Carlos O'Donell [Thu, 10 Dec 2015 20:01:25 +0000 (15:01 -0500)]
gettimeofday.2: Expand on the historic historical meaning of tz_dsttime
Given that the NOTES in question are willing to discuss
history, I have clarified the use of tz_dsttime for non-Linux
and Linux to allow the reader to contrast that with the older
system usage.
On a non-Linux glibc the meaning of tz_dsttime is exactly
that of daylight for the current zone. It has been this way
since the beginning of glibc:
iconv.3: NOTES: describe correct usage for flushing partially buffered input
The following came up yesterday on the wget list.
The iconv.3 man page says
"... 2. The input byte sequence has been entirely converted,
i.e. *inbytesleft has gone down to 0."
and
"A different case is when inbuf is NULL or *inbuf is NULL,
but outbuf is not NULL and *outbuf is not NULL. In this case,
the iconv function attempts to set cd's conversion state to the
initial state and store a corresponding shift sequence at
*outbuf."
The POSIX page says
"For state-dependent encodings, the conversion descriptor cd is
placed into its initial shift state by a call for which inbuf
is a null pointer, or for which inbuf points to a null pointer.
When iconv() is called in this way, and if outbuf is not a null
pointer or a pointer to a null pointer, and outbytesleft points
to a positive value, iconv() shall place, into the output buffer,
the byte sequence to change the output buffer to its initial
shift state."
These texts are slightly misleading, in the sense that, in the
present implementation, iconv() may implement conversion
from an encoding that is not state-dependent in a way that
uses an artificial shift state to store lookahead bytes.
That means that after conversion, when *inbytesleft has gone
down to 0, it may be that contrary to what iconv.3 suggests not
all output has been stored, and a final flushing call is needed.
Maybe this violates POSIX.
A minimal warning is added by this patch.
--- man-pages-4.03/man3/iconv.3 2015-12-05 10:45:25.000000000 +0100
+++ ./iconv.3 2015-12-16 01:41:38.253049938 +0100
@@ -161,6 +161,11 @@
.SH CONFORMING TO
POSIX.1-2001, POSIX.1-2008.
.SH NOTES
+In each series of calls to
+.BR iconv (),
+the last should be one with \fIinbuf\fP or \fI*inbuf\fP equal to NULL,
+in order to flush out any partially converted input.
+
Although
.I inbuf
and
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Thu, 30 Jul 2015 07:17:53 +0000 (09:17 +0200)]
futex.2: Remove warning that FUTEX_REQUEUE is broken
Darren Hart pointed me to the comments from Rich Felker
that there are valid use cases for FUTEX_REQUEUE.
From: Rich Felker <dalias@libc.org>
Date: Wed, 29 Oct 2014 22:43:17 -0400
To: Darren Hart <dvhart@infradead.org> Cc: GLIBC Devel <libc-alpha@sourceware.org>, ...
Subject: Re: Add futex wrapper to glibc?
On Wed, Oct 29, 2014 at 06:59:15PM -0700, Darren Hart wrote:
[...]
> I wonder though... can we not wrap FUTEX_REQUEUE? It's fundamentally
> broken. FUTEX_CMP_REQUEUE should *always* be used instead. The glibc
> wrapper is one way to encourage developers to do the right thing
> (don't expose the bad op in the header).
You're mistaken here. There are plenty of valid ways to use
FUTEX_REQUEUE - for example if the calling thread is requeuing the
target(s) to a lock that the calling thread owns. Just because it
doesn't meet the needs of the way glibc was using it internally
doesn't mean it's useless for other applications.
Reported-by: Darren Hart <dvhart@infradead.org> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
projects / thirdparty / man-pages.git / log
