[v3] manual: Describe glibc's limited linked stream handling

Message ID 87ed0lhkeo.fsf@oldenburg.str.redhat.com (mailing list archive)
State New
Headers
Series [v3] manual: Describe glibc's limited linked stream handling |

Checks

Context Check Description
redhat-pt-bot/TryBot-apply_patch success Patch applied to master at the time it was sent
linaro-tcwg-bot/tcwg_glibc_build--master-aarch64 success Build passed
linaro-tcwg-bot/tcwg_glibc_build--master-arm success Build passed
linaro-tcwg-bot/tcwg_glibc_check--master-arm success Test passed
linaro-tcwg-bot/tcwg_glibc_check--master-aarch64 success Test passed
redhat-pt-bot/TryBot-32bit success Build for i686

Commit Message

Florian Weimer Jan. 29, 2025, 12:30 p.m. UTC
  The implementation was changed in commit 3d759cb8d32614667f58688899f,
but the manual was not updated.

Warn that linked stream handling for stdout may introduce deadlocks.

---
v3: Fix typo identified by Andreas.
 manual/stdio.texi | 27 +++++++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)


base-commit: 5429bae110e2f094482b3f7974b3ce9b4bfdab57
  

Patch

diff --git a/manual/stdio.texi b/manual/stdio.texi
index 01b9f478dd..16b759e57c 100644
--- a/manual/stdio.texi
+++ b/manual/stdio.texi
@@ -513,6 +513,13 @@  themselves would ensure only atomicity of their own operation, but not
 atomicity over all the function calls.  For this it is necessary to
 perform the stream locking in the application code.
 
+@strong{Portability note:} @Theglibc{} may attempt to flush the
+@code{stdout} stream when input occurs on another stream.
+@xref{Flushing Buffers}.  If @code{stdout} has been locked using
+@code{flockfile} or @code{ftrylockfile} while reading from another
+stream, a deadlock may occur.  @Theglibc{} does not implement the
+deadlock detection that POSIX recommends for flushing linked streams.
+
 @deftypefun void flockfile (FILE *@var{stream})
 @standards{POSIX, stdio.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
@@ -4805,8 +4812,24 @@  When the program terminates by calling @code{exit}.
 When a newline is written, if the stream is line buffered.
 
 @item
-Whenever an input operation on @emph{any} stream actually reads data
-from its file.
+@c See the stdout reference in _IO_new_file_underflow.
+When reading from a line-buffered or unbuffered stream and the stream's
+buffer is empty or becomes empty, and the stream being read is the
+original @code{stdin} stream at program start, or has been created using
+@code{fopen} or @code{fdopen}, a line-buffered @code{stdout} stream is
+flushed if it is the original @code{stdout} stream or has been created
+using @code{fopen} or @code{fdopen}.  (The @code{fopen64} function
+counts as @code{fopen} in this regard.)  That is, reading from a stream
+may implicitly flush the @code{stdout} stream under specific
+circumstances.
+
+This exact behavior is specific to @theglibc{}.  According to some
+interpretations of POSIX, such flushing is required for all buffered
+output streams, not just @code{stdout}.  Other C libraries may not
+implement such linked stream handling at all.  A future version of
+@theglibc{} may remove the limited linked stream handling described
+above.  Portable programs cannot rely on this implicit flushing
+behavior.
 @end itemize
 
 If you want to flush the buffered output at another time, call