erl_marshal

This module contains functions for encoding Erlang terms into
a sequence of bytes, and for decoding Erlang terms from a
sequence of bytes.

Functions

unsigned char *bufp1,*bufp2;

This function compares two encoded terms.

bufp1 is a buffer containing an encoded Erlang
term term1.

bufp2 is a buffer containing an encoded Erlang
term term2.

The function returns 0 if the terms are equal, -1 if term1
is less than term2, or 1 if term2 is less than term1.

unsigned char *bufp;

unsigned char **bufpp;

erl_decode() and erl_decode_buf() decode
the contents of a buffer and return the corresponding
Erlang term. erl_decode_buf() provides a simple
mechanism for dealing with several encoded terms stored
consecutively in the buffer.

bufp is a pointer to a buffer containing one or
more encoded Erlang terms.

bufpp is the address of a buffer pointer. The buffer
contains one or more consecutively encoded Erlang terms.
Following a successful call to erl_decode_buf(),
bufpp will be updated so that it points to the next
encoded term.

erl_decode() returns an Erlang term
corresponding to the contents of bufp on success, or
NULL on failure. erl_decode_buf() returns an Erlang
term corresponding to the first of the consecutive terms in
bufpp and moves bufpp forward to point to the
next term in the buffer. On failure, each of the functions
returns NULL.

ETERM *term;

unsigned char *bufp;

unsigned char **bufpp;

erl_encode() and erl_encode_buf() encode
Erlang terms into external format for storage or transmission.
erl_encode_buf() provides a simple mechanism for
encoding several terms consecutively in the same
buffer.

term is an Erlang term to be encoded.

bufp is a pointer to a buffer containing one or
more encoded Erlang terms.

bufpp is a pointer to a pointer to a buffer
containing one or more consecutively encoded Erlang terms.
Following a successful call to erl_encode_buf(),
bufpp will be updated so that it points to the
position for the next encoded term.

These functions returns the number of bytes written to buffer
if successful, otherwise returns 0.

Note that no bounds checking is done on the buffer. It is
the caller's responsibility to make sure that the buffer is
large enough to hold the encoded terms. You can either use a
static buffer that is large enough to hold the terms you
expect to need in your program, or use erl_term_len()
to determine the exact requirements for a given term.

The following can help you estimate the buffer
requirements for a term. Note that this information is
implementation specific, and may change in future versions.
If you are unsure, use erl_term_len().

Erlang terms are encoded with a 1 byte tag that
identifies the type of object, a 2- or 4-byte length field,
and then the data itself. Specifically:

Tuples

need 5 bytes, plus the space for each element.

Lists

need 5 bytes, plus the space for each element, and 1
additional byte for the empty list at the end.

Strings and atoms

need 3 bytes, plus 1 byte for each character (the
terminating 0 is not encoded). Really long strings (more
than 64k characters) are encoded as lists. Atoms cannot
contain more than 256 characters.

Integers

need 5 bytes.

Characters

(integers < 256) need 2 bytes.

Floating point numbers

need 32 bytes.

Pids

need 10 bytes, plus the space for the node name, which
is an atom.

Ports and Refs

need 6 bytes, plus the space for the node name, which
is an atom.

The total space required will be the result calculated
from the information above, plus 1 additional byte for a
version identifier.

unsigned char *bufp;

This function returns the number of elements in an
encoded term.

unsigned char *bufp;

This function identifies and returns the type of Erlang term encoded
in a buffer. It will skip a trailing magic identifier.
Returns 0 if the type can't be determined or one of

ERL_INTEGER

ERL_ATOM

ERL_PID /* Erlang process identifier */

ERL_PORT

ERL_REF /* Erlang reference */

ERL_EMPTY_LIST

ERL_LIST

ERL_TUPLE

ERL_FLOAT

ERL_BINARY

ERL_FUNCTION

unsigned char *bufp;

int pos;

This function is used for stepping over one or more
encoded terms in a buffer, in order to directly access a
later term.

bufp is a pointer to a buffer containing one or
more encoded Erlang terms.

pos indicates how many terms to step over in the
buffer.

The function returns a pointer to a sub-term that can be
used in a subsequent call to erl_decode() in order to retrieve
the term at that position. If there is no term, or pos
would exceed the size of the terms in the buffer, NULL is returned.

ETERM *t;

This function determines the buffer space that would be
needed by t if it were encoded into Erlang external
format by erl_encode().