.TH erl_marshal 3erl "erl_interface 3.7.7" "Ericsson AB" "C Library Functions"
.SH NAME
erl_marshal \- Encoding and Decoding of Erlang terms
.SH DESCRIPTION
.LP
This module contains functions for encoding Erlang terms into a sequence of bytes, and for decoding Erlang terms from a sequence of bytes\&.
.SH EXPORTS
.LP
.B
interl_compare_ext(bufp1, bufp2)
.br
.RS
.LP
Types:

.RS 3
unsigned char *bufp1,*bufp2;
.br
.RE
.RE
.RS
.LP
This function compares two encoded terms\&.
.LP
\fIbufp1\fR\& is a buffer containing an encoded Erlang term term1\&.
.LP
\fIbufp2\fR\& is a buffer containing an encoded Erlang term term2\&.
.LP
The function returns 0 if the terms are equal, -1 if term1 is less than term2, or 1 if term2 is less than term1\&.
.RE

.LP
.B
ETERM *erl_decode(bufp)
.br
.B
ETERM *erl_decode_buf(bufpp)
.br
.RS
.LP
Types:

.RS 3
unsigned char *bufp;
.br
unsigned char **bufpp;
.br
.RE
.RE
.RS
.LP
\fIerl_decode()\fR\& and \fIerl_decode_buf()\fR\& decode the contents of a buffer and return the corresponding Erlang term\&. \fIerl_decode_buf()\fR\& provides a simple mechanism for dealing with several encoded terms stored consecutively in the buffer\&.
.LP
\fIbufp\fR\& is a pointer to a buffer containing one or more encoded Erlang terms\&.
.LP
\fIbufpp\fR\& is the address of a buffer pointer\&. The buffer contains one or more consecutively encoded Erlang terms\&. Following a successful call to \fIerl_decode_buf()\fR\&, \fIbufpp\fR\& will be updated so that it points to the next encoded term\&.
.LP
\fIerl_decode()\fR\& returns an Erlang term corresponding to the contents of \fIbufp\fR\& on success, or NULL on failure\&. \fIerl_decode_buf()\fR\& returns an Erlang term corresponding to the first of the consecutive terms in \fIbufpp\fR\& and moves \fIbufpp\fR\& forward to point to the next term in the buffer\&. On failure, each of the functions returns NULL\&.
.RE

.LP
.B
interl_encode(term, bufp)
.br
.B
interl_encode_buf(term, bufpp)
.br
.RS
.LP
Types:

.RS 3
ETERM *term;
.br
unsigned char *bufp;
.br
unsigned char **bufpp;
.br
.RE
.RE
.RS
.LP
\fIerl_encode()\fR\& and \fIerl_encode_buf()\fR\& encode Erlang terms into external format for storage or transmission\&. \fIerl_encode_buf()\fR\& provides a simple mechanism for encoding several terms consecutively in the same buffer\&.
.LP
\fIterm\fR\& is an Erlang term to be encoded\&.
.LP
\fIbufp\fR\& is a pointer to a buffer containing one or more encoded Erlang terms\&.
.LP
\fIbufpp\fR\& is a pointer to a pointer to a buffer containing one or more consecutively encoded Erlang terms\&. Following a successful call to \fIerl_encode_buf()\fR\&, \fIbufpp\fR\& will be updated so that it points to the position for the next encoded term\&.
.LP
These functions returns the number of bytes written to buffer if successful, otherwise returns 0\&.
.LP
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 \fIerl_term_len()\fR\& to determine the exact requirements for a given term\&.
.LP
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 \fIerl_term_len()\fR\&\&.
.LP
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:
.RS 2
.TP 2
.B
\fITuples\fR\&:
need 5 bytes, plus the space for each element\&.
.TP 2
.B
\fILists\fR\&:
need 5 bytes, plus the space for each element, and 1 additional byte for the empty list at the end\&.
.TP 2
.B
\fIStrings and atoms\fR\&:
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\&.
.TP 2
.B
\fIIntegers\fR\&:
need 5 bytes\&.
.TP 2
.B
\fICharacters\fR\&:
(integers < 256) need 2 bytes\&.
.TP 2
.B
\fIFloating point numbers\fR\&:
need 32 bytes\&.
.TP 2
.B
\fIPids\fR\&:
need 10 bytes, plus the space for the node name, which is an atom\&.
.TP 2
.B
\fIPorts and Refs\fR\&:
need 6 bytes, plus the space for the node name, which is an atom\&.
.RE
.LP
The total space required will be the result calculated from the information above, plus 1 additional byte for a version identifier\&.
.RE

.LP
.B
interl_ext_size(bufp)
.br
.RS
.LP
Types:

.RS 3
unsigned char *bufp;
.br
.RE
.RE
.RS
.LP
This function returns the number of elements in an encoded term\&.
.RE

.LP
.B
unsigned charerl_ext_type(bufp)
.br
.RS
.LP
Types:

.RS 3
unsigned char *bufp;
.br
.RE
.RE
.RS
.LP
This function identifies and returns the type of Erlang term encoded in a buffer\&. It will skip a trailing \fImagic\fR\& identifier\&. Returns \fI0\fR\& if the type can\&'t be determined or one of
.RS 2
.TP 2
*
ERL_INTEGER
.LP
.TP 2
*
ERL_ATOM
.LP
.TP 2
*
ERL_PID \fI/* Erlang process identifier */\fR\&
.LP
.TP 2
*
ERL_PORT
.LP
.TP 2
*
ERL_REF \fI/* Erlang reference */\fR\&
.LP
.TP 2
*
ERL_EMPTY_LIST
.LP
.TP 2
*
ERL_LIST
.LP
.TP 2
*
ERL_TUPLE
.LP
.TP 2
*
ERL_FLOAT
.LP
.TP 2
*
ERL_BINARY
.LP
.TP 2
*
ERL_FUNCTION
.LP
.RE

.RE

.LP
.B
unsigned char *erl_peek_ext(bufp, pos)
.br
.RS
.LP
Types:

.RS 3
unsigned char *bufp;
.br
int pos;
.br
.RE
.RE
.RS
.LP
This function is used for stepping over one or more encoded terms in a buffer, in order to directly access a later term\&.
.LP
\fIbufp\fR\& is a pointer to a buffer containing one or more encoded Erlang terms\&.
.LP
\fIpos\fR\& indicates how many terms to step over in the buffer\&.
.LP
The function returns a pointer to a sub-term that can be used in a subsequent call to \fIerl_decode()\fR\& in order to retrieve the term at that position\&. If there is no term, or \fIpos\fR\& would exceed the size of the terms in the buffer, NULL is returned\&.
.RE

.LP
.B
interl_term_len(t)
.br
.RS
.LP
Types:

.RS 3
ETERM *t;
.br
.RE
.RE
.RS
.LP
This function determines the buffer space that would be needed by \fIt\fR\& if it were encoded into Erlang external format by \fIerl_encode()\fR\&\&.
.LP
The size in bytes is returned\&.
.RE