doc: revise description of truncation and seeking.

* txr.1: Fix text saying that positioning operations
are not supported on string input streams, and
that seeking beyond the end is not allowed.
Extend descriptions of seek-stream and truncate-stream
to mention behaviors and which streams support them.

1 files changed, 51 insertions, 2 deletions

diff --git a/txr.1 b/txr.1
index 1dfdfff0..6eed1ff2 100644
--- a/txr.1
+++ b/txr.1
@@ -66905,7 +66905,16 @@ from the byte sequence. Both
 and
 .code unget-char
 are supported.
-Output and positioning operations are not supported.
+
+Output operations are not supported.
+
+The
+.code truncate-stream
+operation is likewise not supported, and it is an error to attempt to use
+.code seek-stream
+to produce a position beyond the end of
+.metn string ,
+producing an exception.
 
 .coNP Function @ make-strlist-input-stream
 .synb
@@ -67819,6 +67828,18 @@ and the previous position wasn't zero, then the position is decremented by one.
 On failure, it throws an exception of type
 .codn stream-error .
 
+Seeking is supported by streams attached to file-like objects.
+Several kinds of streams support seeking: file streams attached
+to seekable files, buffers streams as well as string input
+streams, string byte input streams and string output streams.
+
+The exact semantics of seeking to a position beyond the end of the
+file-like object depends on the type of object. Regular file
+objects on POSIX platforms allow the position to exceed the
+size of the file. When one or more bytes are written at such
+a position, the file's size is extended to include the bytes,
+and the intervening bytes are all given zero values.
+
 .coNP Function @ truncate-stream
 .synb
 .mets (truncate-stream < stream <> [ length ])
@@ -67832,7 +67853,10 @@ to be set to
 .meta length
 bytes.
 
-The stream must be a file stream, and must be open for writing.
+If the stream is a file stream, then the host platform may imposes additional
+conditions: the stream may be required to be attached to a
+file capable of supporting the operation, and may have to be open
+for writing.
 
 If
 .meta length
@@ -67849,6 +67873,31 @@ Hence, after the
 .code truncate-stream
 operation, that position is one byte past the end of the file.
 
+File streams support
+.code truncate-stream
+as well as string output streams created by
+.codn make-string-output-stream ,
+and buffer stream created by
+.codn make-buf-stream .
+
+The underlying file-like object associated with the stream may
+be made larger using
+.code truncate-stream
+as well as smaller.
+What byte value fills the newly-created space depends on the
+stream type.
+The precise semantics of truncating to a length below the read/write
+position also depends on the stream type.
+
+For files,
+.code truncate-stream
+fills newly created space with zero bytes. Truncating a file to below the
+current position is permitted, and depends on the host platform and the type of
+file. On POSIX systems, a regular file will take on the specified size, causing
+the position to lie outside of the file. If a write operation is issued for at
+least one byte then the file is extended to cover the last byte written,
+and any intervening bytes which come into existence are given values of zero.
+
 .coNP Functions @ stream-get-prop and @ stream-set-prop
 .synb
 .mets (stream-get-prop < stream << indicator )