From ead34780b88448b7ccd9ffd18968a3cef76aa14c Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Sun, 16 Sep 2012 10:37:16 -0700
Subject: [PATCH] doc: document sticky-EOF issue

* doc/posix-functions/fgetc.texi (fgetc):
* doc/posix-functions/fgets.texi (fgets):
* doc/posix-functions/fread.texi (fread):
* doc/posix-functions/fscanf.texi (fscanf):
* doc/posix-functions/getc.texi (getc):
* doc/posix-functions/getchar.texi (getchar):
* doc/posix-functions/scanf.texi (scanf):
Mention that glibc and default Solaris do not conform to
C99 and POSIX-2001 or later, with respect to how getchar
etc. behave when feof reports nonzero.
---
 ChangeLog                        | 14 ++++++++++++++
 doc/posix-functions/fgetc.texi   |  7 +++++++
 doc/posix-functions/fgets.texi   |  7 +++++++
 doc/posix-functions/fread.texi   |  7 +++++++
 doc/posix-functions/fscanf.texi  |  7 +++++++
 doc/posix-functions/getc.texi    |  7 +++++++
 doc/posix-functions/getchar.texi |  7 +++++++
 doc/posix-functions/scanf.texi   |  7 +++++++
 8 files changed, 63 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index c724864c50..268292b107 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2012-09-16  Paul Eggert  <eggert@cs.ucla.edu>
+
+	doc: document sticky-EOF issue
+	* doc/posix-functions/fgetc.texi (fgetc):
+	* doc/posix-functions/fgets.texi (fgets):
+	* doc/posix-functions/fread.texi (fread):
+	* doc/posix-functions/fscanf.texi (fscanf):
+	* doc/posix-functions/getc.texi (getc):
+	* doc/posix-functions/getchar.texi (getchar):
+	* doc/posix-functions/scanf.texi (scanf):
+	Mention that glibc and default Solaris do not conform to
+	C99 and POSIX-2001 or later, with respect to how getchar
+	etc. behave when feof reports nonzero.
+
 2012-09-13  Joachim Schmitz <jojo@schmitz-digital.de>  (tiny change)
 
 	poll: fix poll(0, NULL, msec)
diff --git a/doc/posix-functions/fgetc.texi b/doc/posix-functions/fgetc.texi
index acf7ad7d24..55033fa258 100644
--- a/doc/posix-functions/fgetc.texi
+++ b/doc/posix-functions/fgetc.texi
@@ -18,6 +18,13 @@ mingw, MSVC 9.
 Portability problems not fixed by Gnulib:
 @itemize
 @item
+C99 and POSIX-2001 and later require end-of-file to be sticky, that
+is, they require this function to act as if it reads end-of-file if
+@code{feof} would return nonzero.  However, on some systems this
+function attempts to read from the underlying file descriptor even if
+the stream's end-of-file indicator is set.  These systems include
+glibc and default Solaris.
+@item
 On Windows platforms (excluding Cygwin), this function does not set @code{errno}
 upon failure.
 @item
diff --git a/doc/posix-functions/fgets.texi b/doc/posix-functions/fgets.texi
index b14917e964..2eb8aa20d4 100644
--- a/doc/posix-functions/fgets.texi
+++ b/doc/posix-functions/fgets.texi
@@ -18,6 +18,13 @@ mingw, MSVC 9.
 Portability problems not fixed by Gnulib:
 @itemize
 @item
+C99 and POSIX-2001 and later require end-of-file to be sticky, that
+is, they require this function to act as if it reads end-of-file if
+@code{feof} would return nonzero.  However, on some systems this
+function attempts to read from the underlying file descriptor even if
+the stream's end-of-file indicator is set.  These systems include
+glibc and default Solaris.
+@item
 On Windows platforms (excluding Cygwin), this function does not set @code{errno}
 upon failure.
 @end itemize
