[PATCH v2] Document limitations on streams passed to freopen

[Carlos O'Donell]

On 9/6/24 3:41 PM, Joseph Myers wrote:
> 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".

I was looking at his recently in light of Aaron's double-fclose test.

LGTM.

Reviewed-by: Carlos O'Donell <carlos@redhat.com>

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

OK. You write "original values", but the standard might say "at program startup" as
it does with errno. I interpret them to be the same and I think it is sensible to
interpret "original value" as "at program startup."

> +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})
>