get-bytevector-n!, read-bytevector! - read bytes from a port into a bytevector
LIBRARY
(import (rnrs)) ;R6RS
(import (rnrs io ports)) ;R6RS
(import (scheme base)) ;R7RS
SYNOPSIS
;; R6RS
(get-bytevector-n! binary-input-port bytevector start count)
;; R7RS
(read-bytevector! bytevector)
(read-bytevector! bytevector binary-input-port)
(read-bytevector! bytevector binary-input-port start)
(read-bytevector! bytevector binary-input-port start end)
DESCRIPTION
Reads from
binary-input-port,
blocking as necessary, until
count
bytes are available from
binary-input-port
or until an end of file is reached. The return value depends on the
result of the read operation:
-
If count bytes are available before an end of file, they are
written into
bytevector
starting at index
start,
and the result is
count.
-
If fewer bytes are available
before the next end of file, the available bytes are written
into
bytevector
starting at index
start,
and the result is a number object representing the number of bytes
actually read.
-
If an end of file is reached before any bytes are available, an
end-of-file object is returned.
The input port is updated to point just past the bytes read.
- R7RS
-
The procedure call
(read-bytevector! bv port start end)
procedure is analogous to
(get-bytevector-n! port bv start (- end start)).
The argument
binary-input-port
defaults to the object returned by
current-input-port(3scm),
start
defaults to 0, and
end
defaults to the length of
bytevector.
- Multiple end-of-file conditions
-
The port may return an end-of-file object and then still keep
producing data if another read is attempted. Files do not normally
work this way, but it is possible for other types of ports to do so,
such as terminals. R6RS explicitly mentions this situation while R7RS
does not.
RETURN VALUES
Returns a single value; an exact nonnegative integer, or an
end-of-file object.
- R6RS
-
There is a single, unique end-of-file object.
EXAMPLES
;; Apologies for the nonsensical example.
(call-with-port (open-file-input-port "/dev/zero")
(lambda (p)
(let ((bv (make-bytevector 4 1)))
(get-bytevector-n! p bv 1 1)
bv)))
=> #vu8(1 0 1 1)
APPLICATION USAGE
This procedure is suitable when when you need to read binary data
directly into a buffer, which tends to be the case for some types of
binary structures. Other times it is more appropriate to use
get-bytevector-n(3scm),
which will automatically give you a bytevector limited to the
length of the data returned by the read operation.
ERRORS
This procedure can raise exceptions with the following condition types:
- &assertion (R6RS)
-
The wrong number of arguments was passed or an argument was outside its domain.
In particular,
start
and
count
must be exact, nonnegative integer objects,
and
bytevector
must be a mutable bytevector with at least
start+count
elements.
- &i/o-read (R6RS)
-
There was an I/O error during the read operation.
- &i/o-port (R6RS)
-
This condition specifies the port object related to an
&i/o-read
condition.
- R7RS
-
The assertions described above are errors.
Implementations may signal an error, extend the procedure's
domain of definition to include such arguments,
or fail catastrophically.
SEE ALSO
get-bytevector-n(3scm),
get-bytevector-some(3scm),
get-bytevector-all(3scm),
eof-object?(3scm)
STANDARDS
R6RS,
R7RS
HISTORY
Reports prior to R6RS did not support binary I/O.
AUTHORS
This page is part of the
scheme-manpages
project.
It includes materials from the RnRS documents.
More information can be found at
https://github.com/schemedoc/manpages/
.
BUGS
The default port used by
read-bytevector!
is the current input port, which is normally a textual port that is
not expected to support binary I/O.
Markup created by unroff 1.0sc, March 04, 2023.