19962016 Ericsson AB. All Rights Reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. erl_marshal Torbjörn Törnkvist Torbjörn Törnkvist Bjarne Däcker Torbjörn Törnkvist 1998-07-03 A erl_marshal.xml
erl_marshal Encoding and decoding of Erlang terms.

The support for VxWorks is deprecated as of OTP 22, and will be removed in OTP 23.

The old legacy erl_interface library (functions with prefix erl_) is deprecated as of OTP 22, and will be removed in OTP 23. This does not apply to the ei library. Reasonably new gcc compilers will issue deprecation warnings. In order to disable these warnings, define the macro EI_NO_DEPR_WARN.

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

 interl_compare_ext(bufp1, bufp2) Compare encoded byte sequences. unsigned char *bufp1,*bufp2;

Compares two encoded terms.

bufp1 is a buffer containing an encoded Erlang term term1. bufp2 is a buffer containing an encoded Erlang term term2.

Returns 0 if the terms are equal, -1 if term1 < term2, or 1 if term2 < term1.

 ETERM *erl_decode(bufp) ETERM *erl_decode_buf(bufpp) Convert a term from Erlang external format. 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 is updated so that it points to the next encoded term.

erl_decode() returns an Erlang term corresponding to the contents of bufp on success, otherwise NULL. 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 return NULL.

 interl_encode(term, bufp) interl_encode_buf(term, bufpp) Convert a term into Erlang external format. 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 is updated so that it points to the position for the next encoded term.

These functions return the number of bytes written to buffer on success, otherwise 0.

Notice that no bounds checking is done on the buffer. It is the caller's responsibility to ensure 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. Notice that this information is implementation-specific, and can 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 more 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 is the result calculated from the information above, plus 1 more byte for a version identifier.

 interl_ext_size(bufp) Count elements in encoded term. unsigned char *bufp;

Returns the number of elements in an encoded term.

 unsigned charerl_ext_type(bufp) Determine type of an encoded byte sequence. unsigned char *bufp;

Identifies and returns the type of Erlang term encoded in a buffer. It skips a trailing magic identifier.

Returns 0 if the type cannot 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) Step over encoded term. unsigned char *bufp; int pos;

This function is used for stepping over one or more encoded terms in a buffer, to directly access 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.

Returns a pointer to a subterm that can be used in a later call to erl_decode() 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.

 interl_term_len(t) Determine encoded size of term. ETERM *t;

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

Returns the size in bytes.