open_memstream: update docs wrt posix issue 8

[DJ Delorie]

Collin Funk <collin.funk1@gmail.com> writes:
> 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?

https://issues.redhat.com/browse/RHEL-3008

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

Noted, but the patch started at "patch starts here" since I had a lot of
preliminary text to add.  Same patch attached but with updated commit
text.

---------- patch starts here ----------

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.

https://issues.redhat.com/browse/RHEL-3008
https://pubs.opengroup.org/onlinepubs/9799919799/functions/open_memstream.html

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