[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
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
@@ -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