diff options
author | xsipewe <[email protected]> | 2016-10-20 11:46:03 +0200 |
---|---|---|
committer | Björn-Egil Dahlberg <[email protected]> | 2016-10-20 14:10:04 +0200 |
commit | 031f9ca91ade7fbb9e31c82545401b8a5531e539 (patch) | |
tree | ab191bf48e2e67d99d8e03fd0482ec0f0897e519 /lib/erl_interface/doc/src/erl_eterm.xml | |
parent | 9f5b69e8def226f1d1ce9262477d5bbd1cbc1fe7 (diff) | |
download | otp-031f9ca91ade7fbb9e31c82545401b8a5531e539.tar.gz otp-031f9ca91ade7fbb9e31c82545401b8a5531e539.tar.bz2 otp-031f9ca91ade7fbb9e31c82545401b8a5531e539.zip |
erl_interface: Editorial changes
Diffstat (limited to 'lib/erl_interface/doc/src/erl_eterm.xml')
-rw-r--r-- | lib/erl_interface/doc/src/erl_eterm.xml | 588 |
1 files changed, 336 insertions, 252 deletions
diff --git a/lib/erl_interface/doc/src/erl_eterm.xml b/lib/erl_interface/doc/src/erl_eterm.xml index e5207a271e..8a46c20432 100644 --- a/lib/erl_interface/doc/src/erl_eterm.xml +++ b/lib/erl_interface/doc/src/erl_eterm.xml @@ -28,23 +28,26 @@ <docno></docno> <approved>Bjarne Däcker</approved> <checked>Torbjörn Törnkvist</checked> - <date>980703</date> + <date>1998-07-03</date> <rev>A</rev> <file>erl_eterm.xml</file> </header> <lib>erl_eterm</lib> - <libsummary>Functions for Erlang Term Construction</libsummary> + <libsummary>Functions for Erlang term construction.</libsummary> <description> - <p>This module contains functions for creating and manipulating - Erlang terms. </p> + <p>This module provides 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 + <c><![CDATA[ETERM]]></c>. Applications should not reference any fields + in this structure directly, as it can 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> + applications should use the macros and functions provided.</p> + + <p>Each of the following macros takes a single <c>ETERM</c> pointer as an + argument. The macros return a non-zero value if the test is true, + otherwise <c>0</c>.</p> + <taglist> <tag><c><![CDATA[ERL_IS_INTEGER(t)]]></c></tag> <item>True if <c><![CDATA[t]]></c> is an integer.</item> @@ -55,7 +58,7 @@ <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> + <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> @@ -65,29 +68,31 @@ <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> + <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> + <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> + terms. None of these do any type checking. Results are undefined + if you pass an <c>ETERM*</c> containing the wrong type. For example, + passing a tuple to <c>ERL_ATOM_PTR()</c> likely results in garbage.</p> + <taglist> <tag><c><![CDATA[char *ERL_ATOM_PTR(t)]]></c></tag> - <item/> + <item></item> <tag><c><![CDATA[char *ERL_ATOM_PTR_UTF8(t)]]></c></tag> - <item>A string representing atom <c><![CDATA[t]]></c>. - </item> + <item>A string representing atom <c><![CDATA[t]]></c>.</item> <tag><c><![CDATA[int ERL_ATOM_SIZE(t)]]></c></tag> - <item/> + <item></item> <tag><c><![CDATA[int ERL_ATOM_SIZE_UTF8(t)]]></c></tag> - <item>The length (in bytes) of atom t.</item> + <item>The length (in bytes) of atom <c><![CDATA[t]]></c>.</item> <tag><c><![CDATA[void *ERL_BIN_PTR(t)]]></c></tag> - <item>A pointer to the contents of <c><![CDATA[t]]></c></item> + <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> @@ -97,9 +102,9 @@ <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/> + <item></item> <tag><c><![CDATA[ETERM *ERL_PID_NODE_UTF8(t)]]></c></tag> - <item>The Node in pid <c><![CDATA[t]]></c>.</item> + <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> @@ -111,16 +116,18 @@ <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/> + <item></item> <tag><c><![CDATA[ETERM *ERL_PORT_NODE_UTF8(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> + <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> + <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> + <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> @@ -128,31 +135,38 @@ <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> + <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> + <fsummary>Prepend 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>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> is always to be a list + or an empty list. Notice that <c>NULL</c> is not a valid list.</p> + <list type="bulleted"> + <item><c><![CDATA[head]]></c> is the new term to be added.</item> + <item><c><![CDATA[tail]]></c> is the existing list to which + <c><![CDATA[head]]></c> is concatenated.</item> + </list> <p>The function returns a new list.</p> - <p><c><![CDATA[ERL_CONS_HEAD(list)]]></c> and <c><![CDATA[ERL_CONS_TAIL(list)]]></c> + <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 + from the list. <c><![CDATA[erl_hd(list)]]></c> and + <c><![CDATA[erl_tl(list)]]></c> do the same thing, but check that the argument really is a list.</p> - <p>For example:</p> + <p><em>Example:</em></p> <code type="none"><![CDATA[ ETERM *list,*anAtom,*anInt; anAtom = erl_mk_atom("madonna"); @@ -165,50 +179,56 @@ 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> + <fsummary>Create 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 + <p>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> + <fsummary>Extract 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> + <p>Extracts a specified element from an Erlang tuple.</p> + <iist type="bulleted"> + <item><c><![CDATA[position]]></c> specifies which element to retrieve + from <c><![CDATA[tuple]]></c>. The elements are numbered starting + from 1.</item> + <item><c><![CDATA[tuple]]></c> is an Erlang term containing at least + <c><![CDATA[position]]></c> elements.</item> + </iist> + <p>Returns a new Erlang term corresponding to the requested element, or + <c>NULL</c> if <c><![CDATA[position]]></c> was greater + than the arity of <c><![CDATA[tuple]]></c>.</p> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_hd(list)</nametext></name> - <fsummary>Extracts the first element from a list.</fsummary> + <fsummary>Extract 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> + <p>Returns an Erlang term corresponding to the head + head element in the list, or a <c>NULL</c> pointer if + <c><![CDATA[list]]></c> was not a list.</p> </desc> </func> + <func> <name><ret>void</ret><nametext>erl_init(NULL, 0)</nametext></name> <fsummary>Initialization routine.</fsummary> @@ -218,42 +238,45 @@ erl_free_compound(list); </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 + <p>This function must be called before any of the others in the + <c><![CDATA[Erl_Interface]]></c> library to initialize the library functions. The arguments must be specified as <c><![CDATA[erl_init(NULL,0)]]></c>.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>erl_iolist_length(list)</nametext></name> - <fsummary>Return the length of an IO list.</fsummary> + <fsummary>Return the length of an I/O 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> + <p>Returns the length of an I/O list.</p> + <p><c><![CDATA[list]]></c> is an Erlang term containing an I/O list.</p> + <p>Returns the length of <c><![CDATA[list]]></c>, or + <c>-1</c> if <c><![CDATA[list]]></c> is not an I/O list.</p> + <p>For the definition of an I/O list, see + <seealso marker="#erl_iolist_to_binary"> + <c>erl_iolist_to_binary</c></seealso>.</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> + <fsummary>Convert an I/O 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>Converts an I/O 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> + <p>Returns an Erlang binary term, or <c>NULL</c> if + <c><![CDATA[list]]></c> was not an I/O list.</p> + <marker id="erl_iolist_to_binary"></marker> + <p>Informally, an I/O list is a deep list of characters and + binaries that can be sent to an Erlang port. In BNF, an I/O + list is formally defined as follows:</p> <code type="none"><![CDATA[ iolist ::= [] | Binary @@ -266,44 +289,49 @@ iohead ::= Binary ]]></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> + <fsummary>Convert an I/O 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 + <p>Converts an I/O list to a '\0' terminated C string.</p> + <p><c><![CDATA[list]]></c> is an Erlang term containing an I/O list. + The I/O list must not contain the integer 0, as 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> + <p>Returns a pointer to a dynamically allocated + buffer containing a string. If <c><![CDATA[list]]></c> is not an I/O + list, or if <c><![CDATA[list]]></c> contains the integer 0, + <c>NULL</c> is returned. It + is the caller's responsibility to free the allocated buffer + with <c><![CDATA[erl_free()]]></c>.</p> + <p>For the definition of an I/O list, see + <seealso marker="#erl_iolist_to_binary"> + <c>erl_iolist_to_binary</c></seealso>.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>erl_length(list)</nametext></name> - <fsummary>Determines the length of a list.</fsummary> + <fsummary>Determine 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 + <p><c><![CDATA[list]]></c> is an Erlang term containing a 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> + <p>Returns <c>-1</c> 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> + <fsummary>Create an atom.</fsummary> <type> <v>const char *string;</v> </type> @@ -311,97 +339,114 @@ iohead ::= Binary <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> + <p>Returns an Erlang term containing an atom. Notice that it is + the caller's responsibility to ensure that <c><![CDATA[string]]></c> contains a valid name for an atom.</p> - <p><c><![CDATA[ERL_ATOM_PTR(atom)]]></c> and <c><![CDATA[ERL_ATOM_PTR_UTF8(atom)]]></c> - can be used to retrieve the atom name (as a null terminated string). <c><![CDATA[ERL_ATOM_SIZE(atom)]]></c> - and <c><![CDATA[ERL_ATOM_SIZE_UTF8(atom)]]></c> returns the length of the atom name.</p> - <note><p>Note that the UTF8 variants were introduced in Erlang/OTP releases R16 - and the string returned by <c>ERL_ATOM_PTR(atom)</c> was not null terminated on older releases.</p> + <p><c><![CDATA[ERL_ATOM_PTR(atom)]]></c> and + <c><![CDATA[ERL_ATOM_PTR_UTF8(atom)]]></c> + can be used to retrieve the atom name (as a null-terminated string). + <c><![CDATA[ERL_ATOM_SIZE(atom)]]></c> + and <c><![CDATA[ERL_ATOM_SIZE_UTF8(atom)]]></c> return the length + of the atom name.</p> + <note> + <p>The UTF-8 variants were introduced in Erlang/OTP R16 and the + string returned by <c>ERL_ATOM_PTR(atom)</c> was not + null-terminated on older releases.</p> </note> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_mk_binary(bptr, size)</nametext></name> - <fsummary>Creates a binary object.</fsummary> + <fsummary>Create 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 + <p>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> + <list type="bulleted"> + <item><c><![CDATA[bptr]]></c> is a pointer to a buffer containing + data to be converted.</item> + <item><c><![CDATA[size]]></c> indicates the length of + <c><![CDATA[bptr]]></c>.</item> + </list> + <p>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> + size.</p> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_mk_empty_list()</nametext></name> - <fsummary>Creates an empty Erlang list.</fsummary> + <fsummary>Create 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; + <p>Creates and returns an empty Erlang list. + Notice that <c>NULL</c> 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> + <fsummary>Create 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 + <p>Creates a list from a sequence of bytes.</p> + <list type="bulleted"> + <item><c><![CDATA[string]]></c> is a buffer containing a sequence of + bytes. The buffer does not need to be zero-terminated.</item> + <item><c><![CDATA[len]]></c> is the length of + <c><![CDATA[string]]></c>.</item> + </list> + <p>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> + <fsummary>Create 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> or <c><![CDATA[NULL]]></c> if - <c><![CDATA[f]]></c> is not finite. - </p> + <p><c><![CDATA[f]]></c> is a value to be converted to an Erlang + float.</p> + <p>Returns an Erlang float object with the value + specified in <c><![CDATA[f]]></c> or <c><![CDATA[NULL]]></c> if + <c><![CDATA[f]]></c> is not finite.</p> <p><c><![CDATA[ERL_FLOAT_VALUE(t)]]></c> can be used to retrieve the - value from an Erlang float.</p> + 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> + <fsummary>Create 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 + <p><c><![CDATA[n]]></c> is a value to be converted to an Erlang + integer.</p> + <p>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 + <p><c><![CDATA[ERL_INT_VALUE(t)]]></c> can be used to retrieve the 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> + <fsummary>Create a list from an array.</fsummary> <type> <v>ETERM **array;</v> <v>int arrsize;</v> @@ -409,44 +454,51 @@ iohead ::= Binary <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> + the array.</p> + <list type="bulleted"> + <item><c><![CDATA[array]]></c> is an array of Erlang terms.</item> + <item><c><![CDATA[arrsize]]></c> is the number of elements in + <c><![CDATA[array]]></c>.</item> + </list> <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> + <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_long_ref(node, n1, n2, n3, creation)</nametext></name> - <fsummary>Creates an Erlang reference.</fsummary> + <fsummary>Create 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> + <p>Creates an Erlang reference, with 82 bits.</p> + <list type="bulleted"> + <item><c><![CDATA[node]]></c> is the name of the C-node.</item> + <item><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 is to be chosen + uniquely for each reference created for a given C-node.</item> + <item><c><![CDATA[creation]]></c> is an arbitrary number.</item> + </list> + <p>Notice 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 used.</p> + <p>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> can be used to retrieve the + values used to create the reference.</p> </desc> </func> + <func> <name><ret>ETERM *</ret><nametext>erl_mk_pid(node, number, serial, creation)</nametext></name> - <fsummary>Creates a process identifier.</fsummary> + <fsummary>Create a process identifier.</fsummary> <type> <v>const char *node;</v> <v>unsigned int number;</v> @@ -454,106 +506,125 @@ iohead ::= Binary <v>unsigned int creation;</v> </type> <desc> - <p>This function creates an Erlang process identifier. The + <p>Creates an Erlang process identifier (pid). 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> + communicate with the C-node.</p> + <list type="bulleted"> + <item><c><![CDATA[node]]></c> is the name of the C-node.</item> + <item><c><![CDATA[number]]></c>, <c><![CDATA[serial]]></c>, and + <c><![CDATA[creation]]></c> are + arbitrary numbers. Notice that these are limited in + precision, so only the low 15, 3, and 2 bits of these numbers + are used.</item> + </list> + <p>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> + <fsummary>Create 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> + <p>Creates an Erlang port identifier.</p> + <list type="bulleted"> + <item><c><![CDATA[node]]></c> is the name of the C-node.</item> + <item><c><![CDATA[number]]></c> and <c><![CDATA[creation]]></c> are + arbitrary numbers. Notice that these are limited in + precision, so only the low 18 and 2 bits of these numbers + are used.</item> + </list> + <p>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> + <fsummary>Create 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 + <p>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> + <list type="bulleted"> + <item><c><![CDATA[node]]></c> is the name of the C-node.</item> + <item><c><![CDATA[number]]></c> is to be chosen uniquely for each + reference created for a given C-node.</item> + <item><c><![CDATA[creation]]></c> is an arbitrary number.</item> + </list> + <p>Notice 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 used.</p> + <p>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> can be used to retrieve the + three 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> + <fsummary>Create 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> + <p>Creates a list from a zero-terminated string.</p> + <p><c><![CDATA[string]]></c> is the zero-terminated sequence of + characters + (that is, a C string) from which the list will be created.</p> + <p>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> + <fsummary>Create 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> + <list type="bulleted"> + <item><c><![CDATA[array]]></c> is an array of Erlang terms.</item> + <item><c><![CDATA[arrsize]]></c> is the number of elements in + <c><![CDATA[array]]></c>.</item> + </list> <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[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 function + <c><![CDATA[erl_size]]></c> (which checks the type of the + checked term and works for a binary as well as for a tuple) or <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_size()]]></c> does the same thing, but it checks + that the argument is a tuple. <c><![CDATA[erl_element(index,tuple)]]></c> returns the element - corresponding to a given position in the tuple. </p> + 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> + <fsummary>Create an unsigned integer.</fsummary> <type> <v>unsigned int n;</v> </type> @@ -561,76 +632,83 @@ iohead ::= Binary <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 + <p>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> + <fsummary>Create 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>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> + <p>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> + <fsummary>Print 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> + <p>Prints the specified Erlang term to the specified output stream.</p> + <list type="bulleted"> + <item><c><![CDATA[stream]]></c> indicates where the function is to + send its output.</item> + <item><c><![CDATA[term]]></c> is the Erlang term to print.</item> + </list> + <p>Returns the number of characters written on success, otherwise a + negative value.</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> + <fsummary>Set the Erl_Interface library in compatibility mode.</fsummary> + <marker id="erl_set_compat_rel"/> <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> + <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 Erlang/OTP R10 + is not compatible + with an Erlang emulator from Erlang/OTP R9 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> + directly after the call to function + <seealso marker="#erl_init">erl_init()</seealso>.</p> </note> <warning> <p>You may run into trouble if this feature is used - carelessly. Always make sure that all communicating + carelessly. Always ensure 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> @@ -638,49 +716,55 @@ iohead ::= Binary <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> + <p>Returns either 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>Returns the size of <c><![CDATA[term]]></c> as described + above, or <c>-1</c> 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> + <fsummary>Extract 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 + <p>Returns an Erlang list corresponding to the + original list minus the first element, or <c>NULL</c> 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> + <fsummary>Extract 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 contents of the specified variable in an Erlang term.</p> + <list type="bulleted"> + <item><c><![CDATA[term]]></c> is an Erlang term. In order for this + function to succeed, + <c><![CDATA[term]]></c> must either 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.</item> + <item><c><![CDATA[name]]></c> is the name of an Erlang variable. + </item> + </list> <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> + <c><![CDATA[name]]></c> in <c><![CDATA[term]]></c>. If no variable + with the name <c><![CDATA[name]]></c> is found in + <c><![CDATA[term]]></c>, or if <c><![CDATA[term]]></c> is + not a valid Erlang term, <c>NULL</c> is returned.</p> </desc> </func> </funcs> |