The library ei contains macros and functions to encode
and decode the Erlang binary term format.
ei allows you to convert atoms, lists, numbers, and
binaries to and from the binary format. This is useful when
writing port programs and drivers. ei uses a given
buffer, no dynamic memory (except
ei_decode_fun()) and is often quite fast.
ei also handles C-nodes, C-programs that talks Erlang
distribution with Erlang nodes (or other C-nodes) using the
Erlang distribution format.The ei library is
thread safe, and using threads, one process can handle multiple
The decode and encode functions use a buffer and an index into the
buffer, which points at the point where to encode and
decode. The index is updated to point right after the term
encoded/decoded. No checking is done whether the term fits in
the buffer or not. If encoding goes outside the buffer, the
program can crash.
All functions take two parameters:
The data is thus at buf[*index] when an
ei function is called.
All encode functions assume that the buf and
index parameters point to a buffer large enough for
the data. To get the size of an encoded term, without encoding it,
pass NULL instead of a buffer pointer. Parameter
index is incremented, but nothing will be encoded. This
is the way in ei to "preflight" term encoding.
There are also encode functions that use a dynamic buffer. It
is often more convenient to use these to encode data. All encode
functions comes in two versions; those starting with
ei_x_ use a dynamic buffer of type
All functions return 0 if successful, otherwise
-1 (for example, if a term is not of the expected
type, or the data to decode is an invalid Erlang term).
Some of the decode functions need a pre-allocated buffer. This
buffer must be allocated large enough, and for non-compound types
function returns the size required (notice that for strings an
extra byte is needed for the NULL-terminator).