* lib/freading.h: Improve comments.

* lib/fwriting.h: Likewise.
* lib/fflush.c: Likewise.

diff --git a/ChangeLog b/ChangeLog
index 7d8e5c3f2ec95e4b9230e1ca9d650c90bd1883af..b6897fb3123d080254891b639d518bc1e46ac9fd 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
 2007-04-27  Eric Blake  <ebb9@byu.net>
 
+       * lib/freading.h: Improve comments.
+       * lib/fwriting.h: Likewise.
+       * lib/fflush.c: Likewise.
+
        Fix closein for mingw.
        * modules/closein-tests: Add tests for closein.
        * tests/test-closein.c: New file.

diff --git a/lib/fflush.c b/lib/fflush.c
index 2d814957fa229da592f699dd4c26a63017a4a902..459a7107072d457f01b2e8a0feaff15f78e2d564 100755 (executable)
--- a/lib/fflush.c
+++ b/lib/fflush.c
@@ -46,11 +46,13 @@ rpl_fflush (FILE *stream)
      recent operation was not input", POSIX and C99 requires that fflush
      writes out any buffered data, and all implementations do this.
 
-     When stream is, however, an input stream or an update stream in which
-     the most recent operation was input, POSIX and C99 specify nothing.
-     mingw, in particular, drops the input buffer, leaving the file descriptor
-     positioned at the end of the input buffer. I.e. ftell (stream) is lost.
-     We don't want to call the implementation's fflush in this case.
+     When stream is, however, an input stream or an update stream in
+     which the most recent operation was input, C99 specifies nothing,
+     and POSIX only specifies behavior if the stream is seekable.
+     mingw, in particular, drops the input buffer, leaving the file
+     descriptor positioned at the end of the input buffer. I.e. ftell
+     (stream) is lost.  We don't want to call the implementation's
+     fflush in this case.
 
      We test ! freading (stream) here, rather than fwriting (stream), because
      what we need to know is whether the stream holds a "read buffer", and on
@@ -59,7 +61,8 @@ rpl_fflush (FILE *stream)
     return fflush (stream);
 
   /* POSIX does not specify fflush behavior for non-seekable input
-     streams.  */
+     streams.  Some implementations purge unread data, some return
+     EBADF, some do nothing.  */
   pos = ftello (stream);
   if (pos == -1)
     {
@@ -79,7 +82,7 @@ rpl_fflush (FILE *stream)
     return EOF;
   /* After a successful lseek, update the file descriptor's position cache
      in the stream.  */
-#if defined __sferror               /* FreeBSD, NetBSD, OpenBSD, MacOS X, Cygwin */
+#if defined __sferror           /* FreeBSD, NetBSD, OpenBSD, MacOS X, Cygwin */
   stream->_offset = pos;
   stream->_flags |= __SOFF;
 #endif

diff --git a/lib/freading.h b/lib/freading.h
index e0db1f7d055f61483ffb8b38cd17857aa33eca38..1845de1a85572497f319480e66bad92abaa60d10 100644 (file)
--- a/lib/freading.h
+++ b/lib/freading.h
@@ -18,10 +18,17 @@
 #include <stdbool.h>
 #include <stdio.h>
 
-/* Return true if the stream STREAM is opened read-only, or if the last
-   operation on the stream was a read operation.  Return false if the stream
-   supports writing and the last operation on it was a write operation or
-   there was no such operation.
+/* Return true if the stream STREAM is opened read-only, or if the
+   last operation on the stream was a read operation.  Return false if
+   the stream is opened write-only or append-only, or if it supports
+   writing and there is no current read operation (such as fputc).
+
+   freading and fwriting will never both be true.  If STREAM supports
+   both reads and writes, then both freading and fwriting might be
+   false when the stream is first opened, after repositioning (such as
+   fseek, fsetpos, or rewind), after read encounters EOF, or after
+   fflush, depending on the underlying implementation.
+
    STREAM must not be wide-character oriented.  */
 
 #if HAVE___FREADING && !defined __GLIBC__ /* Solaris >= 7, not glibc >= 2.2  */

diff --git a/lib/fwriting.h b/lib/fwriting.h
index 07037ef1288eb393e74c767aa43ca0afd4f5695f..b354186c85877d1a1a801e34214af80253a4dc0c 100644 (file)
--- a/lib/fwriting.h
+++ b/lib/fwriting.h
@@ -18,10 +18,18 @@
 #include <stdbool.h>
 #include <stdio.h>
 
-/* Return true if the stream STREAM is opened write-only or append-only, or
-   if the last operation on the stream was a write operation.  Return false
-   if the stream supports reading and the last operation on it was a read
-   operation or there was no such operation.
+/* Return true if the stream STREAM is opened write-only or
+   append-only, or if the last operation on the stream was a write
+   operation.  Return false if the stream is opened read-only, or if
+   it supports reading and there is no current write operation (such
+   as fputc).
+
+   freading and fwriting will never both be true.  If STREAM supports
+   both reads and writes, then both freading and fwriting might be
+   false when the stream is first opened, after repositioning (such as
+   fseek, fsetpos, or rewind), after read encounters EOF, or after
+   fflush, depending on the underlying implementation.
+
    STREAM must not be wide-character oriented.  */
 
 #if HAVE___FWRITING /* glibc >= 2.2, Solaris >= 7 */