[PATCH v2] Document limitations on streams passed to freopen

[Joseph Myers]

On Fri, 6 Sep 2024, Florian Weimer wrote:

> We support reassignment of stdin etc., so please say something like “the
> original values of the standatd streams @code{stdin}”.  Assignment to
> stdin does not magically make freopen valid.

Fixed in this version.


Document limitations on streams passed to freopen

As recently discussed, document that freopen does not work with
streams opened with functions such as popen, fmemopen, open_memstream
or fopencookie.  I've filed
<https://austingroupbugs.net/view.php?id=1855> to clarify this issue
in POSIX.

Tested with "make info" and "make html".

---

Changed in v2: specify that it's the original values of the standard
streams that are supported, rather than some non-fopen-opened stream
that might have been assigned to them.

diff --git a/manual/stdio.texi b/manual/stdio.texi
index 29888a361f..8590ae955a 100644
--- a/manual/stdio.texi
+++ b/manual/stdio.texi
@@ -330,6 +330,14 @@ this ability, so using @code{freopen} is more portable.
 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
 32 bit machine this function is in fact @code{freopen64} since the LFS
 interface replaces transparently the old interface.
+
+@Theglibc{} only supports use of @code{freopen} on streams opened with
+@code{fopen} or @code{fopen64} and on the original values of the
+standard streams @code{stdin}, @code{stdout}, and @code{stderr}; such
+a stream may be reopened multiple times with @code{freopen}.  If it is
+called on another kind of stream (opened with functions such as
+@code{popen}, @code{fmemopen}, @code{open_memstream}, and
+@code{fopencookie}), @code{freopen} fails and returns a null pointer.
 @end deftypefun
 
 @deftypefun {FILE *} freopen64 (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})

-- 
Joseph S. Myers
josmyers@redhat.com