.TH erl_eterm 3 "erl_interface  3.5.7" "Ericsson AB" "C LIBRARY FUNCTIONS"
.SH NAME
erl_eterm \- Functions for Erlang Term Construction
.SH DESCRIPTION
.LP
This module contains functions for creating and manipulating Erlang terms\&. 
.LP
An Erlang term is represented by a C structure of type \fIETERM\fR\&. 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\&. 
.LP
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:
.RS 2
.TP 4
.B
\fIERL_IS_INTEGER(t)\fR:
True if \fIt\fR is an integer\&.
.TP 4
.B
\fIERL_IS_UNSIGNED_INTEGER(t)\fR:
True if \fIt\fR is an integer\&.
.TP 4
.B
\fIERL_IS_FLOAT(t)\fR:
True if \fIt\fR is a floating point number\&.
.TP 4
.B
\fIERL_IS_ATOM(t)\fR:
True if \fIt\fR is an atom\&.
.TP 4
.B
\fIERL_IS_PID(t)\fR:
True if \fIt\fR is a Pid (process identifier)\&.
.TP 4
.B
\fIERL_IS_PORT(t)\fR:
True if \fIt\fR is a port\&.
.TP 4
.B
\fIERL_IS_REF(t)\fR:
True if \fIt\fR is a reference\&.
.TP 4
.B
\fIERL_IS_TUPLE(t)\fR:
True if \fIt\fR is a tuple\&.
.TP 4
.B
\fIERL_IS_BINARY(t)\fR:
True if \fIt\fR is a binary\&.
.TP 4
.B
\fIERL_IS_LIST(t)\fR:
True if \fIt\fR is a list with zero or more elements\&.
.TP 4
.B
\fIERL_IS_EMPTY_LIST(t)\fR:
True if \fIt\fR is an empty list\&.
.TP 4
.B
\fIERL_IS_CONS(t)\fR:
True if \fIt\fR is a list with at least one element\&.
.RE
.LP
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\&. 
.RS 2
.TP 4
.B
\fIchar *ERL_ATOM_PTR(t)\fR:
A string representing atom \fIt\fR\&.
.TP 4
.B
\fIint ERL_ATOM_SIZE(t)\fR:
The length (in characters) of atom t\&.
.TP 4
.B
\fIvoid *ERL_BIN_PTR(t)\fR:
A pointer to the contents of \fIt\fR
.TP 4
.B
\fIint ERL_BIN_SIZE(t)\fR:
The length (in bytes) of binary object \fIt\fR\&.
.TP 4
.B
\fIint ERL_INT_VALUE(t)\fR:
The integer of \fIt\fR\&.
.TP 4
.B
\fIunsigned int ERL_INT_UVALUE(t)\fR:
The unsigned integer value of \fIt\fR\&.
.TP 4
.B
\fIdouble ERL_FLOAT_VALUE(t)\fR:
The floating point value of \fIt\fR\&.
.TP 4
.B
\fIETERM *ERL_PID_NODE(t)\fR:
The Node in pid \fIt\fR\&.
.TP 4
.B
\fIint ERL_PID_NUMBER(t)\fR:
The sequence number in pid \fIt\fR\&.
.TP 4
.B
\fIint ERL_PID_SERIAL(t)\fR:
The serial number in pid \fIt\fR\&.
.TP 4
.B
\fIint ERL_PID_CREATION(t)\fR:
The creation number in pid \fIt\fR\&.
.TP 4
.B
\fIint ERL_PORT_NUMBER(t)\fR:
The sequence number in port \fIt\fR\&.
.TP 4
.B
\fIint ERL_PORT_CREATION(t)\fR:
The creation number in port \fIt\fR\&.
.TP 4
.B
\fIETERM *ERL_PORT_NODE(t)\fR:
The node in port \fIt\fR\&.
.TP 4
.B
\fIint ERL_REF_NUMBER(t)\fR:
The first part of the reference number in ref \fIt\fR\&. Use only for compatibility\&.
.TP 4
.B
\fIint ERL_REF_NUMBERS(t)\fR:
Pointer to the array of reference numbers in ref \fIt\fR\&.
.TP 4
.B
\fIint ERL_REF_LEN(t)\fR:
The number of used reference numbers in ref \fIt\fR\&.
.TP 4
.B
\fIint ERL_REF_CREATION(t)\fR:
The creation number in ref \fIt\fR\&.
.TP 4
.B
\fIint ERL_TUPLE_SIZE(t)\fR:
The number of elements in tuple \fIt\fR\&.
.TP 4
.B
\fIETERM *ERL_CONS_HEAD(t)\fR:
The head element of list \fIt\fR\&.
.TP 4
.B
\fIETERM *ERL_CONS_TAIL(t)\fR:
A List representing the tail elements of list \fIt\fR\&.
.RE

