From 031f9ca91ade7fbb9e31c82545401b8a5531e539 Mon Sep 17 00:00:00 2001 From: xsipewe Date: Thu, 20 Oct 2016 11:46:03 +0200 Subject: erl_interface: Editorial changes --- lib/erl_interface/doc/src/erl_eterm.xml | 588 ++++++++++++++++++-------------- 1 file changed, 336 insertions(+), 252 deletions(-) (limited to 'lib/erl_interface/doc/src/erl_eterm.xml') 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 @@ Bjarne Däcker Torbjörn Törnkvist - 980703 + 1998-07-03 A erl_eterm.xml erl_eterm - Functions for Erlang Term Construction + Functions for Erlang term construction. -

This module contains functions for creating and manipulating - Erlang terms.

+

This module provides functions for creating and manipulating + Erlang terms.

+

An Erlang term is represented by a C structure of type - . Applications should not reference any fields in this - structure directly, because it may be changed in future releases + . 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.

-

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:

+ applications should use the macros and functions provided.

+ +

Each of the following macros takes a single ETERM pointer as an + argument. The macros return a non-zero value if the test is true, + otherwise 0.

+ True if is an integer. @@ -55,7 +58,7 @@ True if is an atom. - True if is a Pid (process identifier). + True if is a pid (process identifier). True if is a port. @@ -65,29 +68,31 @@ True if is a binary. - True if is a list with zero or more elements. + True if is a list with zero or more + elements. True if is an empty list. - True if is a list with at least one element. + True if is a list with at least one + element. +

The following macros can be used for retrieving parts of Erlang - terms. None of these do any type checking; results are undefined - if you pass an ETERM* containing the wrong type. For example, - passing a tuple to ERL_ATOM_PTR() will likely result in garbage. -

+ 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() likely results in garbage.

+ - + - A string representing atom . - + A string representing atom . - + - The length (in bytes) of atom t. + The length (in bytes) of atom . - A pointer to the contents of + A pointer to the contents of . The length (in bytes) of binary object . @@ -97,9 +102,9 @@ The floating point value of . - + - The Node in pid . + The node in pid . The sequence number in pid . @@ -111,16 +116,18 @@ The creation number in port . - + The node in port . - The first part of the reference number in ref . Use - only for compatibility. + The first part of the reference number in ref . + Use only for compatibility. - Pointer to the array of reference numbers in ref . + Pointer to the array of reference numbers in ref + . - The number of used reference numbers in ref . + The number of used reference numbers in ref + . The creation number in ref . @@ -128,31 +135,38 @@ The head element of list . - A List representing the tail elements of list . + A list representing the tail elements of list + . + ETERM *erl_cons(head, tail) - Prepends a term to the head of a list. + Prepend a term to the head of a list. ETERM *head; ETERM *tail; -

This function concatenates two Erlang terms, prepending - onto and thereby creating a cell. - To make a proper list, should always be a - list or an empty list. Note that NULL is not a valid list.

-

is the new term to be added.

-

is the existing list to which will - be concatenated.

+

Concatenates two Erlang terms, prepending + onto and thereby creating a + cell. + To make a proper list, is always to be a list + or an empty list. Notice that NULL is not a valid list.

+ + is the new term to be added. + is the existing list to which + is concatenated. +

The function returns a new list.

-

and +

and + can be used to retrieve the head and tail components - from the list. and will do + from the list. and + do the same thing, but check that the argument really is a list.

-

For example:

+

Example:

 + ETERM *erl_copy_term(term) - Creates a copy of an Erlang term. + Create a copy of an Erlang term. ETERM *term; -

This function creates and returns a copy of the Erlang term +

Creates and returns a copy of the Erlang term .

 + ETERM *erl_element(position, tuple) - Extracts an element from an Erlang tuple. + Extract an element from an Erlang tuple. int position; ETERM *tuple; -

This function extracts a specified element from an Erlang - tuple.

-

specifies which element to retrieve from - . The elements are numbered starting from 1.

-

