Library for reading and writing binary data.

Upstream URL


Peter Seibel <>, Manuel Giraud <>


Not determined



This library should be a drop in replacement for monkeylib-binary-data described in Peter Seibel's excellent book: you should start here.

It also contains the following optionals enhancements.

1.1definition/access of octet size of objects

When defining a new binary-type, in addition to :reader and:writer definition, you can set a :size to calculate the octetsize of this new type. You can then access this size withtype-size

Here is an example from common-datatypes.lisp (that comes with binary-io ;-)

;;; Unsigned integers
(define-binary-type unsigned-integer (bits)
  (:reader (fd)
	   (assert (equal (stream-element-type fd) '(unsigned-byte 8)))
	   (let ((byte-indexes (byte-indexes bits *endianness*))
		 (value 0))
	     (dolist (i byte-indexes value)
	       (setf (ldb (byte 8 i) value) (read-byte fd)))))
  (:writer (fd value)
	   (assert (equal (stream-element-type fd) '(unsigned-byte 8)))
	   (let ((byte-indexes (byte-indexes bits *endianness*)))
	     (dolist (i byte-indexes)
	       (write-byte (ldb (byte 8 i) value) fd))))
  (:size () (ceiling bits 8)))

(define-binary-type u2 () (unsigned-integer :bits 16))

(type-size 'u2) ;; -> 2

type-size method also works for binary class.

(define-binary-class test-size ()
  ((a u2)
   (b u2)))

(type-size 'test-size) ;; -> 4

1.2optional initform for slots

You can precise an optional initform for a slot as a third value inthe slot spec of a binary class definition:
(define-binary-class foo-header ()
  ((tag (8bit-string :length 4 :terminator #\Nul) "FOO")
   (counter u2 0)))

(tag (make-instance 'foo-header)) ;; -> "FOO"

1.3a word of warning

binary-io is useful if you have some "complex" data structures thatwill be easily mapped by some define-binary-class. But if youhave binary data that are mostly arrays of the same type, you'dbetter use read-sequence directly (with the correctelement-type on the stream).

I have made some measurement on SBCL and a (binary-io:read-value :vector) is about 3 times slower than an equivalent (read-sequence).

Dependencies (3)

  • 1am
  • alexandria
  • ieee-floats

Dependents (1)

  • GitHub
  • Quicklisp