.SH EXPORTS
.LP
.B
ETERM * erl_cons(head, tail)
.br
.RS
.TP
Types
ETERM *head;
.br
ETERM *tail;
.br
.RE
.RS
.LP
This function concatenates two Erlang terms, prepending \fIhead\fR onto \fItail\fR and thereby creating a \fIcons\fR cell\&. To make a proper list, \fItail\fR should always be a list or an empty list\&. Note that NULL is not a valid list\&.
.LP
\fIhead\fR is the new term to be added\&.
.LP
\fItail\fR is the existing list to which \fIhead\fR will be concatenated\&.
.LP
The function returns a new list\&.
.LP
\fIERL_CONS_HEAD(list)\fR and \fIERL_CONS_TAIL(list)\fR can be used to retrieve the head and tail components from the list\&. \fIerl_hd(list)\fR and \fIerl_tl(list)\fR will do the same thing, but check that the argument really is a list\&.
.LP
For example:

.nf
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);
        
.fi
.RE
.LP
.B
ETERM * erl_copy_term(term)
.br
.RS
.TP
Types
ETERM *term;
.br
.RE
.RS
.LP
This function creates and returns a copy of the Erlang term \fIterm\fR\&.
.RE
.LP
.B
ETERM * erl_element(position, tuple)
.br
.RS
.TP
Types
int position;
.br
ETERM *tuple;
.br
.RE
.RS
.LP
This function extracts a specified element from an Erlang tuple\&. 
.LP
\fIposition\fR specifies which element to retrieve from \fItuple\fR\&. The elements are numbered starting from 1\&.
.LP
\fItuple\fR is an Erlang term containing at least \fIposition\fR elements\&.
.LP
The function returns a new Erlang term corresponding to the requested element, or NULL if \fIposition\fR was greater than the arity of \fItuple\fR\&.
.RE
.LP
.B
void erl_init(NULL, 0)
.br
.RS
.TP
Types
void *NULL;
.br
int 0;
.br
.RE
.RS
.LP
This function must be called before any of the others in the \fIerl_interface\fR library in order to initialize the library functions\&. The arguments must be specified as \fIerl_init(NULL, 0)\fR\&.
.RE
.LP
.B
ETERM * erl_hd(list)
.br
.RS
.TP
Types
ETERM *list;
.br
.RE
.RS
.LP
Extracts the first element from a list\&.
.LP
\fIlist\fR is an Erlang term containing a list\&.
.LP
The function returns an Erlang term corresponding to the head element in the list, or a NULL pointer if \fIlist\fR was not a list\&.
.RE
.LP
.B
ETERM * erl_iolist_to_binary(term)
.br
.RS
.TP
Types
ETERM *list;
.br
.RE
.RS
.LP
This function converts an IO list to a binary term\&.
.LP
\fIlist\fR is an Erlang term containing a list\&.
.LP
This function an Erlang binary term, or NULL if \fIlist\fR was not an IO list\&. 
.LP
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: 

.nf
iolist ::= []
        |   Binary
        |   [iohead | iolist]
        ;
iohead ::= Binary
        |   Byte (integer in the range [0\&.\&.255])
        |   iolist
        ;
        
