Re: mmap stdio breaks GNU ld

[Paul Eggert <eggert at twinsun dot com>]

> Date: Tue, 22 Jan 2002 02:13:31 -0600
> From: Mark Brown <bmark@us.ibm.com>

> This sounds like a minor documentation issue.

Here's a proposed patch to the documentation about this issue:

2001-01-22  Paul Eggert  <eggert@twionsun.com>

	* manual/llio.texi (Linked Channels, Cleaning Streams):
	Make it clearer that a just-opened input stream might need cleaning.

--- manual/llio.texi	Tue Jan 22 00:41:05 2002
+++ manual/llio1.texi	Tue Jan 22 00:53:34 2002
@@ -935,7 +935,8 @@ random-access files, all append-type out
 linked to each other.
 
 @cindex cleaning up a stream
-If you have been using a stream for I/O, and you want to do I/O using
+If you have been using a stream for I/O (or have just opened the stream),
+and you want to do I/O using
 another channel (either a stream or a descriptor) that is linked to it,
 you must first @dfn{clean up} the stream that you have been using.
 @xref{Cleaning Streams}.
@@ -1007,7 +1008,8 @@ You can skip the @code{fclean} or @code{
 is already clean.  A stream is clean whenever its buffer is empty.  For
 example, an unbuffered stream is always clean.  An input stream that is
 at end-of-file is clean.  A line-buffered stream is clean when the last
-character output was a newline.
+character output was a newline.  However, a just-opened input stream
+might not be clean, as its input buffer might not be empty.
 
 There is one case in which cleaning a stream is impossible on most
 systems.  This is when the stream is doing input from a file that is not




> Yes, POSIX doesn't make clear that "the position indicated by the
> file offset" could be anywhere".

That's being generous, as POSIX obscures the issue so much that light
barely escapes.  For example, here's a quote from the POSIX 1003.1-2001
section "Interaction of File Descriptors and Standard I/O Streams":

   * If any previous active handle has been used by a function that
     explicitly changed the file offset, except as required above for
     the first handle, the application shall perform an lseek( ) or
     fseek( ) (as appropriate to the type of handle) to an appropriate
     location.

I still can't parse the phrase "except as required above for the first
handle", and I've read the context several times.

The glibc documentation in this area is much clearer.