open_memstream: update docs wrt posix issue 8

[Collin Funk]

DJ Delorie <dj@redhat.com> writes:

> Issue 8 adds this text:
>
>   "The fseek() and fseeko() functions can be used to set the file
>    position beyond the current buffer length. It is
>    implementation-defined whether this extends the buffer to the new
>    length. If it extends the buffer, the added buffer contents shall
>    be set to null bytes for open_memstream(), or null wide characters
>    for open_wmemstream(); if it does not extend the buffer, then if
>    data is later written at this point, the buffer contents in the gap
>    shall be set to null bytes for open_memstream(), or null wide
>    characters for open_wmemstream(). If fseek() or fseeko() is called
>    with SEEK_END as the whence argument, it is implementation-defined
>    whether the file position is adjusted relative to the current
>    buffer length or relative to the buffer size that would be set by
>    an fflush() call made immediately before the fseek() or fseeko()
>    call."
>
> https://pubs.opengroup.org/onlinepubs/9799919799/functions/open_memstream.html
> https://www.austingroupbugs.net/view.php?id=1406&nbn=6
>
> To define our implementation, I propose the following, which covers
> both "it is implementation-defined whether the file position is
> adjusted relative to the current buffer length or relative to the
> buffer size" as well as addressing the original bug report that
> triggered this path:

What was the bug that triggered this path? I'm assuming it was one
someone filed on bugzilla, not the austingroup one you linked. Can you
add it to the commit message for context?

> manual: Explain our implementation-defined memstream semantics
>
> Posix Issue 8 adds an implementation-defined item we don't already
> cover, about seeking backwards.  This defines our implentation.

s/Posix/POSIX/, small nit but but it is an acronym for Portable
Operating System Interface, so it is more correct.

s/implentation/implementation/

> diff --git a/manual/stdio.texi b/manual/stdio.texi
> index 16d459424e..3ae906cdee 100644
> --- a/manual/stdio.texi
> +++ b/manual/stdio.texi
> @@ -5141,7 +5141,12 @@ is @emph{not} included in the size value stored at @var{sizeloc}.
>  You can move the stream's file position with @code{fseek} or
>  @code{fseeko} (@pxref{File Positioning}).  Moving the file position past
>  the end of the data already written fills the intervening space with
> -zeroes.
> +zeroes.  Note that seeking backwards into existing written data will
> +change the effective ``end of file'' used by @code{fflush} and
> +@code{SEEK_END}.  Thus, if you wish to do ``random-access'' I/O in a
> +memstream, it's important to use @code{fseek} to move the file
> +position to the desired data end (using @code{SEEK_POS}) before
> +flushing or closing it.
>  @end deftypefun
>  
>  Here is an example of using @code{open_memstream}:

Wording looks good based off my brief reading of the Austin Group issue.

Collin