Update comments that refer to POSIX.

* lib/creat.c, lib/fopen.c, lib/open.c, lib/openat.c: Cite the relevant
sentence about trailing slashes.
* lib/fflush.c: Clarify the reasoning.
* tests/test-fflush2.c: Cite the relevant sentence.

7 files changed, 55 insertions, 9 deletions

diff --git a/ChangeLog b/ChangeLog
index cde7792e1a..51812c5650 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,13 @@
 2019-09-28  Bruno Haible  <bruno@clisp.org>
 
+	Update comments that refer to POSIX.
+	* lib/creat.c, lib/fopen.c, lib/open.c, lib/openat.c: Cite the relevant
+	sentence about trailing slashes.
+	* lib/fflush.c: Clarify the reasoning.
+	* tests/test-fflush2.c: Cite the relevant sentence.
+
+2019-09-28  Bruno Haible  <bruno@clisp.org>
+
 	access: Document limitations on Windows.
 	Suggested by Zaretskii <eliz@gnu.org>.
 	* doc/posix-functions/access.texi: Mention two limitations on Windows.
diff --git a/lib/creat.c b/lib/creat.c
index e63b219576..4b075e12c1 100644
--- a/lib/creat.c
+++ b/lib/creat.c
@@ -46,7 +46,11 @@ creat (const char *filename, mode_t mode)
 #if OPEN_TRAILING_SLASH_BUG
   /* Fail if the filename ends in a slash,
      as POSIX says such a filename must name a directory
-     <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13>.
+     <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13>:
+       "A pathname that contains at least one non-<slash> character and that
+        ends with one or more trailing <slash> characters shall not be resolved
+        successfully unless the last pathname component before the trailing
+        <slash> characters names an existing directory"
      creat() is defined as being equivalent to open() with flags
      O_CREAT | O_TRUNC | O_WRONLY.  Therefore:
      If the named file already exists as a directory, then creat() must fail
diff --git a/lib/fflush.c b/lib/fflush.c
index 63862be19e..d5d9f305b0 100644
--- a/lib/fflush.c
+++ b/lib/fflush.c
@@ -159,8 +159,9 @@ rpl_fflush (FILE *stream)
 
 #else
   {
-    /* Notes about the file-position indicator:
-       1) The file position indicator is incremented by fgetc() and decremented
+    /* What POSIX says:
+       1) About the file-position indicator (-> fseeko, ftello):
+          The file position indicator is incremented by fgetc() and decremented
           by ungetc():
           <https://pubs.opengroup.org/onlinepubs/9699919799/functions/fgetc.html>
             "... the fgetc() function shall ... advance the associated file
@@ -172,8 +173,14 @@ rpl_fflush (FILE *stream)
           <https://pubs.opengroup.org/onlinepubs/9699919799/functions/fflush.html>
             "...any characters pushed back onto the stream by ungetc()
              or ungetwc() that have not subsequently been read from the
-             stream shall be discarded (without further changing the
-             file offset)."  */
+             stream shall be discarded..."
+          This implies implicitly: fflush does not change the file position
+          indicator.
+       3) Effects on the file descriptor, if the file descriptor is capable of
+          seeking:
+          <https://pubs.opengroup.org/onlinepubs/9699919799/functions/fflush.html>
+            "...the file offset of the underlying open file description shall
+             be set to the file position of the stream..."  */
 
     /* POSIX does not specify fflush behavior for non-seekable input
        streams.  Some implementations purge unread data, some return
diff --git a/lib/fopen.c b/lib/fopen.c
index 07e3891796..69ba5b968c 100644
--- a/lib/fopen.c
+++ b/lib/fopen.c
@@ -55,7 +55,11 @@ rpl_fopen (const char *filename, const char *mode)
 #if FOPEN_TRAILING_SLASH_BUG
   /* Fail if the mode requires write access and the filename ends in a slash,
      as POSIX says such a filename must name a directory
-     <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13>.
+     <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13>:
+       "A pathname that contains at least one non-<slash> character and that
+        ends with one or more trailing <slash> characters shall not be resolved
+        successfully unless the last pathname component before the trailing
+        <slash> characters names an existing directory"
      If the named file already exists as a directory, then if a mode that
      requires write access is specified, fopen() must fail because POSIX
      <https://pubs.opengroup.org/onlinepubs/9699919799/functions/fopen.html>
diff --git a/lib/open.c b/lib/open.c
index 0623d381a2..0c2742bbda 100644
--- a/lib/open.c
+++ b/lib/open.c
@@ -94,7 +94,11 @@ open (const char *filename, int flags, ...)
 #if OPEN_TRAILING_SLASH_BUG
   /* Fail if one of O_CREAT, O_WRONLY, O_RDWR is specified and the filename
      ends in a slash, as POSIX says such a filename must name a directory
-     <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13>.
+     <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13>:
+       "A pathname that contains at least one non-<slash> character and that
+        ends with one or more trailing <slash> characters shall not be resolved
+        successfully unless the last pathname component before the trailing
+        <slash> characters names an existing directory"
      If the named file already exists as a directory, then
        - if O_CREAT is specified, open() must fail because of the semantics
          of O_CREAT,
@@ -164,6 +168,12 @@ open (const char *filename, int flags, ...)
 #if OPEN_TRAILING_SLASH_BUG
   /* If the filename ends in a slash and fd does not refer to a directory,
      then fail.
+     Rationale: POSIX says such a filename must name a directory
+     <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13>:
+       "A pathname that contains at least one non-<slash> character and that
+        ends with one or more trailing <slash> characters shall not be resolved
+        successfully unless the last pathname component before the trailing
+        <slash> characters names an existing directory"
      If the named file without the slash is not a directory, open() must fail
      with ENOTDIR.  */
   if (fd >= 0)