diff --git a/doc/posix-functions/fread.texi b/doc/posix-functions/fread.texi
index 1d642495c9..626d61fdfa 100644
--- a/doc/posix-functions/fread.texi
+++ b/doc/posix-functions/fread.texi
@@ -18,6 +18,13 @@ mingw, MSVC 9.
 Portability problems not fixed by Gnulib:
 @itemize
 @item
+C99 and POSIX-2001 and later require end-of-file to be sticky, that
+is, they require this function to act as if it reads end-of-file if
+@code{feof} would return nonzero.  However, on some systems this
+function attempts to read from the underlying file descriptor even if
+the stream's end-of-file indicator is set.  These systems include
+glibc and default Solaris.
+@item
 On Windows platforms (excluding Cygwin), this function does not set @code{errno}
 upon failure.
 @item
diff --git a/doc/posix-functions/fscanf.texi b/doc/posix-functions/fscanf.texi
index fef2e51a29..cd3d6ec1b8 100644
--- a/doc/posix-functions/fscanf.texi
+++ b/doc/posix-functions/fscanf.texi
@@ -18,6 +18,13 @@ mingw, MSVC 9.
 Portability problems not fixed by Gnulib:
 @itemize
 @item
+C99 and POSIX-2001 and later require end-of-file to be sticky, that
+is, they require this function to act as if it reads end-of-file if
+@code{feof} would return nonzero.  However, on some systems this
+function attempts to read from the underlying file descriptor even if
+the stream's end-of-file indicator is set.  These systems include
+glibc and default Solaris.
+@item
 On Windows platforms (excluding Cygwin), this function does not set @code{errno}
 upon failure.
 @item
diff --git a/doc/posix-functions/getc.texi b/doc/posix-functions/getc.texi
index 514b0f76a4..2069cdcb2b 100644
--- a/doc/posix-functions/getc.texi
+++ b/doc/posix-functions/getc.texi
@@ -18,6 +18,13 @@ mingw, MSVC 9.
 Portability problems not fixed by Gnulib:
 @itemize
 @item
+C99 and POSIX-2001 and later require end-of-file to be sticky, that
+is, they require this function to act as if it reads end-of-file if
+@code{feof} would return nonzero.  However, on some systems this
+function attempts to read from the underlying file descriptor even if
+the stream's end-of-file indicator is set.  These systems include
+glibc and default Solaris.
+@item
 On Windows platforms (excluding Cygwin), this function does not set @code{errno}
 upon failure.
 @end itemize
diff --git a/doc/posix-functions/getchar.texi b/doc/posix-functions/getchar.texi
index 3acea34058..37ee44b9da 100644
--- a/doc/posix-functions/getchar.texi
+++ b/doc/posix-functions/getchar.texi
@@ -18,6 +18,13 @@ mingw, MSVC 9.
 Portability problems not fixed by Gnulib:
 @itemize
 @item
+C99 and POSIX-2001 and later require end-of-file to be sticky, that
+is, they require this function to act as if it reads end-of-file if
+@code{feof} would return nonzero.  However, on some systems this
+function attempts to read from the underlying file descriptor even if
+the stream's end-of-file indicator is set.  These systems include
+glibc and default Solaris.
+@item
 On Windows platforms (excluding Cygwin), this function does not set @code{errno}
 upon failure.
 @end itemize
diff --git a/doc/posix-functions/scanf.texi b/doc/posix-functions/scanf.texi
index 0c4e2643f1..0948e5f208 100644
--- a/doc/posix-functions/scanf.texi
+++ b/doc/posix-functions/scanf.texi
@@ -18,6 +18,13 @@ mingw, MSVC 9.
 Portability problems not fixed by Gnulib:
 @itemize
 @item
+C99 and POSIX-2001 and later require end-of-file to be sticky, that
+is, they require this function to act as if it reads end-of-file if
+@code{feof} would return nonzero.  However, on some systems this
+function attempts to read from the underlying file descriptor even if
+the stream's end-of-file indicator is set.  These systems include
+glibc and default Solaris.
+@item
 On Windows platforms (excluding Cygwin), this function does not set @code{errno}
 upon failure.
 @item
-- 
2.39.5