Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
erl_marshal(3)		      C	Library	Functions		erl_marshal(3)

NAME
       erl_marshal - Encoding and decoding of Erlang terms.

DESCRIPTION
       This  module  contains  functions  for encoding Erlang terms into a se-
       quence 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  buf-
	      fer  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  con-
		  tains	 one  or more consecutively encoded Erlang terms. Fol-
		  lowing a successful call to erl_decode_buf(),	bufpp  is  up-
		  dated	so that	it points to the next encoded term.

	      erl_decode()  returns  an	 Erlang	term corresponding to the con-
	      tents of bufp on success,	otherwise NULL.	 erl_decode_buf()  re-
	      turns  an	Erlang term corresponding to the first of the consecu-
	      tive 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  ex-
	      ternal format for	storage	or transmission. erl_encode_buf() pro-
	      vides a simple mechanism for  encoding  several  terms  consecu-
	      tively 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 suc-
		  cessful 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 terminat-
		  ing 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  in-
	      formation	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 buf-
	      fer. 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.

Ericsson AB		      erl_interface 3.11		erl_marshal(3)

NAME | DESCRIPTION | EXPORTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=erl_marshal&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help