.TH erl_marshal 3 "erl_interface  3.5.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
int erl_compare_ext(bufp1, bufp2)
.br
.RS
.TP
Types
unsigned char *bufp1, *bufp2;
.br
.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
.TP
Types
unsigned char *bufp;
.br
unsigned char **bufpp;
.br
.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
int erl_encode(term, bufp)
.br
.B
int erl_encode_buf(term, bufpp)
.br
.RS
.TP
Types
ETERM *term;
.br
unsigned char *bufp;
.br
unsigned char **bufpp;
.br
.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 4
.B
\fITuples\fR:
need 5 bytes, plus the space for each element\&.
.TP 4
.B
\fILists\fR:
need 5 bytes, plus the space for each element, and 1 additional byte for the empty list at the end\&.
.TP 4
.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 4
.B
\fIIntegers\fR:
need 5 bytes\&.
.TP 4
.B
\fICharacters\fR:
(integers < 256) need 2 bytes\&.
.TP 4
.B
\fIFloating point numbers\fR:
need 32 bytes\&.
.TP 4
.B
\fIPids\fR:
need 10 bytes, plus the space for the node name, which is an atom\&.
.TP 4
.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
int erl_ext_size(bufp)
.br
.RS
.TP
Types
unsigned char *bufp;
.br
.RE
.RS
.LP
This function returns the number of elements in an encoded term\&.
.RE
.LP
.B
unsigned char erl_ext_type(bufp)
.br
.RS
.TP
Types
unsigned char *bufp;
.br
.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
.TP 2
*
ERL_ATOM
.TP 2
*
ERL_PID \fI/* Erlang process identifier */\fR
.TP 2
*
ERL_PORT
.TP 2
*
ERL_REF \fI/* Erlang reference */\fR
.TP 2
*
ERL_EMPTY_LIST
.TP 2
*
ERL_LIST
.TP 2
*
ERL_TUPLE
.TP 2
*
ERL_FLOAT
.TP 2
*
ERL_BINARY
.TP 2
*
ERL_FUNCTION
.RE
.RE
.LP
.B
unsigned char * erl_peek_ext(bufp, pos)
.br
.RS
.TP
Types
unsigned char *bufp;
.br
int pos;
.br
.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
int erl_term_len(t)
.br
.RS
.TP
Types
ETERM *t;
.br
.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