is an Erlang term containing at least - elements.

-

The function returns a new Erlang term corresponding to the - requested element, or NULL if was greater than - the arity of .

+

Extracts a specified element from an Erlang tuple.

+ + specifies which element to retrieve + from . The elements are numbered starting + from 1. + is an Erlang term containing at least + elements. + +

Returns a new Erlang term corresponding to the requested element, or + NULL if was greater + than the arity of .

 + ETERM *erl_hd(list) - Extracts the first element from a list. + Extract the first element from a list. ETERM *list;

Extracts the first element from a list.

is an Erlang term containing a list.

-

The function returns an Erlang term corresponding to the - head element in the list, or a NULL pointer if was - not a list.

+

Returns an Erlang term corresponding to the head + head element in the list, or a NULL pointer if + was not a list.

 + voiderl_init(NULL, 0) Initialization routine. @@ -218,42 +238,45 @@ erl_free_compound(list); -

This function must be called before any of the others in - the library in order to initialize the +

This function must be called before any of the others in the + library to initialize the library functions. The arguments must be specified as .

 + interl_iolist_length(list) - Return the length of an IO list. + Return the length of an I/O list. ETERM *list; -

Returns the length of an IO list. -

-

is an Erlang term containing an IO list.

-

The function returns the length of , or -1 if - is not an IO list.

-

Refer to for the definition of - an IO list.

+

Returns the length of an I/O list.

+

is an Erlang term containing an I/O list.

+

Returns the length of , or + -1 if is not an I/O list.

+

For the definition of an I/O list, see + + erl_iolist_to_binary.

 + ETERM *erl_iolist_to_binary(term) - Converts an IO list to a binary. + Convert an I/O list to a binary. ETERM *list; -

This function converts an IO list to a binary term.

+

Converts an I/O list to a binary term.

is an Erlang term containing a list.

-

This function an Erlang binary term, or NULL if - was not an IO list.

-

Informally, an IO list is a deep list of characters and - binaries which can be sent to an Erlang port. In BNF, an IO - list is formally defined as follows:

+

Returns an Erlang binary term, or NULL if + was not an I/O list.

+ +

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:

 + char *erl_iolist_to_string(list) - Converts an IO list to a zero terminated string. + Convert an I/O list to a zero-terminated string. ETERM *list; -

This function converts an IO list to a '\0' terminated C - string.

-

is an Erlang term containing an IO list. The IO - list must not contain the integer 0, since C strings may not +

Converts an I/O list to a '\0' terminated C string.

+

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.

-

This function returns a pointer to a dynamically allocated - buffer containing a string. If is not an IO list, - or if contains the integer 0, NULL is returned. It - is the caller's responsibility free the allocated buffer - with .

-

Refer to for the definition of an - IO list.

+

Returns a pointer to a dynamically allocated + buffer containing a string. If is not an I/O + list, or if contains the integer 0, + NULL is returned. It + is the caller's responsibility to free the allocated buffer + with .

+

For the definition of an I/O list, see + + erl_iolist_to_binary.

 + interl_length(list) - Determines the length of a list. + Determine the length of a list. ETERM *list;

Determines the length of a proper list.

-

is an Erlang term containing proper list. In a - proper list, all tails except the last point to another list +

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.

-

Returns -1 if is not a proper list.

+

Returns -1 if is not a proper + list.

 + ETERM *erl_mk_atom(string) - Creates an atom. + Create an atom. const char *string; @@ -311,97 +339,114 @@ iohead ::= Binary

Creates an atom.

is the sequence of characters that will be used to create the atom.

-

Returns an Erlang term containing an atom. Note that it is - the callers responsibility to make sure that +

Returns an Erlang term containing an atom. Notice that it is + the caller's responsibility to ensure that contains a valid name for an atom.

-

and - can be used to retrieve the atom name (as a null terminated string). - and returns the length of the atom name.

-

Note that the UTF8 variants were introduced in Erlang/OTP releases R16 - and the string returned by ERL_ATOM_PTR(atom) was not null terminated on older releases.

