diff options
Diffstat (limited to 'lib/erl_interface/doc/src/erl_eterm.xml')
| -rw-r--r-- | lib/erl_interface/doc/src/erl_eterm.xml | 675 |
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örn Törnkvist</prepared> + <responsible>Torbjörn Törnkvist</responsible> + <docno></docno> + <approved>Bjarne Däcker</approved> + <checked>Torbjörn Tö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> + |