.fi
.RE
.LP
.B
char * erl_iolist_to_string(list)
.br
.RS
.TP
Types
ETERM *list;
.br
.RE
.RS
.LP
This function converts an IO list to a \&'\e0\&' terminated C string\&. 
.LP
\fIlist\fR is an Erlang term containing an IO list\&. The IO list must not contain the integer 0, since C strings may not contain this value except as a terminating marker\&.
.LP
This function returns a pointer to a dynamically allocated buffer containing a string\&. If \fIlist\fR is not an IO list, or if \fIlist\fR contains the integer 0, NULL is returned\&. It is the caller\&'s responsibility free the allocated buffer with \fIerl_free()\fR\&. 
.LP
Refer to \fIerl_iolist_to_binary()\fR for the definition of an IO list\&. 
.RE
.LP
.B
int erl_iolist_length(list)
.br
.RS
.TP
Types
ETERM *list;
.br
.RE
.RS
.LP
Returns the length of an IO list\&. 
.LP
\fIlist\fR is an Erlang term containing an IO list\&. 
.LP
The function returns the length of \fIlist\fR, or -1 if \fIlist\fR is not an IO list\&.
.LP
Refer to \fIerl_iolist_to_binary()\fR for the definition of an IO list\&. 
.RE
.LP
.B
int erl_length(list)
.br
.RS
.TP
Types
ETERM *list;
.br
.RE
.RS
.LP
Determines the length of a proper list\&.
.LP
\fIlist\fR is an Erlang term containing proper list\&. In a proper list, all tails except the last point to another list cell, and the last tail points to an empty list\&.
.LP
Returns -1 if \fIlist\fR is not a proper list\&.
.RE
.LP
.B
ETERM * erl_mk_atom(string)
.br
.RS
.TP
Types
char *string;
.br
.RE
.RS
.LP
Creates an atom\&.
.LP
\fIstring\fR is the sequence of characters that will be used to create the atom\&.
.LP
Returns an Erlang term containing an atom\&. Note that it is the callers responsibility to make sure that \fIstring\fR contains a valid name for an atom\&.
.LP
\fIERL_ATOM_PTR(atom)\fR can be used to retrieve the atom name (as a string)\&. Note that the string is not 0-terminated in the atom\&. \fIERL_ATOM_SIZE(atom)\fRreturns the length of the atom name\&.
.RE
.LP
.B
ETERM * erl_mk_binary(bptr, size)
.br
.RS
.TP
Types
char *bptr;
.br
int size;
.br
.RE
.RS
.LP
This function produces an Erlang binary object from a buffer containing a sequence of bytes\&.
.LP
\fIbptr\fR is a pointer to a buffer containg data to be converted\&.
.LP
\fIsize\fR indicates the length of \fIbptr\fR\&.
.LP
The function returns an Erlang binary object\&.
.LP
\fIERL_BIN_PTR(bin)\fR retrieves a pointer to the binary data\&. \fIERL_BIN_SIZE(bin)\fR retrieves the size\&. 
.RE
.LP
.B
ETERM * erl_mk_empty_list()
.br
.RS
.LP
This function creates and returns an empty Erlang list\&. Note that NULL is not used to represent an empty list; Use this function instead\&.
.RE
.LP
.B
ETERM * erl_mk_estring(string, len)
.br
.RS
.TP
Types
char *string;
.br
int len;
.br
.RE
.RS
.LP
This function creates a list from a sequence of bytes\&.
.LP
\fIstring\fR is a buffer containing a sequence of bytes\&. The buffer does not need to be zero-terminated\&.
.LP
\fIlen\fR is the length of \fIstring\fR\&.
.LP
The function returns an Erlang list object corresponding to the character sequence in \fIstring\fR\&.
.RE
.LP
.B
ETERM * erl_mk_float(f)
.br
.RS
.TP
Types
double f;
.br
.RE
.RS
.LP
Creates an Erlang float\&.
.LP
\fIf\fR is a value to be converted to an Erlang float\&.
.LP

.LP
The function returns an Erlang float object with the value specified in \fIf\fR\&.
.LP
\fIERL_FLOAT_VALUE(t)\fR can be used to retrieve the value from an Erlang float\&.
.RE
.LP
.B
ETERM * erl_mk_int(n)
.br
.RS
.TP
Types
int n;
.br
.RE
.RS
.LP
Creates an Erlang integer\&.
.LP
\fIn\fR is a value to be converted to an Erlang integer\&.
.LP