+

and + + can be used to retrieve the atom name (as a null-terminated string). + + and return the length + of the atom name.

+ +

The UTF-8 variants were introduced in Erlang/OTP R16 and the + string returned by ERL_ATOM_PTR(atom) was not + null-terminated on older releases.

 + ETERM *erl_mk_binary(bptr, size) - Creates a binary object. + Create a binary object. char *bptr; int size; -

This function produces an Erlang binary object from a +

Produces an Erlang binary object from a buffer containing a sequence of bytes.

-

is a pointer to a buffer containing data to be converted.

-

indicates the length of .

-

The function returns an Erlang binary object.

+ + is a pointer to a buffer containing + data to be converted. + indicates the length of + . + +

Returns an Erlang binary object.

retrieves a pointer to the binary data. retrieves the - size.

+ size.

 + ETERM *erl_mk_empty_list() - Creates an empty Erlang list. + Create an empty Erlang list. -

This function creates and returns an empty Erlang list. - Note that NULL is not used to represent an empty list; +

Creates and returns an empty Erlang list. + Notice that NULL is not used to represent an empty list; Use this function instead.

 + ETERM *erl_mk_estring(string, len) - Creates an Erlang string. + Create an Erlang string. char *string; int len; -

This function creates a list from a sequence of bytes.

-

is a buffer containing a sequence of - bytes. The buffer does not need to be zero-terminated.

-

is the length of .

-

The function returns an Erlang list object corresponding to +

Creates a list from a sequence of bytes.

+ + is a buffer containing a sequence of + bytes. The buffer does not need to be zero-terminated. + is the length of + . + +

Returns an Erlang list object corresponding to the character sequence in .

 + ETERM *erl_mk_float(f) - Creates an Erlang float. + Create an Erlang float. double f;

Creates an Erlang float.

-

is a value to be converted to an Erlang float.

-

-

The function returns an Erlang float object with the value - specified in or if - is not finite. -

+

is a value to be converted to an Erlang + float.

+

Returns an Erlang float object with the value + specified in or if + is not finite.

can be used to retrieve the - value from an Erlang float.

+ value from an Erlang float.

 + ETERM *erl_mk_int(n) - Creates an Erlang integer. + Create an Erlang integer. int n;

Creates an Erlang integer.

-

is a value to be converted to an Erlang integer.

-

-

The function returns an Erlang integer object with the +

is a value to be converted to an Erlang + integer.

+

Returns an Erlang integer object with the value specified in .

-

can be used to retrieve the value +

can be used to retrieve the value from an Erlang integer.

 + ETERM *erl_mk_list(array, arrsize) - Creates a list from an array. + Create a list from an array. ETERM **array; int arrsize; @@ -409,44 +454,51 @@ iohead ::= Binary

Creates an Erlang list from an array of Erlang terms, such that each element in the list corresponds to one element in - the array.

-

is an array of Erlang terms.

-

is the number of elements in .

+ the array.

+ + is an array of Erlang terms. + is the number of elements in + . +

The function creates an Erlang list object, whose length - and whose elements are taken from the terms in - .

+ and whose elements are taken from the + terms in .

 + ETERM *erl_mk_long_ref(node, n1, n2, n3, creation) - Creates an Erlang reference. + Create an Erlang reference. const char *node; unsigned int n1, n2, n3; unsigned int creation; -

This function creates an Erlang reference, with 82 bits.

-

is the name of the C node.

-

, and can be seen as one big number - which should be chosen uniquely for - each reference - created for a given C node.

-

is an arbitrary number.

-

Note that and are limited in - precision, so only the low 18 and 2 bits of these numbers - are actually used. -

-

The function returns an Erlang reference object.

-

, , - and - to retrieve the values used - to create the reference.

+

Creates an Erlang reference, with 82 bits.

+ + is the name of the C-node. + , , and + can be seen as one big number + , which is to be chosen + uniquely for each reference created for a given C-node. + is an arbitrary number. + +

