Re: no new modules 'freading', 'fwriting'

[Eric Blake]

Bruno Haible <bruno <at> clisp.org> writes:

> 
> Eric Blake wrote:
> > I'm checking this in now, since I needed it to fix fflush on mingw (see
> > next email).
> 
> Thanks. This was hard to understand, so I'm adding some comments.

I'm improving them somewhat, as well as the documentation for freading/fwriting.

2007-04-27  Eric Blake  <address@hidden>

        * lib/freading.h: Improve comments.
        * lib/fwriting.h: Likewise.
        * lib/fflush.c: Likewise.

Index: lib/fflush.c
===================================================================
RCS file: /sources/gnulib/gnulib/lib/fflush.c,v
retrieving revision 1.7
diff -u -r1.7 fflush.c
--- lib/fflush.c        27 Apr 2007 10:56:51 -0000      1.7
+++ lib/fflush.c        27 Apr 2007 18:02:32 -0000
@@ -46,11 +46,13 @@
      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 @@
     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 @@
     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
Index: lib/freading.h
===================================================================
RCS file: /sources/gnulib/gnulib/lib/freading.h,v
retrieving revision 1.1
diff -u -r1.1 freading.h
--- lib/freading.h      26 Apr 2007 13:16:50 -0000      1.1
+++ lib/freading.h      27 Apr 2007 18:02:32 -0000
@@ -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  */
Index: lib/fwriting.h
===================================================================
RCS file: /sources/gnulib/gnulib/lib/fwriting.h,v
retrieving revision 1.1
diff -u -r1.1 fwriting.h
--- lib/fwriting.h      26 Apr 2007 13:16:50 -0000      1.1
+++ lib/fwriting.h      27 Apr 2007 18:02:32 -0000
@@ -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 */