diff --git a/lib/openat.c b/lib/openat.c
index 25ffd770e0..8aaee49fd1 100644
--- a/lib/openat.c
+++ b/lib/openat.c
@@ -84,7 +84,11 @@ rpl_openat (int dfd, char const *filename, int flags, ...)
 # if OPEN_TRAILING_SLASH_BUG
   /* Fail if one of O_CREAT, O_WRONLY, O_RDWR is specified and the filename
      ends in a slash, as POSIX says such a filename must name a directory
-     <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13>.
+     <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13>:
+       "A pathname that contains at least one non-<slash> character and that
+        ends with one or more trailing <slash> characters shall not be resolved
+        successfully unless the last pathname component before the trailing
+        <slash> characters names an existing directory"
      If the named file already exists as a directory, then
        - if O_CREAT is specified, open() must fail because of the semantics
          of O_CREAT,
@@ -130,6 +134,12 @@ rpl_openat (int dfd, char const *filename, int flags, ...)
 # if OPEN_TRAILING_SLASH_BUG
   /* If the filename ends in a slash and fd does not refer to a directory,
      then fail.
+     Rationale: POSIX says such a filename must name a directory
+     <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13>:
+       "A pathname that contains at least one non-<slash> character and that
+        ends with one or more trailing <slash> characters shall not be resolved
+        successfully unless the last pathname component before the trailing
+        <slash> characters names an existing directory"
      If the named file without the slash is not a directory, open() must fail
      with ENOTDIR.  */
   if (fd >= 0)
diff --git a/tests/test-fflush2.c b/tests/test-fflush2.c
index e7bfa654d8..4caf868a0e 100644
--- a/tests/test-fflush2.c
+++ b/tests/test-fflush2.c
@@ -69,7 +69,10 @@ main (int argc, char **argv)
            according to the Austin Group's resolution on 2009-01-08.  */
         /* Check that fflush after a non-backup ungetc() call discards the
            ungetc buffer.  This is mandated by POSIX
-           <https://pubs.opengroup.org/onlinepubs/9699919799/functions/fflush.html>  */
+           <https://pubs.opengroup.org/onlinepubs/9699919799/functions/fflush.html>:
+             "...any characters pushed back onto the stream by ungetc()
+              or ungetwc() that have not subsequently been read from the
+              stream shall be discarded..."  */
 
         c = fgetc (stdin);
         ASSERT (c == '#');