Notice that and + are limited in precision, so only the low 18 and 2 bits of these + numbers are used.

+

Returns an Erlang reference object.

+

, + , + , and + can be used to retrieve the + values used to create the reference.

 + ETERM *erl_mk_pid(node, number, serial, creation) - Creates a process identifier. + Create a process identifier. const char *node; unsigned int number; @@ -454,106 +506,125 @@ iohead ::= Binary unsigned int creation; -

This function creates an Erlang process identifier. The +

Creates an Erlang process identifier (pid). The resulting pid can be used by Erlang processes wishing to - communicate with the C node.

-

is the name of the C node.

-

, and 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.

-

The function returns an Erlang pid object.

-

, , - and + communicate with the C-node.

+ + is the name of the C-node. + , , and + are + arbitrary numbers. Notice that these are limited in + precision, so only the low 15, 3, and 2 bits of these numbers + are used. + +

Returns an Erlang pid object.

+

, + , + , and + can be used to retrieve the four values used to create the pid.

 + ETERM *erl_mk_port(node, number, creation) - Creates a port identifier. + Create a port identifier. const char *node; unsigned int number; unsigned int creation; -

This function creates an Erlang port identifier.

-

is the name of the C node.

-

and 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.

-

The function returns an Erlang port object.

-

, - and can be used to retrieve the three - values used to create the port.

+

Creates an Erlang port identifier.

+ + is the name of the C-node. + and are + arbitrary numbers. Notice that these are limited in + precision, so only the low 18 and 2 bits of these numbers + are used. + +

Returns an Erlang port object.

+

, + , + and can be used to retrieve the + three values used to create the port.

 + ETERM *erl_mk_ref(node, number, creation) - Creates an old Erlang reference. + Create an old Erlang reference. const char *node; unsigned int number; unsigned int creation; -

This function creates an old Erlang reference, with +

Creates an old Erlang reference, with only 18 bits - use instead.

-

is the name of the C node.

-

should be chosen uniquely for each reference - created for a given C node.

-

is an arbitrary number.

-

Note that and are limited in - precision, so only the low 18 and 2 bits of these numbers - are actually used. -

-

The function returns an Erlang reference object.

-

, , and - to retrieve the three values used - to create the reference.

+ + is the name of the C-node. + is to be chosen uniquely for each + reference created for a given C-node. + is an arbitrary number. + +

Notice that and + are limited in precision, so only the low 18 and 2 bits of these + numbers are used.

+

Returns an Erlang reference object.

+

, + , and + can be used to retrieve the + three values used to create the reference.

 + ETERM *erl_mk_string(string) - Creates a string. + Create a string. char *string; -

This function creates a list from a zero terminated string.

-

is the zero-terminated sequence of characters - (i.e. a C string) from which the list will be created.

-

The function returns an Erlang list.

+

Creates a list from a zero-terminated string.

+

is the zero-terminated sequence of + characters + (that is, a C string) from which the list will be created.

+

Returns an Erlang list.

 + ETERM *erl_mk_tuple(array, arrsize) - Creates an Erlang tuple from an array. + Create an Erlang tuple from an array. ETERM **array; int arrsize;

Creates an Erlang tuple from an array of Erlang terms.

-

is an array of Erlang terms.

-

is the number of elements in .

+ + is an array of Erlang terms. + is the number of elements in + . +

The function creates an Erlang tuple, whose arity is - and whose elements are taken from the terms in - .

-

To retrieve the size of a tuple, either use the - function (which checks the type of the checked - term and works for a binary as well as for a tuple), or the + and whose elements are taken from the terms + in .

+

To retrieve the size of a tuple, either use function + (which checks the type of the + checked term and works for a binary as well as for a tuple) or returns the arity of a tuple. - will do the same thing, but it checks that - the argument really is a tuple. + does the same thing, but it checks + that the argument is a tuple. returns the element - corresponding to a given position in the tuple.

