# erl_marshal

### C LIBRARY

erl_marshal

### C LIBRARY SUMMARY

Encoding and Decoding of Erlang terms

### DESCRIPTION

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

### EXPORTS

`int erl_compare_ext(bufp1, bufp2)`

Types:

`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.

`ETERM *erl_decode(bufp)`
`ETERM *erl_decode_buf(bufpp)`

Types:

`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.

`int erl_encode(term, bufp)`
`int erl_encode_buf(term, bufpp)`

Types:

`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 return 0 in success, or 1 if `term` was not a valid Erlang term.

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 additonal 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.

`int erl_ext_size(bufp)`

Types:

`unsigned char *bufp;`

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

`unsigned char erl_ext_type(bufp)`

Types:

`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 *erl_peek_ext(bufp, pos)`

Types:

`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.

`int erl_term_len(t)`

Types:

`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()`.

The size in bytes is returned.

### AUTHORS

T.Törnkvist - support@erlang.ericsson.se
Gordon Beaton - support@erlang.ericsson.se

erl_interface 3.4
Copyright © 1991-2003 Ericsson Utvecklings AB