Provided by: erlang-manpages_22.2.7+dfsg-1_all bug

NAME

       erl_marshal - Encoding and decoding of Erlang terms.

DESCRIPTION

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

   Note:
       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.

EXPORTS

       int erl_compare_ext(bufp1, bufp2)

              Types:

                 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)

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

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

       int erl_ext_size(bufp)

              Types:

                 unsigned char *bufp;

              Returns the number of elements in an encoded term.

       unsigned char erl_ext_type(bufp)

              Types:

                 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)

              Types:

                 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.

       int erl_term_len(t)

              Types:

                 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.