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

[Florian Weimer]

The implementation was changed in commit 3d759cb8d32614667f58688899f,
but the manual was not updated.

Warn that linked stream handling for stdout may introduce deadlocks.

---
v2: Warn about deadlocks.  Try to clarify the linked stream behavior.
 manual/stdio.texi | 27 +++++++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/manual/stdio.texi b/manual/stdio.texi
index 01b9f478dd..cc715668f2 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 requiring 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

base-commit: 5429bae110e2f094482b3f7974b3ce9b4bfdab57