erl_eterm(3erl) C Library Functions erl_eterm(3erl)
NAME
erl_eterm - Functions for Erlang Term Construction
DESCRIPTION
This module contains functions for creating and manipulating Erlang terms.
An Erlang term is represented by a C structure of type ETERM . Applications should not reference any fields in this structure directly,
because it may be changed in future releases to provide faster and more compact term storage. Instead, applications should us the macros
and functions provided.
The following macros each take a single ETERM pointer as an argument. They return a non-zero value if the test is true, and 0 otherwise:
ERL_IS_INTEGER(t) :
True if t is an integer.
ERL_IS_UNSIGNED_INTEGER(t) :
True if t is an integer.
ERL_IS_FLOAT(t) :
True if t is a floating point number.
ERL_IS_ATOM(t) :
True if t is an atom.
ERL_IS_PID(t) :
True if t is a Pid (process identifier).
ERL_IS_PORT(t) :
True if t is a port.
ERL_IS_REF(t) :
True if t is a reference.
ERL_IS_TUPLE(t) :
True if t is a tuple.
ERL_IS_BINARY(t) :
True if t is a binary.
ERL_IS_LIST(t) :
True if t is a list with zero or more elements.
ERL_IS_EMPTY_LIST(t) :
True if t is an empty list.
ERL_IS_CONS(t) :
True if t is a list with at least one element.
The following macros can be used for retrieving parts of Erlang terms. None of these do any type checking; results are undefined if you
pass an ETERM* containing the wrong type. For example, passing a tuple to ERL_ATOM_PTR() will likely result in garbage.
char *ERL_ATOM_PTR(t) :
A string representing atom t .
int ERL_ATOM_SIZE(t) :
The length (in characters) of atom t.
void *ERL_BIN_PTR(t) :
A pointer to the contents of t
int ERL_BIN_SIZE(t) :
The length (in bytes) of binary object t .
int ERL_INT_VALUE(t) :
The integer of t .
unsigned int ERL_INT_UVALUE(t) :
The unsigned integer value of t .
double ERL_FLOAT_VALUE(t) :
The floating point value of t .
ETERM *ERL_PID_NODE(t) :
The Node in pid t .
int ERL_PID_NUMBER(t) :
The sequence number in pid t .
int ERL_PID_SERIAL(t) :
The serial number in pid t .
int ERL_PID_CREATION(t) :
The creation number in pid t .
int ERL_PORT_NUMBER(t) :
The sequence number in port t .
int ERL_PORT_CREATION(t) :
The creation number in port t .
ETERM *ERL_PORT_NODE(t) :
The node in port t .
int ERL_REF_NUMBER(t) :
The first part of the reference number in ref t . Use only for compatibility.
int ERL_REF_NUMBERS(t) :
Pointer to the array of reference numbers in ref t .
int ERL_REF_LEN(t) :
The number of used reference numbers in ref t .
int ERL_REF_CREATION(t) :
The creation number in ref t .
int ERL_TUPLE_SIZE(t) :
The number of elements in tuple t .
ETERM *ERL_CONS_HEAD(t) :
The head element of list t .
ETERM *ERL_CONS_TAIL(t) :
A List representing the tail elements of list t .
EXPORTS
ETERM * erl_cons(head, tail)
Types ETERM *head;
ETERM *tail;
This function concatenates two Erlang terms, prepending head onto tail and thereby creating a cons cell. To make a proper list, tail
should always be a list or an empty list. Note that NULL is not a valid list.
head is the new term to be added.
tail is the existing list to which head will be concatenated.
The function returns a new list.
ERL_CONS_HEAD(list) and ERL_CONS_TAIL(list) can be used to retrieve the head and tail components from the list. erl_hd(list) and
erl_tl(list) will do the same thing, but check that the argument really is a list.
For example:
ETERM *list,*anAtom,*anInt;
anAtom = erl_mk_atom("madonna");
anInt = erl_mk_int(21);
list = erl_mk_empty_list();
list = erl_cons(anAtom, list);
list = erl_cons(anInt, list);
... /* do some work */
erl_free_compound(list);
ETERM * erl_copy_term(term)
Types ETERM *term;
This function creates and returns a copy of the Erlang term term .
ETERM * erl_element(position, tuple)
Types int position;
ETERM *tuple;
This function extracts a specified element from an Erlang tuple.
position specifies which element to retrieve from tuple . The elements are numbered starting from 1.
tuple is an Erlang term containing at least position elements.
The function returns a new Erlang term corresponding to the requested element, or NULL if position was greater than the arity of
tuple .
void erl_init(NULL, 0)
Types void *NULL;
int 0;
This function must be called before any of the others in the erl_interface library in order to initialize the library functions. The
arguments must be specified as erl_init(NULL,0) .
ETERM * erl_hd(list)
Types ETERM *list;
Extracts the first element from a list.
list is an Erlang term containing a list.
The function returns an Erlang term corresponding to the head element in the list, or a NULL pointer if list was not a list.
ETERM * erl_iolist_to_binary(term)
Types ETERM *list;
This function converts an IO list to a binary term.
list is an Erlang term containing a list.
This function an Erlang binary term, or NULL if list was not an IO list.
Informally, an IO list is a deep list of characters and binaries which can be sent to an Erlang port. In BNF, an IO list is formally
defined as follows:
iolist ::= []
| Binary
| [iohead | iolist]
;
iohead ::= Binary
| Byte (integer in the range [0..255])
| iolist
;
char * erl_iolist_to_string(list)
Types ETERM *list;
This function converts an IO list to a '