aboutsummaryrefslogtreecommitdiffstats
path: root/lib/erl_interface/doc/src/erl_eterm.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/erl_interface/doc/src/erl_eterm.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/erl_interface/doc/src/erl_eterm.xml')
-rw-r--r--lib/erl_interface/doc/src/erl_eterm.xml675
1 files changed, 675 insertions, 0 deletions
diff --git a/lib/erl_interface/doc/src/erl_eterm.xml b/lib/erl_interface/doc/src/erl_eterm.xml
new file mode 100644
index 0000000000..ce14549672
--- /dev/null
+++ b/lib/erl_interface/doc/src/erl_eterm.xml
@@ -0,0 +1,675 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE cref SYSTEM "cref.dtd">
+
+<cref>
+ <header>
+ <copyright>
+ <year>1996</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>erl_eterm</title>
+ <prepared>Torbj&ouml;rn T&ouml;rnkvist</prepared>
+ <responsible>Torbj&ouml;rn T&ouml;rnkvist</responsible>
+ <docno></docno>
+ <approved>Bjarne D&auml;cker</approved>
+ <checked>Torbj&ouml;rn T&ouml;rnkvist</checked>
+ <date>980703</date>
+ <rev>A</rev>
+ <file>erl_eterm.sgml</file>
+ </header>
+ <lib>erl_eterm</lib>
+ <libsummary>Functions for Erlang Term Construction</libsummary>
+ <description>
+ <p>This module contains functions for creating and manipulating
+ Erlang terms. </p>
+ <p>An Erlang term is represented by a C structure of type
+ <c><![CDATA[ETERM]]></c>. 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. </p>
+ <p>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:</p>
+ <taglist>
+ <tag><c><![CDATA[ERL_IS_INTEGER(t)]]></c></tag>
+ <item>True if <c><![CDATA[t]]></c> is an integer.</item>
+ <tag><c><![CDATA[ERL_IS_UNSIGNED_INTEGER(t)]]></c></tag>
+ <item>True if <c><![CDATA[t]]></c> is an integer.</item>
+ <tag><c><![CDATA[ERL_IS_FLOAT(t)]]></c></tag>
+ <item>True if <c><![CDATA[t]]></c> is a floating point number.</item>
+ <tag><c><![CDATA[ERL_IS_ATOM(t)]]></c></tag>
+ <item>True if <c><![CDATA[t]]></c> is an atom.</item>
+ <tag><c><![CDATA[ERL_IS_PID(t)]]></c></tag>
+ <item>True if <c><![CDATA[t]]></c> is a Pid (process identifier).</item>
+ <tag><c><![CDATA[ERL_IS_PORT(t)]]></c></tag>
+ <item>True if <c><![CDATA[t]]></c> is a port.</item>
+ <tag><c><![CDATA[ERL_IS_REF(t)]]></c></tag>
+ <item>True if <c><![CDATA[t]]></c> is a reference.</item>
+ <tag><c><![CDATA[ERL_IS_TUPLE(t)]]></c></tag>
+ <item>True if <c><![CDATA[t]]></c> is a tuple.</item>
+ <tag><c><![CDATA[ERL_IS_BINARY(t)]]></c></tag>
+ <item>True if <c><![CDATA[t]]></c> is a binary.</item>
+ <tag><c><![CDATA[ERL_IS_LIST(t)]]></c></tag>
+ <item>True if <c><![CDATA[t]]></c> is a list with zero or more elements.</item>
+ <tag><c><![CDATA[ERL_IS_EMPTY_LIST(t)]]></c></tag>
+ <item>True if <c><![CDATA[t]]></c> is an empty list.</item>
+ <tag><c><![CDATA[ERL_IS_CONS(t)]]></c></tag>
+ <item>True if <c><![CDATA[t]]></c> is a list with at least one element.</item>
+ </taglist>
+ <p>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.
+ </p>
+ <taglist>
+ <tag><c><![CDATA[char *ERL_ATOM_PTR(t)]]></c></tag>
+ <item>A string representing atom <c><![CDATA[t]]></c>.
+ </item>
+ <tag><c><![CDATA[int ERL_ATOM_SIZE(t)]]></c></tag>
+ <item>The length (in characters) of atom t.</item>
+ <tag><c><![CDATA[void *ERL_BIN_PTR(t)]]></c></tag>
+ <item>A pointer to the contents of <c><![CDATA[t]]></c></item>
+ <tag><c><![CDATA[int ERL_BIN_SIZE(t)]]></c></tag>
+ <item>The length (in bytes) of binary object <c><![CDATA[t]]></c>.</item>
+ <tag><c><![CDATA[int ERL_INT_VALUE(t)]]></c></tag>
+ <item>The integer of <c><![CDATA[t]]></c>.</item>
+ <tag><c><![CDATA[unsigned int ERL_INT_UVALUE(t)]]></c></tag>
+ <item>The unsigned integer value of <c><![CDATA[t]]></c>.</item>
+ <tag><c><![CDATA[double ERL_FLOAT_VALUE(t)]]></c></tag>
+ <item>The floating point value of <c><![CDATA[t]]></c>.</item>
+ <tag><c><![CDATA[ETERM *ERL_PID_NODE(t)]]></c></tag>
+ <item>The Node in pid <c><![CDATA[t]]></c>.</item>
+ <tag><c><![CDATA[int ERL_PID_NUMBER(t)]]></c></tag>
+ <item>The sequence number in pid <c><![CDATA[t]]></c>.</item>
+ <tag><c><![CDATA[int ERL_PID_SERIAL(t)]]></c></tag>
+ <item>The serial number in pid <c><![CDATA[t]]></c>.</item>
+ <tag><c><![CDATA[int ERL_PID_CREATION(t)]]></c></tag>
+ <item>The creation number in pid <c><![CDATA[t]]></c>.</item>
+ <tag><c><![CDATA[int ERL_PORT_NUMBER(t)]]></c></tag>
+ <item>The sequence number in port <c><![CDATA[t]]></c>.</item>
+ <tag><c><![CDATA[int ERL_PORT_CREATION(t)]]></c></tag>
+ <item>The creation number in port <c><![CDATA[t]]></c>.</item>
+ <tag><c><![CDATA[ETERM *ERL_PORT_NODE(t)]]></c></tag>
+ <item>The node in port <c><![CDATA[t]]></c>.</item>
+ <tag><c><![CDATA[int ERL_REF_NUMBER(t)]]></c></tag>
+ <item>The first part of the reference number in ref <c><![CDATA[t]]></c>. Use
+ only for compatibility.</item>
+ <tag><c><![CDATA[int ERL_REF_NUMBERS(t)]]></c></tag>
+ <item>Pointer to the array of reference numbers in ref <c><![CDATA[t]]></c>.</item>
+ <tag><c><![CDATA[int ERL_REF_LEN(t)]]></c></tag>
+ <item>The number of used reference numbers in ref <c><![CDATA[t]]></c>.</item>
+ <tag><c><![CDATA[int ERL_REF_CREATION(t)]]></c></tag>
+ <item>The creation number in ref <c><![CDATA[t]]></c>.</item>
+ <tag><c><![CDATA[int ERL_TUPLE_SIZE(t)]]></c></tag>
+ <item>The number of elements in tuple <c><![CDATA[t]]></c>.</item>
+ <tag><c><![CDATA[ETERM *ERL_CONS_HEAD(t)]]></c></tag>
+ <item>The head element of list <c><![CDATA[t]]></c>.</item>
+ <tag><c><![CDATA[ETERM *ERL_CONS_TAIL(t)]]></c></tag>
+ <item>A List representing the tail elements of list <c><![CDATA[t]]></c>.</item>
+ </taglist>
+ </description>
+ <funcs>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_cons(head, tail)</nametext></name>
+ <fsummary>Prepends a term to the head of a list.</fsummary>
+ <type>
+ <v>ETERM *head;</v>
+ <v>ETERM *tail;</v>
+ </type>
+ <desc>
+ <p>This function concatenates two Erlang terms, prepending
+ <c><![CDATA[head]]></c> onto <c><![CDATA[tail]]></c> and thereby creating a <c><![CDATA[cons]]></c> cell.
+ To make a proper list, <c><![CDATA[tail]]></c> should always be a
+ list or an empty list. Note that NULL is not a valid list.</p>
+ <p><c><![CDATA[head]]></c> is the new term to be added.</p>
+ <p><c><![CDATA[tail]]></c> is the existing list to which <c><![CDATA[head]]></c> will
+ be concatenated.</p>
+ <p>The function returns a new list.</p>
+ <p><c><![CDATA[ERL_CONS_HEAD(list)]]></c> and <c><![CDATA[ERL_CONS_TAIL(list)]]></c>
+ can be used to retrieve the head and tail components
+ from the list. <c><![CDATA[erl_hd(list)]]></c> and <c><![CDATA[erl_tl(list)]]></c> will do
+ the same thing, but check that the argument really is a list.</p>
+ <p>For example:</p>
+ <code type="none"><![CDATA[
+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);
+ ]]></code>
+ </desc>
+ </func>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_copy_term(term)</nametext></name>
+ <fsummary>Creates a copy of an Erlang term</fsummary>
+ <type>
+ <v>ETERM *term;</v>
+ </type>
+ <desc>
+ <p>This function creates and returns a copy of the Erlang term
+ <c><![CDATA[term]]></c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_element(position, tuple)</nametext></name>
+ <fsummary>Extracts an element from an Erlang tuple</fsummary>
+ <type>
+ <v>int position;</v>
+ <v>ETERM *tuple;</v>
+ </type>
+ <desc>
+ <p>This function extracts a specified element from an Erlang
+ tuple. </p>
+ <p><c><![CDATA[position]]></c> specifies which element to retrieve from
+ <c><![CDATA[tuple]]></c>. The elements are numbered starting from 1.</p>
+ <p><c><![CDATA[tuple]]></c> is an Erlang term containing at least
+ <c><![CDATA[position]]></c> elements.</p>
+ <p>The function returns a new Erlang term corresponding to the
+ requested element, or NULL if <c><![CDATA[position]]></c> was greater than
+ the arity of <c><![CDATA[tuple]]></c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>void</ret><nametext>erl_init(NULL, 0)</nametext></name>
+ <fsummary>Initialization routine</fsummary>
+ <type>
+ <v>void *NULL;</v>
+ <v>int 0;</v>
+ </type>
+ <desc>
+ <marker id="erl_init"></marker>
+ <p>This function must be called before any of the others in
+ the <c><![CDATA[erl_interface]]></c> library in order to initialize the
+ library functions. The arguments must be specified as
+ <c><![CDATA[erl_init(NULL,0)]]></c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_hd(list)</nametext></name>
+ <fsummary>Extracts the first element from a list</fsummary>
+ <type>
+ <v>ETERM *list;</v>
+ </type>
+ <desc>
+ <p>Extracts the first element from a list.</p>
+ <p><c><![CDATA[list]]></c> is an Erlang term containing a list.</p>
+ <p>The function returns an Erlang term corresponding to the
+ head element in the list, or a NULL pointer if <c><![CDATA[list]]></c> was
+ not a list.</p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_iolist_to_binary(term)</nametext></name>
+ <fsummary>Converts an IO list to a binary</fsummary>
+ <type>
+ <v>ETERM *list;</v>
+ </type>
+ <desc>
+ <p>This function converts an IO list to a binary term.</p>
+ <p><c><![CDATA[list]]></c> is an Erlang term containing a list.</p>
+ <p>This function an Erlang binary term, or NULL if <c><![CDATA[list]]></c>
+ was not an IO list. </p>
+ <p>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: </p>
+ <code type="none"><![CDATA[
+iolist ::= []
+ | Binary
+ | [iohead | iolist]
+ ;
+iohead ::= Binary
+ | Byte (integer in the range [0..255])
+ | iolist
+ ;
+ ]]></code>
+ </desc>
+ </func>
+ <func>
+ <name><ret>char *</ret><nametext>erl_iolist_to_string(list)</nametext></name>
+ <fsummary>Converts an IO list to a zero terminated string</fsummary>
+ <type>
+ <v>ETERM *list;</v>
+ </type>
+ <desc>
+ <p>This function converts an IO list to a '\\0' terminated C
+ string. </p>
+ <p><c><![CDATA[list]]></c> 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.</p>
+ <p>This function returns a pointer to a dynamically allocated
+ buffer containing a string. If <c><![CDATA[list]]></c> is not an IO list,
+ or if <c><![CDATA[list]]></c> contains the integer 0, NULL is returned. It
+ is the caller's responsibility free the allocated buffer
+ with <c><![CDATA[erl_free()]]></c>. </p>
+ <p>Refer to <c><![CDATA[erl_iolist_to_binary()]]></c> for the definition of an
+ IO list. </p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>int</ret><nametext>erl_iolist_length(list)</nametext></name>
+ <fsummary>Return the length of an IO list</fsummary>
+ <type>
+ <v>ETERM *list;</v>
+ </type>
+ <desc>
+ <p>Returns the length of an IO list.
+ </p>
+ <p><c><![CDATA[list]]></c> is an Erlang term containing an IO list. </p>
+ <p>The function returns the length of <c><![CDATA[list]]></c>, or -1 if
+ <c><![CDATA[list]]></c> is not an IO list.</p>
+ <p>Refer to <c><![CDATA[erl_iolist_to_binary()]]></c> for the definition of
+ an IO list. </p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>int</ret><nametext>erl_length(list)</nametext></name>
+ <fsummary>Determines the length of a list</fsummary>
+ <type>
+ <v>ETERM *list;</v>
+ </type>
+ <desc>
+ <p>Determines the length of a proper list.</p>
+ <p><c><![CDATA[list]]></c> 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.</p>
+ <p>Returns -1 if <c><![CDATA[list]]></c> is not a proper list.</p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_mk_atom(string)</nametext></name>
+ <fsummary>Creates an atom</fsummary>
+ <type>
+ <v>char *string;</v>
+ </type>
+ <desc>
+ <p>Creates an atom.</p>
+ <p><c><![CDATA[string]]></c> is the sequence of characters that will be
+ used to create the atom.</p>
+ <p>Returns an Erlang term containing an atom. Note that it is
+ the callers responsibility to make sure that <c><![CDATA[string]]></c>
+ contains a valid name for an atom.</p>
+ <p><c><![CDATA[ERL_ATOM_PTR(atom)]]></c> can be used to retrieve the
+ atom name (as a string). Note that the string is not
+ 0-terminated in the atom. <c><![CDATA[ERL_ATOM_SIZE(atom)]]></c>returns
+ the length of the atom name.</p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_mk_binary(bptr, size)</nametext></name>
+ <fsummary>Creates a binary object</fsummary>
+ <type>
+ <v>char *bptr;</v>
+ <v>int size;</v>
+ </type>
+ <desc>
+ <p>This function produces an Erlang binary object from a
+ buffer containing a sequence of bytes.</p>
+ <p><c><![CDATA[bptr]]></c> is a pointer to a buffer containing data to be converted.</p>
+ <p><c><![CDATA[size]]></c> indicates the length of <c><![CDATA[bptr]]></c>.</p>
+ <p>The function returns an Erlang binary object.</p>
+ <p><c><![CDATA[ERL_BIN_PTR(bin)]]></c> retrieves a pointer to
+ the binary data. <c><![CDATA[ERL_BIN_SIZE(bin)]]></c> retrieves the
+ size. </p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_mk_empty_list()</nametext></name>
+ <fsummary>Creates an empty Erlang list</fsummary>
+ <desc>
+ <p>This function creates and returns an empty Erlang list.
+ Note that NULL is not used to represent an empty list;
+ Use this function instead.</p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_mk_estring(string, len)</nametext></name>
+ <fsummary>Creates an Erlang string</fsummary>
+ <type>
+ <v>char *string;</v>
+ <v>int len;</v>
+ </type>
+ <desc>
+ <p>This function creates a list from a sequence of bytes.</p>
+ <p><c><![CDATA[string]]></c> is a buffer containing a sequence of
+ bytes. The buffer does not need to be zero-terminated.</p>
+ <p><c><![CDATA[len]]></c> is the length of <c><![CDATA[string]]></c>.</p>
+ <p>The function returns an Erlang list object corresponding to
+ the character sequence in <c><![CDATA[string]]></c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_mk_float(f)</nametext></name>
+ <fsummary>Creates an Erlang float</fsummary>
+ <type>
+ <v>double f;</v>
+ </type>
+ <desc>
+ <p>Creates an Erlang float.</p>
+ <p><c><![CDATA[f]]></c> is a value to be converted to an Erlang float.</p>
+ <p></p>
+ <p>The function returns an Erlang float object with the value
+ specified in <c><![CDATA[f]]></c>.</p>
+ <p><c><![CDATA[ERL_FLOAT_VALUE(t)]]></c> can be used to retrieve the
+ value from an Erlang float.</p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_mk_int(n)</nametext></name>
+ <fsummary>Creates an Erlang integer</fsummary>
+ <type>
+ <v>int n;</v>
+ </type>
+ <desc>
+ <p>Creates an Erlang integer.</p>
+ <p><c><![CDATA[n]]></c> is a value to be converted to an Erlang integer.</p>
+ <p></p>
+ <p>The function returns an Erlang integer object with the
+ value specified in <c><![CDATA[n]]></c>.</p>
+ <p><c><![CDATA[ERL_INT_VALUE(t)]]></c> can be used to retrieve the value
+ value from an Erlang integer.</p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_mk_list(array, arrsize)</nametext></name>
+ <fsummary>Creates a list from an array</fsummary>
+ <type>
+ <v>ETERM **array;</v>
+ <v>int arrsize;</v>
+ </type>
+ <desc>
+ <p>Creates an Erlang list from an array of Erlang terms, such
+ that each element in the list corresponds to one element in
+ the array. </p>
+ <p><c><![CDATA[array]]></c> is an array of Erlang terms.</p>
+ <p><c><![CDATA[arrsize]]></c> is the number of elements in <c><![CDATA[array]]></c>.</p>
+ <p>The function creates an Erlang list object, whose length
+ <c><![CDATA[arrsize]]></c> and whose elements are taken from the terms in
+ <c><![CDATA[array]]></c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_mk_pid(node, number, serial, creation)</nametext></name>
+ <fsummary>Creates a process identifier</fsummary>
+ <type>
+ <v>const char *node;</v>
+ <v>unsigned int number;</v>
+ <v>unsigned int serial;</v>
+ <v>unsigned int creation;</v>
+ </type>
+ <desc>
+ <p>This function creates an Erlang process identifier. The
+ resulting pid can be used by Erlang processes wishing to
+ communicate with the C node.</p>
+ <p><c><![CDATA[node]]></c> is the name of the C node.</p>
+ <p><c><![CDATA[number]]></c>, <c><![CDATA[serial]]></c> and <c><![CDATA[creation]]></c> 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.</p>
+ <p>The function returns an Erlang pid object.</p>
+ <p><c><![CDATA[ERL_PID_NODE(pid)]]></c>, <c><![CDATA[ERL_PID_NUMBER(pid)]]></c>,
+ <c><![CDATA[ERL_PID_SERIAL(pid)]]></c> and <c><![CDATA[ERL_PID_CREATION(pid)]]></c>
+ can be used to retrieve the four values used to create the pid.</p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_mk_port(node, number, creation)</nametext></name>
+ <fsummary>Creates a port identifier</fsummary>
+ <type>
+ <v>const char *node;</v>
+ <v>unsigned int number;</v>
+ <v>unsigned int creation;</v>
+ </type>
+ <desc>
+ <p>This function creates an Erlang port identifier. </p>
+ <p><c><![CDATA[node]]></c> is the name of the C node.</p>
+ <p><c><![CDATA[number]]></c> and <c><![CDATA[creation]]></c> 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.</p>
+ <p>The function returns an Erlang port object.</p>
+ <p><c><![CDATA[ERL_PORT_NODE(port)]]></c>, <c><![CDATA[ERL_PORT_NUMBER(port)]]></c>
+ and <c><![CDATA[ERL_PORT_CREATION]]></c> can be used to retrieve the three
+ values used to create the port. </p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_mk_ref(node, number, creation)</nametext></name>
+ <fsummary>Creates an old Erlang reference</fsummary>
+ <type>
+ <v>const char *node;</v>
+ <v>unsigned int number;</v>
+ <v>unsigned int creation;</v>
+ </type>
+ <desc>
+ <p>This function creates an old Erlang reference, with
+ only 18 bits - use <c><![CDATA[erl_mk_long_ref]]></c> instead.</p>
+ <p><c><![CDATA[node]]></c> is the name of the C node.</p>
+ <p><c><![CDATA[number]]></c> should be chosen uniquely for each reference
+ created for a given C node.</p>
+ <p><c><![CDATA[creation]]></c> is an arbitrary number.</p>
+ <p>Note that <c><![CDATA[number]]></c> and <c><![CDATA[creation]]></c> are limited in
+ precision, so only the low 18 and 2 bits of these numbers
+ are actually used.
+ </p>
+ <p>The function returns an Erlang reference object.</p>
+ <p><c><![CDATA[ERL_REF_NODE(ref)]]></c>, <c><![CDATA[ERL_REF_NUMBER(ref)]]></c>, and
+ <c><![CDATA[ERL_REF_CREATION(ref)]]></c> to retrieve the three values used
+ to create the reference. </p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_mk_long_ref(node, n1, n2, n3, creation)</nametext></name>
+ <fsummary>Creates an Erlang reference</fsummary>
+ <type>
+ <v>const char *node;</v>
+ <v>unsigned int n1, n2, n3;</v>
+ <v>unsigned int creation;</v>
+ </type>
+ <desc>
+ <p>This function creates an Erlang reference, with 82 bits.</p>
+ <p><c><![CDATA[node]]></c> is the name of the C node.</p>
+ <p><c><![CDATA[n1]]></c>, <c><![CDATA[n2]]></c> and <c><![CDATA[n3]]></c> can be seen as one big number
+ <c><![CDATA[n1*2^64+n2*2^32+n3]]></c> which should be chosen uniquely for
+ each reference
+ created for a given C node.</p>
+ <p><c><![CDATA[creation]]></c> is an arbitrary number.</p>
+ <p>Note that <c><![CDATA[n3]]></c> and <c><![CDATA[creation]]></c> are limited in
+ precision, so only the low 18 and 2 bits of these numbers
+ are actually used.
+ </p>
+ <p>The function returns an Erlang reference object.</p>
+ <p><c><![CDATA[ERL_REF_NODE(ref)]]></c>, <c><![CDATA[ERL_REF_NUMBERS(ref)]]></c>,
+ <c><![CDATA[ERL_REF_LEN(ref)]]></c> and
+ <c><![CDATA[ERL_REF_CREATION(ref)]]></c> to retrieve the values used
+ to create the reference. </p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_mk_string(string)</nametext></name>
+ <fsummary>Creates a string</fsummary>
+ <type>
+ <v>char *string;</v>
+ </type>
+ <desc>
+ <p>This function creates a list from a zero terminated string.</p>
+ <p><c><![CDATA[string]]></c> is the zero-terminated sequence of characters
+ (i.e. a C string) from which the list will be created.</p>
+ <p>The function returns an Erlang list.</p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_mk_tuple(array, arrsize)</nametext></name>
+ <fsummary>Creates an Erlang tuple from an array</fsummary>
+ <type>
+ <v>ETERM **array;</v>
+ <v>int arrsize;</v>
+ </type>
+ <desc>
+ <p>Creates an Erlang tuple from an array of Erlang terms.</p>
+ <p><c><![CDATA[array]]></c> is an array of Erlang terms.</p>
+ <p><c><![CDATA[arrsize]]></c> is the number of elements in <c><![CDATA[array]]></c>.</p>
+ <p>The function creates an Erlang tuple, whose arity is
+ <c><![CDATA[size]]></c> and whose elements are taken from the terms in
+ <c><![CDATA[array]]></c>.</p>
+ <p>To retrieve the size of a tuple, either use the
+ <c><![CDATA[erl_size]]></c> function (which checks the type of the checked
+ term and works for a binary as well as for a tuple), or the
+ <c><![CDATA[ERL_TUPLE_SIZE(tuple)]]></c> returns the arity of a tuple.
+ <c><![CDATA[erl_size()]]></c> will do the same thing, but it checks that
+ the argument really is a tuple.
+ <c><![CDATA[erl_element(index,tuple)]]></c> returns the element
+ corresponding to a given position in the tuple. </p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_mk_uint(n)</nametext></name>
+ <fsummary>Creates an unsigned integer</fsummary>
+ <type>
+ <v>unsigned int n;</v>
+ </type>
+ <desc>
+ <p>Creates an Erlang unsigned integer.</p>
+ <p><c><![CDATA[n]]></c> is a value to be converted to an Erlang
+ unsigned integer.</p>
+ <p></p>
+ <p>The function returns an Erlang unsigned integer object with
+ the value specified in <c><![CDATA[n]]></c>.</p>
+ <p><c><![CDATA[ERL_INT_UVALUE(t)]]></c> can be used to retrieve the
+ value from an Erlang unsigned integer.</p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_mk_var(name)</nametext></name>
+ <fsummary>Creates an Erlang variable</fsummary>
+ <type>
+ <v>char *name;</v>
+ </type>
+ <desc>
+ <p>This function creates an unbound Erlang variable. The
+ variable can later be bound through pattern matching or assignment.</p>
+ <p><c><![CDATA[name]]></c> specifies a name for the variable.</p>
+ <p>The function returns an Erlang variable object with the
+ name <c><![CDATA[name]]></c>. </p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>int</ret><nametext>erl_print_term(stream, term)</nametext></name>
+ <fsummary>Prints an Erlang term</fsummary>
+ <type>
+ <v>FILE *stream;</v>
+ <v>ETERM *term;</v>
+ </type>
+ <desc>
+ <p>This function prints the specified Erlang term to the given
+ output stream.</p>
+ <p><c><![CDATA[stream]]></c> indicates where the function should send its
+ output.</p>
+ <p><c><![CDATA[term]]></c> is the Erlang term to print.</p>
+ <p>The function returns the number of characters written, or a
+ negative value if there was an error.</p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>void</ret><nametext>erl_set_compat_rel(release_number)</nametext></name>
+ <fsummary>Set the erl_interface library in compatibility mode</fsummary>
+ <type>
+ <v>unsigned release_number;</v>
+ </type>
+ <desc>
+ <marker id="erl_set_compat_rel"></marker>
+ <p>By default, the <c><![CDATA[erl_interface]]></c> library is only guaranteed
+ to be compatible with other Erlang/OTP components from the same
+ release as the <c><![CDATA[erl_interface]]></c> library itself. For example,
+ <c><![CDATA[erl_interface]]></c> from the OTP R10 release is not compatible
+ with an Erlang emulator from the OTP R9 release by default.</p>
+ <p>A call to <c><![CDATA[erl_set_compat_rel(release_number)]]></c> sets the
+ <c><![CDATA[erl_interface]]></c> library in compatibility mode of release
+ <c><![CDATA[release_number]]></c>. Valid range of <c><![CDATA[release_number]]></c>
+ is [7, current release]. This makes it possible to
+ communicate with Erlang/OTP components from earlier releases.</p>
+ <note>
+ <p>If this function is called, it may only be called once
+ directly after the call to the
+ <seealso marker="#erl_init">erl_init()</seealso> function.</p>
+ </note>
+ <warning>
+ <p>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.</p>
+ </warning>
+ </desc>
+ </func>
+ <func>
+ <name><ret>int</ret><nametext>erl_size(term)</nametext></name>
+ <fsummary>Return the arity of a tuple or binary</fsummary>
+ <type>
+ <v>ETERM *term;</v>
+ </type>
+ <desc>
+ <p>Returns the arity of an Erlang tuple, or the
+ number of bytes in an Erlang binary object. </p>
+ <p><c><![CDATA[term]]></c> is an Erlang tuple or an Erlang binary object.</p>
+ <p>The function returns the size of <c><![CDATA[term]]></c> as described
+ above, or -1 if <c><![CDATA[term]]></c> is not one of the two supported
+ types. </p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_tl(list)</nametext></name>
+ <fsummary>Extracts the tail from a list</fsummary>
+ <type>
+ <v>ETERM *list;</v>
+ </type>
+ <desc>
+ <p>Extracts the tail from a list.</p>
+ <p><c><![CDATA[list]]></c> is an Erlang term containing a list.</p>
+ <p>The function returns an Erlang list corresponding to the
+ original list minus the first element, or NULL pointer if
+ <c><![CDATA[list]]></c> was not a list.</p>
+ </desc>
+ </func>
+ <func>
+ <name><ret>ETERM *</ret><nametext>erl_var_content(term, name)</nametext></name>
+ <fsummary>Extracts the content of a variable</fsummary>
+ <type>
+ <v>ETERM *term;</v>
+ <v>char *name;</v>
+ </type>
+ <desc>
+ <p>This function returns the contents of the specified
+ variable in an Erlang term.
+ </p>
+ <p><c><![CDATA[term]]></c> is an Erlang term. In order for this function
+ to succeed, <c><![CDATA[term]]></c> 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.</p>
+ <p><c><![CDATA[name]]></c> is the name of an Erlang variable.</p>
+ <p>Returns the Erlang object corresponding to the value of
+ <c><![CDATA[name]]></c> in <c><![CDATA[term]]></c>. If no variable with the name
+ <c><![CDATA[name]]></c> was found in <c><![CDATA[term]]></c>, or if <c><![CDATA[term]]></c> is
+ not a valid Erlang term, NULL is returned.</p>
+ </desc>
+ </func>
+ </funcs>
+</cref>
+