Guile’s ports are fundamentally binary in nature: at the lowest level, they work on bytes. This section describes Guile’s core binary I/O operations. See Textual I/O, for input and output of strings and characters.
To use these routines, first include the binary I/O module:
(use-modules (ice-9 binary-ports))
Note that although this module’s name suggests that binary ports are some different kind of port, that’s not the case: all ports in Guile are both binary and textual ports.
Return an octet read from port, an input port, blocking as necessary, or the end-of-file object.
Like get-u8 but does not update port’s position to point
past the octet.
The end-of-file object is unlike any other kind of object: it’s not a
pair, a symbol, or anything else. To check if a value is the
end-of-file object, use the eof-object? predicate.
Return #t if x is an end-of-file object, or #f
otherwise.
Note that unlike other procedures in this module, eof-object? is
defined in the default environment.
Read count octets from port, blocking as necessary and return a bytevector containing the octets read. If fewer bytes are available, a bytevector smaller than count is returned.
Read count bytes from port and store them in bv starting at index start. Return either the number of bytes actually read or the end-of-file object.
Read from port, blocking as necessary, until bytes are available or an end-of-file is reached. Return either the end-of-file object or a new bytevector containing some of the available bytes (at least one), and update the port position to point just past these bytes.
Read up to count bytes from port, blocking as necessary until at least one byte is available or an end-of-file is reached. Store them in bv starting at index start. Return the number of bytes actually read, or an end-of-file object.
Read from port, blocking as necessary, until the end-of-file is reached. Return either a new bytevector containing the data read or the end-of-file object (if no data were available).
Place the contents of bv in port, optionally starting at index start and limiting to count octets, so that its bytes will be read from left-to-right as the next bytes from port during subsequent read operations. If called multiple times, the unread bytes will be read again in last-in first-out order.
To perform binary output on a port, use put-u8 or
put-bytevector.
Write octet, an integer in the 0–255 range, to port, a binary output port.
Write the contents of bv to port, optionally starting at index start and limiting to count octets.
R7RS defines the following binary I/O procedures. Access them with
(use-modules (scheme base))
Returns a binary output port that will accumulate bytes
for retrieval by get-output-bytevector.
Writes byte to the given binary output port out and returns
an unspecified value. out defaults to (current-output-port).
See also put-u8.
Returns the next byte available from the binary input port in,
updating the port to point to the following byte. If no more bytes are
available, an end-of-file object is returned. in defaults to
(current-input-port).
See also get-u8.
Returns the next byte available from the binary input port in,
but without updating the port to point to the following
byte. If no more bytes are available, an end-of-file object
is returned. in defaults to (current-input-port).
See also lookahead-u8.
Returns a bytevector consisting of the bytes that have been output to
port so far in the order they were output. It is an error if
port was not created with
open-output-bytevector.
(define out (open-output-bytevector)) (write-u8 1 out) (write-u8 2 out) (write-u8 3 out) (get-output-bytevector out) ⇒ #vu8(1 2 3)
Takes a bytevector bv and returns a binary input port that delivers bytes from bv.
(define in (open-input-bytevector #vu8(1 2 3))) (read-u8 in) ⇒ 1 (peek-u8 in) ⇒ 2 (read-u8 in) ⇒ 2 (read-u8 in) ⇒ 3 (read-u8 in) ⇒ #<eof>
Reads the next end - start bytes, or as many as are available before the end of file, from the binary input port into the bytevector bv in left-to-right order beginning at the start position. If end is not supplied, reads until the end of bv has been reached. If start is not supplied, reads beginning at position 0.
Returns the number of bytes read. If no bytes are available, an end-of-file object is returned.
(define in (open-input-bytevector #vu8(1 2 3))) (define bv (make-bytevector 5 0)) (read-bytevector! bv in 1 3) ⇒ 2 bv ⇒ #vu8(0 1 2 0 0 0)
Reads the next k bytes, or as many as are available before the end of file if that is less than k, from the binary input port in into a newly allocated bytevector in left-to-right order, and returns the bytevector. If no bytes are available before the end of file, an end-of-file object is returned.
(define bv #vu8(1 2 3)) (read-bytevector 2 (open-input-bytevector bv)) ⇒ #vu8(1 2) (read-bytevector 10 (open-input-bytevector bv)) ⇒ #vu8(1 2 3)
Writes the bytes of bytevector bv from start to end in left-to-right order to the binary output port. start defaults to 0 and end defaults to the length of bv.
(define out (open-output-bytevector)) (write-bytevector #vu8(0 1 2 3 4) out 2 4) (get-output-bytevector out) ⇒ #vu8(2 3)