+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.
#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
#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
<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
#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>
#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,
#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)
# 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,
# 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)
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 == '#');