file-get-buf: size limit, seek offset.

* share/txr/stdlib/getput.tl (sys:get-buf-common): Take two
more arguments for maximum bytes to read and offset.
Read loop simplified with fill-buf-adjust.
(file-get-buf, command-get-buf): Take two new arguments,
pass though to sys:get-buf-common.

* txr.1: Documented.

1 files changed, 21 insertions, 3 deletions

diff --git a/txr.1 b/txr.1
index c94e2fb0..25ce4255 100644
--- a/txr.1
+++ b/txr.1
@@ -24947,15 +24947,15 @@ adjusts the length of the buffer to match the position that is returned.
 
 .coNP Functions @ file-get-buf and @ command-get-buf
 .synb
-.mets (file-get-buf << name )
-.mets (command-get-buf << cmd )
+.mets (file-get-buf < name >> [ max-bytes <> [ skip-bytes ]])
+.mets (command-get-buf < cmd >> [ max-bytes <> [ skip-bytes ]])
 .syne
 .desc
 The
 .code file-get-buf
 function opens a binary stream over the file indicated by the string argument
 .meta name
-for reading. The entire file is read and its contents are returned as a
+for reading. By default, the entire file is read and its contents are returned as a
 buffer object. The buffer's length corresponds to the number of bytes
 read from the file.
 
@@ -24969,6 +24969,24 @@ as if by the
 function.  It read bytes from the pipe until the indication that no more
 input is available. The bytes are returned aggregated into a buffer object.
 
+If the
+.meta max-bytes
+parameter is given an argument, it must be a non-negative integer.
+That value specifies a limit on the number of bytes to read. A buffer
+no longer than
+.meta max-bytes
+shall be returned.
+
+If the
+.meta skip-bytes
+parameter is given an argument, it must be a non-negative integer.
+That value specifies how many initial bytes of the input should be
+discarded before accumulation of the buffer begins.
+If possible, the semantics of this parameter is achieved by performing a
+.code seek-stream
+operation, falling back on reading and discarding bytes if the
+stream doesn't support seeking.
+
 .coNP Functions @, file-put-buf @ file-append-buf and @ command-put-buf
 .synb
 .mets (file-put-buf < name << buf )