+ corresponding to a given position in the tuple.

 + ETERM *erl_mk_uint(n) - Creates an unsigned integer. + Create an unsigned integer. unsigned int n; @@ -561,76 +632,83 @@ iohead ::= Binary

Creates an Erlang unsigned integer.

is a value to be converted to an Erlang unsigned integer.

-

-

The function returns an Erlang unsigned integer object with +

Returns an Erlang unsigned integer object with the value specified in .

can be used to retrieve the value from an Erlang unsigned integer.

 + ETERM *erl_mk_var(name) - Creates an Erlang variable. + Create an Erlang variable. char *name; -

This function creates an unbound Erlang variable. The - variable can later be bound through pattern matching or assignment.

+

Creates an unbound Erlang variable. The variable can later be bound + through pattern matching or assignment.

specifies a name for the variable.

-

The function returns an Erlang variable object with the - name .

+

Returns an Erlang variable object with the + name .

 + interl_print_term(stream, term) - Prints an Erlang term. + Print an Erlang term. FILE *stream; ETERM *term; -

This function prints the specified Erlang term to the given - output stream.

-

indicates where the function should send its - output.

-

is the Erlang term to print.

-

The function returns the number of characters written, or a - negative value if there was an error.

+

Prints the specified Erlang term to the specified output stream.

+ + indicates where the function is to + send its output. + is the Erlang term to print. + +

Returns the number of characters written on success, otherwise a + negative value.

 + voiderl_set_compat_rel(release_number) - Set the erl_interface library in compatibility mode. + Set the Erl_Interface library in compatibility mode. + unsigned release_number; -

By default, the library is only guaranteed - to be compatible with other Erlang/OTP components from the same - release as the library itself. For example, - from the OTP R10 release is not compatible - with an Erlang emulator from the OTP R9 release by default.

-

A call to sets the - library in compatibility mode of release - . Valid range of +

By default, the library is only + guaranteed to be compatible with other Erlang/OTP components from the + same release as the library itself. + For example, from Erlang/OTP R10 + is not compatible + with an Erlang emulator from Erlang/OTP R9 by default.

+

A call to sets + the library in compatibility mode of + release . Valid range of + is [7, current release]. This makes it possible to communicate with Erlang/OTP components from earlier releases.

If this function is called, it may only be called once - directly after the call to the - erl_init() function.

+ directly after the call to function + erl_init().

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.

 + interl_size(term) Return the arity of a tuple or binary. @@ -638,49 +716,55 @@ iohead ::= Binary ETERM *term; -

Returns the arity of an Erlang tuple, or the - number of bytes in an Erlang binary object.

-

is an Erlang tuple or an Erlang binary object.

-

The function returns the size of as described - above, or -1 if is not one of the two supported - types.

+

Returns either the arity of an Erlang tuple or the + number of bytes in an Erlang binary object.

+

is an Erlang tuple or an Erlang binary + object.

+

Returns the size of as described + above, or -1 if is not one of the two + supported types.

 + ETERM *erl_tl(list) - Extracts the tail from a list. + Extract the tail from a list. ETERM *list;

Extracts the tail from a list.

is an Erlang term containing a list.

-

The function returns an Erlang list corresponding to the - original list minus the first element, or NULL pointer if +

Returns an Erlang list corresponding to the + original list minus the first element, or NULL pointer if was not a list.

 + ETERM *erl_var_content(term, name) - Extracts the content of a variable. + Extract the content of a variable. ETERM *term; char *name; -

This function returns the contents of the specified - variable in an Erlang term. -

-

is an Erlang term. In order for this function - to succeed, 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.

-

is the name of an Erlang variable.

+

Returns the contents of the specified variable in an Erlang term.

+ + is an Erlang term. In order for this + function to succeed, + 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. + is the name of an Erlang variable. + +

Returns the Erlang object corresponding to the value of - in . If no variable with the name - was found in , or if is - not a valid Erlang term, NULL is returned.

+ in . If no variable + with the name is found in + , or if is + not a valid Erlang term, NULL is returned.

 -- cgit v1.2.3