.LP
The function returns an Erlang integer object with the value specified in \fIn\fR\&.
.LP
\fIERL_INT_VALUE(t)\fR can be used to retrieve the value value from an Erlang integer\&.
.RE
.LP
.B
ETERM * erl_mk_list(array, arrsize)
.br
.RS
.TP
Types
ETERM **array;
.br
int arrsize;
.br
.RE
.RS
.LP
Creates an Erlang list from an array of Erlang terms, such that each element in the list corresponds to one element in the array\&. 
.LP
\fIarray\fR is an array of Erlang terms\&.
.LP
\fIarrsize\fR is the number of elements in \fIarray\fR\&.
.LP
The function creates an Erlang list object, whose length \fIarrsize\fR and whose elements are taken from the terms in \fIarray\fR\&.
.RE
.LP
.B
ETERM * erl_mk_pid(node, number, serial, creation)
.br
.RS
.TP
Types
const char *node;
.br
unsigned int number;
.br
unsigned int serial;
.br
unsigned int creation;
.br
.RE
.RS
.LP
This function creates an Erlang process identifier\&. The resulting pid can be used by Erlang processes wishing to communicate with the C node\&.
.LP
\fInode\fR is the name of the C node\&.
.LP
\fInumber\fR, \fIserial\fR and \fIcreation\fR are arbitrary numbers\&. Note though, that these are limited in precision, so only the low 15, 3 and 2 bits of these numbers are actually used\&.
.LP
The function returns an Erlang pid object\&.
.LP
\fIERL_PID_NODE(pid)\fR, \fIERL_PID_NUMBER(pid)\fR, \fIERL_PID_SERIAL(pid)\fR and \fIERL_PID_CREATION(pid)\fR can be used to retrieve the four values used to create the pid\&.
.RE
.LP
.B
ETERM * erl_mk_port(node, number, creation)
.br
.RS
.TP
Types
const char *node;
.br
unsigned int number;
.br
unsigned int creation;
.br
.RE
.RS
.LP
This function creates an Erlang port identifier\&. 
.LP
\fInode\fR is the name of the C node\&.
.LP
\fInumber\fR and \fIcreation\fR are arbitrary numbers\&. Note though, that these are limited in precision, so only the low 18 and 2 bits of these numbers are actually used\&. 
.LP
The function returns an Erlang port object\&.
.LP
\fIERL_PORT_NODE(port)\fR, \fIERL_PORT_NUMBER(port)\fR and \fIERL_PORT_CREATION\fR can be used to retrieve the three values used to create the port\&. 
.RE
.LP
.B
ETERM * erl_mk_ref(node, number, creation)
.br
.RS
.TP
Types
const char *node;
.br
unsigned int number;
.br
unsigned int creation;
.br
.RE
.RS
.LP
This function creates an old Erlang reference, with only 18 bits - use \fIerl_mk_long_ref\fR instead\&.
.LP
\fInode\fR is the name of the C node\&.
.LP
\fInumber\fR should be chosen uniquely for each reference created for a given C node\&.
.LP
\fIcreation\fR is an arbitrary number\&.
.LP
Note that \fInumber\fR and \fIcreation\fR are limited in precision, so only the low 18 and 2 bits of these numbers are actually used\&. 
.LP
The function returns an Erlang reference object\&.
.LP
\fIERL_REF_NODE(ref)\fR, \fIERL_REF_NUMBER(ref)\fR, and \fIERL_REF_CREATION(ref)\fR to retrieve the three values used to create the reference\&. 
.RE
.LP
.B
ETERM * erl_mk_long_ref(node, n1, n2, n3, creation)
.br
.RS
.TP
Types
const char *node;
.br
unsigned int n1, n2, n3;
.br
unsigned int creation;
.br
.RE
.RS
.LP
This function creates an Erlang reference, with 82 bits\&.
.LP
\fInode\fR is the name of the C node\&.
.LP
\fIn1\fR, \fIn2\fR and \fIn3\fR can be seen as one big number \fIn1*2^64+n2*2^32+n3\fR which should be chosen uniquely for each reference created for a given C node\&.
.LP
\fIcreation\fR is an arbitrary number\&.
.LP
Note that \fIn3\fR and \fIcreation\fR are limited in precision, so only the low 18 and 2 bits of these numbers are actually used\&. 
.LP
The function returns an Erlang reference object\&.
.LP
\fIERL_REF_NODE(ref)\fR, \fIERL_REF_NUMBERS(ref)\fR, \fIERL_REF_LEN(ref)\fR and \fIERL_REF_CREATION(ref)\fR to retrieve the values used to create the reference\&. 
.RE
.LP
.B
ETERM * erl_mk_string(string)
.br
.RS
.TP
Types
char *string;
.br
.RE
.RS
.LP
This function creates a list from a zero terminated string\&.
.LP
\fIstring\fR is the zero-terminated sequence of characters (i\&.e\&. a C string) from which the list will be created\&.
.LP
The function returns an Erlang list\&.
.RE
.LP
.B
ETERM * erl_mk_tuple(array, arrsize)
.br
.RS
.TP
Types
ETERM **array;
.br
int arrsize;
.br
.RE
.RS
.LP
Creates an Erlang tuple from an array of Erlang terms\&.
.LP
\fIarray\fR is an array of Erlang terms\&.
.LP
\fIarrsize\fR is the number of elements in \fIarray\fR\&.
.LP
The function creates an Erlang tuple, whose arity is \fIsize\fR and whose elements are taken from the terms in \fIarray\fR\&.
.LP
To retrieve the size of a tuple, either use the \fIerl_size\fR function (which checks the type of the checked term and works for a binary as well as for a tuple), or the \fIERL_TUPLE_SIZE(tuple)\fR returns the arity of a tuple\&. \fIerl_size()\fR will do the same thing, but it checks that the argument really is a tuple\&. \fIerl_element(index, tuple)\fR returns the element corresponding to a given position in the tuple\&. 
.RE
.LP
.B
ETERM * erl_mk_uint(n)
.br
.RS
.TP
Types
unsigned int n;
.br
.RE
.RS
.LP
Creates an Erlang unsigned integer\&.
.LP
\fIn\fR is a value to be converted to an Erlang unsigned integer\&.
.LP

