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

Reviewed-by: Florian Weimer <fweimer@redhat.com>
Reviewed-by Collin Funk <collin.funk1@gmail.com>

diff --git a/manual/stdio.texi b/manual/stdio.texi
index 16d459424e8fd200e9659ee4af2705f2fdf1010f..e8f60b09c1c9f5a4d8df0ffa4b7132ba07c1e2c2 100644 (file)
--- a/manual/stdio.texi
+++ b/manual/stdio.texi
@@ -5135,13 +5135,21 @@ remain valid only as long as no further output on the stream takes
 place.  If you do more output, you must flush the stream again to store
 new values before you use them again.
 
-A null character is written at the end of the buffer.  This null character
-is @emph{not} included in the size value stored at @var{sizeloc}.
+A null character is written at the end of the buffer when the stream
+is flushed, and at the current location when closed (these locations
+may be different if @code{fseek} is used).  This null character 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.
+@code{fseeko} (@pxref{File Positioning}).  Moving the file position
+past the end of the data already written fills the intervening space
+with zeroes.  Note that seeking backwards into existing written data
+will change the effective ``end of file'' used by @code{fflush} and
+@code{SEEK_END} (and where the trailing null character is written,
+when closed).  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
+closing it.
 @end deftypefun
 
 Here is an example of using @code{open_memstream}: