Re: Change http: to https: and update URLs

[Bruno Haible]

Hi Paul,

> feel free to further improve the citations, wording, quoting, etc.

OK...

> > There are a few nits, though:
> >    * http://www.w3.org/TR/html401/loose.dtd is not a URL; it's a 
> > declaration.
> 
> Thanks, that should be fixed in the attached patch.

Thanks.

> >    * I don't find it adequate to remove comments in
> >        lib/creat.c
> >        lib/fopen.c
> >        lib/open.c
> >        lib/openat.c
> >        tests/test-fflush2.c
> >      I mean, just pointing to a 13-page long document
> >        
> > https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html
> >      as a rationale for some small technical decision really obscures the
> >      technical argument.
> 
> True, however the problem was the POSIX wording got considerably longer, 
> and at some point the lengthy comment was going to be more trouble than 
> it was worth. I attempted to fix this in the attached patch by 
> paraphrasing rather than quoting, and by using an id in the URL to point 
> to the relevant section of the document.

If the URL with the id was a stable one (like the ones produced by makeinfo
for GNU documentation), that would be sufficient for me. But a tag #tag_04_13
is not future-proof: it may well change in future POSIX revisions. Therefore
I prefer to add a citation.

> the POSIX wording got considerably longer

Huh? The essential wording is now just a single sentence. It's easier to cite
than before.

> >    * What happened to point 3 in lib/fflush.c?
> 
> It was supposed to be subsumed into point 2, since we can now refer to 
> the updated POSIX rather than to the old POSIX plus an Austin bug 
> report. However, I didn't subsume it well, since this is fflush.c so the 
> comment should cite the fflush spec rather than the ungetc spec. I 
> attempted to fix this in the attached patch.

I reword it further, to make it clear that "file position indicator" and
"file offset" (of the underlying file descriptor) are really different things.


2019-09-28  Bruno Haible  <address@hidden>

        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.

diff --git a/lib/creat.c b/lib/creat.c
index e63b219..4b075e1 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/fopen.c b/lib/fopen.c
index 07e3891..69ba5b9 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 0623d38..0c2742b 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 25ffd77..8aaee49 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/lib/fflush.c b/lib/fflush.c
index 63862be..d5d9f30 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/tests/test-fflush2.c b/tests/test-fflush2.c
index e7bfa65..4caf868 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 == '#');