.LP
The function returns an Erlang unsigned integer object with the value specified in \fIn\fR\&.
.LP
\fIERL_INT_UVALUE(t)\fR can be used to retrieve the value from an Erlang unsigned integer\&.
.RE
.LP
.B
ETERM * erl_mk_var(name)
.br
.RS
.TP
Types
char *name;
.br
.RE
.RS
.LP
This function creates an unbound Erlang variable\&. The variable can later be bound through pattern matching or assignment\&.
.LP
\fIname\fR specifies a name for the variable\&.
.LP
The function returns an Erlang variable object with the name \fIname\fR\&. 
.RE
.LP
.B
int erl_print_term(stream, term)
.br
.RS
.TP
Types
FILE *stream;
.br
ETERM *term;
.br
.RE
.RS
.LP
This function prints the specified Erlang term to the given output stream\&.
.LP
\fIstream\fR indicates where the function should send its output\&.
.LP
\fIterm\fR is the Erlang term to print\&.
.LP
The function returns the number of characters written, or a negative value if there was an error\&.
.RE
.LP
.B
void erl_set_compat_rel(release_number)
.br
.RS
.TP
Types
unsigned release_number;
.br
.RE
.RS
.LP
By default, the \fIerl_interface\fR library is only guaranteed to be compatible with other Erlang/OTP components from the same release as the \fIerl_interface\fR library itself\&. For example, \fIerl_interface\fR from the OTP R10 release is not compatible with an Erlang emulator from the OTP R9 release by default\&.
.LP
A call to \fIerl_set_compat_rel(release_number)\fR sets the \fIerl_interface\fR library in compatibility mode of release \fIrelease_number\fR\&. Valid range of \fIrelease_number\fR is [7, current release]\&. This makes it possible to communicate with Erlang/OTP components from earlier releases\&.
.SS Note:
.LP
If this function is called, it may only be called once directly after the call to the erl_init() function\&.

.SS Warning:
.LP
You may run into trouble if this feature is used carelessly\&. Always make sure that all communicating components are either from the same Erlang/OTP release, or from release X and release Y where all components from release Y are in compatibility mode of release X\&.

.RE
.LP
.B
int erl_size(term)
.br
.RS
.TP
Types
ETERM *term;
.br
.RE
.RS
.LP
Returns the arity of an Erlang tuple, or the number of bytes in an Erlang binary object\&. 
.LP
\fIterm\fR is an Erlang tuple or an Erlang binary object\&.
.LP
The function returns the size of \fIterm\fR as described above, or -1 if \fIterm\fR is not one of the two supported types\&. 
.RE
.LP
.B
ETERM * erl_tl(list)
.br
.RS
.TP
Types
ETERM *list;
.br
.RE
.RS
.LP
Extracts the tail from a list\&.
.LP
\fIlist\fR is an Erlang term containing a list\&.
.LP
The function returns an Erlang list corresponding to the original list minus the first element, or NULL pointer if \fIlist\fR was not a list\&.
.RE
.LP
.B
ETERM * erl_var_content(term, name)
.br
.RS
.TP
Types
ETERM *term;
.br
char *name;
.br
.RE
.RS
.LP
This function returns the contents of the specified variable in an Erlang term\&. 
.LP
\fIterm\fR is an Erlang term\&. In order for this function to succeed, \fIterm\fR must be an Erlang variable with the specified name, or it must be an Erlang list or tuple containing a variable with the specified name\&. Other Erlang types cannot contain variables\&.
.LP
\fIname\fR is the name of an Erlang variable\&.
.LP
Returns the Erlang object corresponding to the value of \fIname\fR in \fIterm\fR\&. If no variable with the name \fIname\fR was found in \fIterm\fR, or if \fIterm\fR is not a valid Erlang term, NULL is returned\&.
.RE