From 32ac9f8049adc7a7b92c3f27286de745691ad233 Mon Sep 17 00:00:00 2001 From: Florian Weimer Date: Wed, 29 Jan 2025 10:28:10 +0100 Subject: [PATCH] manual: Update compatibility note on flushing of line-oriented files Operation systems which represent text files in a line-oriented fashion (and not as byte streams with a character sequence reserved for line termination) logically cannot flush a buffer without also creating a terminated line. Update this portability note and move it to the Binary Streams section. Add another related compatibility concern, too. --- manual/stdio.texi | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/manual/stdio.texi b/manual/stdio.texi index 747b1abf45..01b9f478dd 100644 --- a/manual/stdio.texi +++ b/manual/stdio.texi @@ -4346,6 +4346,18 @@ fail to handle lines more than 254 characters long (including the terminating newline character). @cindex lines (in a text file) +@item +If the system does not use POSIX-style in-band signalling to indicate +line termination, it can be impossibe to write anything to a text stream +without adding a line terminator. As a result, flushing a text stream +(by calling @code{fflush}, for example) may produce a logical line +terminator even if no @code{'\n'} character was written by the program. + +@item +Text files may contain lines that embed @code{'\n'} characters that are +not treated as line terminators by the system. C programs cannot read +such text files reliably using the @file{stdio.h} facilities. + @item On some systems, text files can contain only printing characters, horizontal tab characters, and newlines, and so text streams may not @@ -4838,12 +4850,6 @@ currently opened. This function is declared in the @file{stdio_ext.h} header. @end deftypefun -@strong{Compatibility Note:} Some brain-damaged operating systems have -been known to be so thoroughly fixated on line-oriented input and output -that flushing a line buffered stream causes a newline to be written! -Fortunately, this ``feature'' seems to be becoming less common. You do -not need to worry about this with @theglibc{}. - In some situations it might be useful to not flush the output pending for a stream but instead simply forget it. If transmission is costly and the output is not needed anymore this is valid reasoning. In this