6.14.2 Binary I/O

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.

Scheme Procedure: get-u8 port

C Function: scm_get_u8 (port)

Return an octet read from port, an input port, blocking as necessary, or the end-of-file object.

Scheme Procedure: lookahead-u8 port

C Function: scm_lookahead_u8 (port)

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.

Scheme Procedure: eof-object? x

C Function: scm_eof_object_p (x)

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.

Scheme Procedure: get-bytevector-n port count

C Function: scm_get_bytevector_n (port, count)

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.

Scheme Procedure: get-bytevector-n! port bv start count

C Function: scm_get_bytevector_n_x (port, bv, start, count)

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.

Scheme Procedure: get-bytevector-some port

C Function: scm_get_bytevector_some (port)

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.

Scheme Procedure: get-bytevector-some! port bv start count

C Function: scm_get_bytevector_some_x (port, bv, start, count)

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.

Scheme Procedure: get-bytevector-all port

C Function: scm_get_bytevector_all (port)

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).

Scheme Procedure: unget-bytevector port bv [start [count]]

C Function: scm_unget_bytevector (port, bv, start, count)

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.

Scheme Procedure: put-u8 port octet

C Function: scm_put_u8 (port, octet)

Write octet, an integer in the 0–255 range, to port, a binary output port.

Scheme Procedure: put-bytevector port bv [start [count]]

C Function: scm_put_bytevector (port, bv, start, count)

Write the contents of bv to port, optionally starting at index start and limiting to count octets.