binaryio: Functions for Reading and Writing Binary Data
This library provides functions for reading, writing, and converting binary data. It is designed for the use case of implementing network protocols, although this library focuses on low-level support, not high-level protocol specification.
(require binaryio) | package: binaryio-lib |
This module combines the exports of binaryio/bytes, binaryio/integer, and binaryio/float.
1 Bytes
(require binaryio/bytes) | package: binaryio-lib |
procedure
(read-bytes* len [in]) → bytes?
len : exact-nonnegative-integer? in : input-port? = (current-input-port)
> (define in (open-input-bytes #"abcde")) > (read-bytes* 4 in) #"abcd"
> (read-bytes* 2 in) read-bytes*: unexpected end of input
tried to read: 2 bytes
available: 1 bytes
received: #"e"
procedure
(write-null-terminated-bytes bstr [ out start end]) → void? bstr : bytes? out : output-port? = (current-output-port) start : exact-nonnegative-integer? = 0 end : exact-nonnegative-integer? = (bytes-length bstr)
If bstr contains any null bytes between start and end, an error is raised.
procedure
(read-null-terminated-bytes [in]) → bytes?
in : input-port? = (current-input-port)
> (define-values (in out) (make-pipe)) > (write-null-terminated-bytes #"abcde" out) > (read-null-terminated-bytes in) #"abcde"
2 Integers
(require binaryio/integer) | package: binaryio-lib |
procedure
(integer->bytes val size signed? [ big-endian? dest start]) → bytes? val : exact-integer? size : exact-positive-integer? signed? : boolean? big-endian? : boolean? = #t dest : (and/c bytes? (not/c mutable?)) = (make-bytes size) start : exact-nonnegative-integer? = 0
> (integer->bytes -1 3 #t) #"\377\377\377"
> (integer->bytes (expt 23 31) 18 #f) #"\22\305U2\375\302\332\26_\5\6\235q\30~\253\6\247"
procedure
(bytes->integer bstr signed? [ big-endian? start end]) → exact-integer? bstr : bytes? signed? : boolean? big-endian? : boolean? = #t start : exact-nonnegative-integer? = 0 end : exact-nonnegative-integer? = (bytes-length bstr)
procedure
(integer-bytes-length val signed?) → exact-nonnegative-integer?
val : exact-integer? signed? : boolean?
> (integer-bytes-length 127 #t) 1
> (integer-bytes-length 128 #t) 2
procedure
(integer-bytes-length<=? val nbytes signed?) → boolean?
val : exact-integer? nbytes : exact-nonnegative-integer? signed? : boolean?
procedure
(write-integer val size signed? [ out big-endian?]) → void? val : exact-integer? size : exact-positive-integer? signed? : boolean? out : output-port? = (current-output-port) big-endian? : boolean? = #t
Equivalent to (write-bytes (integer->bytes val size signed? big-endian?) out).
procedure
(read-integer size signed? [in big-endian?]) → exact-integer?
size : exact-positive-integer? signed? : boolean? in : input-port? = (current-input-port) big-endian? : boolean? = #t
Equivalent to (bytes->integer (read-bytes* size in) signed? big-endian?).
3 Floating-point
(require binaryio/float) | package: binaryio-lib |
procedure
(write-float val size [out big-endian?]) → void?
val : real? size : (or/c 4 8) out : output-port? = (current-output-port) big-endian? : boolean? = #t
procedure
(read-float size [in big-endian?]) → real?
size : (or/c 4 8) in : input-port? = (current-input-port) big-endian? : boolean? = #t
4 Binary Reader
(require binaryio/reader) | package: binaryio-lib |
Added in version 1.1 of package binaryio-lib.
procedure
(make-binary-reader in [ #:limit limit #:error-handler error-handler]) → binary-reader? in : input-port? limit : (or/c exact-nonnegative-integer? #f) = #f error-handler : (binary-reader-error-handler? #f) = #f
Convenience functions for reading binary encodings of integers and floating-point numbers of different lengths, endianness, etc.
The error-handler hook for customizing error message. See make-binary-reader-error-handler for details.
Automatic handling of short reads. If in returns eof or fewer bytes than requested in a read operation on the binary reader, the error-handler is used to raise an error. Thus, for example, the caller of (b-read-bytes br len) can rely on receiving a bytestring of exactly len bytes.
A stack of limits, maintained with b-push-limit and b-pop-limit. On every read operation, the limits are decremented by the number of bytes read. If a read operation requests more bytes than the current limit, the error-handler is used to raise an error.
Binary readers are not thread-safe. Be careful when interleaving uses of a binary reader with direct uses of its input port. For example, direct reads from in do not count against limits imposed on the binary reader.
procedure
(binary-reader? v) → boolean?
v : any/c
procedure
(make-binary-reader-error-handler [ #:error error-callback #:show-data? show-data?-callback]) → binary-reader-error-handler?
error-callback : (or/c #f (->* [binary-reader? symbol? string?] [] #:rest list? none/c)) = #f
show-data?-callback : (or/c #f (-> binary-reader? symbol? boolean?)) = #f
When an error occurs, the error-callback is called with the binary reader, the name of the function that raised the error, and a format string and arguments for the error message. If error-callback is #f, the error procedure is called instead (omitting the binary reader argument). The error-callback must escape, typically by throwing an exception; if it returns an exception is raised.
When a short read occurs, the show-data?-callback determines whether the error message contains the data actually read.
procedure
v : any/c
procedure
(b-get-limit br) → (or/c exact-nonnegative-integer? #f)
br : binary-reader?
procedure
(b-at-limit? br) → boolean?
br : binary-reader?
procedure
(b-at-limit/eof? br) → boolean?
br : binary-reader?
procedure
(b-push-limit br limit) → void?
br : binary-reader? limit : exact-nonnegative-integer?
procedure
(b-pop-limit br) → void?
br : binary-reader?
procedure
(b-check-exhausted br what) → void?
br : binary-reader? what : (or/c string? #f)
procedure
(b-read-bytes br len) → bytes?
br : binary-reader? len : exact-nonnegative-integer?
procedure
(b-read-bytes! br bs [start end]) → exact-nonnegative-integer?
br : binary-reader? bs : bytes? start : exact-nonnegative-integer? = 0 end : exact-nonnegative-integer? = (bytes-length bs)
procedure
(b-read-byte br) → byte?
br : binary-reader?
procedure
(b-read-integer br size signed? [big-endian?]) → exact-integer?
br : binary-reader? size : exact-positive-integer? signed? : boolean? big-endian? : boolean? = #t
procedure
(b-read-float br size [big-endian?]) → real?
br : binary-reader? size : (or/c 4 8) big-endian? : boolean? = #t
procedure
(b-read-be-int br size) → exact-integer?
br : binary-reader? size : exact-positive-integer?
procedure
(b-read-be-uint br size) → exact-nonnegative-integer?
br : binary-reader? size : exact-positive-integer?
procedure
(b-read-le-int br size) → exact-integer?
br : binary-reader? size : exact-positive-integer?
procedure
(b-read-le-uint br size) → exact-integer?
br : binary-reader? size : exact-positive-integer?
procedure
br : binary-reader?
5 Fixup Ports
Added in version 1.1 of package binaryio-lib.
(require binaryio/fixup-port) | package: binaryio-lib |
procedure
Operations on fixup ports are not thread-safe.
procedure
(fixup-port? v) → boolean?
v : any/c
procedure
(push-fixup fp [size]) → void?
fp : fixup-port? size : (or/c exact-positive-integer? #f) = #f
procedure
fp : fixup-port? fixup : (-> exact-nonnegative-integer? bytes?)
If the fixup was created with size size, then (fixup len) must return exactly size bytes, otherwise an error is raised.
procedure
(fixup-port-flush fp out) → void?
fp : fixup-port? out : output-port?