Description
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 C-nodes.
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 ei_x_buff
.
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 the ei_get_type()
function returns the size required (notice that for strings an extra byte is needed for the NULL
-terminator).