* 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>
 
 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.
        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.
 
      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
 
      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
     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)
     {
   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.  */
     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
   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>
 
 #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  */
    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>
 
 #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 */
    STREAM must not be wide-character oriented.  */
 
 #if HAVE___FWRITING /* glibc >= 2.2, Solaris >= 7 */