diff options
| author | Björn-Egil Dahlberg <[email protected]> | 2016-10-21 15:44:49 +0200 |
|---|---|---|
| committer | Björn-Egil Dahlberg <[email protected]> | 2016-10-24 10:54:48 +0200 |
| commit | 5f5fb466630db9dc8e17895c90ed74105852e827 (patch) | |
| tree | acd49e3700885cb9f1c77e8ae5c45479f0cc9c14 /lib/erl_interface/doc | |
| parent | 2aa61a092b11c63387574622f473ac16d8ace6e9 (diff) | |
| download | otp-5f5fb466630db9dc8e17895c90ed74105852e827.tar.gz otp-5f5fb466630db9dc8e17895c90ed74105852e827.tar.bz2 otp-5f5fb466630db9dc8e17895c90ed74105852e827.zip | |
erl_interface: Remove CDATA tag except for example code
Diffstat (limited to 'lib/erl_interface/doc')
| -rw-r--r-- | lib/erl_interface/doc/src/ei.xml | 280 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/ei_connect.xml | 334 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/ei_users_guide.xml | 152 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/erl_call.xml | 76 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/erl_connect.xml | 332 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/erl_error.xml | 32 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/erl_eterm.xml | 392 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/erl_format.xml | 38 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/erl_global.xml | 42 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/erl_interface.xml | 198 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/erl_malloc.xml | 36 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/erl_marshal.xml | 66 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/ref_man_ei.xml | 13 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/registry.xml | 244 |
14 files changed, 1117 insertions, 1118 deletions
diff --git a/lib/erl_interface/doc/src/ei.xml b/lib/erl_interface/doc/src/ei.xml index 9b01f4af98..ddfb4d88a8 100644 --- a/lib/erl_interface/doc/src/ei.xml +++ b/lib/erl_interface/doc/src/ei.xml @@ -35,24 +35,24 @@ <lib>ei</lib> <libsummary>Routines for handling the Erlang binary term format.</libsummary> <description> - <p>The library <c><![CDATA[ei]]></c> contains macros and functions to encode + <p>The library <c>ei</c> contains macros and functions to encode and decode the Erlang binary term format.</p> - <p><c><![CDATA[ei]]></c> allows you to convert atoms, lists, numbers, and + <p><c>ei</c> allows you to convert atoms, lists, numbers, and binaries to and from the binary format. This is useful when - writing port programs and drivers. <c><![CDATA[ei]]></c> uses a given + writing port programs and drivers. <c>ei</c> uses a given buffer, no dynamic memory (except - <c><![CDATA[ei_decode_fun()]]></c>) and is often quite fast.</p> + <c>ei_decode_fun()</c>) and is often quite fast.</p> - <p><c><![CDATA[ei]]></c> also handles C-nodes, C-programs that talks Erlang + <p><c>ei</c> also handles C-nodes, C-programs that talks Erlang distribution with Erlang nodes (or other C-nodes) using the - Erlang distribution format. The difference between <c><![CDATA[ei]]></c> - and <c><![CDATA[erl_interface]]></c> is that <c><![CDATA[ei]]></c> uses + Erlang distribution format. The difference between <c>ei</c> + and <c>erl_interface</c> is that <c>ei</c> uses the binary format directly when sending and receiving terms. It is also thread safe, and using threads, one process can handle multiple - C-nodes. The <c><![CDATA[erl_interface]]></c> library is built on top of - <c><![CDATA[ei]]></c>, but of legacy reasons, it does not allow for - multiple C-nodes. In general, <c><![CDATA[ei]]></c> is the preferred way + C-nodes. The <c>erl_interface</c> library is built on top of + <c>ei</c>, but of legacy reasons, it does not allow for + multiple C-nodes. In general, <c>ei</c> is the preferred way of doing C-nodes.</p> <p>The decode and encode functions use a buffer and an index into the @@ -65,37 +65,37 @@ <p>All functions take two parameters:</p> <list type="bulleted"> - <item><p><c><![CDATA[buf]]></c> is a pointer to + <item><p><c>buf</c> is a pointer to the buffer where the binary data is or will be.</p> </item> - <item><p><c><![CDATA[index]]></c> is a pointer to an index into the + <item><p><c>index</c> is a pointer to an index into the buffer. This parameter is incremented with the size of the term decoded/encoded.</p> </item> </list> - <p>The data is thus at <c><![CDATA[buf[*index]]]></c> when an - <c><![CDATA[ei]]></c> function is called.</p> + <p>The data is thus at <c>buf[*index]</c> when an + <c>ei</c> function is called.</p> - <p>All encode functions assume that the <c><![CDATA[buf]]></c> and - <c><![CDATA[index]]></c> parameters point to a buffer large enough for + <p>All encode functions assume that the <c>buf</c> and + <c>index</c> parameters point to a buffer large enough for the data. To get the size of an encoded term, without encoding it, - pass <c><![CDATA[NULL]]></c> instead of a buffer pointer. Parameter - <c><![CDATA[index]]></c> is incremented, but nothing will be encoded. This - is the way in <c><![CDATA[ei]]></c> to "preflight" term encoding.</p> + pass <c>NULL</c> instead of a buffer pointer. Parameter + <c>index</c> is incremented, but nothing will be encoded. This + is the way in <c>ei</c> to "preflight" term encoding.</p> <p>There are also encode functions that use a dynamic buffer. It is often more convenient to use these to encode data. All encode functions comes in two versions; those starting with - <c><![CDATA[ei_x]]></c> use a dynamic buffer.</p> + <c>ei_x</c> use a dynamic buffer.</p> - <p>All functions return <c><![CDATA[0]]></c> if successful, otherwise - <c><![CDATA[-1]]></c> (for example, if a term is not of the expected + <p>All functions return <c>0</c> if successful, otherwise + <c>-1</c> (for example, if a term is not of the expected type, or the data to decode is an invalid Erlang term).</p> <p>Some of the decode functions need a pre-allocated buffer. This buffer must be allocated large enough, and for non-compound types - the <c><![CDATA[ei_get_type()]]></c> + the <c>ei_get_type()</c> function returns the size required (notice that for strings an extra byte is needed for the <c>NULL</c>-terminator).</p> </description> @@ -128,8 +128,8 @@ typedef enum { <fsummary>Decode an atom.</fsummary> <desc> <p>Decodes an atom from the binary format. The <c>NULL</c>-terminated - name of the atom is placed at <c><![CDATA[p]]></c>. At most - <c><![CDATA[MAXATOMLEN]]></c> bytes can be placed in the buffer.</p> + name of the atom is placed at <c>p</c>. At most + <c>MAXATOMLEN</c> bytes can be placed in the buffer.</p> </desc> </func> @@ -162,7 +162,7 @@ typedef enum { <fsummary>Decode a GMP arbitrary precision integer.</fsummary> <desc> <p>Decodes an integer in the binary format to a GMP - <c><![CDATA[mpz_t]]></c> integer. To use this function, the <c>ei</c> + <c>mpz_t</c> integer. To use this function, the <c>ei</c> library must be configured and compiled to use the GMP library.</p> </desc> </func> @@ -172,10 +172,10 @@ typedef enum { <fsummary>Decode a binary.</fsummary> <desc> <p>Decodes a binary from the binary format. Parameter - <c><![CDATA[len]]></c> is set to the actual size of the - binary. Notice that <c><![CDATA[ei_decode_binary()]]></c> assumes that + <c>len</c> is set to the actual size of the + binary. Notice that <c>ei_decode_binary()</c> assumes that there is enough room for the binary. The size required can be - fetched by <c><![CDATA[ei_get_type()]]></c>.</p> + fetched by <c>ei_get_type()</c>.</p> </desc> </func> @@ -184,8 +184,8 @@ typedef enum { <fsummary>Decode a boolean.</fsummary> <desc> <p>Decodes a boolean value from the binary format. - A boolean is actually an atom, <c><![CDATA[true]]></c> decodes 1 - and <c><![CDATA[false]]></c> decodes 0.</p> + A boolean is actually an atom, <c>true</c> decodes 1 + and <c>false</c> decodes 0.</p> </desc> </func> @@ -195,9 +195,9 @@ typedef enum { <desc> <p>Decodes a char (8-bit) integer between 0-255 from the binary format. For historical reasons the returned integer is of - type <c><![CDATA[char]]></c>. Your C code is to consider the - returned value to be of type <c><![CDATA[unsigned char]]></c> even if - the C compilers and system can define <c><![CDATA[char]]></c> to be + type <c>char</c>. Your C code is to consider the + returned value to be of type <c>unsigned char</c> even if + the C compilers and system can define <c>char</c> to be signed.</p> </desc> </func> @@ -216,16 +216,16 @@ typedef enum { <fsummary>Decode a term, without previous knowledge of type.</fsummary> <desc> <p>Decodes any term, or at least tries to. If the term - pointed at by <c><![CDATA[*index]]></c> in <c><![CDATA[buf]]></c> fits - in the <c><![CDATA[term]]></c> union, it is decoded, and the - appropriate field in <c><![CDATA[term->value]]></c> is set, and - <c><![CDATA[*index]]></c> is incremented by the term size.</p> + pointed at by <c>*index</c> in <c>buf</c> fits + in the <c>term</c> union, it is decoded, and the + appropriate field in <c>term->value</c> is set, and + <c>*index</c> is incremented by the term size.</p> <p>The function returns <c>1</c> on successful decoding, <c>-1</c> on error, and <c>0</c> if the term seems alright, but does not fit in the - <c><![CDATA[term]]></c> structure. If <c>1</c> is returned, the - <c><![CDATA[index]]></c> is incremented, and <c><![CDATA[term]]></c> + <c>term</c> structure. If <c>1</c> is returned, the + <c>index</c> is incremented, and <c>term</c> contains the decoded term.</p> - <p>The <c><![CDATA[term]]></c> structure contains the arity for a tuple + <p>The <c>term</c> structure contains the arity for a tuple or list, size for a binary, string, or atom. It contains a term if it is any of the following: integer, float, atom, pid, port, or ref.</p> @@ -238,11 +238,11 @@ typedef enum { <fsummary>Decode a fun.</fsummary> <desc> <p>Decodes a fun from the binary format. Parameter - <c><![CDATA[p]]></c> is to be <c>NULL</c> or point to an - <c><![CDATA[erlang_fun]]></c> structure. This is the only decode - function that allocates memory. When the <c><![CDATA[erlang_fun]]></c> + <c>p</c> is to be <c>NULL</c> or point to an + <c>erlang_fun</c> structure. This is the only decode + function that allocates memory. When the <c>erlang_fun</c> is no longer needed, it is to be freed with - <c><![CDATA[free_fun]]></c>. (This has to do with the arbitrary size + <c>free_fun</c>. (This has to do with the arbitrary size of the environment for a fun.)</p> </desc> </func> @@ -253,13 +253,13 @@ typedef enum { <desc> <p>Decodes a list header from the binary format. The number of elements is returned in - <c><![CDATA[arity]]></c>. The <c><![CDATA[arity+1]]></c> elements + <c>arity</c>. The <c>arity+1</c> elements follow (the last one is the tail of the list, normally an empty list). - If <c><![CDATA[arity]]></c> is <c><![CDATA[0]]></c>, it is an empty + If <c>arity</c> is <c>0</c>, it is an empty list.</p> <p>Notice that lists are encoded as strings if they consist entirely of integers in the range 0..255. This function do - not decode such strings, use <c><![CDATA[ei_decode_string()]]></c> + not decode such strings, use <c>ei_decode_string()</c> instead.</p> </desc> </func> @@ -278,8 +278,8 @@ typedef enum { <name><ret>int</ret><nametext>ei_decode_longlong(const char *buf, int *index, long long *p)</nametext></name> <fsummary>Decode integer.</fsummary> <desc> - <p>Decodes a GCC <c><![CDATA[long long]]></c> or Visual C++ - <c><![CDATA[__int64]]></c> + <p>Decodes a GCC <c>long long</c> or Visual C++ + <c>__int64</c> (64-bit) integer from the binary format. This function is missing in the VxWorks port.</p> </desc> @@ -300,7 +300,7 @@ typedef enum { <func> <name><ret>int</ret><nametext>ei_decode_pid(const char *buf, int *index, erlang_pid *p)</nametext></name> - <fsummary>Decode a <c><![CDATA[pid]]></c>.</fsummary> + <fsummary>Decode a <c>pid</c>.</fsummary> <desc> <p>Decodes a process identifier (pid) from the binary format.</p> </desc> @@ -329,9 +329,9 @@ typedef enum { <p>Decodes a string from the binary format. A string in Erlang is a list of integers between 0 and 255. Notice that as the string is just a list, sometimes - lists are encoded as strings by <c><![CDATA[term_to_binary/1]]></c>, + lists are encoded as strings by <c>term_to_binary/1</c>, even if it was not intended.</p> - <p>The string is copied to <c><![CDATA[p]]></c>, and enough space must + <p>The string is copied to <c>p</c>, and enough space must be allocated. The returned string is <c>NULL</c>-terminated, so you must add an extra byte to the memory requirement.</p> </desc> @@ -339,11 +339,11 @@ typedef enum { <func> <name><ret>int</ret><nametext>ei_decode_term(const char *buf, int *index, void *t)</nametext></name> - <fsummary>Decode a <c><![CDATA[ETERM]]></c>.</fsummary> + <fsummary>Decode a <c>ETERM</c>.</fsummary> <desc> <p>Decodes a term from the binary format. The term - is return in <c><![CDATA[t]]></c> as a <c><![CDATA[ETERM*]]></c>, so - <c><![CDATA[t]]></c> is actually an <c><![CDATA[ETERM**]]></c> (see + is return in <c>t</c> as a <c>ETERM*</c>, so + <c>t</c> is actually an <c>ETERM**</c> (see <seealso marker="erl_eterm"><c>erl_eterm</c></seealso>). The term is later to be deallocated.</p> <p>Notice that this function is located in the <c>Erl_Interface</c> @@ -364,7 +364,7 @@ typedef enum { <fsummary>Decode a tuple.</fsummary> <desc> <p>Decodes a tuple header, the number of elements - is returned in <c><![CDATA[arity]]></c>. The tuple elements follow + is returned in <c>arity</c>. The tuple elements follow in order in the buffer.</p> </desc> </func> @@ -383,15 +383,15 @@ typedef enum { <name><ret>int</ret><nametext>ei_decode_ulonglong(const char *buf, int *index, unsigned long long *p)</nametext></name> <fsummary>Decode unsigned integer.</fsummary> <desc> - <p>Decodes a GCC <c><![CDATA[unsigned long long]]></c> or Visual C++ - <c><![CDATA[unsigned __int64]]></c> (64-bit) integer from the binary + <p>Decodes a GCC <c>unsigned long long</c> or Visual C++ + <c>unsigned __int64</c> (64-bit) integer from the binary format. This function is missing in the VxWorks port.</p> </desc> </func> <func> <name><ret>int</ret><nametext>ei_decode_version(const char *buf, int *index, int *version)</nametext></name> - <fsummary>Decode an empty list (<c><![CDATA[nil]]></c>).</fsummary> + <fsummary>Decode an empty list (<c>nil</c>).</fsummary> <desc> <p>Decodes the version magic number for the Erlang binary term format. It must be the first token in a @@ -406,11 +406,11 @@ typedef enum { <name><ret>int</ret><nametext>ei_x_encode_atom_len(ei_x_buff* x, const char *p, int len)</nametext></name> <fsummary>Encode an atom.</fsummary> <desc> - <p>Encodes an atom in the binary format. Parameter <c><![CDATA[p]]></c> + <p>Encodes an atom in the binary format. Parameter <c>p</c> is the name of the atom in Latin-1 encoding. Only up to <c>MAXATOMLEN-1</c> bytes are encoded. The name is to be <c>NULL</c>-terminated, except for - the <c><![CDATA[ei_x_encode_atom_len()]]></c> function.</p> + the <c>ei_x_encode_atom_len()</c> function.</p> </desc> </func> @@ -445,7 +445,7 @@ typedef enum { <name><ret>int</ret><nametext>ei_x_encode_bignum(ei_x_buff *x, mpz_t obj)</nametext></name> <fsummary>Encode an arbitrary precision integer.</fsummary> <desc> - <p>Encodes a GMP <c><![CDATA[mpz_t]]></c> integer to binary format. + <p>Encodes a GMP <c>mpz_t</c> integer to binary format. To use this function, the <c>ei</c> library must be configured and compiled to use the GMP library.</p> </desc> @@ -457,7 +457,7 @@ typedef enum { <fsummary>Encode a binary.</fsummary> <desc> <p>Encodes a binary in the binary format. The data is at - <c><![CDATA[p]]></c>, of <c><![CDATA[len]]></c> bytes length.</p> + <c>p</c>, of <c>len</c> bytes length.</p> </desc> </func> @@ -466,8 +466,8 @@ typedef enum { <name><ret>int</ret><nametext>ei_x_encode_boolean(ei_x_buff* x, int p)</nametext></name> <fsummary>Encode a boolean.</fsummary> <desc> - <p>Encodes a boolean value as the atom <c><![CDATA[true]]></c> if - <c>p</c> is not zero, or <c><![CDATA[false]]></c> if <c>p</c> is + <p>Encodes a boolean value as the atom <c>true</c> if + <c>p</c> is not zero, or <c>false</c> if <c>p</c> is zero.</p> </desc> </func> @@ -479,9 +479,9 @@ typedef enum { <desc> <p>Encodes a char (8-bit) as an integer between 0-255 in the binary format. For historical reasons the integer argument is of - type <c><![CDATA[char]]></c>. Your C code is to consider the specified - argument to be of type <c><![CDATA[unsigned char]]></c> even if - the C compilers and system may define <c><![CDATA[char]]></c> to be + type <c>char</c>. Your C code is to consider the specified + argument to be of type <c>unsigned char</c> even if + the C compilers and system may define <c>char</c> to be signed.</p> </desc> </func> @@ -493,7 +493,7 @@ typedef enum { <desc> <p>Encodes a double-precision (64-bit) floating point number in the binary format.</p> - <p>Returns <c><![CDATA[-1]]></c> if the floating point + <p>Returns <c>-1</c> if the floating point number is not finite.</p> </desc> </func> @@ -501,7 +501,7 @@ typedef enum { <func> <name><ret>int</ret><nametext>ei_encode_empty_list(char* buf, int* index)</nametext></name> <name><ret>int</ret><nametext>ei_x_encode_empty_list(ei_x_buff* x)</nametext></name> - <fsummary>Encode an empty list (<c><![CDATA[nil]]></c>).</fsummary> + <fsummary>Encode an empty list (<c>nil</c>).</fsummary> <desc> <p>Encodes an empty list. It is often used at the tail of a list.</p> </desc> @@ -512,10 +512,10 @@ typedef enum { <name><ret>int</ret><nametext>ei_x_encode_fun(ei_x_buff* x, const erlang_fun* fun)</nametext></name> <fsummary>Encode a fun.</fsummary> <desc> - <p>Encodes a fun in the binary format. Parameter <c><![CDATA[p]]></c> - points to an <c><![CDATA[erlang_fun]]></c> structure. The - <c><![CDATA[erlang_fun]]></c> is not freed automatically, the - <c><![CDATA[free_fun]]></c> is to be called if the fun is not needed + <p>Encodes a fun in the binary format. Parameter <c>p</c> + points to an <c>erlang_fun</c> structure. The + <c>erlang_fun</c> is not freed automatically, the + <c>free_fun</c> is to be called if the fun is not needed after encoding.</p> </desc> </func> @@ -526,12 +526,12 @@ typedef enum { <fsummary>Encode a list.</fsummary> <desc> <p>Encodes a list header, with a specified - arity. The next <c><![CDATA[arity+1]]></c> terms are the elements - (actually its <c><![CDATA[arity]]></c> cons cells) and the tail of the + arity. The next <c>arity+1</c> terms are the elements + (actually its <c>arity</c> cons cells) and the tail of the list. Lists and tuples are encoded recursively, so that a list can contain another list or tuple.</p> <p>For example, to encode the list - <c><![CDATA[[c, d, [e | f]]]]></c>:</p> + <c>[c, d, [e | f]]</c>:</p> <pre> ei_encode_list_header(buf, &i, 3); ei_encode_atom(buf, &i, "c"); @@ -543,8 +543,8 @@ ei_encode_empty_list(buf, &i);</pre> <note> <p>It may seem that there is no way to create a list without knowing the number of elements in advance. But indeed - there is a way. Notice that the list <c><![CDATA[[a, b, c]]]></c> - can be written as <c><![CDATA[[a | [b | [c]]]]]></c>. + there is a way. Notice that the list <c>[a, b, c]</c> + can be written as <c>[a | [b | [c]]]</c>. Using this, a list can be written as conses.</p> </note> <p>To encode a list, without knowing the arity in advance:</p> @@ -573,8 +573,8 @@ ei_x_encode_empty_list(&x);</pre> <name><ret>int</ret><nametext>ei_x_encode_longlong(ei_x_buff* x, long long p)</nametext></name> <fsummary>Encode integer.</fsummary> <desc> - <p>Encodes a GCC <c><![CDATA[long long]]></c> or Visual C++ - <c><![CDATA[__int64]]></c> (64-bit) integer in the binary format. + <p>Encodes a GCC <c>long long</c> or Visual C++ + <c>__int64</c> (64-bit) integer in the binary format. This function is missing in the VxWorks port.</p> </desc> </func> @@ -606,9 +606,9 @@ ei_x_encode_string(&x, "Banana");</pre> <fsummary>Encode a pid.</fsummary> <desc> <p>Encodes an Erlang process identifier (pid) in the binary - format. Parameter <c><![CDATA[p]]></c> points to an - <c><![CDATA[erlang_pid]]></c> structure (which should have been - obtained earlier with <c><![CDATA[ei_decode_pid()]]></c>).</p> + format. Parameter <c>p</c> points to an + <c>erlang_pid</c> structure (which should have been + obtained earlier with <c>ei_decode_pid()</c>).</p> </desc> </func> @@ -618,9 +618,9 @@ ei_x_encode_string(&x, "Banana");</pre> <fsummary>Encode a port.</fsummary> <desc> <p>Encodes an Erlang port in the binary format. Parameter - <c><![CDATA[p]]></c> points to a <c><![CDATA[erlang_port]]></c> + <c>p</c> points to a <c>erlang_port</c> structure (which should have been obtained earlier with - <c><![CDATA[ei_decode_port()]]></c>).</p> + <c>ei_decode_port()</c>).</p> </desc> </func> @@ -630,9 +630,9 @@ ei_x_encode_string(&x, "Banana");</pre> <fsummary>Encode a ref.</fsummary> <desc> <p>Encodes an Erlang reference in the binary format. Parameter - <c><![CDATA[p]]></c> points to a <c><![CDATA[erlang_ref]]></c> + <c>p</c> points to a <c>erlang_ref</c> structure (which should have been obtained earlier with - <c><![CDATA[ei_decode_ref()]]></c>).</p> + <c>ei_decode_ref()</c>).</p> </desc> </func> @@ -646,19 +646,19 @@ ei_x_encode_string(&x, "Banana");</pre> <p>Encodes a string in the binary format. (A string in Erlang is a list, but is encoded as a character array in the binary format.) The string is to be <c>NULL</c>-terminated, except for - the <c><![CDATA[ei_x_encode_string_len()]]></c> function.</p> + the <c>ei_x_encode_string_len()</c> function.</p> </desc> </func> <func> <name><ret>int</ret><nametext>ei_encode_term(char *buf, int *index, void *t)</nametext></name> <name><ret>int</ret><nametext>ei_x_encode_term(ei_x_buff* x, void *t)</nametext></name> - <fsummary>Encode an <c><![CDATA[erl_interface]]></c> term.</fsummary> + <fsummary>Encode an <c>erl_interface</c> term.</fsummary> <desc> - <p>Encodes an <c><![CDATA[ETERM]]></c>, as obtained from - <c><![CDATA[erl_interface]]></c>. Parameter <c><![CDATA[t]]></c> is - actually an <c><![CDATA[ETERM]]></c> pointer. This function - does not free the <c><![CDATA[ETERM]]></c>.</p> + <p>Encodes an <c>ETERM</c>, as obtained from + <c>erl_interface</c>. Parameter <c>t</c> is + actually an <c>ETERM</c> pointer. This function + does not free the <c>ETERM</c>.</p> </desc> </func> <func> @@ -667,9 +667,9 @@ ei_x_encode_string(&x, "Banana");</pre> <fsummary>Encode a trace token.</fsummary> <desc> <p>Encodes an Erlang trace token in the binary format. - Parameter <c><![CDATA[p]]></c> points to a - <c><![CDATA[erlang_trace]]></c> structure (which should have been - obtained earlier with <c><![CDATA[ei_decode_trace()]]></c>).</p> + Parameter <c>p</c> points to a + <c>erlang_trace</c> structure (which should have been + obtained earlier with <c>ei_decode_trace()</c>).</p> </desc> </func> @@ -679,10 +679,10 @@ ei_x_encode_string(&x, "Banana");</pre> <fsummary>Encode a tuple.</fsummary> <desc> <p>Encodes a tuple header, with a specified - arity. The next <c><![CDATA[arity]]></c> terms encoded will be the + arity. The next <c>arity</c> terms encoded will be the elements of the tuple. Tuples and lists are encoded recursively, so that a tuple can contain another tuple or list.</p> - <p>For example, to encode the tuple <c><![CDATA[{a, {b, {}}}]]></c>:</p> + <p>For example, to encode the tuple <c>{a, {b, {}}}</c>:</p> <pre> ei_encode_tuple_header(buf, &i, 2); ei_encode_atom(buf, &i, "a"); @@ -708,8 +708,8 @@ ei_encode_tuple_header(buf, &i, 0);</pre> <name><ret>int</ret><nametext>ei_x_encode_ulonglong(ei_x_buff* x, unsigned long long p)</nametext></name> <fsummary>Encode unsigned integer.</fsummary> <desc> - <p>Encodes a GCC <c><![CDATA[unsigned long long]]></c> or Visual C++ - <c><![CDATA[unsigned __int64]]></c> (64-bit) integer in the binary + <p>Encodes a GCC <c>unsigned long long</c> or Visual C++ + <c>unsigned __int64</c> (64-bit) integer in the binary format. This function is missing in the VxWorks port.</p> </desc> </func> @@ -728,13 +728,13 @@ ei_encode_tuple_header(buf, &i, 0);</pre> <name><ret>int</ret><nametext>ei_get_type(const char *buf, const int *index, int *type, int *size)</nametext></name> <fsummary>Fetch the type and size of an encoded term.</fsummary> <desc> - <p>Returns the type in <c><![CDATA[type]]></c> and size in - <c><![CDATA[size]]></c> of the encoded term. For strings and atoms, + <p>Returns the type in <c>type</c> and size in + <c>size</c> of the encoded term. For strings and atoms, size is the number of characters <em>not</em> including the - terminating <c>NULL</c>. For binaries, <c><![CDATA[size]]></c> is the number of - bytes. For lists and tuples, <c><![CDATA[size]]></c> is the arity of - the object. For other types, <c><![CDATA[size]]></c> is 0. In all - cases, <c><![CDATA[index]]></c> is left unchanged.</p> + terminating <c>NULL</c>. For binaries, <c>size</c> is the number of + bytes. For lists and tuples, <c>size</c> is the arity of + the object. For other types, <c>size</c> is 0. In all + cases, <c>index</c> is left unchanged.</p> </desc> </func> @@ -744,21 +744,21 @@ ei_encode_tuple_header(buf, &i, 0);</pre> <fsummary>Print a term in clear text.</fsummary> <desc> <p>Prints a term, in clear text, to the file - specified by <c><![CDATA[fp]]></c>, or the buffer pointed to by - <c><![CDATA[s]]></c>. It + specified by <c>fp</c>, or the buffer pointed to by + <c>s</c>. It tries to resemble the term printing in the Erlang shell.</p> - <p>In <c><![CDATA[ei_s_print_term()]]></c>, parameter - <c><![CDATA[s]]></c> is to + <p>In <c>ei_s_print_term()</c>, parameter + <c>s</c> is to point to a dynamically (malloc) allocated string of - <c><![CDATA[BUFSIZ]]></c> bytes or a <c>NULL</c> pointer. The string - can be reallocated (and <c><![CDATA[*s]]></c> can be updated) by this - function if the result is more than <c><![CDATA[BUFSIZ]]></c> + <c>BUFSIZ</c> bytes or a <c>NULL</c> pointer. The string + can be reallocated (and <c>*s</c> can be updated) by this + function if the result is more than <c>BUFSIZ</c> characters. The string returned is <c>NULL</c>-terminated.</p> <p>The return value is the number of characters written to the file - or string, or <c>-1</c> if <c><![CDATA[buf[index]]]></c> does not + or string, or <c>-1</c> if <c>buf[index]</c> does not contain a valid term. - Unfortunately, I/O errors on <c><![CDATA[fp]]></c> is not checked.</p> - <p>Argument <c><![CDATA[index]]></c> is updated, that is, this function + Unfortunately, I/O errors on <c>fp</c> is not checked.</p> + <p>Argument <c>index</c> is updated, that is, this function can be viewed as a decode function that decodes a term into a human-readable format.</p> </desc> @@ -772,22 +772,22 @@ ei_encode_tuple_header(buf, &i, 0);</pre> </type> <desc> <marker id="ei_set_compat_rel"></marker> - <p>By default, the <c><![CDATA[ei]]></c> library is only guaranteed + <p>By default, the <c>ei</c> library is only guaranteed to be compatible with other Erlang/OTP components from the same - release as the <c><![CDATA[ei]]></c> library itself. For example, - <c><![CDATA[ei]]></c> from + release as the <c>ei</c> library itself. For example, + <c>ei</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[ei_set_compat_rel(release_number)]]></c> sets - the <c><![CDATA[ei]]></c> library in compatibility mode of release - <c><![CDATA[release_number]]></c>. Valid range of - <c><![CDATA[release_number]]></c> + <p>A call to <c>ei_set_compat_rel(release_number)</c> sets + the <c>ei</c> library in compatibility mode of release + <c>release_number</c>. Valid range of + <c>release_number</c> is <c>[7, current release]</c>. This makes it possible to communicate with Erlang/OTP components from earlier releases.</p> <note> <p>If this function is called, it can only be called once and must be called before any other functions in the - <c><![CDATA[ei]]></c> library are called.</p> + <c>ei</c> library are called.</p> </note> <warning> <p>You can run into trouble if this feature is used @@ -807,16 +807,16 @@ ei_encode_tuple_header(buf, &i, 0);</pre> recursively skips elements of lists and tuples, so that a full term is skipped. This is a way to get the size of an Erlang term.</p> - <p><c><![CDATA[buf]]></c> is the buffer.</p> - <p><c><![CDATA[index]]></c> is updated to point right after the term + <p><c>buf</c> is the buffer.</p> + <p><c>index</c> is updated to point right after the term in the buffer.</p> <note> <p>This can be useful when you want to hold arbitrary terms: skip them and copy the binary term data to some buffer.</p> </note> - <p>Returns <c><![CDATA[0]]></c> on success, otherwise - <c><![CDATA[-1]]></c>.</p> + <p>Returns <c>0</c> on success, otherwise + <c>-1</c>.</p> </desc> </func> @@ -825,7 +825,7 @@ ei_encode_tuple_header(buf, &i, 0);</pre> <name><ret>int</ret><nametext>ei_x_append_buf(ei_x_buff* x, const char* buf, int len)</nametext></name> <fsummary>Append a buffer at the end.</fsummary> <desc> - <p>Appends data at the end of buffer <c><![CDATA[x]]></c>.</p> + <p>Appends data at the end of buffer <c>x</c>.</p> </desc> </func> @@ -836,8 +836,8 @@ ei_encode_tuple_header(buf, &i, 0);</pre> <desc> <p>Formats a term, given as a string, to a buffer. Works like a sprintf for Erlang terms. - <c><![CDATA[fmt]]></c> contains a format string, with arguments like - <c><![CDATA[~d]]></c>, to insert terms from variables. The following + <c>fmt</c> contains a format string, with arguments like + <c>~d</c>, to insert terms from variables. The following formats are supported (with the C types given):</p> <pre> ~a An atom, char* @@ -853,7 +853,7 @@ ei_encode_tuple_header(buf, &i, 0);</pre> <pre> ei_x_format("{~a,~i,~d}", "numbers", 12, 3.14159) encodes the tuple {numbers,12,3.14159}</pre> - <p><c><![CDATA[ei_x_format_wo_ver()]]></c> formats into a buffer, + <p><c>ei_x_format_wo_ver()</c> formats into a buffer, without the initial version byte.</p> </desc> </func> @@ -862,7 +862,7 @@ encodes the tuple {numbers,12,3.14159}</pre> <name><ret>int</ret><nametext>ei_x_free(ei_x_buff* x)</nametext></name> <fsummary>Free a buffer.</fsummary> <desc> - <p>Frees an <c><![CDATA[ei_x_buff]]></c> buffer. + <p>Frees an <c>ei_x_buff</c> buffer. The memory used by the buffer is returned to the OS.</p> </desc> </func> @@ -872,12 +872,12 @@ encodes the tuple {numbers,12,3.14159}</pre> <name><ret>int</ret><nametext>ei_x_new_with_version(ei_x_buff* x)</nametext></name> <fsummary>Allocate a new buffer.</fsummary> <desc> - <p>Allocates a new <c><![CDATA[ei_x_buff]]></c> buffer. The - fields of the structure pointed to by parameter <c><![CDATA[x]]></c> + <p>Allocates a new <c>ei_x_buff</c> buffer. The + fields of the structure pointed to by parameter <c>x</c> is filled in, and a default buffer is allocated. - <c><![CDATA[ei_x_new_with_version()]]></c> also puts an initial + <c>ei_x_new_with_version()</c> also puts an initial version byte, which is used in the binary format (so that - <c><![CDATA[ei_x_encode_version()]]></c> will not be needed.)</p> + <c>ei_x_encode_version()</c> will not be needed.)</p> </desc> </func> </funcs> @@ -889,7 +889,7 @@ encodes the tuple {numbers,12,3.14159}</pre> <list type="bulleted"> <item>Be careful with the version header, use - <c><![CDATA[ei_x_new_with_version()]]></c> when appropriate.</item> + <c>ei_x_new_with_version()</c> when appropriate.</item> <item>Turn on distribution tracing on the Erlang node.</item> <item>Check the result codes from <c>ei_decode_-calls</c>.</item> </list> diff --git a/lib/erl_interface/doc/src/ei_connect.xml b/lib/erl_interface/doc/src/ei_connect.xml index be34fb7c53..607a7cbff4 100644 --- a/lib/erl_interface/doc/src/ei_connect.xml +++ b/lib/erl_interface/doc/src/ei_connect.xml @@ -44,32 +44,32 @@ <seealso marker="erts:erlang#nodes/0"><c>erlang:nodes/0</c></seealso> in <c>ERTS</c>.</p> - <p>The environment variable <c><![CDATA[ERL_EPMD_PORT]]></c> can be used + <p>The environment variable <c>ERL_EPMD_PORT</c> can be used to indicate which logical cluster a C-node belongs to.</p> </description> <section> <title>Time-Out Functions</title> <p>Most functions appear in a version with the suffix - <c><![CDATA[_tmo]]></c> appended to the function name. Those functions + <c>_tmo</c> appended to the function name. Those functions take an extra argument, a time-out in <em>milliseconds</em>. The semantics is this: for each communication primitive involved in the operation, if the primitive does not complete within the time specified, the function returns an error and - <c><![CDATA[erl_errno]]></c> is set to <c><![CDATA[ETIMEDOUT]]></c>. + <c>erl_errno</c> is set to <c>ETIMEDOUT</c>. With communication primitive is meant an operation on the socket, like - <c><![CDATA[connect]]></c>, <c><![CDATA[accept]]></c>, - <c><![CDATA[recv]]></c>, or <c><![CDATA[send]]></c>.</p> + <c>connect</c>, <c>accept</c>, + <c>recv</c>, or <c>send</c>.</p> <p>Clearly the time-outs are for implementing fault tolerance, - not to keep hard real-time promises. The <c><![CDATA[_tmo]]></c> functions + not to keep hard real-time promises. The <c>_tmo</c> functions are for detecting non-responsive peers and to avoid blocking on socket operations.</p> - <p>A time-out value of <c><![CDATA[0]]></c> (zero) means that time-outs are - disabled. Calling a <c><![CDATA[_tmo]]></c> function with the last - argument as <c><![CDATA[0]]></c> is therefore the same thing as calling - the function without the <c><![CDATA[_tmo]]></c> suffix.</p> + <p>A time-out value of <c>0</c> (zero) means that time-outs are + disabled. Calling a <c>_tmo</c> function with the last + argument as <c>0</c> is therefore the same thing as calling + the function without the <c>_tmo</c> suffix.</p> <p>As with all other functions starting with <c>ei_</c>, you are <em>not</em> expected @@ -80,9 +80,9 @@ avoid problems, leave the socket options alone. <c>ei</c> handles any socket options that need modification.</p> - <p>In all other senses, the <c><![CDATA[_tmo]]></c> functions inherit all + <p>In all other senses, the <c>_tmo</c> functions inherit all the return values and the semantics from the functions without - the <c><![CDATA[_tmo]]></c> suffix.</p> + the <c>_tmo</c> suffix.</p> </section> <funcs> @@ -105,15 +105,15 @@ connection from a client process.</p> <list type="bulleted"> <item> - <p><c><![CDATA[ec]]></c> is the C-node structure.</p> + <p><c>ec</c> is the C-node structure.</p> </item> <item> - <p><c><![CDATA[listensock]]></c> is an open socket descriptor on - which <c><![CDATA[listen()]]></c> has previously been called.</p> + <p><c>listensock</c> is an open socket descriptor on + which <c>listen()</c> has previously been called.</p> </item> <item> - <p><c><![CDATA[conp]]></c> is a pointer to an - <c><![CDATA[ErlConnect]]></c> struct, described as follows:</p> + <p><c>conp</c> is a pointer to an + <c>ErlConnect</c> struct, described as follows:</p> <code type="none"><![CDATA[ typedef struct { char ipadr[4]; @@ -122,10 +122,10 @@ typedef struct { ]]></code> </item> </list> - <p>On success, <c><![CDATA[conp]]></c> is filled in with the address and + <p>On success, <c>conp</c> is filled in with the address and node name of the connecting client and a file descriptor is - returned. On failure, <c><![CDATA[ERL_ERROR]]></c> is returned and - <c><![CDATA[erl_errno]]></c> is set to <c><![CDATA[EIO]]></c>.</p> + returned. On failure, <c>ERL_ERROR</c> is returned and + <c>erl_errno</c> is set to <c>EIO</c>.</p> </desc> </func> @@ -146,34 +146,34 @@ typedef struct { <fsummary>Establish a connection to an Erlang node.</fsummary> <desc> <p>Sets up a connection to an Erlang node.</p> - <p><c><![CDATA[ei_xconnect()]]></c> requires the IP address of the + <p><c>ei_xconnect()</c> requires the IP address of the remote host and the alive name of the remote node to be - specified. <c><![CDATA[ei_connect()]]></c> provides an alternative + specified. <c>ei_connect()</c> provides an alternative interface and determines the information from the node name provided.</p> <list type="bulleted"> - <item><c><![CDATA[addr]]></c> is the 32-bit IP address of the remote + <item><c>addr</c> is the 32-bit IP address of the remote host.</item> - <item><c><![CDATA[alive]]></c> is the alivename of the remote node. + <item><c>alive</c> is the alivename of the remote node. </item> - <item><c><![CDATA[node]]></c> is the name of the remote node.</item> + <item><c>node</c> is the name of the remote node.</item> </list> <p>These functions return an open file descriptor on success, or a negative value indicating that an error occurred. In the latter - case they set <c><![CDATA[erl_errno]]></c> to one of the + case they set <c>erl_errno</c> to one of the following:</p> <taglist> - <tag><c><![CDATA[EHOSTUNREACH]]></c></tag> - <item>The remote host <c><![CDATA[node]]></c> is unreachable.</item> - <tag><c><![CDATA[ENOMEM]]></c></tag> + <tag><c>EHOSTUNREACH</c></tag> + <item>The remote host <c>node</c> is unreachable.</item> + <tag><c>ENOMEM</c></tag> <item>No more memory is available.</item> - <tag><c><![CDATA[EIO]]></c></tag> + <tag><c>EIO</c></tag> <item>I/O error.</item> </taglist> - <p>Also, <c><![CDATA[errno]]></c> values from - <c><![CDATA[socket]]></c><em>(2)</em> and - <c><![CDATA[connect]]></c><em>(2)</em> - system calls may be propagated into <c><![CDATA[erl_errno]]></c>.</p> + <p>Also, <c>errno</c> values from + <c>socket</c><em>(2)</em> and + <c>connect</c><em>(2)</em> + system calls may be propagated into <c>erl_errno</c>.</p> <p><em>Example:</em></p> <code type="none"><![CDATA[ #define NODE "[email protected]" @@ -196,49 +196,49 @@ fd = ei_xconnect(&ec, &addr, ALIVE); <name><ret>int</ret><nametext>ei_connect_xinit(ei_cnode* ec, const char *thishostname, const char *thisalivename, const char *thisnodename, Erl_IpAddr thisipaddr, const char *cookie, short creation)</nametext></name> <fsummary>Initialize for a connection.</fsummary> <desc> - <p>Initializes the <c><![CDATA[ec]]></c> structure, to + <p>Initializes the <c>ec</c> structure, to identify the node name and cookie of the server. One of them must be called before other functions that works on the - <c><![CDATA[ei_cnode]]></c> type or a file descriptor associated with + <c>ei_cnode</c> type or a file descriptor associated with a connection to another node is used.</p> <list type="bulleted"> <item> - <p><c><![CDATA[ec]]></c> is a structure containing information about - the C-node. It is used in other <c><![CDATA[ei]]></c> functions + <p><c>ec</c> is a structure containing information about + the C-node. It is used in other <c>ei</c> functions for connecting and receiving data.</p> </item> <item> - <p><c><![CDATA[this_node_name]]></c> is the registered name of the + <p><c>this_node_name</c> is the registered name of the process (the name before '@').</p> </item> <item> - <p><c><![CDATA[cookie]]></c> is the cookie for the node.</p> + <p><c>cookie</c> is the cookie for the node.</p> </item> <item> - <p><c><![CDATA[creation]]></c> identifies a specific instance of a + <p><c>creation</c> identifies a specific instance of a C-node. It can help prevent the node from receiving messages sent to an earlier process with the same registered name.</p> </item> <item> - <p><c><![CDATA[thishostname]]></c> is the name of the machine we are + <p><c>thishostname</c> is the name of the machine we are running on. If long names are to be used, they are to be fully - qualified (that is, <c><![CDATA[durin.erix.ericsson.se]]></c> - instead of <c><![CDATA[durin]]></c>).</p> + qualified (that is, <c>durin.erix.ericsson.se</c> + instead of <c>durin</c>).</p> </item> <item> - <p><c><![CDATA[thisalivename]]></c> is the registered name of the + <p><c>thisalivename</c> is the registered name of the process.</p> </item> <item> - <p><c><![CDATA[thisnodename]]></c> is the full name of the node, - that is, <c><![CDATA[einode@durin]]></c>.</p> + <p><c>thisnodename</c> is the full name of the node, + that is, <c>einode@durin</c>.</p> </item> <item> - <p><c><![CDATA[thispaddr]]></c> if the IP address of the host.</p> + <p><c>thispaddr</c> if the IP address of the host.</p> </item> </list> <p>A C-node acting as a server is assigned a creation - number when it calls <c><![CDATA[ei_publish()]]></c>.</p> + number when it calls <c>ei_publish()</c>.</p> <p>A connection is closed by simply closing the socket. For information about how to close the socket gracefully (when there are outgoing packets before close), see the relevant system @@ -306,32 +306,32 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { with the local name server EPMD, thereby allowing other processes to send messages by using the registered name. Before calling either of these functions, the process should - have called <c><![CDATA[bind()]]></c> and <c><![CDATA[listen()]]></c> + have called <c>bind()</c> and <c>listen()</c> on an open socket.</p> <list type="bulleted"> <item> - <p><c><![CDATA[ec]]></c> is the C-node structure.</p> + <p><c>ec</c> is the C-node structure.</p> </item> <item> - <p><c><![CDATA[port]]></c> is the local name to register, and is to + <p><c>port</c> is the local name to register, and is to be the same as the port number that was previously bound to the socket.</p> </item> <item> - <p><c><![CDATA[addr]]></c> is the 32-bit IP address of the local + <p><c>addr</c> is the 32-bit IP address of the local host.</p> </item> </list> <p>To unregister with EPMD, simply close the returned descriptor. Do - not use <c><![CDATA[ei_unpublish()]]></c>, which is deprecated + not use <c>ei_unpublish()</c>, which is deprecated anyway.</p> <p>On success, the function returns a descriptor connecting the calling process to EPMD. On failure, <c>-1</c> is returned and - <c><![CDATA[erl_errno]]></c> is set to <c><![CDATA[EIO]]></c>.</p> - <p>Also, <c><![CDATA[errno]]></c> values from - <c><![CDATA[socket]]></c><em>(2)</em> and - <c><![CDATA[connect]]></c><em>(2)</em> system calls may be propagated - into <c><![CDATA[erl_errno]]></c>.</p> + <c>erl_errno</c> is set to <c>EIO</c>.</p> + <p>Also, <c>errno</c> values from + <c>socket</c><em>(2)</em> and + <c>connect</c><em>(2)</em> system calls may be propagated + into <c>erl_errno</c>.</p> </desc> </func> @@ -353,34 +353,34 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { of bytes in the Erlang external format.</p> <list type="bulleted"> <item> - <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang + <p><c>fd</c> is an open descriptor to an Erlang connection. It is obtained from a previous - <c><![CDATA[ei_connect]]></c> or <c><![CDATA[ei_accept]]></c>.</p> + <c>ei_connect</c> or <c>ei_accept</c>.</p> </item> <item> - <p><c><![CDATA[bufp]]></c> is a buffer large enough to hold the + <p><c>bufp</c> is a buffer large enough to hold the expected message.</p> </item> <item> - <p><c><![CDATA[bufsize]]></c> indicates the size of - <c><![CDATA[bufp]]></c>.</p> + <p><c>bufsize</c> indicates the size of + <c>bufp</c>.</p> </item> </list> <p>If a <em>tick</em> occurs, that is, the Erlang node on the other end of the connection has polled this node to see if it - is still alive, the function returns <c><![CDATA[ERL_TICK]]></c> and + is still alive, the function returns <c>ERL_TICK</c> and no message is placed in the buffer. Also, - <c><![CDATA[erl_errno]]></c> is set to <c><![CDATA[EAGAIN]]></c>.</p> + <c>erl_errno</c> is set to <c>EAGAIN</c>.</p> <p>On success, the message is placed in the specified buffer and the function returns the number of bytes actually read. On - failure, the function returns <c><![CDATA[ERL_ERROR]]></c> and sets - <c><![CDATA[erl_errno]]></c> to one of the following:</p> + failure, the function returns <c>ERL_ERROR</c> and sets + <c>erl_errno</c> to one of the following:</p> <taglist> - <tag><c><![CDATA[EAGAIN]]></c></tag> + <tag><c>EAGAIN</c></tag> <item>Temporary error: Try again.</item> - <tag><c><![CDATA[EMSGSIZE]]></c></tag> + <tag><c>EMSGSIZE</c></tag> <item>Buffer is too small.</item> - <tag><c><![CDATA[EIO]]></c></tag> + <tag><c>EIO</c></tag> <item>I/O error.</item> </taglist> </desc> @@ -394,20 +394,20 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { generated by the interface compiler and with code following examples in the same application.</p> <p>In essence, the function performs the same operation as - <c><![CDATA[ei_xreceive_msg]]></c>, but instead of using an + <c>ei_xreceive_msg</c>, but instead of using an <c>ei_x_buff</c>, the function expects a pointer to a character - pointer (<c><![CDATA[mbufp]]></c>), where the character pointer - is to point to a memory area allocated by <c><![CDATA[malloc]]></c>. - Argument <c><![CDATA[bufsz]]></c> is to be a pointer to an integer + pointer (<c>mbufp</c>), where the character pointer + is to point to a memory area allocated by <c>malloc</c>. + Argument <c>bufsz</c> is to be a pointer to an integer containing the exact size (in bytes) of the memory area. The function may reallocate the memory area and will in such cases put the new - size in <c><![CDATA[*bufsz]]></c> and update - <c><![CDATA[*mbufp]]></c>.</p> + size in <c>*bufsz</c> and update + <c>*mbufp</c>.</p> <p>Returns either <c>ERL_TICK</c> or the - <c><![CDATA[msgtype]]></c> field of the - <c><![CDATA[erlang_msg *msg]]></c>. The length - of the message is put in <c><![CDATA[*msglen]]></c>. On error - a value <c><![CDATA[< 0]]></c> is returned.</p> + <c>msgtype</c> field of the + <c>erlang_msg *msg</c>. The length + of the message is put in <c>*msglen</c>. On error + a value <c>< 0</c> is returned.</p> <p>It is recommended to use <c>ei_xreceive_msg</c> instead when possible, for the sake of readability. However, the function will be retained in the interface for compatibility and @@ -432,23 +432,23 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { <name><ret>int</ret><nametext>ei_xreceive_msg(int fd, erlang_msg* msg, ei_x_buff* x)</nametext></name> <fsummary>Receive a message.</fsummary> <desc> - <p>Receives a message to the buffer in <c><![CDATA[x]]></c>. - <c><![CDATA[ei_xreceive_msg]]></c> allows the buffer in - <c><![CDATA[x]]></c> to grow, but <c><![CDATA[ei_receive_msg]]></c> + <p>Receives a message to the buffer in <c>x</c>. + <c>ei_xreceive_msg</c> allows the buffer in + <c>x</c> to grow, but <c>ei_receive_msg</c> fails if the message is larger than the pre-allocated buffer in - <c><![CDATA[x]]></c>.</p> + <c>x</c>.</p> <list type="bulleted"> - <item><c><![CDATA[fd]]></c> is an open descriptor to an Erlang + <item><c>fd</c> is an open descriptor to an Erlang connection.</item> - <item><c><![CDATA[msg]]></c> is a pointer to an - <c><![CDATA[erlang_msg]]></c> structure + <item><c>msg</c> is a pointer to an + <c>erlang_msg</c> structure and contains information on the message received.</item> - <item><c><![CDATA[x]]></c> is buffer obtained from - <c><![CDATA[ei_x_new]]></c>.</item> + <item><c>x</c> is buffer obtained from + <c>ei_x_new</c>.</item> </list> - <p>On success, the functions return <c><![CDATA[ERL_MSG]]></c> and the - <c><![CDATA[msg]]></c> struct is initialized. - <c><![CDATA[erlang_msg]]></c> is defined as follows:</p> + <p>On success, the functions return <c>ERL_MSG</c> and the + <c>msg</c> struct is initialized. + <c>erlang_msg</c> is defined as follows:</p> <code type="none"><![CDATA[ typedef struct { long msgtype; @@ -459,31 +459,31 @@ typedef struct { erlang_trace token; } erlang_msg; ]]></code> - <p><c><![CDATA[msgtype]]></c> identifies the type of message, and is + <p><c>msgtype</c> identifies the type of message, and is one of the following:</p> <taglist> - <tag><c><![CDATA[ERL_SEND]]></c></tag> + <tag><c>ERL_SEND</c></tag> <item> <p>Indicates that an ordinary send operation has occurred. - <c><![CDATA[msg->to]]></c> contains the pid of the recipient (the + <c>msg->to</c> contains the pid of the recipient (the C-node).</p> </item> - <tag><c><![CDATA[ERL_REG_SEND]]></c></tag> + <tag><c>ERL_REG_SEND</c></tag> <item> <p>A registered send operation occurred. - <c><![CDATA[msg->from]]></c> contains the pid of the sender.</p> + <c>msg->from</c> contains the pid of the sender.</p> </item> - <tag><c><![CDATA[ERL_LINK]]></c> or - <c><![CDATA[ERL_UNLINK]]></c></tag> + <tag><c>ERL_LINK</c> or + <c>ERL_UNLINK</c></tag> <item> - <p><c><![CDATA[msg->to]]></c> and - <c><![CDATA[msg->from]]></c> contain the pids of the + <p><c>msg->to</c> and + <c>msg->from</c> contain the pids of the sender and recipient of the link or unlink.</p> </item> - <tag><c><![CDATA[ERL_EXIT]]></c></tag> + <tag><c>ERL_EXIT</c></tag> <item> - <p>Indicates a broken link. <c><![CDATA[msg->to]]></c> and - <c><![CDATA[msg->from]]></c> contain the pids of the linked + <p>Indicates a broken link. <c>msg->to</c> and + <c>msg->from</c> contain the pids of the linked processes.</p> </item> </taglist> @@ -520,19 +520,19 @@ typedef struct { <p>Sends an Erlang term to a registered process.</p> <list type="bulleted"> <item> - <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang + <p><c>fd</c> is an open descriptor to an Erlang connection.</p> </item> - <item><c><![CDATA[server_name]]></c> is the registered name of the + <item><c>server_name</c> is the registered name of the intended recipient.</item> - <item><c><![CDATA[buf]]></c> is the buffer containing the term in + <item><c>buf</c> is the buffer containing the term in binary format.</item> - <item><c><![CDATA[len]]></c> is the length of the message in bytes. + <item><c>len</c> is the length of the message in bytes. </item> </list> <p>Returns <c>0</c> if successful, otherwise <c>-1</c>. In - the latter case it sets <c><![CDATA[erl_errno]]></c> to - <c><![CDATA[EIO]]></c>.</p> + the latter case it sets <c>erl_errno</c> to + <c>EIO</c>.</p> <p><em>Example:</em></p> <p>Send the atom "ok" to the process "worker":</p> <code type="none"><![CDATA[ @@ -563,75 +563,75 @@ if (ei_reg_send(&ec, fd, x.buff, x.index) < 0) <fsummary>Remote Procedure Call from C to Erlang.</fsummary> <desc> <p>Supports calling Erlang functions on remote nodes. - <c><![CDATA[ei_rpc_to()]]></c> sends an RPC request to a remote node - and <c><![CDATA[ei_rpc_from()]]></c> receives the results of such a - call. <c><![CDATA[ei_rpc()]]></c> combines the functionality of these + <c>ei_rpc_to()</c> sends an RPC request to a remote node + and <c>ei_rpc_from()</c> receives the results of such a + call. <c>ei_rpc()</c> combines the functionality of these two functions by sending an RPC request and waiting for the results. See also <seealso marker="kernel:rpc#call/4"> <c>rpc:call/4</c></seealso> in Kernel.</p> <list type="bulleted"> <item> - <p><c><![CDATA[ec]]></c> is the C-node structure previously - initiated by a call to <c><![CDATA[ei_connect_init()]]></c> or - <c><![CDATA[ei_connect_xinit()]]></c>.</p> + <p><c>ec</c> is the C-node structure previously + initiated by a call to <c>ei_connect_init()</c> or + <c>ei_connect_xinit()</c>.</p> </item> <item> - <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang + <p><c>fd</c> is an open descriptor to an Erlang connection.</p> </item> <item> - <p><c><![CDATA[timeout]]></c> is the maximum time (in milliseconds) - to wait for results. Specify <c><![CDATA[ERL_NO_TIMEOUT]]></c> to + <p><c>timeout</c> is the maximum time (in milliseconds) + to wait for results. Specify <c>ERL_NO_TIMEOUT</c> to wait forever. - <c><![CDATA[ei_rpc()]]></c> waits infinitely for the answer, + <c>ei_rpc()</c> waits infinitely for the answer, that is, the call will never time out.</p> </item> <item> - <p><c><![CDATA[mod]]></c> is the name of the module containing the + <p><c>mod</c> is the name of the module containing the function to be run on the remote node.</p> </item> <item> - <p><c><![CDATA[fun]]></c> is the name of the function to run.</p> + <p><c>fun</c> is the name of the function to run.</p> </item> <item> - <p><c><![CDATA[argbuf]]></c> is a pointer to a buffer with an + <p><c>argbuf</c> is a pointer to a buffer with an encoded Erlang list, without a version magic number, containing the arguments to be passed to the function.</p> </item> <item> - <p><c><![CDATA[argbuflen]]></c> is the length of the buffer + <p><c>argbuflen</c> is the length of the buffer containing the encoded Erlang list.</p> </item> <item> - <p><c><![CDATA[msg]]></c> is structure of type - <c><![CDATA[erlang_msg]]></c> and contains information on the + <p><c>msg</c> is structure of type + <c>erlang_msg</c> and contains information on the message - received. For a description of the <c><![CDATA[erlang_msg]]></c> + received. For a description of the <c>erlang_msg</c> format, see <seealso marker="#ei_receive_msg"> <c>ei_receive_msg</c></seealso>.</p> </item> <item> - <p><c><![CDATA[x]]></c> points to the dynamic buffer that receives - the result. For <c><![CDATA[ei_rpc()]]></c> this is the result + <p><c>x</c> points to the dynamic buffer that receives + the result. For <c>ei_rpc()</c> this is the result without the version magic number. For - <c><![CDATA[ei_rpc_from()]]></c> the result returns a version - magic number and a 2-tuple <c><![CDATA[{rex,Reply}]]></c>.</p> + <c>ei_rpc_from()</c> the result returns a version + magic number and a 2-tuple <c>{rex,Reply}</c>.</p> </item> </list> - <p><c><![CDATA[ei_rpc()]]></c> returns the number of bytes in the + <p><c>ei_rpc()</c> returns the number of bytes in the result on success and <c>-1</c> on failure. - <c><![CDATA[ei_rpc_from()]]></c> returns the - number of bytes, otherwise one of <c><![CDATA[ERL_TICK]]></c>, - <c><![CDATA[ERL_TIMEOUT]]></c>, - and <c><![CDATA[ERL_ERROR]]></c>. When failing, all three - functions set <c><![CDATA[erl_errno]]></c> to one of the + <c>ei_rpc_from()</c> returns the + number of bytes, otherwise one of <c>ERL_TICK</c>, + <c>ERL_TIMEOUT</c>, + and <c>ERL_ERROR</c>. When failing, all three + functions set <c>erl_errno</c> to one of the following:</p> <taglist> - <tag><c><![CDATA[EIO]]></c></tag> + <tag><c>EIO</c></tag> <item>I/O error.</item> - <tag><c><![CDATA[ETIMEDOUT]]></c></tag> + <tag><c>ETIMEDOUT</c></tag> <item>Time-out expired.</item> - <tag><c><![CDATA[EAGAIN]]></c></tag> + <tag><c>EAGAIN</c></tag> <item>Temporary error: Try again.</item> </taglist> <p><em>Example:</em></p> @@ -662,11 +662,11 @@ if (ei_decode_version(result.buff, &index) < 0 <fsummary>Retrieve the pid of the C-node.</fsummary> <desc> <p>Retrieves the pid of the C-node. Every C-node - has a (pseudo) pid used in <c><![CDATA[ei_send_reg]]></c>, - <c><![CDATA[ei_rpc]]></c>, - and others. This is contained in a field in the <c><![CDATA[ec]]></c> + has a (pseudo) pid used in <c>ei_send_reg</c>, + <c>ei_rpc</c>, + and others. This is contained in a field in the <c>ec</c> structure. It will be safe for a long time to fetch this - field directly from the <c><![CDATA[ei_cnode]]></c> structure.</p> + field directly from the <c>ei_cnode</c> structure.</p> </desc> </func> @@ -676,18 +676,18 @@ if (ei_decode_version(result.buff, &index) < 0 <desc> <p>Sends an Erlang term to a process.</p> <list type="bulleted"> - <item><c><![CDATA[fd]]></c> is an open descriptor to an Erlang + <item><c>fd</c> is an open descriptor to an Erlang connection.</item> - <item><c><![CDATA[to]]></c> is the pid of the intended recipient of + <item><c>to</c> is the pid of the intended recipient of the message.</item> - <item><c><![CDATA[buf]]></c> is the buffer containing the term in + <item><c>buf</c> is the buffer containing the term in binary format.</item> - <item><c><![CDATA[len]]></c> is the length of the message in bytes. + <item><c>len</c> is the length of the message in bytes. </item> </list> <p>Returns <c>0</c> if successful, otherwise <c>-1</c>. In - the latter case it sets <c><![CDATA[erl_errno]]></c> to - <c><![CDATA[EIO]]></c>.</p> + the latter case it sets <c>erl_errno</c> to + <c>EIO</c>.</p> </desc> </func> @@ -720,14 +720,14 @@ if (ei_decode_version(result.buff, &index) < 0 <p>This function is retained for compatibility with code generated by the interface compiler and with code following examples in the same application.</p> - <p>The function works as <c><![CDATA[ei_reg_send]]></c> with one - exception. Instead of taking <c><![CDATA[ei_cnode]]></c> as first + <p>The function works as <c>ei_reg_send</c> with one + exception. Instead of taking <c>ei_cnode</c> as first argument, it takes a second argument, an - <c><![CDATA[erlang_pid]]></c>, + <c>erlang_pid</c>, which is to be the process identifier of the sending process (in the Erlang distribution protocol).</p> - <p>A suitable <c><![CDATA[erlang_pid]]></c> can be constructed from the - <c><![CDATA[ei_cnode]]></c> structure by the following example + <p>A suitable <c>erlang_pid</c> can be constructed from the + <c>ei_cnode</c> structure by the following example code:</p> <code type="none"><![CDATA[ ei_cnode ec; @@ -769,10 +769,10 @@ self->num = fd; <desc> <p>Can be used to retrieve information about the C-node. These values are initially set with - <c><![CDATA[ei_connect_init()]]></c> or - <c><![CDATA[ei_connect_xinit()]]></c>.</p> + <c>ei_connect_init()</c> or + <c>ei_connect_xinit()</c>.</p> <p>These function simply fetch the appropriate field from the - <c><![CDATA[ec]]></c> + <c>ec</c> structure. Read the field directly will probably be safe for a long time, so these functions are not really needed.</p> </desc> @@ -788,16 +788,16 @@ self->num = fd; <c>-relaxed_command_check</c>, which it normally is not.</p> <p>To unregister a node you have published, you should close the descriptor that was returned by - <c><![CDATA[ei_publish()]]></c>.</p> + <c>ei_publish()</c>.</p> <warning> <p>This function is deprecated and will be removed in a future release.</p> </warning> - <p><c><![CDATA[ec]]></c> is the node structure of the node to + <p><c>ec</c> is the node structure of the node to unregister.</p> <p>If the node was successfully unregistered from EPMD, the function returns <c>0</c>. Otherwise, <c>-1</c> is returned and - <c><![CDATA[erl_errno]]></c> is set to <c><![CDATA[EIO]]></c>.</p> + <c>erl_errno</c> is set to <c>EIO</c>.</p> </desc> </func> @@ -818,18 +818,18 @@ self->num = fd; <p>If a connection attempt fails, the following can be checked:</p> <list type="bulleted"> - <item><c><![CDATA[erl_errno]]></c>.</item> + <item><c>erl_errno</c>.</item> <item>That the correct cookie was used</item> <item>That EPMD is running</item> <item>That the remote Erlang node on the other side is running the - same version of Erlang as the <c><![CDATA[ei]]></c> library</item> - <item>That environment variable <c><![CDATA[ERL_EPMD_PORT]]></c> + same version of Erlang as the <c>ei</c> library</item> + <item>That environment variable <c>ERL_EPMD_PORT</c> is set correctly</item> </list> <p>The connection attempt can be traced by setting a trace level by either - using <c><![CDATA[ei_set_tracelevel]]></c> or by setting environment - variable <c><![CDATA[EI_TRACELEVEL]]></c>. + using <c>ei_set_tracelevel</c> or by setting environment + variable <c>EI_TRACELEVEL</c>. The trace levels have the following messages:</p> <list> diff --git a/lib/erl_interface/doc/src/ei_users_guide.xml b/lib/erl_interface/doc/src/ei_users_guide.xml index 2c82f9ae7f..0eed50b50b 100644 --- a/lib/erl_interface/doc/src/ei_users_guide.xml +++ b/lib/erl_interface/doc/src/ei_users_guide.xml @@ -102,21 +102,21 @@ Eshell V4.7.4 (abort with ^G) /usr/local/otp ]]></code> <p>To compile your code, ensure that your C compiler knows where - to find <c><![CDATA[erl_interface.h]]></c> by specifying an appropriate - <c><![CDATA[-I]]></c> argument on the command line, or add it to - the <c><![CDATA[CFLAGS]]></c> definition in your - <c><![CDATA[Makefile]]></c>. The correct value for this path is - <c><![CDATA[$OTPROOT/lib/erl_interface-$EIVSN/include]]></c>, + to find <c>erl_interface.h</c> by specifying an appropriate + <c>-I</c> argument on the command line, or add it to + the <c>CFLAGS</c> definition in your + <c>Makefile</c>. The correct value for this path is + <c>$OTPROOT/lib/erl_interface-$EIVSN/include</c>, where:</p> <list type="bulleted"> <item> - <p><c><![CDATA[$OTPROOT]]></c> is the path reported by - <c><![CDATA[code:root_dir/0]]></c> in the example above.</p> + <p><c>$OTPROOT</c> is the path reported by + <c>code:root_dir/0</c> in the example above.</p> </item> <item> - <p><c><![CDATA[$EIVSN]]></c> is the version of the <c>Erl_Interface</c> application, - for example, <c><![CDATA[erl_interface-3.2.3]]></c>.</p> + <p><c>$EIVSN</c> is the version of the <c>Erl_Interface</c> application, + for example, <c>erl_interface-3.2.3</c>.</p> </item> </list> @@ -128,16 +128,16 @@ $ cc -c -I/usr/local/otp/lib/erl_interface-3.2.3/include myprog.c ]]></code> <p>When linking:</p> <list type="bulleted"> - <item>Specify the path to <c><![CDATA[liberl_interface.a]]></c> and - <c><![CDATA[libei.a]]></c> with - <c><![CDATA[-L$OTPROOT/lib/erl_interface-3.2.3/lib]]></c>.</item> + <item>Specify the path to <c>liberl_interface.a</c> and + <c>libei.a</c> with + <c>-L$OTPROOT/lib/erl_interface-3.2.3/lib</c>.</item> <item>Specify the name of the libraries with - <c><![CDATA[-lerl_interface -lei]]></c>.</item> + <c>-lerl_interface -lei</c>.</item> </list> <p>Do this on the command line or add the flags to the - <c><![CDATA[LDFLAGS]]></c> definition in your - <c><![CDATA[Makefile]]></c>.</p> + <c>LDFLAGS</c> definition in your + <c>Makefile</c>.</p> <p>Linking the code:</p> @@ -146,9 +146,9 @@ $ ld -L/usr/local/otp/lib/erl_interface-3.2.3/ lib myprog.o -lerl_interface -lei -o myprog ]]></code> <p>On some systems it can be necessary to link with some more - libraries (for example, <c><![CDATA[libnsl.a]]></c> and - <c><![CDATA[libsocket.a]]></c> on Solaris, or - <c><![CDATA[wsock32.lib]]></c> on Windows) to use the + libraries (for example, <c>libnsl.a</c> and + <c>libsocket.a</c> on Solaris, or + <c>wsock32.lib</c> on Windows) to use the communication facilities of <c>Erl_Interface</c>.</p> <p>If you use the <c>Erl_Interface</c> functions in a threaded @@ -156,18 +156,18 @@ $ ld -L/usr/local/otp/lib/erl_interface-3.2.3/ <c>Erl_Interface</c> needs access to some of the synchronization facilities in your threads package. You must specify extra compiler flags to indicate which of the packages you use. Define - <c><![CDATA[_REENTRANT]]></c> and either <c><![CDATA[STHREADS]]></c> or - <c><![CDATA[PTHREADS]]></c>. The default is to use POSIX threads if - <c><![CDATA[_REENTRANT]]></c> is specified.</p> + <c>_REENTRANT</c> and either <c>STHREADS</c> or + <c>PTHREADS</c>. The default is to use POSIX threads if + <c>_REENTRANT</c> is specified.</p> </section> <section> <title>Initializing the Erl_Interface Library</title> <p>Before calling any of the other <c>Erl_Interface</c> functions, call - <c><![CDATA[erl_init()]]></c> exactly once to initialize the library. - <c><![CDATA[erl_init()]]></c> takes two arguments. However, the arguments + <c>erl_init()</c> exactly once to initialize the library. + <c>erl_init()</c> takes two arguments. However, the arguments are no longer used by <c>Erl_Interface</c> and are therefore to be - specified as <c><![CDATA[erl_init(NULL,0)]]></c>.</p> + specified as <c>erl_init(NULL,0)</c>.</p> </section> <section> @@ -181,7 +181,7 @@ $ ld -L/usr/local/otp/lib/erl_interface-3.2.3/ several C functions that create and manipulate Erlang data structures. The library also contains an encode and a decode function. The following example shows how to create and encode an Erlang tuple - <c><![CDATA[{tobbe,3928}]]></c>:</p> + <c>{tobbe,3928}</c>:</p> <code type="none"><![CDATA[ ETERM *arr[2], *tuple; @@ -193,8 +193,8 @@ arr[1] = erl_mk_integer(3928); tuple = erl_mk_tuple(arr, 2); i = erl_encode(tuple, buf); ]]></code> - <p>Alternatively, you can use <c><![CDATA[erl_send()]]></c> and - <c><![CDATA[erl_receive_msg]]></c>, which handle the encoding and + <p>Alternatively, you can use <c>erl_send()</c> and + <c>erl_receive_msg</c>, which handle the encoding and decoding of messages transparently.</p> <p>For a complete description, see the following modules:</p> @@ -232,8 +232,8 @@ erl_free_compound(ep); ]]></code> <p>As in the previous examples, it is your responsibility to free the memory allocated for Erlang terms. In this example, - <c><![CDATA[erl_free_compound()]]></c> ensures that the complete term - pointed to by <c><![CDATA[ep]]></c> is released. This is necessary + <c>erl_free_compound()</c> ensures that the complete term + pointed to by <c>ep</c> is released. This is necessary because the pointer from the second call to <c>erl_format</c> is lost.</p> <p>The following example shows a slightly different solution:</p> @@ -247,7 +247,7 @@ erl_free_term(ep); erl_free_term(ep2); ]]></code> <p>In this case, you free the two terms independently. The order in - which you free the terms <c><![CDATA[ep]]></c> and <c><![CDATA[ep2]]></c> + which you free the terms <c>ep</c> and <c>ep2</c> is not important, because the <c>Erl_Interface</c> library uses reference counting to determine when it is safe to remove objects.</p> @@ -274,7 +274,7 @@ erl_eterm_release(); <section> <title>Pattern Matching</title> <p>An Erlang pattern is a term that can contain unbound variables or - <c><![CDATA["do not care"]]></c> symbols. Such a pattern can be matched + <c>"do not care"</c> symbols. Such a pattern can be matched against a term and, if the match is successful, any unbound variables in the pattern will be bound as a side effect. The content of a bound @@ -348,7 +348,7 @@ erl_connect_init(identification_number, cookie, creation); ]]></code> <p>After initialization, you set up the connection to the Erlang node. To specify the Erlang node you want to connect to, use - <c><![CDATA[erl_connect()]]></c>. The following example sets up the + <c>erl_connect()</c>. The following example sets up the connection and is to result in a valid socket file descriptor:</p> <code type="none"><![CDATA[ @@ -357,7 +357,7 @@ char *nodename="[email protected]"; /* An example */ if ((sockfd = erl_connect(nodename)) < 0) erl_err_quit("ERROR: erl_connect failed"); ]]></code> - <p><c><![CDATA[erl_err_quit()]]></c> prints the specified string and + <p><c>erl_err_quit()</c> prints the specified string and terminates the program. For more information, see the <seealso marker="erl_error"><c>erl_error</c></seealso> module.</p> </section> @@ -366,24 +366,24 @@ if ((sockfd = erl_connect(nodename)) < 0) <title>Using EPMD</title> <p><seealso marker="erts:epmd"><c>erts:epmd</c></seealso> is the Erlang Port Mapper Daemon. Distributed - Erlang nodes register with <c><![CDATA[epmd]]></c> on the local host to + Erlang nodes register with <c>epmd</c> on the local host to indicate to other nodes that they exist and can accept connections. - <c><![CDATA[epmd]]></c> maintains a register of + <c>epmd</c> maintains a register of node and port number information, and when a node wishes to connect to - another node, it first contacts <c><![CDATA[epmd]]></c> to find the + another node, it first contacts <c>epmd</c> to find the correct port number to connect to.</p> <p>When you use <seealso marker="erl_connect"><c>erl_connect</c></seealso> to connect to an Erlang node, a connection is first made to - <c><![CDATA[epmd]]></c> and, if the node is known, a + <c>epmd</c> and, if the node is known, a connection is then made to the Erlang node.</p> - <p>C nodes can also register themselves with <c><![CDATA[epmd]]></c> + <p>C nodes can also register themselves with <c>epmd</c> if they want other nodes in the system to be able to find and connect to them.</p> - <p>Before registering with <c><![CDATA[epmd]]></c>, you must first + <p>Before registering with <c>epmd</c>, you must first create a listen socket and bind it to a port. Then:</p> <code type="none"><![CDATA[ @@ -391,17 +391,17 @@ int pub; pub = erl_publish(port); ]]></code> - <p><c><![CDATA[pub]]></c> is a file descriptor now connected to - <c><![CDATA[epmd]]></c>. <c><![CDATA[epmd]]></c> + <p><c>pub</c> is a file descriptor now connected to + <c>epmd</c>. <c>epmd</c> monitors the other end of the connection. If it detects that the connection has been closed, the node becomes unregistered. So, if you explicitly close the descriptor or if your node fails, it becomes - unregistered from <c><![CDATA[epmd]]></c>.</p> + unregistered from <c>epmd</c>.</p> <p>Notice that on some systems (such as VxWorks), a failed node is not detected by this mechanism, as the operating system does not automatically close descriptors that were left open when the node - failed. If a node has failed in this way, <c><![CDATA[epmd]]></c> + failed. If a node has failed in this way, <c>epmd</c> prevents you from registering a new node with the old name, as it thinks that the old name is still in use. In this case, you must unregister the name @@ -410,7 +410,7 @@ pub = erl_publish(port); ]]></code> <code type="none"><![CDATA[ erl_unpublish(node); ]]></code> - <p>This causes <c><![CDATA[epmd]]></c> to close the connection from the + <p>This causes <c>epmd</c> to close the connection from the far end. Notice that if the name was in fact still in use by a node, the results of this operation are unpredictable. Also, doing this does not cause the @@ -442,15 +442,15 @@ erl_unpublish(node); ]]></code> <c>erl_connect:erl_receive_msg</c></seealso></item> </list> - <p><c><![CDATA[erl_receive()]]></c> receives the message into a buffer, - while <c><![CDATA[erl_receive_msg()]]></c> decodes the message into an + <p><c>erl_receive()</c> receives the message into a buffer, + while <c>erl_receive_msg()</c> decodes the message into an Erlang term.</p> <section> <title>Example of Sending Messages</title> - <p>In the following example, <c><![CDATA[{Pid, hello_world}]]></c> is - sent to a registered process <c><![CDATA[my_server]]></c>. The message - is encoded by <c><![CDATA[erl_send()]]></c>:</p> + <p>In the following example, <c>{Pid, hello_world}</c> is + sent to a registered process <c>my_server</c>. The message + is encoded by <c>erl_send()</c>:</p> <code type="none"><![CDATA[ extern const char *erl_thisnodename(void); @@ -467,16 +467,16 @@ erl_reg_send(sockfd, "my_server", emsg); erl_free_term(emsg); ]]></code> <p>The first element of the tuple that is sent is your own - pid. This enables <c><![CDATA[my_server]]></c> to reply. + pid. This enables <c>my_server</c> to reply. For more information about the primitives, see the <seealso marker="erl_connect"><c>erl_connect</c></seealso> module.</p> </section> <section> <title>Example of Receiving Messages</title> - <p>In this example, <c><![CDATA[{Pid, Something}]]></c> is received. The + <p>In this example, <c>{Pid, Something}</c> is received. The received pid is then used to return - <c><![CDATA[{goodbye,Pid}]]></c>.</p> + <c>{goodbye,Pid}</c>.</p> <code type="none"><![CDATA[ ETERM *arr[2], *answer; @@ -498,15 +498,15 @@ if ((rc = erl_receive_msg(sockfd , buf, BUFSIZE, &emsg)) == ERL_MSG) { occasionally polls all its connected neighbors in an attempt to detect failed nodes or communication links. A node that receives such a message is expected to respond immediately with an - <c><![CDATA[ERL_TICK]]></c> message. This is done automatically by - <c><![CDATA[erl_receive()]]></c>. However, when this has occurred, - <c><![CDATA[erl_receive]]></c> returns <c><![CDATA[ERL_TICK]]></c> to + <c>ERL_TICK</c> message. This is done automatically by + <c>erl_receive()</c>. However, when this has occurred, + <c>erl_receive</c> returns <c>ERL_TICK</c> to the caller without storing a message into the - <c><![CDATA[ErlMessage]]></c> structure.</p> + <c>ErlMessage</c> structure.</p> <p>When a message has been received, it is the caller's responsibility - to free the received message <c><![CDATA[emsg.msg]]></c> and - <c><![CDATA[emsg.to]]></c> or <c><![CDATA[emsg.from]]></c>, + to free the received message <c>emsg.msg</c> and + <c>emsg.to</c> or <c>emsg.from</c>, depending on the type of message received.</p> <p>For more information, see the @@ -538,14 +538,14 @@ if (!erl_match(ep, reply)) erl_free_term(ep); erl_free_term(reply); ]]></code> - <p><c><![CDATA[c:c/1]]></c> is called to compile the specified module on - the remote node. <c><![CDATA[erl_match()]]></c> checks that the + <p><c>c:c/1</c> is called to compile the specified module on + the remote node. <c>erl_match()</c> checks that the compilation was - successful by testing for the expected <c><![CDATA[ok]]></c>.</p> + successful by testing for the expected <c>ok</c>.</p> - <p>For more information about <c><![CDATA[erl_rpc()]]></c> and its - companions <c><![CDATA[erl_rpc_to()]]></c> and - <c><![CDATA[erl_rpc_from()]]></c>, see the + <p>For more information about <c>erl_rpc()</c> and its + companions <c>erl_rpc_to()</c> and + <c>erl_rpc_from()</c>, see the <seealso marker="erl_connect"><c>erl_connect</c></seealso> module.</p> </section> @@ -582,15 +582,15 @@ free(names); ]]></code> <c>erl_global:erl_global_names</c></seealso> allocates and returns a buffer containing all the names known to the <c>global</c> module in <c>Kernel</c>. - <c><![CDATA[count]]></c> is initialized to + <c>count</c> is initialized to indicate the number of names in the array. The array of strings in names is terminated by a <c>NULL</c> pointer, so it is not necessary to use - <c><![CDATA[count]]></c> to determine when the last name is reached.</p> + <c>count</c> to determine when the last name is reached.</p> <p>It is the caller's responsibility to free the array. <c>erl_global_names</c> allocates the array and all the strings - using a single call to <c><![CDATA[malloc()]]></c>, so - <c><![CDATA[free(names)]]></c> is all that is necessary.</p> + using a single call to <c>malloc()</c>, so + <c>free(names)</c> is all that is necessary.</p> <p>To look up one of the names:</p> @@ -600,16 +600,16 @@ char node[256]; pid = erl_global_whereis(fd,"schedule",node); ]]></code> - <p>If <c><![CDATA["schedule"]]></c> is known to the + <p>If <c>"schedule"</c> is known to the <c>global</c> module in <c>Kernel</c>, an Erlang pid is returned that can be used to send messages to the schedule service. - Also, <c><![CDATA[node]]></c> is initialized to contain the name of + Also, <c>node</c> is initialized to contain the name of the node where the service is registered, so that you can make a connection to it by simply passing the variable to <seealso marker="erl_connect"><c>erl_connect</c></seealso>.</p> <p>Before registering a name, you should already have registered your - port number with <c><![CDATA[epmd]]></c>. This is not strictly necessary, + port number with <c>epmd</c>. This is not strictly necessary, but if you neglect to do so, then other nodes wishing to communicate with your service cannot find or connect to your process.</p> @@ -629,7 +629,7 @@ erl_global_register(fd,servicename,pid); ]]></code> to wait for incoming connections.</p> <note> - <p>Remember to free <c><![CDATA[pid]]></c> later with + <p>Remember to free <c>pid</c> later with <seealso marker="erl_malloc#erl_free_term"> <c>erl_malloc:erl_free_term</c></seealso>.</p> </note> @@ -743,7 +743,7 @@ ei_reg_close(reg); ]]></code> ei_reg_dump(fd, reg, "mtab", dumpflags); ]]></code> <p>This example back up the contents of the registry to the - specified <c>Mnesia</c> table <c><![CDATA["mtab"]]></c>. + specified <c>Mnesia</c> table <c>"mtab"</c>. Once a registry has been backed up to <c>Mnesia</c> like this, more backups only affect objects that have been modified since the most recent backup, that is, @@ -756,7 +756,7 @@ ei_reg_dump(fd, reg, "mtab", dumpflags); ]]></code> <code type="none"><![CDATA[ ei_reg_restore(fd, reg, "mtab"); ]]></code> - <p>This reads the entire contents of <c><![CDATA["mtab"]]></c> into the + <p>This reads the entire contents of <c>"mtab"</c> into the specified registry. After the restore, all the objects in the registry are marked as unmodified, so a later backup only affects objects that you have modified since the restore.</p> @@ -775,8 +775,8 @@ ei_reg_restore(fd, reg, "mtab"); ]]></code> important that some simple guidelines are followed.</p> <p>Most importantly, the object must have been created with a single call - to <c><![CDATA[malloc()]]></c> (or similar), so that it can later be - removed by a single call to <c><![CDATA[free()]]></c>. + to <c>malloc()</c> (or similar), so that it can later be + removed by a single call to <c>free()</c>. Objects are freed by the registry when it is closed, or when you assign a new value to an object that previously contained a string or binary.</p> diff --git a/lib/erl_interface/doc/src/erl_call.xml b/lib/erl_interface/doc/src/erl_call.xml index 706dd271cc..f1e52b1889 100644 --- a/lib/erl_interface/doc/src/erl_call.xml +++ b/lib/erl_interface/doc/src/erl_call.xml @@ -35,9 +35,9 @@ <com>erl_call</com> <comsummary>Call/start a distributed Erlang node.</comsummary> <description> - <p><c><![CDATA[erl_call]]></c> makes it possible to start and/or + <p><c>erl_call</c> makes it possible to start and/or communicate with a distributed Erlang node. It is built upon the - <c><![CDATA[Erl_Interface]]></c> library as an example application. + <c>Erl_Interface</c> library as an example application. Its purpose is to use a Unix shell script to interact with a distributed Erlang node. It performs all communication with the Erlang <em>rex server</em>, using the standard Erlang RPC facility. It does not @@ -45,14 +45,14 @@ <p>The main use is to either start a distributed Erlang node or to make an ordinary function call. However, it is also - possible to pipe an Erlang module to <c><![CDATA[erl_call]]></c> and have + possible to pipe an Erlang module to <c>erl_call</c> and have it compiled, or to pipe a sequence of Erlang expressions to be evaluated (similar to the Erlang shell).</p> - <p>Options, which cause <c><![CDATA[stdin]]></c> to be read, can be used + <p>Options, which cause <c>stdin</c> to be read, can be used with advantage, as scripts from within (Unix) shell scripts. Another nice use - of <c><![CDATA[erl_call]]></c> could be from (HTTP) CGI-bin scripts.</p> + of <c>erl_call</c> could be from (HTTP) CGI-bin scripts.</p> </description> <funcs> @@ -67,65 +67,65 @@ <tag><c>-a [Mod [Fun [Args]]]]</c></tag> <item> <p>(<em>Optional.</em>) Applies the specified function - and returns the result. <c><![CDATA[Mod]]></c> must be specified. + and returns the result. <c>Mod</c> must be specified. However, <c>start</c> and <c>[]</c> are assumed for unspecified - <c><![CDATA[Fun]]></c> and <c><![CDATA[Args]]></c>, respectively. - <c><![CDATA[Args]]></c> is to be in the same format as for + <c>Fun</c> and <c>Args</c>, respectively. + <c>Args</c> is to be in the same format as for <seealso marker="erts:erlang#apply/3"> <c>erlang:apply/3</c></seealso> in <c>ERTS</c>.</p> <p>Notice that this flag takes exactly one argument, so quoting - can be necessary to group <c><![CDATA[Mod]]></c>, - <c><![CDATA[Fun]]></c>, and <c><![CDATA[Args]]></c> in a manner + can be necessary to group <c>Mod</c>, + <c>Fun</c>, and <c>Args</c> in a manner dependent on the behavior of your command shell.</p> </item> <tag><c>-c Cookie</c></tag> <item> <p>(<em>Optional.</em>) Use this option to specify a certain cookie. - If no cookie is specified, the <c><![CDATA[~/.erlang.cookie]]></c> + If no cookie is specified, the <c>~/.erlang.cookie</c> file is read and its content is used as cookie. The Erlang node we want to communicate with must have the same cookie.</p> </item> <tag><c>-d</c></tag> <item> <p>(<em>Optional.</em>) Debug mode. This causes all I/O to be output - to the <c><![CDATA[~/.erl_call.out.Nodename]]></c> file, where - <c><![CDATA[Nodename]]></c> + to the <c>~/.erl_call.out.Nodename</c> file, where + <c>Nodename</c> is the node name of the Erlang node in question.</p> </item> <tag><c>-e</c></tag> <item> <p>(<em>Optional.</em>) Reads a sequence of Erlang expressions, separated by comma (,) and ended with a full stop (.), from - <c><![CDATA[stdin]]></c> until EOF (Control-D). Evaluates the + <c>stdin</c> until EOF (Control-D). Evaluates the expressions and returns the result from the last expression. - Returns <c><![CDATA[{ok,Result}]]></c> on success.</p> + Returns <c>{ok,Result}</c> on success.</p> </item> <tag><c>-h HiddenName</c></tag> <item> <p>(<em>Optional.</em>) Specifies the name of the hidden node - that <c><![CDATA[erl_call]]></c> represents.</p> + that <c>erl_call</c> represents.</p> </item> <tag><c>-m</c></tag> <item> <p>(<em>Optional.</em>) Reads an Erlang module from - <c><![CDATA[stdin]]></c> and compiles it.</p> + <c>stdin</c> and compiles it.</p> </item> <tag><c>-n Node</c></tag> <item> - <p>(One of <c><![CDATA[-n, -name, -sname]]></c> is required.) - Has the same meaning as <c><![CDATA[-name]]></c> and can still be + <p>(One of <c>-n, -name, -sname</c> is required.) + Has the same meaning as <c>-name</c> and can still be used for backward compatibility reasons.</p> </item> <tag><c>-name Node</c></tag> <item> - <p>(One of <c><![CDATA[-n, -name, -sname]]></c> is required.) - <c><![CDATA[Node]]></c> is the name of the node to be + <p>(One of <c>-n, -name, -sname</c> is required.) + <c>Node</c> is the name of the node to be started or communicated with. It is assumed that - <c><![CDATA[Node]]></c> is started with - <c><![CDATA[erl -name]]></c>, which means that fully + <c>Node</c> is started with + <c>erl -name</c>, which means that fully qualified long node names are used. If option - <c><![CDATA[-s]]></c> is specified, an Erlang node will (if - necessary) be started with <c><![CDATA[erl -name]]></c>.</p> + <c>-s</c> is specified, an Erlang node will (if + necessary) be started with <c>erl -name</c>.</p> </item> <tag><c>-q</c></tag> <item> @@ -135,13 +135,13 @@ <tag><c>-r</c></tag> <item> <p>(<em>Optional.</em>) Generates a random name of the hidden node - that <c><![CDATA[erl_call]]></c> represents.</p> + that <c>erl_call</c> represents.</p> </item> <tag><c>-s</c></tag> <item> <p>(<em>Optional.</em>) Starts a distributed Erlang node if necessary. This means that in a sequence of calls, where - '<c><![CDATA[-s]]></c>' and '<c><![CDATA[-n Node]]></c>' are + '<c>-s</c>' and '<c>-n Node</c>' are constant, only the first call starts the Erlang node. This makes the rest of the communication very fast. This flag is currently only available on Unix-like platforms (Linux, Mac OS X, Solaris, @@ -149,25 +149,25 @@ </item> <tag><c>-sname Node</c></tag> <item> - <p>(One of <c><![CDATA[-n, -name, -sname]]></c> is required.) - <c><![CDATA[Node]]></c> is the name of the node to be started - or communicated with. It is assumed that <c><![CDATA[Node]]></c> - is started with <c><![CDATA[erl -sname]]></c>, which means that - short node names are used. If option <c><![CDATA[-s]]></c> is + <p>(One of <c>-n, -name, -sname</c> is required.) + <c>Node</c> is the name of the node to be started + or communicated with. It is assumed that <c>Node</c> + is started with <c>erl -sname</c>, which means that + short node names are used. If option <c>-s</c> is specified, an Erlang node is started (if necessary) with - <c><![CDATA[erl -sname]]></c>.</p> + <c>erl -sname</c>.</p> </item> <tag><c>-v</c></tag> <item> - <p>(<em>Optional.</em>) Prints a lot of <c><![CDATA[verbose]]></c> + <p>(<em>Optional.</em>) Prints a lot of <c>verbose</c> information. This is only useful for the developer and maintainer - of <c><![CDATA[erl_call]]></c>.</p> + of <c>erl_call</c>.</p> </item> <tag><c>-x ErlScript</c></tag> <item> <p>(<em>Optional.</em>) Specifies another name of the Erlang startup script to be used. If not specified, the standard - <c><![CDATA[erl]]></c> startup script is used.</p> + <c>erl</c> startup script is used.</p> </item> </taglist> </desc> @@ -176,7 +176,7 @@ <section> <title>Examples</title> - <p>To start an Erlang node and call <c><![CDATA[erlang:time/0]]></c>:</p> + <p>To start an Erlang node and call <c>erlang:time/0</c>:</p> <code type="none"><![CDATA[ erl_call -s -a 'erlang time' -n madonna @@ -184,7 +184,7 @@ erl_call -s -a 'erlang time' -n madonna ]]></code> <p>To terminate an Erlang node by calling - <c><![CDATA[erlang:halt/0]]></c>:</p> + <c>erlang:halt/0</c>:</p> <code type="none"><![CDATA[ erl_call -s -a 'erlang halt' -n madonna diff --git a/lib/erl_interface/doc/src/erl_connect.xml b/lib/erl_interface/doc/src/erl_connect.xml index a6b9e586f4..76ef6588c2 100644 --- a/lib/erl_interface/doc/src/erl_connect.xml +++ b/lib/erl_interface/doc/src/erl_connect.xml @@ -59,10 +59,10 @@ <p>This function is used by a server process to accept a connection from a client process.</p> <list type="bulleted"> - <item><c><![CDATA[listensock]]></c> is an open socket descriptor on - which <c><![CDATA[listen()]]></c> has previously been called.</item> - <item><c><![CDATA[conp]]></c> is a pointer to an - <c><![CDATA[ErlConnect]]></c> struct, described as follows:</item> + <item><c>listensock</c> is an open socket descriptor on + which <c>listen()</c> has previously been called.</item> + <item><c>conp</c> is a pointer to an + <c>ErlConnect</c> struct, described as follows:</item> </list> <code type="none"><![CDATA[ typedef struct { @@ -70,10 +70,10 @@ typedef struct { char nodename[MAXNODELEN]; } ErlConnect; ]]></code> - <p>On success, <c><![CDATA[conp]]></c> is filled in with the address and + <p>On success, <c>conp</c> is filled in with the address and node name of the connecting client and a file descriptor is - returned. On failure, <c><![CDATA[ERL_ERROR]]></c> is returned and - <c><![CDATA[erl_errno]]></c> is set to <c><![CDATA[EIO]]></c>.</p> + returned. On failure, <c>ERL_ERROR</c> is returned and + <c>erl_errno</c> is set to <c>EIO</c>.</p> </desc> </func> @@ -85,9 +85,9 @@ typedef struct { </type> <desc> <p>Closes an open connection to an Erlang node.</p> - <p><c><![CDATA[Fd]]></c> is a file descriptor obtained from - <c><![CDATA[erl_connect()]]></c> or - <c><![CDATA[erl_xconnect()]]></c>.</p> + <p><c>Fd</c> is a file descriptor obtained from + <c>erl_connect()</c> or + <c>erl_xconnect()</c>.</p> <p>Returns <c>0</c> on success. If the call fails, a non-zero value is returned, and the reason for the error can be obtained with the appropriate platform-dependent call.</p> @@ -104,33 +104,33 @@ typedef struct { </type> <desc> <p>Sets up a connection to an Erlang node.</p> - <p><c><![CDATA[erl_xconnect()]]></c> requires the IP address of the + <p><c>erl_xconnect()</c> requires the IP address of the remote host and the alivename of the remote node to be - specified. <c><![CDATA[erl_connect()]]></c> provides an alternative + specified. <c>erl_connect()</c> provides an alternative interface, and determines the information from the node name provided.</p> <list type="bulleted"> - <item><c><![CDATA[addr]]></c> is the 32-bit IP address of the remote + <item><c>addr</c> is the 32-bit IP address of the remote host.</item> - <item><c><![CDATA[alive]]></c> is the alivename of the remote node. + <item><c>alive</c> is the alivename of the remote node. </item> - <item><c><![CDATA[node]]></c> is the name of the remote node.</item> + <item><c>node</c> is the name of the remote node.</item> </list> <p>Returns an open file descriptor on success, otherwise a negative - value. In the latter case <c><![CDATA[erl_errno]]></c> is set to one + value. In the latter case <c>erl_errno</c> is set to one of:</p> <taglist> - <tag><c><![CDATA[EHOSTUNREACH]]></c></tag> - <item>The remote host <c><![CDATA[node]]></c> is unreachable.</item> - <tag><c><![CDATA[ENOMEM]]></c></tag> + <tag><c>EHOSTUNREACH</c></tag> + <item>The remote host <c>node</c> is unreachable.</item> + <tag><c>ENOMEM</c></tag> <item>No more memory is available.</item> - <tag><c><![CDATA[EIO]]></c></tag> + <tag><c>EIO</c></tag> <item>I/O error.</item> </taglist> - <p>Also, <c><![CDATA[errno]]></c> values from - <c><![CDATA[socket]]></c><em>(2)</em> and - <c><![CDATA[connect]]></c><em>(2)</em> - system calls can be propagated into <c><![CDATA[erl_errno]]></c>.</p> + <p>Also, <c>errno</c> values from + <c>socket</c><em>(2)</em> and + <c>connect</c><em>(2)</em> + system calls can be propagated into <c>erl_errno</c>.</p> <p><em>Example:</em></p> <code type="none"><![CDATA[ #define NODE "[email protected]" @@ -160,69 +160,69 @@ erl_xconnect( &addr , ALIVE ); <v>struct in_addr *addr;</v> </type> <desc> - <p>Initializes the <c><![CDATA[erl_connect]]></c> module. + <p>Initializes the <c>erl_connect</c> module. In particular, these functions are used to identify the name of the C-node from which they are called. One of these functions must be called before any of the other functions in the <c>erl_connect</c> module are used.</p> - <p><c><![CDATA[erl_connect_xinit()]]></c> stores for later use + <p><c>erl_connect_xinit()</c> stores for later use information about:</p> <list type="bulleted"> - <item>Hostname of the node, <c><![CDATA[host]]></c></item> - <item>Alivename, <c><![CDATA[alive]]></c></item> - <item>Node name, <c><![CDATA[node]]></c></item> - <item>IP address, <c><![CDATA[addr]]></c></item> - <item>Cookie, <c><![CDATA[cookie]]></c></item> - <item>Creation number, <c><![CDATA[creation]]></c></item> + <item>Hostname of the node, <c>host</c></item> + <item>Alivename, <c>alive</c></item> + <item>Node name, <c>node</c></item> + <item>IP address, <c>addr</c></item> + <item>Cookie, <c>cookie</c></item> + <item>Creation number, <c>creation</c></item> </list> - <p><c><![CDATA[erl_connect_init()]]></c> + <p><c>erl_connect_init()</c> provides an alternative interface that does not require as much information from the caller. Instead, - <c><![CDATA[erl_connect_init()]]></c> - uses <c><![CDATA[gethostbyname()]]></c> to obtain default values.</p> - <p>If you use <c><![CDATA[erl_connect_init()]]></c>, your node will + <c>erl_connect_init()</c> + uses <c>gethostbyname()</c> to obtain default values.</p> + <p>If you use <c>erl_connect_init()</c>, your node will have a short name, that is, it will not be fully qualified. If you need to use fully qualified (long) names, use - <c><![CDATA[erl_connect_xinit()]]></c> instead.</p> + <c>erl_connect_xinit()</c> instead.</p> <list type="bulleted"> <item> - <p><c><![CDATA[host]]></c> is the name of the host on which the node + <p><c>host</c> is the name of the host on which the node is running.</p> </item> <item> - <p><c><![CDATA[alive]]></c> is the alivename of the node.</p> + <p><c>alive</c> is the alivename of the node.</p> </item> <item> - <p><c><![CDATA[node]]></c> is the node name. It is to + <p><c>node</c> is the node name. It is to be of the form <em>alivename@hostname</em>.</p> </item> <item> - <p><c><![CDATA[addr]]></c> is the 32-bit IP address of - <c><![CDATA[host]]></c>.</p> + <p><c>addr</c> is the 32-bit IP address of + <c>host</c>.</p> </item> <item> - <p><c><![CDATA[cookie]]></c> is the authorization string required + <p><c>cookie</c> is the authorization string required for access to the remote node. If <c>NULL</c>, the user <c>HOME</c> directory is searched for a cookie file - <c><![CDATA[.erlang.cookie]]></c>. The path to + <c>.erlang.cookie</c>. The path to the home directory is retrieved from environment variable - <c><![CDATA[HOME]]></c> on Unix and from the - <c><![CDATA[HOMEDRIVE]]></c> and - <c><![CDATA[HOMEPATH]]></c> variables on Windows. For more + <c>HOME</c> on Unix and from the + <c>HOMEDRIVE</c> and + <c>HOMEPATH</c> variables on Windows. For more details, see the <seealso marker="kernel:auth"> <c>auth</c></seealso> module in Kernel.</p> </item> <item> - <p><c><![CDATA[creation]]></c> helps identifying a particular + <p><c>creation</c> helps identifying a particular instance of a C-node. In particular, it can help prevent us from receiving messages sent to an earlier process with the same registered name.</p> </item> </list> <p>A C-node acting as a server is assigned a creation number - when it calls <c><![CDATA[erl_publish()]]></c>.</p> - <p><c><![CDATA[number]]></c> is used by - <c><![CDATA[erl_connect_init()]]></c> to + when it calls <c>erl_publish()</c>.</p> + <p><c>number</c> is used by + <c>erl_connect_init()</c> to construct the actual node name. In Example 2 below, <em>"[email protected]"</em> is the resulting node name.</p> <p><em>Example 1:</em></p> @@ -256,23 +256,23 @@ if (!erl_connect_init(17, "samplecookiestring...", 0)) with the local name server EPMD, thereby allowing other processes to send messages by using the registered name. Before calling this function, the process should - have called <c><![CDATA[bind()]]></c> and <c><![CDATA[listen()]]></c> + have called <c>bind()</c> and <c>listen()</c> on an open socket.</p> - <p><c><![CDATA[port]]></c> is the local name to register, and is to be + <p><c>port</c> is the local name to register, and is to be the same as the port number that was previously bound to the socket.</p> <p>To unregister with EPMD, simply close the returned descriptor.</p> <p>On success, a descriptor connecting the calling process to EPMD is returned. On failure, <c>-1</c> is returned and - <c><![CDATA[erl_errno]]></c> is set to:</p> + <c>erl_errno</c> is set to:</p> <taglist> - <tag><c><![CDATA[EIO]]></c></tag> + <tag><c>EIO</c></tag> <item>I/O error.</item> </taglist> - <p>Also, <c><![CDATA[errno]]></c> values from - <c><![CDATA[socket]]></c><em>(2)</em> - and <c><![CDATA[connect]]></c><em>(2)</em> system calls can be - propagated into <c><![CDATA[erl_errno]]></c>.</p> + <p>Also, <c>errno</c> values from + <c>socket</c><em>(2)</em> + and <c>connect</c><em>(2)</em> system calls can be + propagated into <c>erl_errno</c>.</p> </desc> </func> @@ -288,28 +288,28 @@ if (!erl_connect_init(17, "samplecookiestring...", 0)) <p>Receives a message consisting of a sequence of bytes in the Erlang external format.</p> <list type="bulleted"> - <item><c><![CDATA[fd]]></c> is an open descriptor to an Erlang + <item><c>fd</c> is an open descriptor to an Erlang connection.</item> - <item><c><![CDATA[bufp]]></c> is a buffer large enough to hold the + <item><c>bufp</c> is a buffer large enough to hold the expected message.</item> - <item><c><![CDATA[bufsize]]></c> indicates the size of - <c><![CDATA[bufp]]></c>.</item> + <item><c>bufsize</c> indicates the size of + <c>bufp</c>.</item> </list> <p>If a <em>tick</em> occurs, that is, the Erlang node on the other end of the connection has polled this node to see if it - is still alive, the function returns <c><![CDATA[ERL_TICK]]></c> and + is still alive, the function returns <c>ERL_TICK</c> and no message is placed in the buffer. Also, - <c><![CDATA[erl_errno]]></c> is set to <c><![CDATA[EAGAIN]]></c>.</p> + <c>erl_errno</c> is set to <c>EAGAIN</c>.</p> <p>On success, the message is placed in the specified buffer and the function returns the number of bytes actually read. On failure, the function returns a negative value and sets - <c><![CDATA[erl_errno]]></c> to one of:</p> + <c>erl_errno</c> to one of:</p> <taglist> - <tag><c><![CDATA[EAGAIN]]></c></tag> + <tag><c>EAGAIN</c></tag> <item>Temporary error: Try again.</item> - <tag><c><![CDATA[EMSGSIZE]]></c></tag> + <tag><c>EMSGSIZE</c></tag> <item>Buffer is too small.</item> - <tag><c><![CDATA[EIO]]></c></tag> + <tag><c>EIO</c></tag> <item>I/O error.</item> </taglist> </desc> @@ -326,18 +326,18 @@ if (!erl_connect_init(17, "samplecookiestring...", 0)) </type> <desc> <p>Receives the message into the specified buffer - and decodes into <c><![CDATA[(ErlMessage *) emsg]]></c>.</p> + and decodes into <c>(ErlMessage *) emsg</c>.</p> <list type="bulleted"> - <item><c><![CDATA[fd]]></c> is an open descriptor to an Erlang + <item><c>fd</c> is an open descriptor to an Erlang connection.</item> - <item><c><![CDATA[bufp]]></c> is a buffer large enough to hold the + <item><c>bufp</c> is a buffer large enough to hold the expected message.</item> - <item><c><![CDATA[bufsize]]></c> indicates the size of - <c><![CDATA[bufp]]></c>.</item> - <item>><c><![CDATA[emsg]]></c> is a pointer to an - <c><![CDATA[ErlMessage]]></c> structure + <item><c>bufsize</c> indicates the size of + <c>bufp</c>.</item> + <item>><c>emsg</c> is a pointer to an + <c>ErlMessage</c> structure into which the message will be decoded. - <c><![CDATA[ErlMessage]]></c> is defined as follows:</item> + <c>ErlMessage</c> is defined as follows:</item> </list> <code type="none"><![CDATA[ typedef struct { @@ -349,62 +349,62 @@ typedef struct { } ErlMessage; ]]></code> <note> - <p>The definition of <c><![CDATA[ErlMessage]]></c> has changed since + <p>The definition of <c>ErlMessage</c> has changed since earlier versions of <c>Erl_Interface</c>.</p> </note> - <p><c><![CDATA[type]]></c> identifies the type of message, one of the + <p><c>type</c> identifies the type of message, one of the following:</p> <taglist> - <tag><c><![CDATA[ERL_SEND]]></c></tag> + <tag><c>ERL_SEND</c></tag> <item> <p>An ordinary send operation has occurred and - <c><![CDATA[emsg->to]]></c> contains the pid of the recipient. - The message is in <c><![CDATA[emsg->msg]]></c>.</p> + <c>emsg->to</c> contains the pid of the recipient. + The message is in <c>emsg->msg</c>.</p> </item> - <tag><c><![CDATA[ERL_REG_SEND]]></c></tag> + <tag><c>ERL_REG_SEND</c></tag> <item> <p>A registered send operation has occurred and - <c><![CDATA[emsg->from]]></c> contains the pid of the sender. - The message is in <c><![CDATA[emsg->msg]]></c>.</p> + <c>emsg->from</c> contains the pid of the sender. + The message is in <c>emsg->msg</c>.</p> </item> - <tag><c><![CDATA[ERL_LINK]]></c> or <c><![CDATA[ERL_UNLINK]]></c> + <tag><c>ERL_LINK</c> or <c>ERL_UNLINK</c> </tag> <item> - <p><c><![CDATA[emsg->to]]></c> and <c><![CDATA[emsg->from]]></c> + <p><c>emsg->to</c> and <c>emsg->from</c> contain the pids of the sender and recipient of the link or - unlink. <c><![CDATA[emsg->msg]]></c> is not used.</p> + unlink. <c>emsg->msg</c> is not used.</p> </item> - <tag><c><![CDATA[ERL_EXIT]]></c></tag> + <tag><c>ERL_EXIT</c></tag> <item> - <p>A link is broken. <c><![CDATA[emsg->to]]></c> and - <c><![CDATA[emsg->from]]></c> contain the pids of the linked - processes, and <c><![CDATA[emsg->msg]]></c> contains the reason + <p>A link is broken. <c>emsg->to</c> and + <c>emsg->from</c> contain the pids of the linked + processes, and <c>emsg->msg</c> contains the reason for the exit.</p> </item> </taglist> <note> <p>It is the caller's responsibility to release the - memory pointed to by <c><![CDATA[emsg->msg]]></c>, - <c><![CDATA[emsg->to]]></c>, and - <c><![CDATA[emsg->from]]></c>.</p> + memory pointed to by <c>emsg->msg</c>, + <c>emsg->to</c>, and + <c>emsg->from</c>.</p> </note> <p>If a <em>tick</em> occurs, that is, the Erlang node on the other end of the connection has polled this node to see if it - is still alive, the function returns <c><![CDATA[ERL_TICK]]></c> + is still alive, the function returns <c>ERL_TICK</c> indicating that the tick has been received and responded to, but no message is placed in the buffer. In this case you - are to call <c><![CDATA[erl_receive_msg()]]></c> again.</p> - <p>On success, the function returns <c><![CDATA[ERL_MSG]]></c> and the - <c><![CDATA[Emsg]]></c> struct is initialized as described above, or - <c><![CDATA[ERL_TICK]]></c>, in which case no message is returned. On - failure, the function returns <c><![CDATA[ERL_ERROR]]></c> and sets - <c><![CDATA[erl_errno]]></c> to one of:</p> + are to call <c>erl_receive_msg()</c> again.</p> + <p>On success, the function returns <c>ERL_MSG</c> and the + <c>Emsg</c> struct is initialized as described above, or + <c>ERL_TICK</c>, in which case no message is returned. On + failure, the function returns <c>ERL_ERROR</c> and sets + <c>erl_errno</c> to one of:</p> <taglist> - <tag><c><![CDATA[EMSGSIZE]]></c></tag> + <tag><c>EMSGSIZE</c></tag> <item>Buffer is too small.</item> - <tag><c><![CDATA[ENOMEM]]></c></tag> + <tag><c>ENOMEM</c></tag> <item>No more memory is available.</item> - <tag><c><![CDATA[EIO]]></c></tag> + <tag><c>EIO</c></tag> <item>I/O error.</item> </taglist> </desc> @@ -421,18 +421,18 @@ typedef struct { <desc> <p>Sends an Erlang term to a registered process.</p> <list type="bulleted"> - <item><c><![CDATA[fd]]></c> is an open descriptor to an Erlang + <item><c>fd</c> is an open descriptor to an Erlang connection.</item> - <item><c><![CDATA[to]]></c> is a string containing the registered name + <item><c>to</c> is a string containing the registered name of the intended recipient of the message.</item> - <item><c><![CDATA[msg]]></c> is the Erlang term to be sent.</item> + <item><c>msg</c> is the Erlang term to be sent.</item> </list> <p>Returns <c>1</c> on success, otherwise <c>0</c>. In - the latter case <c><![CDATA[erl_errno]]></c> is set to one of:</p> + the latter case <c>erl_errno</c> is set to one of:</p> <taglist> - <tag><c><![CDATA[ENOMEM]]></c></tag> + <tag><c>ENOMEM</c></tag> <item>No more memory is available.</item> - <tag><c><![CDATA[EIO]]></c></tag> + <tag><c>EIO</c></tag> <item>I/O error.</item> </taglist> </desc> @@ -451,60 +451,60 @@ typedef struct { </type> <desc> <p>Supports calling Erlang functions on remote nodes. - <c><![CDATA[erl_rpc_to()]]></c> sends an RPC request to a remote node - and <c><![CDATA[erl_rpc_from()]]></c> receives the results of such a - call. <c><![CDATA[erl_rpc()]]></c> combines the functionality of + <c>erl_rpc_to()</c> sends an RPC request to a remote node + and <c>erl_rpc_from()</c> receives the results of such a + call. <c>erl_rpc()</c> combines the functionality of these two functions by sending an RPC request and waiting for the results. See also <seealso marker="kernel:rpc#call/4"> <c>rpc:call/4</c></seealso> in <c>Kernel</c>.</p> <list type="bulleted"> - <item><c><![CDATA[fd]]></c> is an open descriptor to an Erlang + <item><c>fd</c> is an open descriptor to an Erlang connection.</item> - <item><c><![CDATA[timeout]]></c> is the maximum time (in milliseconds) + <item><c>timeout</c> is the maximum time (in milliseconds) to wait for - results. To wait forever, specify <c><![CDATA[ERL_NO_TIMEOUT]]></c>. + results. To wait forever, specify <c>ERL_NO_TIMEOUT</c>. When <c>erl_rpc()</c> calls <c>erl_rpc_from()</c>, the call will never timeout.</item> - <item><c><![CDATA[mod]]></c> is the name of the module containing the + <item><c>mod</c> is the name of the module containing the function to be run on the remote node.</item> - <item><c><![CDATA[fun]]></c> is the name of the function to run. + <item><c>fun</c> is the name of the function to run. </item> - <item><c><![CDATA[args]]></c> is an Erlang list, containing the + <item><c>args</c> is an Erlang list, containing the arguments to be passed to the function.</item> - <item><c><![CDATA[emsg]]></c> is a message containing the result of + <item><c>emsg</c> is a message containing the result of the function call.</item> </list> <p>The actual message returned by the RPC server - is a 2-tuple <c><![CDATA[{rex,Reply}]]></c>. If you use - <c><![CDATA[erl_rpc_from()]]></c> in your code, this is the message - you will need to parse. If you use <c><![CDATA[erl_rpc()]]></c>, the + is a 2-tuple <c>{rex,Reply}</c>. If you use + <c>erl_rpc_from()</c> in your code, this is the message + you will need to parse. If you use <c>erl_rpc()</c>, the tuple itself is parsed for you, and the message returned to your - program is the Erlang term containing <c><![CDATA[Reply]]></c> only. + program is the Erlang term containing <c>Reply</c> only. Replies to RPC requests are always <c>ERL_SEND</c> messages.</p> <note> <p>It is the caller's responsibility to free the returned - <c><![CDATA[ETERM]]></c> structure and the memory pointed to by - <c><![CDATA[emsg->msg]]></c> and <c><![CDATA[emsg->to]]></c>.</p> + <c>ETERM</c> structure and the memory pointed to by + <c>emsg->msg</c> and <c>emsg->to</c>.</p> </note> - <p><c><![CDATA[erl_rpc()]]></c> returns the remote function's return - value on success, otherwise <c><![CDATA[NULL]]></c>.</p> - <p><c><![CDATA[erl_rpc_to()]]></c> returns <c>0</c> on + <p><c>erl_rpc()</c> returns the remote function's return + value on success, otherwise <c>NULL</c>.</p> + <p><c>erl_rpc_to()</c> returns <c>0</c> on success, otherwise a negative number.</p> - <p><c><![CDATA[erl_rcp_from()]]></c> returns <c><![CDATA[ERL_MSG]]></c> - on success (with <c><![CDATA[Emsg]]></c> now + <p><c>erl_rcp_from()</c> returns <c>ERL_MSG</c> + on success (with <c>Emsg</c> now containing the reply tuple), otherwise one of - <c><![CDATA[ERL_TICK]]></c>, <c><![CDATA[ERL_TIMEOUT]]></c>, or - <c><![CDATA[ERL_ERROR]]></c>.</p> + <c>ERL_TICK</c>, <c>ERL_TIMEOUT</c>, or + <c>ERL_ERROR</c>.</p> <p>When failing, - all three functions set <c><![CDATA[erl_errno]]></c> to one of:</p> + all three functions set <c>erl_errno</c> to one of:</p> <taglist> - <tag><c><![CDATA[ENOMEM]]></c></tag> + <tag><c>ENOMEM</c></tag> <item>No more memory is available.</item> - <tag><c><![CDATA[EIO]]></c></tag> + <tag><c>EIO</c></tag> <item>I/O error.</item> - <tag><c><![CDATA[ETIMEDOUT]]></c></tag> + <tag><c>ETIMEDOUT</c></tag> <item>Timeout has expired.</item> - <tag><c><![CDATA[EAGAIN]]></c></tag> + <tag><c>EAGAIN</c></tag> <item>Temporary error: Try again.</item> </taglist> </desc> @@ -520,21 +520,21 @@ typedef struct { <desc> <p>Sends an Erlang term to a process.</p> <list type="bulleted"> - <item><c><![CDATA[fd]]></c> is an open descriptor to an Erlang + <item><c>fd</c> is an open descriptor to an Erlang connection.</item> - <item><c><![CDATA[to]]></c> is an Erlang term containing the pid of + <item><c>to</c> is an Erlang term containing the pid of the intended recipient of the message.</item> - <item>><c><![CDATA[msg]]></c> is the Erlang term to be sent.</item> + <item>><c>msg</c> is the Erlang term to be sent.</item> </list> <p>Returns <c>1</c> on success, otherwise <c>0</c>. In - the latter case <c><![CDATA[erl_errno]]></c> is set to one of:</p> + the latter case <c>erl_errno</c> is set to one of:</p> <taglist> - <tag><c><![CDATA[EINVAL]]></c></tag> - <item>Invalid argument: <c><![CDATA[to]]></c> is not a valid Erlang + <tag><c>EINVAL</c></tag> + <item>Invalid argument: <c>to</c> is not a valid Erlang pid.</item> - <tag><c><![CDATA[ENOMEM]]></c></tag> + <tag><c>ENOMEM</c></tag> <item>No more memory is available.</item> - <tag><c><![CDATA[EIO]]></c></tag> + <tag><c>EIO</c></tag> <item>I/O error.</item> </taglist> </desc> @@ -550,8 +550,8 @@ typedef struct { <desc> <p>Retrieves information about the C-node. These values are initially set with - <c><![CDATA[erl_connect_init()]]></c> or - <c><![CDATA[erl_connect_xinit()]]></c>.</p> + <c>erl_connect_init()</c> or + <c>erl_connect_xinit()</c>.</p> </desc> </func> @@ -568,17 +568,17 @@ typedef struct { <c>-relaxed_command_check</c>, which it normally is not.</p> <p>To unregister a node you have published, you should instead close the descriptor that was returned by - <c><![CDATA[ei_publish()]]></c>.</p> + <c>ei_publish()</c>.</p> <warning> <p>This function is deprecated and will be removed in a future release.</p> </warning> - <p><c><![CDATA[alive]]></c> is the name of the node to unregister, that + <p><c>alive</c> is the name of the node to unregister, that is, the first component of the node name, without - <c><![CDATA[@hostname]]></c>.</p> + <c>@hostname</c>.</p> <p>If the node was successfully unregistered from EPMD, <c>0</c> is returned, otherwise <c>-1</c> is returned and - <c><![CDATA[erl_errno]]></c> is set to <c><![CDATA[EIO]]></c>.</p> + <c>erl_errno</c> is set to <c>EIO</c>.</p> </desc> </func> @@ -592,24 +592,24 @@ typedef struct { <v>ErlMessage *emsg;</v> </type> <desc> - <p>Similar to <c><![CDATA[erl_receive_msg]]></c>. The difference is - that <c><![CDATA[erl_xreceive_msg]]></c> expects the buffer to - have been allocated by <c><![CDATA[malloc]]></c>, and reallocates it + <p>Similar to <c>erl_receive_msg</c>. The difference is + that <c>erl_xreceive_msg</c> expects the buffer to + have been allocated by <c>malloc</c>, and reallocates it if the received message does not fit into the original buffer. Therefore both buffer and buffer length are given as pointers; their values can change by the call.</p> - <p>On success, the function returns <c><![CDATA[ERL_MSG]]></c> and the - <c><![CDATA[Emsg]]></c> struct is initialized as described above, or - <c><![CDATA[ERL_TICK]]></c>, in which case no message is returned. On - failure, the function returns <c><![CDATA[ERL_ERROR]]></c> and sets - <c><![CDATA[erl_errno]]></c> to one of:</p> + <p>On success, the function returns <c>ERL_MSG</c> and the + <c>Emsg</c> struct is initialized as described above, or + <c>ERL_TICK</c>, in which case no message is returned. On + failure, the function returns <c>ERL_ERROR</c> and sets + <c>erl_errno</c> to one of:</p> <taglist> - <tag><c><![CDATA[EMSGSIZE]]></c></tag> + <tag><c>EMSGSIZE</c></tag> <item>Buffer is too small.</item> - <tag><c><![CDATA[ENOMEM]]></c></tag> + <tag><c>ENOMEM</c></tag> <item>No more memory is available.</item> - <tag><c><![CDATA[EIO]]></c></tag> + <tag><c>EIO</c></tag> <item>I/O error.</item> </taglist> </desc> @@ -643,11 +643,11 @@ typedef struct { <p>If a connection attempt fails, the following can be checked:</p> <list type="bulleted"> - <item><c><![CDATA[erl_errno]]></c></item> + <item><c>erl_errno</c></item> <item>That the correct cookie was used</item> <item>That EPMD is running</item> <item>That the remote Erlang node on the other side is running the same - version of Erlang as the <c><![CDATA[erl_interface]]></c> library</item> + version of Erlang as the <c>erl_interface</c> library</item> </list> </section> </cref> diff --git a/lib/erl_interface/doc/src/erl_error.xml b/lib/erl_interface/doc/src/erl_error.xml index a85969d7ff..8139c9b343 100644 --- a/lib/erl_interface/doc/src/erl_error.xml +++ b/lib/erl_interface/doc/src/erl_error.xml @@ -40,9 +40,9 @@ by W. Richard Stevens.</p> <p>These functions are all called in the same manner as - <c><![CDATA[printf()]]></c>, that is, with a string containing format + <c>printf()</c>, that is, with a string containing format specifiers followed by a list of corresponding arguments. All output from - these functions is to <c><![CDATA[stderr]]></c>.</p> + these functions is to <c>stderr</c>.</p> </description> <funcs> @@ -54,7 +54,7 @@ </type> <desc> <p>The message provided by the caller is printed. This - function is simply a wrapper for <c><![CDATA[fprintf()]]></c>.</p> + function is simply a wrapper for <c>fprintf()</c>.</p> </desc> </func> @@ -105,37 +105,37 @@ <title>Error Reporting</title> <p>Most functions in <c>Erl_Interface</c> report failures to the caller by returning some otherwise meaningless value (typically - <c><![CDATA[NULL]]></c> + <c>NULL</c> or a negative number). As this only tells you that things did not - go well, examine the error code in <c><![CDATA[erl_errno]]></c> if you + go well, examine the error code in <c>erl_errno</c> if you want to find out more about the failure.</p> </section> <funcs> <func> <name><ret>volatile int</ret><nametext>erl_errno</nametext></name> - <fsummary>Variable <c><![CDATA[erl_errno]]></c> contains the + <fsummary>Variable <c>erl_errno</c> contains the Erl_Interface error number. You can change the value if you wish. </fsummary> <desc> - <p><c><![CDATA[erl_errno]]></c> is initially (at program startup) zero + <p><c>erl_errno</c> is initially (at program startup) zero and is then set by many <c>Erl_Interface</c> functions on failure to a non-zero error code to indicate what kind of error it encountered. A successful function call can change - <c><![CDATA[erl_errno]]></c> (by calling some other function that + <c>erl_errno</c> (by calling some other function that fails), but no function does never set it to zero. This means - that you cannot use <c><![CDATA[erl_errno]]></c> to see <em>if</em> a + that you cannot use <c>erl_errno</c> to see <em>if</em> a function call failed. Instead, each function reports failure in its own way (usually by returning a negative number or - <c><![CDATA[NULL]]></c>), in which case you can examine - <c><![CDATA[erl_errno]]></c> for details.</p> - <p><c><![CDATA[erl_errno]]></c> uses the error codes defined in your - system's <c><![CDATA[<errno.h>]]></c>.</p> + <c>NULL</c>), in which case you can examine + <c>erl_errno</c> for details.</p> + <p><c>erl_errno</c> uses the error codes defined in your + system's <c><errno.h></c>.</p> <note> - <p><c><![CDATA[erl_errno]]></c> is a "modifiable lvalue" (just - like ISO C defines <c><![CDATA[errno]]></c> to be) rather than a + <p><c>erl_errno</c> is a "modifiable lvalue" (just + like ISO C defines <c>errno</c> to be) rather than a variable. This means it can be implemented as a macro - (expanding to, for example, <c><![CDATA[*_erl_errno()]]></c>). + (expanding to, for example, <c>*_erl_errno()</c>). For reasons of thread safety (or task safety), this is exactly what we do on most platforms.</p> </note> diff --git a/lib/erl_interface/doc/src/erl_eterm.xml b/lib/erl_interface/doc/src/erl_eterm.xml index e619232e4c..9a05196a70 100644 --- a/lib/erl_interface/doc/src/erl_eterm.xml +++ b/lib/erl_interface/doc/src/erl_eterm.xml @@ -39,7 +39,7 @@ 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 + <c>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 use the macros and functions provided.</p> @@ -49,31 +49,31 @@ 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> - <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 + <tag><c>ERL_IS_INTEGER(t)</c></tag> + <item>True if <c>t</c> is an integer.</item> + <tag><c>ERL_IS_UNSIGNED_INTEGER(t)</c></tag> + <item>True if <c>t</c> is an integer.</item> + <tag><c>ERL_IS_FLOAT(t)</c></tag> + <item>True if <c>t</c> is a floating point number.</item> + <tag><c>ERL_IS_ATOM(t)</c></tag> + <item>True if <c>t</c> is an atom.</item> + <tag><c>ERL_IS_PID(t)</c></tag> + <item>True if <c>t</c> is a pid (process identifier).</item> + <tag><c>ERL_IS_PORT(t)</c></tag> + <item>True if <c>t</c> is a port.</item> + <tag><c>ERL_IS_REF(t)</c></tag> + <item>True if <c>t</c> is a reference.</item> + <tag><c>ERL_IS_TUPLE(t)</c></tag> + <item>True if <c>t</c> is a tuple.</item> + <tag><c>ERL_IS_BINARY(t)</c></tag> + <item>True if <c>t</c> is a binary.</item> + <tag><c>ERL_IS_LIST(t)</c></tag> + <item>True if <c>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 + <tag><c>ERL_IS_EMPTY_LIST(t)</c></tag> + <item>True if <c>t</c> is an empty list.</item> + <tag><c>ERL_IS_CONS(t)</c></tag> + <item>True if <c>t</c> is a list with at least one element.</item> </taglist> @@ -83,60 +83,60 @@ 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> + <tag><c>char *ERL_ATOM_PTR(t)</c></tag> <item></item> - <tag><c><![CDATA[char *ERL_ATOM_PTR_UTF8(t)]]></c></tag> - <item>A string representing atom <c><![CDATA[t]]></c>.</item> - <tag><c><![CDATA[int ERL_ATOM_SIZE(t)]]></c></tag> + <tag><c>char *ERL_ATOM_PTR_UTF8(t)</c></tag> + <item>A string representing atom <c>t</c>.</item> + <tag><c>int ERL_ATOM_SIZE(t)</c></tag> <item></item> - <tag><c><![CDATA[int ERL_ATOM_SIZE_UTF8(t)]]></c></tag> - <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> - <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> + <tag><c>int ERL_ATOM_SIZE_UTF8(t)</c></tag> + <item>The length (in bytes) of atom <c>t</c>.</item> + <tag><c>void *ERL_BIN_PTR(t)</c></tag> + <item>A pointer to the contents of <c>t</c>.</item> + <tag><c>int ERL_BIN_SIZE(t)</c></tag> + <item>The length (in bytes) of binary object <c>t</c>.</item> + <tag><c>int ERL_INT_VALUE(t)</c></tag> + <item>The integer of <c>t</c>.</item> + <tag><c>unsigned int ERL_INT_UVALUE(t)</c></tag> + <item>The unsigned integer value of <c>t</c>.</item> + <tag><c>double ERL_FLOAT_VALUE(t)</c></tag> + <item>The floating point value of <c>t</c>.</item> + <tag><c>ETERM *ERL_PID_NODE(t)</c></tag> <item></item> - <tag><c><![CDATA[ETERM *ERL_PID_NODE_UTF8(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> + <tag><c>ETERM *ERL_PID_NODE_UTF8(t)</c></tag> + <item>The node in pid <c>t</c>.</item> + <tag><c>int ERL_PID_NUMBER(t)</c></tag> + <item>The sequence number in pid <c>t</c>.</item> + <tag><c>int ERL_PID_SERIAL(t)</c></tag> + <item>The serial number in pid <c>t</c>.</item> + <tag><c>int ERL_PID_CREATION(t)</c></tag> + <item>The creation number in pid <c>t</c>.</item> + <tag><c>int ERL_PORT_NUMBER(t)</c></tag> + <item>The sequence number in port <c>t</c>.</item> + <tag><c>int ERL_PORT_CREATION(t)</c></tag> + <item>The creation number in port <c>t</c>.</item> + <tag><c>ETERM *ERL_PORT_NODE(t)</c></tag> <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>. + <tag><c>ETERM *ERL_PORT_NODE_UTF8(t)</c></tag> + <item>The node in port <c>t</c>.</item> + <tag><c>int ERL_REF_NUMBER(t)</c></tag> + <item>The first part of the reference number in ref <c>t</c>. Use only for compatibility.</item> - <tag><c><![CDATA[int ERL_REF_NUMBERS(t)]]></c></tag> + <tag><c>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> + <c>t</c>.</item> + <tag><c>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> + <c>t</c>.</item> + <tag><c>int ERL_REF_CREATION(t)</c></tag> + <item>The creation number in ref <c>t</c>.</item> + <tag><c>int ERL_TUPLE_SIZE(t)</c></tag> + <item>The number of elements in tuple <c>t</c>.</item> + <tag><c>ETERM *ERL_CONS_HEAD(t)</c></tag> + <item>The head element of list <c>t</c>.</item> + <tag><c>ETERM *ERL_CONS_TAIL(t)</c></tag> <item>A list representing the tail elements of list - <c><![CDATA[t]]></c>.</item> + <c>t</c>.</item> </taglist> </description> @@ -149,22 +149,22 @@ <v>ETERM *tail;</v> </type> <desc> - <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 + <p>Concatenates two Erlang terms, prepending <c>head</c> + onto <c>tail</c> and thereby creating a + <c>cons</c> cell. + To make a proper list, <c>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> + <item><c>head</c> is the new term to be added.</item> + <item><c>tail</c> is the existing list to which + <c>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>ERL_CONS_HEAD(list)</c> and + <c>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> do + from the list. <c>erl_hd(list)</c> and + <c>erl_tl(list)</c> do the same thing, but check that the argument really is a list.</p> <p><em>Example:</em></p> <code type="none"><![CDATA[ @@ -188,7 +188,7 @@ erl_free_compound(list); </type> <desc> <p>Creates and returns a copy of the Erlang term - <c><![CDATA[term]]></c>.</p> + <c>term</c>.</p> </desc> </func> @@ -202,15 +202,15 @@ erl_free_compound(list); <desc> <p>Extracts a specified element from an Erlang tuple.</p> <list type="bulleted"> - <item><c><![CDATA[position]]></c> specifies which element to retrieve - from <c><![CDATA[tuple]]></c>. The elements are numbered starting + <item><c>position</c> specifies which element to retrieve + from <c>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> + <item><c>tuple</c> is an Erlang term containing at least + <c>position</c> elements.</item> </list> <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> + <c>NULL</c> if <c>position</c> was greater + than the arity of <c>tuple</c>.</p> </desc> </func> @@ -222,10 +222,10 @@ erl_free_compound(list); </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><c>list</c> is an Erlang term containing 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> + <c>list</c> was not a list.</p> </desc> </func> @@ -238,9 +238,9 @@ erl_free_compound(list); </type> <desc> <p>This function must be called before any of the others in the - <c><![CDATA[Erl_Interface]]></c> library to initialize the + <c>Erl_Interface</c> library to initialize the library functions. The arguments must be specified as - <c><![CDATA[erl_init(NULL,0)]]></c>.</p> + <c>erl_init(NULL,0)</c>.</p> </desc> </func> @@ -252,9 +252,9 @@ erl_free_compound(list); </type> <desc> <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><c>list</c> is an Erlang term containing an I/O list.</p> + <p>Returns the length of <c>list</c>, or + <c>-1</c> if <c>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> @@ -269,9 +269,9 @@ erl_free_compound(list); </type> <desc> <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><c>list</c> is an Erlang term containing a list.</p> <p>Returns an Erlang binary term, or <c>NULL</c> if - <c><![CDATA[list]]></c> was not an I/O list.</p> + <c>list</c> was not an I/O list.</p> <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> @@ -296,15 +296,15 @@ iohead ::= Binary </type> <desc> <p>Converts an I/O list to a <c>NULL</c>-terminated C string.</p> - <p><c><![CDATA[list]]></c> is an Erlang term containing an I/O list. + <p><c>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>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, + buffer containing a string. If <c>list</c> is not an I/O + list, or if <c>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> + with <c>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> @@ -319,10 +319,10 @@ iohead ::= Binary </type> <desc> <p>Determines the length of a proper list.</p> - <p><c><![CDATA[list]]></c> is an Erlang term containing a proper list. + <p><c>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 <c>-1</c> if <c><![CDATA[list]]></c> is not a proper + <p>Returns <c>-1</c> if <c>list</c> is not a proper list.</p> </desc> </func> @@ -335,16 +335,16 @@ iohead ::= Binary </type> <desc> <p>Creates an atom.</p> - <p><c><![CDATA[string]]></c> is the sequence of characters that will be + <p><c>string</c> is the sequence of characters that will be used to create the atom.</p> <p>Returns an Erlang term containing an atom. Notice that it is - the caller's responsibility to ensure that <c><![CDATA[string]]></c> + the caller's responsibility to ensure that <c>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> + <p><c>ERL_ATOM_PTR(atom)</c> and + <c>ERL_ATOM_PTR_UTF8(atom)</c> can be used to retrieve the atom name (as a <c>NULL</c>-terminated string). - <c><![CDATA[ERL_ATOM_SIZE(atom)]]></c> - and <c><![CDATA[ERL_ATOM_SIZE_UTF8(atom)]]></c> return the length + <c>ERL_ATOM_SIZE(atom)</c> + and <c>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 @@ -365,14 +365,14 @@ iohead ::= Binary <p>Produces an Erlang binary object from a buffer containing a sequence of bytes.</p> <list type="bulleted"> - <item><c><![CDATA[bptr]]></c> is a pointer to a buffer containing + <item><c>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> + <item><c>size</c> indicates the length of + <c>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 + <p><c>ERL_BIN_PTR(bin)</c> retrieves a pointer to + the binary data. <c>ERL_BIN_SIZE(bin)</c> retrieves the size.</p> </desc> </func> @@ -397,13 +397,13 @@ iohead ::= Binary <desc> <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 + <item><c>string</c> is a buffer containing a sequence of bytes. The buffer does not need to be <c>NULL</c>-terminated.</item> - <item><c><![CDATA[len]]></c> is the length of - <c><![CDATA[string]]></c>.</item> + <item><c>len</c> is the length of + <c>string</c>.</item> </list> <p>Returns an Erlang list object corresponding to - the character sequence in <c><![CDATA[string]]></c>.</p> + the character sequence in <c>string</c>.</p> </desc> </func> @@ -415,12 +415,12 @@ iohead ::= Binary </type> <desc> <p>Creates an Erlang float.</p> - <p><c><![CDATA[f]]></c> is a value to be converted to an Erlang + <p><c>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 + specified in <c>f</c> or <c>NULL</c> if + <c>f</c> is not finite.</p> + <p><c>ERL_FLOAT_VALUE(t)</c> can be used to retrieve the value from an Erlang float.</p> </desc> </func> @@ -433,11 +433,11 @@ iohead ::= Binary </type> <desc> <p>Creates an Erlang integer.</p> - <p><c><![CDATA[n]]></c> is a value to be converted to an Erlang + <p><c>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 specified in <c>n</c>.</p> + <p><c>ERL_INT_VALUE(t)</c> can be used to retrieve the value from an Erlang integer.</p> </desc> </func> @@ -454,13 +454,13 @@ iohead ::= Binary that each element in the list corresponds to one element in 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> + <item><c>array</c> is an array of Erlang terms.</item> + <item><c>arrsize</c> is the number of elements in + <c>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>arrsize</c> and whose elements are taken from the + terms in <c>array</c>.</p> </desc> </func> @@ -475,21 +475,21 @@ iohead ::= Binary <desc> <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 + <item><c>node</c> is the name of the C-node.</item> + <item><c>n1</c>, <c>n2</c>, and + <c>n3</c> can be seen as one big number + <c>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> + <item><c>creation</c> is an arbitrary number.</item> </list> - <p>Notice that <c><![CDATA[n3]]></c> and <c><![CDATA[creation]]></c> + <p>Notice that <c>n3</c> and <c>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 + <p><c>ERL_REF_NODE(ref)</c>, + <c>ERL_REF_NUMBERS(ref)</c>, + <c>ERL_REF_LEN(ref)</c>, and + <c>ERL_REF_CREATION(ref)</c> can be used to retrieve the values used to create the reference.</p> </desc> </func> @@ -508,18 +508,18 @@ iohead ::= Binary resulting pid can be used by Erlang processes wishing to 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 + <item><c>node</c> is the name of the C-node.</item> + <item><c>number</c>, <c>serial</c>, and + <c>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> + <p><c>ERL_PID_NODE(pid)</c>, + <c>ERL_PID_NUMBER(pid)</c>, + <c>ERL_PID_SERIAL(pid)</c>, and + <c>ERL_PID_CREATION(pid)</c> can be used to retrieve the four values used to create the pid.</p> </desc> </func> @@ -535,16 +535,16 @@ iohead ::= Binary <desc> <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 + <item><c>node</c> is the name of the C-node.</item> + <item><c>number</c> and <c>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 + <p><c>ERL_PORT_NODE(port)</c>, + <c>ERL_PORT_NUMBER(port)</c>, + and <c>ERL_PORT_CREATION</c> can be used to retrieve the three values used to create the port.</p> </desc> </func> @@ -559,20 +559,20 @@ iohead ::= Binary </type> <desc> <p>Creates an old Erlang reference, with - only 18 bits - use <c><![CDATA[erl_mk_long_ref]]></c> instead.</p> + only 18 bits - use <c>erl_mk_long_ref</c> instead.</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 + <item><c>node</c> is the name of the C-node.</item> + <item><c>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> + <item><c>creation</c> is an arbitrary number.</item> </list> - <p>Notice that <c><![CDATA[number]]></c> and <c><![CDATA[creation]]></c> + <p>Notice that <c>number</c> and <c>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 + <p><c>ERL_REF_NODE(ref)</c>, + <c>ERL_REF_NUMBER(ref)</c>, and + <c>ERL_REF_CREATION(ref)</c> can be used to retrieve the three values used to create the reference.</p> </desc> </func> @@ -585,7 +585,7 @@ iohead ::= Binary </type> <desc> <p>Creates a list from a <c>NULL</c>-terminated string.</p> - <p><c><![CDATA[string]]></c> is a <c>NULL</c>-terminated sequence of + <p><c>string</c> is a <c>NULL</c>-terminated sequence of characters (that is, a C string) from which the list will be created.</p> <p>Returns an Erlang list.</p> @@ -602,20 +602,20 @@ iohead ::= Binary <desc> <p>Creates an Erlang tuple from an array of Erlang terms.</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> + <item><c>array</c> is an array of Erlang terms.</item> + <item><c>arrsize</c> is the number of elements in + <c>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> + <c>size</c> and whose elements are taken from the terms + in <c>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 + <c>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> does the same thing, but it checks + <c>ERL_TUPLE_SIZE(tuple)</c> returns the arity of a tuple. + <c>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 + <c>erl_element(index,tuple)</c> returns the element corresponding to a given position in the tuple.</p> </desc> </func> @@ -628,11 +628,11 @@ iohead ::= Binary </type> <desc> <p>Creates an Erlang unsigned integer.</p> - <p><c><![CDATA[n]]></c> is a value to be converted to an Erlang + <p><c>n</c> is a value to be converted to an Erlang unsigned integer.</p> <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 + the value specified in <c>n</c>.</p> + <p><c>ERL_INT_UVALUE(t)</c> can be used to retrieve the value from an Erlang unsigned integer.</p> </desc> </func> @@ -646,9 +646,9 @@ iohead ::= Binary <desc> <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><c>name</c> specifies a name for the variable.</p> <p>Returns an Erlang variable object with the - name <c><![CDATA[name]]></c>.</p> + name <c>name</c>.</p> </desc> </func> @@ -662,9 +662,9 @@ iohead ::= Binary <desc> <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 + <item><c>stream</c> indicates where the function is to send its output.</item> - <item><c><![CDATA[term]]></c> is the Erlang term to print.</item> + <item><c>term</c> is the Erlang term to print.</item> </list> <p>Returns the number of characters written on success, otherwise a negative value.</p> @@ -678,16 +678,16 @@ iohead ::= Binary <v>unsigned release_number;</v> </type> <desc> - <p>By default, the <c><![CDATA[Erl_Interface]]></c> library is only + <p>By default, the <c>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 + same release as the <c>Erl_Interface</c> library itself. + For example, <c>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> + <p>A call to <c>erl_set_compat_rel(release_number)</c> sets + the <c>Erl_Interface</c> library in compatibility mode of + release <c>release_number</c>. Valid range of + <c>release_number</c> is [7, current release]. This makes it possible to communicate with Erlang/OTP components from earlier releases.</p> <note> @@ -714,10 +714,10 @@ iohead ::= Binary <desc> <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 + <p><c>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 + <p>Returns the size of <c>term</c> as described + above, or <c>-1</c> if <c>term</c> is not one of the two supported types.</p> </desc> </func> @@ -730,10 +730,10 @@ iohead ::= Binary </type> <desc> <p>Extracts the tail from a list.</p> - <p><c><![CDATA[list]]></c> is an Erlang term containing a list.</p> + <p><c>list</c> is an Erlang term containing a list.</p> <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> + <c>list</c> was not a list.</p> </desc> </func> @@ -747,19 +747,19 @@ iohead ::= Binary <desc> <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 + <item><c>term</c> is an Erlang term. In order for this function to succeed, - <c><![CDATA[term]]></c> must either be an Erlang variable with + <c>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><c>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> is found in - <c><![CDATA[term]]></c>, or if <c><![CDATA[term]]></c> is + <c>name</c> in <c>term</c>. If no variable + with the name <c>name</c> is found in + <c>term</c>, or if <c>term</c> is not a valid Erlang term, <c>NULL</c> is returned.</p> </desc> </func> diff --git a/lib/erl_interface/doc/src/erl_format.xml b/lib/erl_interface/doc/src/erl_format.xml index f6f27326ff..5b8b7b5e78 100644 --- a/lib/erl_interface/doc/src/erl_format.xml +++ b/lib/erl_interface/doc/src/erl_format.xml @@ -49,8 +49,8 @@ <desc> <p>A general function for creating Erlang terms using a format specifier and a corresponding set of arguments, much - in the way <c><![CDATA[printf()]]></c> works.</p> - <p><c><![CDATA[FormatStr]]></c> is a format specification string. + in the way <c>printf()</c> works.</p> + <p><c>FormatStr</c> is a format specification string. The valid format specifiers are as follows:</p> <list type="bulleted"> <item><c>~i</c> - Integer</item> @@ -59,10 +59,10 @@ <item><c>~s</c> - String</item> <item><c>~w</c> - Arbitrary Erlang term</item> </list> - <p>For each format specifier included in <c><![CDATA[FormatStr]]></c>, + <p>For each format specifier included in <c>FormatStr</c>, there must be a corresponding argument following - <c><![CDATA[FormatStr]]></c>. An Erlang term is built according to - <c><![CDATA[FormatStr]]></c> with values and Erlang terms substituted + <c>FormatStr</c>. An Erlang term is built according to + <c>FormatStr</c> with values and Erlang terms substituted from the corresponding arguments, and according to the individual format specifiers. For example:</p> <code type="none"><![CDATA[ @@ -71,11 +71,11 @@ erl_format("[{name,~a},{age,~i},{data,~w}]", 21, erl_format("[{adr,~s,~i}]","E-street",42)); ]]></code> - <p>This creates an <c><![CDATA[(ETERM *)]]></c> structure corresponding + <p>This creates an <c>(ETERM *)</c> structure corresponding to the Erlang term - <c><![CDATA[[{name,madonna},{age,21},{data,[{adr,"E-street",42}]}]]]></c></p> + <c>[{name,madonna},{age,21},{data,[{adr,"E-street",42}]}]</c></p> <p>The function returns an Erlang term, or <c>NULL</c> if - <c><![CDATA[FormatStr]]></c> does not describe a valid Erlang + <c>FormatStr</c> does not describe a valid Erlang term.</p> </desc> </func> @@ -92,18 +92,18 @@ erl_format("[{name,~a},{age,~i},{data,~w}]", section <seealso marker="doc/reference_manual:patterns"> Pattern Matching</seealso> in the Erlang Reference Manual.</p> <list type="bulleted"> - <item><c><![CDATA[Pattern]]></c> is an Erlang term, possibly + <item><c>Pattern</c> is an Erlang term, possibly containing unbound variables.</item> - <item><c><![CDATA[Term]]></c> is an Erlang term that we wish to match - against <c><![CDATA[Pattern]]></c>.</item> + <item><c>Term</c> is an Erlang term that we wish to match + against <c>Pattern</c>.</item> </list> - <p><c><![CDATA[Term]]></c> and <c><![CDATA[Pattern]]></c> are compared - and any unbound variables in <c><![CDATA[Pattern]]></c> are bound to - corresponding values in <c><![CDATA[Term]]></c>.</p> - <p>If <c><![CDATA[Term]]></c> and <c><![CDATA[Pattern]]></c> can be + <p><c>Term</c> and <c>Pattern</c> are compared + and any unbound variables in <c>Pattern</c> are bound to + corresponding values in <c>Term</c>.</p> + <p>If <c>Term</c> and <c>Pattern</c> can be matched, the function returns a non-zero value and binds any unbound - variables in <c><![CDATA[Pattern]]></c>. If <c><![CDATA[Term]]></c> - and <c><![CDATA[Pattern]]></c> do + variables in <c>Pattern</c>. If <c>Term</c> + and <c>Pattern</c> do not match, <c>0</c> is returned. For example:</p> <code type="none"><![CDATA[ ETERM *term, *pattern, *pattern2; @@ -129,9 +129,9 @@ if (erl_match(pattern2, term2)) { ... } ]]></code> - <p><c><![CDATA[erl_var_content()]]></c> can be used to retrieve the + <p><c>erl_var_content()</c> can be used to retrieve the content of any variables bound as a result of a call to - <c><![CDATA[erl_match()]]></c>.</p> + <c>erl_match()</c>.</p> </desc> </func> </funcs> diff --git a/lib/erl_interface/doc/src/erl_global.xml b/lib/erl_interface/doc/src/erl_global.xml index 0808ea0eee..2fa0045adf 100644 --- a/lib/erl_interface/doc/src/erl_global.xml +++ b/lib/erl_interface/doc/src/erl_global.xml @@ -57,23 +57,23 @@ <desc> <p>Retrieves a list of all known global names.</p> <list type="bulleted"> - <item><c><![CDATA[fd]]></c> is an open descriptor to an Erlang + <item><c>fd</c> is an open descriptor to an Erlang connection.</item> - <item><c><![CDATA[count]]></c> is the address of an integer, or - <c>NULL</c>. If <c><![CDATA[count]]></c> is not <c>NULL</c>, it is + <item><c>count</c> is the address of an integer, or + <c>NULL</c>. If <c>count</c> is not <c>NULL</c>, it is set by the function to the number of names found.</item> </list> <p>On success, the function returns an array of strings, each containing a single registered name, and sets - <c><![CDATA[count]]></c> to + <c>count</c> to the number of names found. The array is terminated by a single <c>NULL</c> pointer. On failure, the function returns - <c>NULL</c> and <c><![CDATA[count]]></c> is not modified.</p> + <c>NULL</c> and <c>count</c> is not modified.</p> <note> <p>It is the caller's responsibility to free the array afterwards. It has been allocated by the function with a - single call to <c><![CDATA[malloc()]]></c>, so a single - <c><![CDATA[free()]]></c> is all that is necessary.</p> + single call to <c>malloc()</c>, so a single + <c>free()</c> is all that is necessary.</p> </note> </desc> </func> @@ -89,13 +89,13 @@ <desc> <p>Registers a name in <c>global</c>.</p> <list type="bulleted"> - <item><c><![CDATA[fd]]></c> is an open descriptor to an Erlang + <item><c>fd</c> is an open descriptor to an Erlang connection.</item> - <item><c><![CDATA[name]]></c> is the name to register in + <item><c>name</c> is the name to register in <c>global</c>.</item> - <item><c><![CDATA[pid]]></c> is the pid that is to be associated with - <c><![CDATA[name]]></c>. This value is returned by <c>global</c> - when processes request the location of <c><![CDATA[name]]></c>. + <item><c>pid</c> is the pid that is to be associated with + <c>name</c>. This value is returned by <c>global</c> + when processes request the location of <c>name</c>. </item> </list> <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> @@ -112,9 +112,9 @@ <desc> <p>Unregisters a name from <c>global</c>.</p> <list type="bulleted"> - <item><c><![CDATA[fd]]></c> is an open descriptor to an Erlang + <item><c>fd</c> is an open descriptor to an Erlang connection.</item> - <item><c><![CDATA[name]]></c> is the name to unregister from + <item><c>name</c> is the name to unregister from <c>global</c>.</item> </list> <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> @@ -132,19 +132,19 @@ <desc> <p>Looks up a name in <c>global</c>.</p> <list type="bulleted"> - <item><c><![CDATA[fd]]></c> is an open descriptor to an Erlang + <item><c>fd</c> is an open descriptor to an Erlang connection.</item> - <item><c><![CDATA[name]]></c> is the name that is to be looked up in + <item><c>name</c> is the name that is to be looked up in <c>global</c>.</item> </list> - <p>If <c><![CDATA[node]]></c> is not <c>NULL</c>, it is a pointer to a + <p>If <c>node</c> is not <c>NULL</c>, it is a pointer to a buffer where the function can fill in the name of the node where - <c><![CDATA[name]]></c> is found. <c><![CDATA[node]]></c> can be - passed directly to <c><![CDATA[erl_connect()]]></c> if necessary.</p> + <c>name</c> is found. <c>node</c> can be + passed directly to <c>erl_connect()</c> if necessary.</p> <p>On success, the function returns an Erlang pid containing the address of the specified name, and the node is initialized to - the node name where <c><![CDATA[name]]></c> is found. On failure, - <c>NULL</c> is returned and <c><![CDATA[node]]></c> is not + the node name where <c>name</c> is found. On failure, + <c>NULL</c> is returned and <c>node</c> is not modified.</p> </desc> </func> diff --git a/lib/erl_interface/doc/src/erl_interface.xml b/lib/erl_interface/doc/src/erl_interface.xml index ab5b46cc01..4e66655b39 100644 --- a/lib/erl_interface/doc/src/erl_interface.xml +++ b/lib/erl_interface/doc/src/erl_interface.xml @@ -72,51 +72,51 @@ Eshell V4.7.4 (abort with ^G) 1> code:root_dir(). /usr/local/otp ]]></code> <p>To compile your code, make sure that your C compiler knows where - to find <c><![CDATA[erl_interface.h]]></c> by specifying an appropriate <c><![CDATA[-I]]></c> - argument on the command line, or by adding it to the <c><![CDATA[CFLAGS]]></c> - definition in your <c><![CDATA[Makefile]]></c>. The correct value for this path is - <c><![CDATA[$OTPROOT/lib/erl_interface]]></c><em>Vsn</em><c><![CDATA[/include]]></c>, where <c><![CDATA[$OTPROOT]]></c> is the path - reported by <c><![CDATA[code:root_dir/0]]></c> in the above example, and <em>Vsn</em> is + to find <c>erl_interface.h</c> by specifying an appropriate <c>-I</c> + argument on the command line, or by adding it to the <c>CFLAGS</c> + definition in your <c>Makefile</c>. The correct value for this path is + <c>$OTPROOT/lib/erl_interface</c><em>Vsn</em><c>/include</c>, where <c>$OTPROOT</c> is the path + reported by <c>code:root_dir/0</c> in the above example, and <em>Vsn</em> is the version of the Erl_interface application, for example - <c><![CDATA[erl_interface-3.2.3]]></c></p> + <c>erl_interface-3.2.3</c></p> <code type="none"><![CDATA[ $ cc -c -I/usr/local/otp/lib/erl_interface-3.2.3/include myprog.c ]]></code> <p>When linking, you will need to specify the path to - <c><![CDATA[liberl_interface.a]]></c> and <c><![CDATA[libei.a]]></c> with - <c><![CDATA[-L$OTPROOT/lib/erl_interface-3.2.3/lib]]></c>, and you will need to specify the - name of the libraries with <c><![CDATA[-lerl_interface -lei]]></c>. You can do - this on the command line or by adding the flags to the <c><![CDATA[LDFLAGS]]></c> - definition in your <c><![CDATA[Makefile]]></c>.</p> + <c>liberl_interface.a</c> and <c>libei.a</c> with + <c>-L$OTPROOT/lib/erl_interface-3.2.3/lib</c>, and you will need to specify the + name of the libraries with <c>-lerl_interface -lei</c>. You can do + this on the command line or by adding the flags to the <c>LDFLAGS</c> + definition in your <c>Makefile</c>.</p> <code type="none"><![CDATA[ $ ld -L/usr/local/otp/lib/erl_interface-3.2.3/ lib myprog.o -lerl_interface -lei -o myprog ]]></code> <p>Also, on some systems it may be necessary to link with some - additional libraries (e.g. <c><![CDATA[libnsl.a]]></c> and <c><![CDATA[libsocket.a]]></c> on - Solaris, or <c><![CDATA[wsock32.lib]]></c> on Windows) in order to use the + additional libraries (e.g. <c>libnsl.a</c> and <c>libsocket.a</c> on + Solaris, or <c>wsock32.lib</c> on Windows) in order to use the communication facilities of Erl_Interface.</p> <p>If you are using Erl_Interface functions in a threaded application based on POSIX threads or Solaris threads, then Erl_Interface needs access to some of the synchronization facilities in your threads package, and you will need to specify additional compiler flags in order to indicate which of the packages - you are using. Define <c><![CDATA[_REENTRANT]]></c> and either <c><![CDATA[STHREADS]]></c> or - <c><![CDATA[PTHREADS]]></c>. The default is to use POSIX threads if - <c><![CDATA[_REENTRANT]]></c> is specified.</p> + you are using. Define <c>_REENTRANT</c> and either <c>STHREADS</c> or + <c>PTHREADS</c>. The default is to use POSIX threads if + <c>_REENTRANT</c> is specified.</p> <p>Note that both single threaded and default versions of the Erl_interface and Ei libraries are provided. (The single threaded versions are named - <c><![CDATA[liberl_interface_st]]></c> and <c><![CDATA[libei_st]]></c>). Whether the default + <c>liberl_interface_st</c> and <c>libei_st</c>). Whether the default versions of the libraries have support for threads or not is determined by if the platform in question has support for POSIX or Solaris threads. To check this, - have a look in the <c><![CDATA[eidefs.mk]]></c> file in the erl_interface src directory.</p> + have a look in the <c>eidefs.mk</c> file in the erl_interface src directory.</p> </section> <section> <title>Initializing the erl_interface Library</title> <p>Before calling any of the other Erl_Interface functions, you - must call <c><![CDATA[erl_init()]]></c> exactly once to initialize the library. - <c><![CDATA[erl_init()]]></c> takes two arguments, however the arguments are no + must call <c>erl_init()</c> exactly once to initialize the library. + <c>erl_init()</c> takes two arguments, however the arguments are no longer used by Erl_Interface, and should therefore be specified - as <c><![CDATA[erl_init(NULL,0)]]></c>.</p> + as <c>erl_init(NULL,0)</c>.</p> </section> <section> @@ -129,7 +129,7 @@ $ ld -L/usr/local/otp/lib/erl_interface-3.2.3/ number of C functions which create and manipulate Erlang data structures. The library also contains an encode and a decode function. The example below shows how to create and encode an Erlang tuple - <c><![CDATA[{tobbe,3928}]]></c>:</p> + <c>{tobbe,3928}</c>:</p> <code type="none"><![CDATA[ ETERM *arr[2], *tuple; @@ -140,26 +140,26 @@ arr[0] = erl_mk_atom("tobbe"); arr[1] = erl_mk_integer(3928); tuple = erl_mk_tuple(arr, 2); i = erl_encode(tuple, buf); ]]></code> - <p>Alternatively, you can use <c><![CDATA[erl_send()]]></c> and - <c><![CDATA[erl_receive_msg]]></c>, which handle the encoding and decoding of + <p>Alternatively, you can use <c>erl_send()</c> and + <c>erl_receive_msg</c>, which handle the encoding and decoding of messages transparently.</p> <p>Refer to the Reference Manual for a complete description of the following modules:</p> <list type="bulleted"> - <item>the <c><![CDATA[erl_eterm]]></c> module for creating Erlang terms</item> - <item>the <c><![CDATA[erl_marshal]]></c> module for encoding and decoding routines.</item> + <item>the <c>erl_eterm</c> module for creating Erlang terms</item> + <item>the <c>erl_marshal</c> module for encoding and decoding routines.</item> </list> </section> <section> <title>Building Terms and Patterns</title> <p>The previous example can be simplified by using - <c><![CDATA[erl_format()]]></c> to create an Erlang term.</p> + <c>erl_format()</c> to create an Erlang term.</p> <code type="none"><![CDATA[ ETERM *ep; ep = erl_format("{~a,~i}", "tobbe", 3928); ]]></code> - <p>Refer to the Reference Manual, the <c><![CDATA[erl_format]]></c> module, for a + <p>Refer to the Reference Manual, the <c>erl_format</c> module, for a full description of the different format directives. The following example is more complex:</p> <code type="none"><![CDATA[ @@ -172,9 +172,9 @@ ep = erl_format("[{name,~a},{age,~i},{data,~w}]", erl_free_compound(ep); ]]></code> <p>As in previous examples, it is your responsibility to free the memory allocated for Erlang terms. In this example, - <c><![CDATA[erl_free_compound()]]></c> ensures that the complete term pointed to - by <c><![CDATA[ep]]></c> is released. This is necessary, because the pointer from - the second call to <c><![CDATA[erl_format()]]></c> is lost. </p> + <c>erl_free_compound()</c> ensures that the complete term pointed to + by <c>ep</c> is released. This is necessary, because the pointer from + the second call to <c>erl_format()</c> is lost. </p> <p>The following example shows a slightly different solution:</p> <code type="none"><![CDATA[ @@ -186,7 +186,7 @@ ep = erl_format("[{name,~a},{age,~i},{data,~w}]", erl_free_term(ep); erl_free_term(ep2); ]]></code> <p>In this case, you free the two terms independently. The order in - which you free the terms <c><![CDATA[ep]]></c> and <c><![CDATA[ep2]]></c> is not important, + which you free the terms <c>ep</c> and <c>ep2</c> is not important, because the Erl_Interface library uses reference counting to determine when it is safe to actually remove objects. </p> <p>If you are not sure whether you have freed the terms properly, you @@ -204,14 +204,14 @@ printf("length of freelist: %ld\ /* really free the freelist */ erl_eterm_release(); ]]></code> - <p>Refer to the Reference Manual, the <c><![CDATA[erl_malloc]]></c> module for more + <p>Refer to the Reference Manual, the <c>erl_malloc</c> module for more information.</p> </section> <section> <title>Pattern Matching</title> <p>An Erlang pattern is a term that may contain unbound variables or - <c><![CDATA["do not care"]]></c> symbols. Such a pattern can be matched against a + <c>"do not care"</c> symbols. Such a pattern can be matched against a term and, if the match is successful, any unbound variables in the pattern will be bound as a side effect. The content of a bound variable can then be retrieved.</p> @@ -219,13 +219,13 @@ erl_eterm_release(); ETERM *pattern; pattern = erl_format("{madonna,Age,_}"); ]]></code> - <p><c><![CDATA[erl_match()]]></c> is used to perform pattern matching. It takes a + <p><c>erl_match()</c> is used to perform pattern matching. It takes a pattern and a term and tries to match them. As a side effect any unbound variables in the pattern will be bound. In the following example, we create a pattern with a variable <em>Age</em> which appears at two positions in the tuple. The pattern match is performed as follows:</p> <list type="ordered"> - <item><c><![CDATA[erl_match()]]></c> will bind the contents of + <item><c>erl_match()</c> will bind the contents of <em>Age</em> to <em>21</em> the first time it reaches the variable</item> <item>the second occurrence of <em>Age</em> will cause a test for equality between the terms since <em>Age</em> is already bound to @@ -248,14 +248,14 @@ if (erl_match(pattern, term)) { } erl_free_term(pattern); erl_free_term(term); ]]></code> - <p>Refer to the Reference Manual, the <c><![CDATA[erl_match()]]></c> function for + <p>Refer to the Reference Manual, the <c>erl_match()</c> function for more information.</p> </section> <section> <title>Connecting to a Distributed Erlang Node</title> <p>In order to connect to a distributed Erlang node you need to first - initialize the connection routine with <c><![CDATA[erl_connect_init()]]></c>, + initialize the connection routine with <c>erl_connect_init()</c>, which stores information such as the host name, node name, and IP address for later use:</p> <code type="none"><![CDATA[ @@ -263,9 +263,9 @@ int identification_number = 99; int creation=1; char *cookie="a secret cookie string"; /* An example */ erl_connect_init(identification_number, cookie, creation); ]]></code> - <p>Refer to the Reference Manual, the <c><![CDATA[erl_connect]]></c> module for more information.</p> + <p>Refer to the Reference Manual, the <c>erl_connect</c> module for more information.</p> <p>After initialization, you set up the connection to the Erlang node. - Use <c><![CDATA[erl_connect()]]></c> to specify the Erlang node you want to + Use <c>erl_connect()</c> to specify the Erlang node you want to connect to. The following example sets up the connection and should result in a valid socket file descriptor:</p> <code type="none"><![CDATA[ @@ -273,45 +273,45 @@ int sockfd; char *nodename="[email protected]"; /* An example */ if ((sockfd = erl_connect(nodename)) < 0) erl_err_quit("ERROR: erl_connect failed"); ]]></code> - <p><c><![CDATA[erl_err_quit()]]></c> prints the specified string and terminates - the program. Refer to the Reference Manual, the <c><![CDATA[erl_error()]]></c> + <p><c>erl_err_quit()</c> prints the specified string and terminates + the program. Refer to the Reference Manual, the <c>erl_error()</c> function for more information.</p> </section> <section> <title>Using EPMD</title> - <p><c><![CDATA[Epmd]]></c> is the Erlang Port Mapper Daemon. Distributed Erlang nodes - register with <c><![CDATA[epmd]]></c> on the localhost to indicate to other nodes that - they exist and can accept connections. <c><![CDATA[Epmd]]></c> maintains a register of + <p><c>Epmd</c> is the Erlang Port Mapper Daemon. Distributed Erlang nodes + register with <c>epmd</c> on the localhost to indicate to other nodes that + they exist and can accept connections. <c>Epmd</c> maintains a register of node and port number information, and when a node wishes to connect to - another node, it first contacts <c><![CDATA[epmd]]></c> in order to find out the correct + another node, it first contacts <c>epmd</c> in order to find out the correct port number to connect to.</p> - <p>When you use <c><![CDATA[erl_connect()]]></c> to connect to an Erlang node, a - connection is first made to <c><![CDATA[epmd]]></c> and, if the node is known, a + <p>When you use <c>erl_connect()</c> to connect to an Erlang node, a + connection is first made to <c>epmd</c> and, if the node is known, a connection is then made to the Erlang node.</p> - <p>C nodes can also register themselves with <c><![CDATA[epmd]]></c> if they want other + <p>C nodes can also register themselves with <c>epmd</c> if they want other nodes in the system to be able to find and connect to them.</p> - <p>Before registering with <c><![CDATA[epmd]]></c>, you need to first create a listen socket + <p>Before registering with <c>epmd</c>, you need to first create a listen socket and bind it to a port. Then:</p> <code type="none"><![CDATA[ int pub; pub = erl_publish(port); ]]></code> - <p><c><![CDATA[pub]]></c> is a file descriptor now connected to <c><![CDATA[epmd]]></c>. <c><![CDATA[Epmd]]></c> + <p><c>pub</c> is a file descriptor now connected to <c>epmd</c>. <c>Epmd</c> monitors the other end of the connection, and if it detects that the connection has been closed, the node will be unregistered. So, if you explicitly close the descriptor or if your node fails, it will be - unregistered from <c><![CDATA[epmd]]></c>.</p> + unregistered from <c>epmd</c>.</p> <p>Be aware that on some systems (such as VxWorks), a failed node will not be detected by this mechanism since the operating system does not automatically close descriptors that were left open when the node - failed. If a node has failed in this way, <c><![CDATA[epmd]]></c> will prevent you from + failed. If a node has failed in this way, <c>epmd</c> will prevent you from registering a new node with the old name, since it thinks that the old name is still in use. In this case, you must unregister the name explicitly:</p> <code type="none"><![CDATA[ erl_unpublish(node); ]]></code> - <p>This will cause <c><![CDATA[epmd]]></c> to close the connection from the far end. Note + <p>This will cause <c>epmd</c> to close the connection from the far end. Note that if the name was in fact still in use by a node, the results of this operation are unpredictable. Also, doing this does not cause the local end of the connection to close, so resources may be consumed.</p> @@ -321,8 +321,8 @@ erl_unpublish(node); ]]></code> <title>Sending and Receiving Erlang Messages</title> <p>Use one of the following two functions to send messages:</p> <list type="bulleted"> - <item><c><![CDATA[erl_send()]]></c></item> - <item><c><![CDATA[erl_reg_send()]]></c></item> + <item><c>erl_send()</c></item> + <item><c>erl_reg_send()</c></item> </list> <p>As in Erlang, it is possible to send messages to a <em>Pid</em> or to a registered name. It is easier to send a @@ -330,17 +330,17 @@ erl_unpublish(node); ]]></code> a suitable <em>Pid</em>.</p> <p>Use one of the following two functions to receive messages:</p> <list type="bulleted"> - <item><c><![CDATA[erl_receive()]]></c></item> - <item><c><![CDATA[erl_receive_msg()]]></c></item> + <item><c>erl_receive()</c></item> + <item><c>erl_receive_msg()</c></item> </list> - <p><c><![CDATA[erl_receive()]]></c> receives the message into a buffer, while - <c><![CDATA[erl_receive_msg()]]></c> decodes the message into an Erlang term. </p> + <p><c>erl_receive()</c> receives the message into a buffer, while + <c>erl_receive_msg()</c> decodes the message into an Erlang term. </p> <section> <title>Example of Sending Messages</title> - <p>In the following example, <c><![CDATA[{Pid, hello_world}]]></c> is - sent to a registered process <c><![CDATA[my_server]]></c>. The message is encoded - by <c><![CDATA[erl_send()]]></c>:</p> + <p>In the following example, <c>{Pid, hello_world}</c> is + sent to a registered process <c>my_server</c>. The message is encoded + by <c>erl_send()</c>:</p> <code type="none"><![CDATA[ extern const char *erl_thisnodename(void); extern short erl_thiscreation(void); @@ -355,15 +355,15 @@ emsg = erl_mk_tuple(arr, 2); erl_reg_send(sockfd, "my_server", emsg); erl_free_term(emsg); ]]></code> <p>The first element of the tuple that is sent is your own - <em>Pid</em>. This enables <c><![CDATA[my_server]]></c> to reply. Refer to the - Reference Manual, the <c><![CDATA[erl_connect]]></c> module for more information + <em>Pid</em>. This enables <c>my_server</c> to reply. Refer to the + Reference Manual, the <c>erl_connect</c> module for more information about send primitives.</p> </section> <section> <title>Example of Receiving Messages</title> - <p>In this example <c><![CDATA[{Pid, Something}]]></c> is received. The - received Pid is then used to return <c><![CDATA[{goodbye,Pid}]]></c></p> + <p>In this example <c>{Pid, Something}</c> is received. The + received Pid is then used to return <c>{goodbye,Pid}</c></p> <code type="none"><![CDATA[ ETERM *arr[2], *answer; int sockfd,rc; @@ -383,18 +383,18 @@ if ((rc = erl_receive_msg(sockfd , buf, BUFSIZE, &emsg)) == ERL_MSG) { <p>In order to provide robustness, a distributed Erlang node occasionally polls all its connected neighbours in an attempt to detect failed nodes or communication links. A node which receives such - a message is expected to respond immediately with an <c><![CDATA[ERL_TICK]]></c> message. - This is done automatically by <c><![CDATA[erl_receive()]]></c>, however when this - has occurred <c><![CDATA[erl_receive]]></c> returns <c><![CDATA[ERL_TICK]]></c> to the caller - without storing a message into the <c><![CDATA[ErlMessage]]></c> structure.</p> + a message is expected to respond immediately with an <c>ERL_TICK</c> message. + This is done automatically by <c>erl_receive()</c>, however when this + has occurred <c>erl_receive</c> returns <c>ERL_TICK</c> to the caller + without storing a message into the <c>ErlMessage</c> structure.</p> <p>When a message has been received, it is the caller's responsibility - to free the received message <c><![CDATA[emsg.msg]]></c> as well as <c><![CDATA[emsg.to]]></c> - or <c><![CDATA[emsg.from]]></c>, depending on the type of message received.</p> + to free the received message <c>emsg.msg</c> as well as <c>emsg.to</c> + or <c>emsg.from</c>, depending on the type of message received.</p> <p>Refer to the Reference Manual for additional information about the following modules:</p> <list type="bulleted"> - <item><c><![CDATA[erl_connect]]></c></item> - <item><c><![CDATA[erl_eterm]]></c>.</item> + <item><c>erl_connect</c></item> + <item><c>erl_eterm</c>.</item> </list> </section> </section> @@ -421,12 +421,12 @@ if (!erl_match(ep, reply)) "); erl_free_term(ep); erl_free_term(reply); ]]></code> - <p><c><![CDATA[c:c/1]]></c> is called to compile the specified module on the - remote node. <c><![CDATA[erl_match()]]></c> checks that the compilation was - successful by testing for the expected <c><![CDATA[ok]]></c>.</p> - <p>Refer to the Reference Manual, the <c><![CDATA[erl_connect]]></c> module for - more information about <c><![CDATA[erl_rpc()]]></c>, and its companions - <c><![CDATA[erl_rpc_to()]]></c> and <c><![CDATA[erl_rpc_from()]]></c>.</p> + <p><c>c:c/1</c> is called to compile the specified module on the + remote node. <c>erl_match()</c> checks that the compilation was + successful by testing for the expected <c>ok</c>.</p> + <p>Refer to the Reference Manual, the <c>erl_connect</c> module for + more information about <c>erl_rpc()</c>, and its companions + <c>erl_rpc_to()</c> and <c>erl_rpc_from()</c>.</p> </section> <section> @@ -454,14 +454,14 @@ if (names) ",names[i]); free(names); ]]></code> - <p><c><![CDATA[erl_global_names()]]></c> allocates and returns a buffer containing - all the names known to global. <c><![CDATA[count]]></c> will be initialized to + <p><c>erl_global_names()</c> allocates and returns a buffer containing + all the names known to global. <c>count</c> will be initialized to indicate how many names are in the array. The array of strings in names is terminated by a NULL pointer, so it is not necessary to use - <c><![CDATA[count]]></c> to determine when the last name is reached.</p> + <c>count</c> to determine when the last name is reached.</p> <p>It is the caller's responsibility to free the array. - <c><![CDATA[erl_global_names()]]></c> allocates the array and all of the strings - using a single call to <c><![CDATA[malloc()]]></c>, so <c><![CDATA[free(names)]]></c> is all + <c>erl_global_names()</c> allocates the array and all of the strings + using a single call to <c>malloc()</c>, so <c>free(names)</c> is all that is necessary.</p> <p>To look up one of the names:</p> <code type="none"><![CDATA[ @@ -469,13 +469,13 @@ ETERM *pid; char node[256]; pid = erl_global_whereis(fd,"schedule",node); ]]></code> - <p>If <c><![CDATA["schedule"]]></c> is known to global, an Erlang pid is returned + <p>If <c>"schedule"</c> is known to global, an Erlang pid is returned that can be used to send messages to the schedule service. - Additionally, <c><![CDATA[node]]></c> will be initialized to contain the name of + Additionally, <c>node</c> will be initialized to contain the name of the node where the service is registered, so that you can make a - connection to it by simply passing the variable to <c><![CDATA[erl_connect()]]></c>.</p> + connection to it by simply passing the variable to <c>erl_connect()</c>.</p> <p>Before registering a name, you should already have registered your - port number with <c><![CDATA[epmd]]></c>. This is not strictly necessary, but if you + port number with <c>epmd</c>. This is not strictly necessary, but if you neglect to do so, then other nodes wishing to communicate with your service will be unable to find or connect to your process.</p> <p>Create a pid that Erlang processes can use to communicate with your @@ -485,9 +485,9 @@ ETERM *pid; pid = erl_mk_pid(thisnode,14,0,0); erl_global_register(fd,servicename,pid); ]]></code> - <p>After registering the name, you should use <c><![CDATA[erl_accept()]]></c> to wait for + <p>After registering the name, you should use <c>erl_accept()</c> to wait for incoming connections.</p> - <p>Do not forget to free <c><![CDATA[pid]]></c> later with <c><![CDATA[erl_free_term()]]></c>!</p> + <p>Do not forget to free <c>pid</c> later with <c>erl_free_term()</c>!</p> <p>To unregister a name:</p> <code type="none"><![CDATA[ erl_global_unregister(fd,servicename); ]]></code> @@ -570,12 +570,12 @@ ei_reg_close(reg); ]]></code> <title>Backing Up the Registry to Mnesia</title> <p>The contents of a registry can be backed up to Mnesia on a "nearby" Erlang node. You need to provide an open connection to the Erlang node - (see <c><![CDATA[erl_connect()]]></c>). Also, Mnesia 3.0 or later must be running + (see <c>erl_connect()</c>). Also, Mnesia 3.0 or later must be running on the Erlang node before the backup is initiated:</p> <code type="none"><![CDATA[ ei_reg_dump(fd, reg, "mtab", dumpflags); ]]></code> <p>The example above will backup the contents of the registry to the - specified Mnesia table <c><![CDATA["mtab"]]></c>. Once a registry has been backed + specified Mnesia table <c>"mtab"</c>. Once a registry has been backed up to Mnesia in this manner, additional backups will only affect objects that have been modified since the most recent backup, i.e. objects that have been created, changed or deleted. The backup @@ -584,7 +584,7 @@ ei_reg_dump(fd, reg, "mtab", dumpflags); ]]></code> <p>In the same manner, a registry can be restored from a Mnesia table:</p> <code type="none"><![CDATA[ ei_reg_restore(fd, reg, "mtab"); ]]></code> - <p>This will read the entire contents of <c><![CDATA["mtab"]]></c> into the specified + <p>This will read the entire contents of <c>"mtab"</c> into the specified registry. After the restore, all of the objects in the registry will be marked as unmodified, so a subsequent backup will only affect objects that you have modified since the restore.</p> @@ -600,8 +600,8 @@ ei_reg_restore(fd, reg, "mtab"); ]]></code> <p>When string or binary objects are stored in the registry it is important that a number of simple guidelines are followed. </p> <p>Most importantly, the object must have been created with a single call - to <c><![CDATA[malloc()]]></c> (or similar), so that it can later be removed by a - single call to <c><![CDATA[free()]]></c>. Objects will be freed by the registry + to <c>malloc()</c> (or similar), so that it can later be removed by a + single call to <c>free()</c>. Objects will be freed by the registry when it is closed, or when you assign a new value to an object that previously contained a string or binary.</p> <p>You should also be aware that if you store binary objects that are @@ -618,8 +618,8 @@ ei_reg_restore(fd, reg, "mtab"); ]]></code> you make, possibly causing it to be missed the next time you make a Mnesia backup of the registry contents. This can be avoided if you mark the object as dirty after any such changes with - <c><![CDATA[ei_reg_markdirty()]]></c>, or pass appropriate flags to - <c><![CDATA[ei_reg_dump()]]></c>.</p> + <c>ei_reg_markdirty()</c>, or pass appropriate flags to + <c>ei_reg_dump()</c>.</p> </section> </section> </chapter> diff --git a/lib/erl_interface/doc/src/erl_malloc.xml b/lib/erl_interface/doc/src/erl_malloc.xml index e08924ec51..c0eebc29e9 100644 --- a/lib/erl_interface/doc/src/erl_malloc.xml +++ b/lib/erl_interface/doc/src/erl_malloc.xml @@ -47,8 +47,8 @@ <v>unsigned char etype;</v> </type> <desc> - <p>Allocates an <c><![CDATA[(ETERM)]]></c> structure.</p> - <p>Specify <c><![CDATA[etype]]></c> as one of the following + <p>Allocates an <c>(ETERM)</c> structure.</p> + <p>Specify <c>etype</c> as one of the following constants:</p> <list type="bulleted"> <item><c>ERL_INTEGER</c> @@ -80,9 +80,9 @@ <item><c>ERL_U_SMALL_BIG</c> (bignum) </item> </list> - <p><c><![CDATA[ERL_SMALL_BIG]]></c> and - <c><![CDATA[ERL_U_SMALL_BIG]]></c> are for - creating Erlang <c><![CDATA[bignums]]></c>, which can contain integers + <p><c>ERL_SMALL_BIG</c> and + <c>ERL_U_SMALL_BIG</c> are for + creating Erlang <c>bignums</c>, which can contain integers of any size. The size of an integer in Erlang is machine-dependent, but any integer > 2^28 requires a bignum.</p> </desc> @@ -93,8 +93,8 @@ <fsummary>Clear the ETERM freelist.</fsummary> <desc> <p>Clears the freelist, where blocks are placed when they are - released by <c><![CDATA[erl_free_term()]]></c> and - <c><![CDATA[erl_free_compound()]]></c>.</p> + released by <c>erl_free_term()</c> and + <c>erl_free_compound()</c>.</p> </desc> </func> @@ -107,20 +107,20 @@ </type> <desc> <p>Reports term allocation statistics.</p> - <p><c><![CDATA[allocated]]></c> and <c><![CDATA[freed]]></c> are + <p><c>allocated</c> and <c>freed</c> are initialized to contain information about the fix-allocator used to allocate <c>ETERM</c> components.</p> <list type="bulleted"> <item> - <p><c><![CDATA[allocated]]></c> is the number of blocks currently + <p><c>allocated</c> is the number of blocks currently allocated to <c>ETERM</c> objects.</p> </item> <item> - <p><c><![CDATA[freed]]></c> is the length of the freelist, where + <p><c>freed</c> is the length of the freelist, where blocks are placed when they are - released by <c><![CDATA[erl_free_term()]]></c> and - <c><![CDATA[erl_free_compound()]]></c>.</p> + released by <c>erl_free_term()</c> and + <c>erl_free_compound()</c>.</p> </item> </list> </desc> @@ -134,7 +134,7 @@ </type> <desc> <p>Calls the standard - <c><![CDATA[free()]]></c> function.</p> + <c>free()</c> function.</p> </desc> </func> @@ -148,8 +148,8 @@ <desc> <p>Frees an array of Erlang terms.</p> <list type="bulleted"> - <item><c><![CDATA[array]]></c> is an array of ETERM* objects.</item> - <item><c><![CDATA[size]]></c> is the number of terms in the array. + <item><c>array</c> is an array of ETERM* objects.</item> + <item><c>size</c> is the number of terms in the array. </item> </list> </desc> @@ -164,12 +164,12 @@ <desc> <p>Normally it is the programmer's responsibility to free each Erlang term that has been returned from any of the - <c><![CDATA[Erl_Interface]]></c> functions. However, as many of the + <c>Erl_Interface</c> functions. However, as many of the functions that build new Erlang terms in fact share objects with other existing terms, it can be difficult for the programmer to maintain pointers to all such terms to free them individually.</p> - <p><c><![CDATA[erl_free_compound()]]></c> recursively frees all of the + <p><c>erl_free_compound()</c> recursively frees all of the subterms associated with a specified Erlang term, regardless of whether we are still holding pointers to the subterms.</p> <p>For an example, see section @@ -197,7 +197,7 @@ </type> <desc> <p>Calls the standard - <c><![CDATA[malloc()]]></c> function.</p> + <c>malloc()</c> function.</p> </desc> </func> </funcs> diff --git a/lib/erl_interface/doc/src/erl_marshal.xml b/lib/erl_interface/doc/src/erl_marshal.xml index b333bc9993..2ad658f78b 100644 --- a/lib/erl_interface/doc/src/erl_marshal.xml +++ b/lib/erl_interface/doc/src/erl_marshal.xml @@ -50,9 +50,9 @@ <desc> <p>Compares two encoded terms.</p> <list type="bulleted"> - <item><c><![CDATA[bufp1]]></c> is a buffer containing an encoded + <item><c>bufp1</c> is a buffer containing an encoded Erlang term term1.</item> - <item><c><![CDATA[bufp2]]></c> is a buffer containing an encoded + <item><c>bufp2</c> is a buffer containing an encoded Erlang term term2.</item> </list> <p>Returns <c>0</c> if the terms are equal, <c>-1</c> if @@ -70,31 +70,31 @@ <v>unsigned char **bufpp;</v> </type> <desc> - <p><c><![CDATA[erl_decode()]]></c> and - <c><![CDATA[erl_decode_buf()]]></c> decode + <p><c>erl_decode()</c> and + <c>erl_decode_buf()</c> decode the contents of a buffer and return the corresponding - Erlang term. <c><![CDATA[erl_decode_buf()]]></c> provides a simple + Erlang term. <c>erl_decode_buf()</c> provides a simple mechanism for dealing with several encoded terms stored consecutively in the buffer.</p> <list type="bulleted"> <item> - <p><c><![CDATA[bufp]]></c> is a pointer to a buffer containing one + <p><c>bufp</c> is a pointer to a buffer containing one or more encoded Erlang terms.</p> </item> <item> - <p><c><![CDATA[bufpp]]></c> is the address of a buffer pointer. The + <p><c>bufpp</c> is the address of a buffer pointer. The buffer contains one or more consecutively encoded Erlang terms. Following a successful call to - <c><![CDATA[erl_decode_buf()]]></c>, <c><![CDATA[bufpp]]></c> is + <c>erl_decode_buf()</c>, <c>bufpp</c> is updated so that it points to the next encoded term.</p> </item> </list> - <p><c><![CDATA[erl_decode()]]></c> returns an Erlang term - corresponding to the contents of <c><![CDATA[bufp]]></c> on success, - otherwise <c>NULL</c>. <c><![CDATA[erl_decode_buf()]]></c> + <p><c>erl_decode()</c> returns an Erlang term + corresponding to the contents of <c>bufp</c> on success, + otherwise <c>NULL</c>. <c>erl_decode_buf()</c> returns an Erlang term corresponding to the first of the consecutive terms in - <c><![CDATA[bufpp]]></c> and moves <c><![CDATA[bufpp]]></c> forward + <c>bufpp</c> and moves <c>bufpp</c> forward to point to the next term in the buffer. On failure, each of the functions return <c>NULL</c>.</p> @@ -111,10 +111,10 @@ <v>unsigned char **bufpp;</v> </type> <desc> - <p><c><![CDATA[erl_encode()]]></c> and - <c><![CDATA[erl_encode_buf()]]></c> encode + <p><c>erl_encode()</c> and + <c>erl_encode_buf()</c> encode Erlang terms into external format for storage or transmission. - <c><![CDATA[erl_encode_buf()]]></c> provides a simple mechanism for + <c>erl_encode_buf()</c> provides a simple mechanism for encoding several terms consecutively in the same buffer.</p> <list type="bulleted"> <item> @@ -128,7 +128,7 @@ <p><c>bufpp</c> is a pointer to a pointer to a buffer containing one or more consecutively encoded Erlang terms. Following a successful call to - <c><![CDATA[erl_encode_buf()]]></c>, <c>bufpp</c> is updated so + <c>erl_encode_buf()</c>, <c>bufpp</c> is updated so that it points to the position for the next encoded term.</p> </item> @@ -139,36 +139,36 @@ the caller's responsibility to ensure that the buffer is large enough to hold the encoded terms. You can either use a static buffer that is large enough to hold the terms you expect - to need in your program, or use <c><![CDATA[erl_term_len()]]></c> + to need in your program, or use <c>erl_term_len()</c> to determine the exact requirements for a given term.</p> <p>The following can help you estimate the buffer requirements for a term. Notice that this information is implementation-specific, and can change in future versions. - If you are unsure, use <c><![CDATA[erl_term_len()]]></c>.</p> + If you are unsure, use <c>erl_term_len()</c>.</p> <p>Erlang terms are encoded with a 1 byte tag that identifies the type of object, a 2- or 4-byte length field, and then the data itself. Specifically:</p> <taglist> - <tag><c><![CDATA[Tuples]]></c></tag> + <tag><c>Tuples</c></tag> <item>Need 5 bytes, plus the space for each element.</item> - <tag><c><![CDATA[Lists]]></c></tag> + <tag><c>Lists</c></tag> <item>Need 5 bytes, plus the space for each element, and 1 more byte for the empty list at the end.</item> - <tag><c><![CDATA[Strings and atoms]]></c></tag> + <tag><c>Strings and atoms</c></tag> <item>Need 3 bytes, plus 1 byte for each character (the terminating 0 is not encoded). Really long strings (more than 64k characters) are encoded as lists. Atoms cannot contain more than 256 characters.</item> - <tag><c><![CDATA[Integers]]></c></tag> + <tag><c>Integers</c></tag> <item>Need 5 bytes.</item> - <tag><c><![CDATA[Characters]]></c></tag> + <tag><c>Characters</c></tag> <item>(Integers < 256) need 2 bytes.</item> - <tag><c><![CDATA[Floating point numbers]]></c></tag> + <tag><c>Floating point numbers</c></tag> <item>Need 32 bytes.</item> - <tag><c><![CDATA[Pids]]></c></tag> + <tag><c>Pids</c></tag> <item>Need 10 bytes, plus the space for the node name, which is an atom.</item> - <tag><c><![CDATA[Ports and Refs]]></c></tag> + <tag><c>Ports and Refs</c></tag> <item>Need 6 bytes, plus the space for the node name, which is an atom.</item> </taglist> @@ -198,7 +198,7 @@ <desc> <p>Identifies and returns the type of Erlang term encoded in a buffer. It skips a trailing <em>magic</em> identifier.</p> - <p>Returns <c><![CDATA[0]]></c> if the type cannot be determined or + <p>Returns <c>0</c> if the type cannot be determined or one of:</p> <list type="bulleted"> <item><c>ERL_INTEGER</c> @@ -238,15 +238,15 @@ <p>This function is used for stepping over one or more encoded terms in a buffer, to directly access later term.</p> <list type="bulleted"> - <item><c><![CDATA[bufp]]></c> is a pointer to a buffer containing one + <item><c>bufp</c> is a pointer to a buffer containing one or more encoded Erlang terms.</item> - <item><c><![CDATA[pos]]></c> indicates how many terms to step over in + <item><c>pos</c> indicates how many terms to step over in the buffer.</item> </list> <p>Returns a pointer to a subterm that can be - used in a later call to <c><![CDATA[erl_decode()]]></c> to retrieve + used in a later call to <c>erl_decode()</c> to retrieve the term at that position. If there is no term, or - <c><![CDATA[pos]]></c> would exceed the size of the terms in the + <c>pos</c> would exceed the size of the terms in the buffer, <c>NULL</c> is returned.</p> </desc> </func> @@ -259,8 +259,8 @@ </type> <desc> <p>Determines the buffer space that would be - needed by <c><![CDATA[t]]></c> if it were encoded into Erlang external - format by <c><![CDATA[erl_encode()]]></c>.</p> + needed by <c>t</c> if it were encoded into Erlang external + format by <c>erl_encode()</c>.</p> <p>Returns the size in bytes.</p> </desc> </func> diff --git a/lib/erl_interface/doc/src/ref_man_ei.xml b/lib/erl_interface/doc/src/ref_man_ei.xml index d24828c394..92ff9ed328 100644 --- a/lib/erl_interface/doc/src/ref_man_ei.xml +++ b/lib/erl_interface/doc/src/ref_man_ei.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>EI Library Reference</title> @@ -30,12 +30,12 @@ <file>ref_man_ei.xml</file> </header> <description> - <p>The <c><![CDATA[ei]]></c> library is a <c><![CDATA[C]]></c> interface library for - communication with <c><![CDATA[Erlang]]></c>.</p> + <p>The <c>ei</c> library is a <c>C</c> interface library for + communication with <c>Erlang</c>.</p> <note> - <p>By default, the <c><![CDATA[ei]]></c> library is only guaranteed + <p>By default, the <c>ei</c> library is only guaranteed to be compatible with other Erlang/OTP components from the same - release as the <c><![CDATA[ei]]></c> library itself. See the documentation of the + release as the <c>ei</c> library itself. See the documentation of the <seealso marker="ei#ei_set_compat_rel">ei_set_compat_rel()</seealso> function on how to communicate with Erlang/OTP components from earlier releases.</p> @@ -45,4 +45,3 @@ <xi:include href="ei_connect.xml"/> <xi:include href="registry.xml"/> </application> - diff --git a/lib/erl_interface/doc/src/registry.xml b/lib/erl_interface/doc/src/registry.xml index 00b8f770de..6d70fb3475 100644 --- a/lib/erl_interface/doc/src/registry.xml +++ b/lib/erl_interface/doc/src/registry.xml @@ -51,9 +51,9 @@ </type> <desc> <p>A registry that has previously been created with - <c><![CDATA[ei_reg_open()]]></c> is closed, and all the objects it + <c>ei_reg_open()</c> is closed, and all the objects it contains are freed.</p> - <p><c><![CDATA[reg]]></c> is the registry to close.</p> + <p><c>reg</c> is the registry to close.</p> <p>Returns <c>0</c>.</p> </desc> </func> @@ -73,12 +73,12 @@ well. If another object is later created with the same key, the object will be reused. </p> <p>The object is removed from the registry after a call to - <c><![CDATA[ei_reg_dump()]]></c> or <c><![CDATA[ei_reg_purge()]]></c>. + <c>ei_reg_dump()</c> or <c>ei_reg_purge()</c>. </p> <list type="bulleted"> - <item><c><![CDATA[reg]]></c> is the registry containing - <c><![CDATA[key]]></c>.</item> - <item><c><![CDATA[key]]></c> is the object to remove.</item> + <item><c>reg</c> is the registry containing + <c>key</c>.</item> + <item><c>key</c> is the object to remove.</item> </list> <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> @@ -99,17 +99,17 @@ If any errors are encountered while backing up the data, the entire operation is aborted.</p> <list type="bulleted"> - <item><c><![CDATA[fd]]></c> is an open connection to Erlang. + <item><c>fd</c> is an open connection to Erlang. <c>Mnesia</c> 3.0 or later must be running on the Erlang node. </item> - <item><c><![CDATA[reg]]></c> is the registry to back up.</item> - <item><c><![CDATA[mntab]]></c> is the name of the <c>Mnesia</c> table + <item><c>reg</c> is the registry to back up.</item> + <item><c>mntab</c> is the name of the <c>Mnesia</c> table where the backed up data is to be placed. If the table does not exist, it is created automatically using configurable defaults. For information about configuring this behavior, see <seealso marker="mnesia:mnesia"><c>Mnesia</c></seealso>.</item> </list> - <p>If <c><![CDATA[flags]]></c> is <c>0</c>, the backup includes only + <p>If <c>flags</c> is <c>0</c>, the backup includes only those objects that have been created, modified, or deleted since the last backup or restore (that is, an incremental backup). After the backup, any objects that were marked dirty are now clean, and any @@ -118,7 +118,7 @@ backup to be done, and <c>EI_NOPURGE</c> causes the deleted objects to be left in the registry afterwards. These can be bitwise OR'ed together if both behaviors are desired. If <c>EI_NOPURGE</c> was - specified, <c><![CDATA[ei_reg_purge()]]></c> can be used to + specified, <c>ei_reg_purge()</c> can be used to explicitly remove the deleted items from the registry later.</p> <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> @@ -132,21 +132,21 @@ <v>const char *key;</v> </type> <desc> - <p>Gets the value associated with <c><![CDATA[key]]></c> in the + <p>Gets the value associated with <c>key</c> in the registry. The value must be a floating point type.</p> <list type="bulleted"> - <item><c><![CDATA[reg]]></c> is the registry where the object will be + <item><c>reg</c> is the registry where the object will be looked up.</item> - <item><c><![CDATA[key]]></c> is the name of the object to look up. + <item><c>key</c> is the name of the object to look up. </item> </list> <p>On success, the function returns the value associated with - <c><![CDATA[key]]></c>. + <c>key</c>. If the object is not found or if it is not a floating point object, <c>-1.0</c> is returned. To avoid problems with in-band error reporting (that is, if you cannot distinguish between <c>-1.0</c> and a valid result), use the more general function - <c><![CDATA[ei_reg_getval()]]></c> instead.</p> + <c>ei_reg_getval()</c> instead.</p> </desc> </func> @@ -158,21 +158,21 @@ <v>const char *key;</v> </type> <desc> - <p>Gets the value associated with <c><![CDATA[key]]></c> in the + <p>Gets the value associated with <c>key</c> in the registry. The value must be an integer.</p> <list type="bulleted"> - <item><c><![CDATA[reg]]></c> is the registry where the object will be + <item><c>reg</c> is the registry where the object will be looked up.</item> - <item><c><![CDATA[key]]></c> is the name of the object to look up. + <item><c>key</c> is the name of the object to look up. </item> </list> <p>On success, the function returns the value associated with - <c><![CDATA[key]]></c>. + <c>key</c>. If the object is not found or if it is not an integer object, <c>-1</c> is returned. To avoid problems with in-band error reporting (that is, if you cannot distinguish between <c>-1</c> and a valid result), use the more general function - <c><![CDATA[ei_reg_getval()]]></c> instead.</p> + <c>ei_reg_getval()</c> instead.</p> </desc> </func> @@ -185,24 +185,24 @@ <v>int size;</v> </type> <desc> - <p>Gets the value associated with <c><![CDATA[key]]></c> in the + <p>Gets the value associated with <c>key</c> in the registry. The value must be a binary (pointer) type.</p> <list type="bulleted"> - <item><c><![CDATA[reg]]></c> is the registry where the object will be + <item><c>reg</c> is the registry where the object will be looked up.</item> - <item><c><![CDATA[key]]></c> is the name of the object to look up. + <item><c>key</c> is the name of the object to look up. </item> - <item><c><![CDATA[size]]></c> is initialized to contain the length in + <item><c>size</c> is initialized to contain the length in bytes of the object, if it is found.</item> </list> <p>On success, the function returns the value associated with - <c><![CDATA[key]]></c> and indicates its length in - <c><![CDATA[size]]></c>. + <c>key</c> and indicates its length in + <c>size</c>. If the object is not found or if it is not a binary object, <c>NULL</c> is returned. To avoid problems with in-band error reporting (that is, if you cannot distinguish between <c>NULL</c> and a valid result), use the more general function - <c><![CDATA[ei_reg_getval()]]></c> instead.</p> + <c>ei_reg_getval()</c> instead.</p> </desc> </func> @@ -214,20 +214,20 @@ <v>const char *key;</v> </type> <desc> - <p>Gets the value associated with <c><![CDATA[key]]></c> in the + <p>Gets the value associated with <c>key</c> in the registry. The value must be a string.</p> <list type="bulleted"> - <item><c><![CDATA[reg]]></c> is the registry where the object will be + <item><c>reg</c> is the registry where the object will be looked up.</item> - <item><c><![CDATA[key]]></c> is the name of the object to look up. + <item><c>key</c> is the name of the object to look up. </item> </list> <p>On success, the function returns the value associated with - <c><![CDATA[key]]></c>. If the object is not found or if it is not a + <c>key</c>. If the object is not found or if it is not a string, <c>NULL</c> is returned. To avoid problems with in-band error reporting (that is, if you cannot distinguish between <c>NULL</c> and a valid result), use the more general function - <c><![CDATA[ei_reg_getval()]]></c> instead.</p> + <c>ei_reg_getval()</c> instead.</p> </desc> </func> @@ -245,32 +245,32 @@ object from the registry.</p> <list type="bulleted"> <item> - <p><c><![CDATA[reg]]></c> is the registry where the object will be + <p><c>reg</c> is the registry where the object will be looked up.</p> </item> <item> - <p><c><![CDATA[key]]></c> is the name of the object to look up.</p> + <p><c>key</c> is the name of the object to look up.</p> </item> <item> - <p><c><![CDATA[flags]]></c> indicates the type of object that you - are looking for. If <c><![CDATA[flags]]></c> is <c>0</c>, any + <p><c>flags</c> indicates the type of object that you + are looking for. If <c>flags</c> is <c>0</c>, any kind of object is returned. - If <c><![CDATA[flags]]></c> is <c>EI_INT</c>, <c>EI_FLT</c>, + If <c>flags</c> is <c>EI_INT</c>, <c>EI_FLT</c>, <c>EI_STR</c>, or <c>EI_BIN</c>, then only values of that kind are returned.</p> - <p>The buffer pointed to by <c><![CDATA[v]]></c> + <p>The buffer pointed to by <c>v</c> must be large enough to hold the return data, that is, it must be - a pointer to one of <c><![CDATA[int]]></c>, - <c><![CDATA[double]]></c>, <c><![CDATA[char*]]></c>, or - <c><![CDATA[void*]]></c>, respectively.</p> - <p>If <c><![CDATA[flags]]></c> is <c>EI_BIN</c>, a fifth argument - <c><![CDATA[int *size]]></c> is required, so that the size of the + a pointer to one of <c>int</c>, + <c>double</c>, <c>char*</c>, or + <c>void*</c>, respectively.</p> + <p>If <c>flags</c> is <c>EI_BIN</c>, a fifth argument + <c>int *size</c> is required, so that the size of the object can be returned.</p> </item> </list> - <p>On success, <c><![CDATA[v]]></c> (and <c><![CDATA[size]]></c> if the + <p>On success, <c>v</c> (and <c>size</c> if the object is binary) is initialized with the value associated - with <c><![CDATA[key]]></c>, and the function returns <c>EI_INT</c>, + with <c>key</c>, and the function returns <c>EI_INT</c>, <c>EI_FLT</c>, <c>EI_STR</c>, or <c>EI_BIN</c>, indicating the type of object. On failure, <c>-1</c> is returned and the arguments are not updated.</p> @@ -295,9 +295,9 @@ unmodified. This function allows you to make such modifications and then let the registry know about them.</p> <list type="bulleted"> - <item><c><![CDATA[reg]]></c> is the registry containing the object. + <item><c>reg</c> is the registry containing the object. </item> - <item><c><![CDATA[key]]></c> is the name of the object to mark. + <item><c>key</c> is the name of the object to mark. </item> </list> <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> @@ -312,14 +312,14 @@ </type> <desc> <p>Opens (creates) a registry, which initially is empty. To - close the registry later, use <c><![CDATA[ei_reg_close()]]></c>.</p> - <p><c><![CDATA[size]]></c> is the approximate number of objects you + close the registry later, use <c>ei_reg_close()</c>.</p> + <p><c>size</c> is the approximate number of objects you intend to store in the registry. As the registry uses a hash table with collision chaining, no absolute upper limit exists on the number of objects that can be stored in it. However, for reasons of efficiency, it is a good idea to choose a number that is appropriate for your needs. To change the size later, use - <c><![CDATA[ei_reg_resize()]]></c>. Notice that the number + <c>ei_reg_resize()</c>. Notice that the number you provide is increased to the nearest larger prime number.</p> <p>Returns an empty registry on success, otherwise <c>NULL</c>.</p> </desc> @@ -333,13 +333,13 @@ </type> <desc> <p>Removes all objects marked for deletion. When objects - are deleted with <c><![CDATA[ei_reg_delete()]]></c> they are not + are deleted with <c>ei_reg_delete()</c> they are not removed from the registry, only marked for later removal. On a later backup to <c>Mnesia</c>, the objects can also be removed from the <c>Mnesia</c> table. If you are not backing up to <c>Mnesia</c>, you may wish to remove the objects manually with this function.</p> - <p><c><![CDATA[reg]]></c> is a registry containing objects marked for + <p><c>reg</c> is a registry containing objects marked for deletion.</p> <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> @@ -354,7 +354,7 @@ </type> <desc> <p>Changes the size of a registry.</p> - <p><c><![CDATA[newsize]]></c> is the new size to make the registry. The + <p><c>newsize</c> is the new size to make the registry. The number is increased to the nearest larger prime number.</p> <p>On success, the registry is resized, all contents rehashed, and <c>0</c> is returned. On failure, the @@ -373,17 +373,17 @@ <desc> <p>The contents of a <c>Mnesia</c> table are read into the registry.</p> <list type="bulleted"> - <item><c><![CDATA[fd]]></c> is an open connection to Erlang. + <item><c>fd</c> is an open connection to Erlang. <c>Mnesia</c> 3.0 or later must be running on the Erlang node. </item> - <item><c><![CDATA[reg]]></c> is the registry where the data is to be + <item><c>reg</c> is the registry where the data is to be placed.</item> - <item><c><![CDATA[mntab]]></c> is the name of the <c>Mnesia</c> table + <item><c>mntab</c> is the name of the <c>Mnesia</c> table to read data from.</item> </list> <p>Notice that only tables of a certain format can be restored, that is, those that have been created and backed up to - with <c><![CDATA[ei_reg_dump()]]></c>. If the registry was not empty + with <c>ei_reg_dump()</c>. If the registry was not empty before the operation, the contents of the table are added to the contents of the registry. If the table contains objects with the same keys as those already in the registry, the registry objects @@ -407,16 +407,16 @@ <v>double f;</v> </type> <desc> - <p>Creates a key-value pair with the specified <c><![CDATA[key]]></c> - and floating point value <c><![CDATA[f]]></c>. If an object already - exists with the same <c><![CDATA[key]]></c>, the new value replaces + <p>Creates a key-value pair with the specified <c>key</c> + and floating point value <c>f</c>. If an object already + exists with the same <c>key</c>, the new value replaces the old one. If the previous value was a binary or string, it is - freed with <c><![CDATA[free()]]></c>.</p> + freed with <c>free()</c>.</p> <list type="bulleted"> - <item><c><![CDATA[reg]]></c> is the registry where the object is to be + <item><c>reg</c> is the registry where the object is to be placed.</item> - <item><c><![CDATA[key]]></c> is the object name.</item> - <item><c><![CDATA[f]]></c> is the floating point value to assign. + <item><c>key</c> is the object name.</item> + <item><c>f</c> is the floating point value to assign. </item> </list> <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> @@ -432,16 +432,16 @@ <v>int i;</v> </type> <desc> - <p>Creates a key-value pair with the specified <c><![CDATA[key]]></c> - and integer value <c><![CDATA[i]]></c>. If an object already exists - with the same <c><![CDATA[key]]></c>, the new value replaces the old + <p>Creates a key-value pair with the specified <c>key</c> + and integer value <c>i</c>. If an object already exists + with the same <c>key</c>, the new value replaces the old one. If the previous value was a binary or string, it is freed with - <c><![CDATA[free()]]></c>.</p> + <c>free()</c>.</p> <list type="bulleted"> - <item><c><![CDATA[reg]]></c> is the registry where the object is to be + <item><c>reg</c> is the registry where the object is to be placed.</item> - <item><c><![CDATA[key]]></c> is the object name.</item> - <item><c><![CDATA[i]]></c> is the integer value to assign.</item> + <item><c>key</c> is the object name.</item> + <item><c>i</c> is the integer value to assign.</item> </list> <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> @@ -457,21 +457,21 @@ <v>int size;</v> </type> <desc> - <p>Creates a key-value pair with the specified <c><![CDATA[key]]></c> - whose "value" is the binary object pointed to by <c><![CDATA[p]]></c>. - If an object already exists with the same <c><![CDATA[key]]></c>, + <p>Creates a key-value pair with the specified <c>key</c> + whose "value" is the binary object pointed to by <c>p</c>. + If an object already exists with the same <c>key</c>, the new value replaces the old one. If the previous value was a - binary or string, it is freed with <c><![CDATA[free()]]></c>.</p> + binary or string, it is freed with <c>free()</c>.</p> <list type="bulleted"> - <item><c><![CDATA[reg]]></c> is the registry where the object is to be + <item><c>reg</c> is the registry where the object is to be placed.</item> - <item><c><![CDATA[key]]></c> is the object name.</item> - <item><c><![CDATA[p]]></c> is a pointer to the binary object. The + <item><c>key</c> is the object name.</item> + <item><c>p</c> is a pointer to the binary object. The object itself must have been created through a single call to - <c><![CDATA[malloc()]]></c> or a similar function, so that the + <c>malloc()</c> or a similar function, so that the registry can later delete it if necessary by calling - <c><![CDATA[free()]]></c>.</item> - <item><c><![CDATA[size]]></c> is the length in bytes of the binary + <c>free()</c>.</item> + <item><c>size</c> is the length in bytes of the binary object.</item> </list> <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> @@ -487,20 +487,20 @@ <v>const char *s;</v> </type> <desc> - <p>Creates a key-value pair with the specified <c><![CDATA[key]]></c> - whose "value" is the specified string <c><![CDATA[s]]></c>. If an - object already exists with the same <c><![CDATA[key]]></c>, the new + <p>Creates a key-value pair with the specified <c>key</c> + whose "value" is the specified string <c>s</c>. If an + object already exists with the same <c>key</c>, the new value replaces the old one. If the previous value was a binary or - string, it is freed with <c><![CDATA[free()]]></c>.</p> + string, it is freed with <c>free()</c>.</p> <list type="bulleted"> - <item><c><![CDATA[reg]]></c> is the registry where the object is to be + <item><c>reg</c> is the registry where the object is to be placed.</item> - <item><c><![CDATA[key]]></c> is the object name.</item> - <item><c><![CDATA[s]]></c> is the string to assign. The string itself + <item><c>key</c> is the object name.</item> + <item><c>s</c> is the string to assign. The string itself must have been created through a single call to - <c><![CDATA[malloc()]]></c> or similar a function, + <c>malloc()</c> or similar a function, so that the registry can later delete it if - necessary by calling <c><![CDATA[free()]]></c>.</item> + necessary by calling <c>free()</c>.</item> </list> <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> @@ -516,36 +516,36 @@ <v>v (see below)</v> </type> <desc> - <p>Creates a key-value pair with the specified <c><![CDATA[key]]></c> - whose value is specified by <c><![CDATA[v]]></c>. If an object already - exists with the same <c><![CDATA[key]]></c>, the new value replaces + <p>Creates a key-value pair with the specified <c>key</c> + whose value is specified by <c>v</c>. If an object already + exists with the same <c>key</c>, the new value replaces the old one. If the previous value was a binary or string, it is freed - with <c><![CDATA[free()]]></c>.</p> + with <c>free()</c>.</p> <list type="bulleted"> <item> - <p><c><![CDATA[reg]]></c> is the registry where the object is to be + <p><c>reg</c> is the registry where the object is to be placed.</p> </item> <item> - <p><c><![CDATA[key]]></c> is the object name.</p> + <p><c>key</c> is the object name.</p> </item> <item> - <p><c><![CDATA[flags]]></c> indicates the type of the object - specified by <c><![CDATA[v]]></c>. Flags must be one of + <p><c>flags</c> indicates the type of the object + specified by <c>v</c>. Flags must be one of <c>EI_INT</c>, <c>EI_FLT</c>, <c>EI_STR</c>, and <c>EI_BIN</c>, indicating whether - <c><![CDATA[v]]></c> is <c><![CDATA[int]]></c>, - <c><![CDATA[double]]></c>, <c><![CDATA[char*]]></c>, or - <c><![CDATA[void*]]></c>.</p> - <p>If <c><![CDATA[flags]]></c> is <c>EI_BIN</c>, a fifth argument - <c><![CDATA[size]]></c> is required, indicating the size - in bytes of the object pointed to by <c><![CDATA[v]]></c>.</p> + <c>v</c> is <c>int</c>, + <c>double</c>, <c>char*</c>, or + <c>void*</c>.</p> + <p>If <c>flags</c> is <c>EI_BIN</c>, a fifth argument + <c>size</c> is required, indicating the size + in bytes of the object pointed to by <c>v</c>.</p> </item> </list> <p>If you wish to store an arbitrary pointer in the registry, - specify a <c><![CDATA[size]]></c> of <c>0</c>. In this case, the + specify a <c>size</c> of <c>0</c>. In this case, the object itself is not transferred by an - <c><![CDATA[ei_reg_dump()]]></c> operation, only the pointer + <c>ei_reg_dump()</c> operation, only the pointer value.</p> <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> @@ -562,11 +562,11 @@ <desc> <p>Returns information about an object.</p> <list type="bulleted"> - <item><c><![CDATA[reg]]></c> is the registry containing the object. + <item><c>reg</c> is the registry containing the object. </item> - <item><c><![CDATA[key]]></c> is the object name.</item> - <item><c><![CDATA[obuf]]></c> is a pointer to an - <c><![CDATA[ei_reg_stat]]></c> structure, defined as follows:</item> + <item><c>key</c> is the object name.</item> + <item><c>obuf</c> is a pointer to an + <c>ei_reg_stat</c> structure, defined as follows:</item> </list> <code type="none"><![CDATA[ struct ei_reg_stat { @@ -574,17 +574,17 @@ struct ei_reg_stat { int size; }; ]]></code> - <p>In <c><![CDATA[attr]]></c> the attributes of the object are stored + <p>In <c>attr</c> the attributes of the object are stored as the logical <em>OR</em> of its type (one of <c>EI_INT</c>, <c>EI_FLT</c>, <c>EI_BIN</c>, and <c>EI_STR</c>), whether it is marked for deletion (<c>EI_DELET</c>), and whether it has been modified since the last backup to <c>Mnesia</c> (<c>EI_DIRTY</c>).</p> - <p>Field <c><![CDATA[size]]></c> indicates the size in bytes required + <p>Field <c>size</c> indicates the size in bytes required to store <c>EI_STR</c> (including the terminating <c>0</c>) and <c>EI_BIN</c> objects, or <c>0</c> for <c>EI_INT</c> and <c>EI_FLT</c>.</p> - <p>Returns <c>0</c> and initializes <c><![CDATA[obuf]]></c> on success, + <p>Returns <c>0</c> and initializes <c>obuf</c> on success, otherwise <c>-1</c>.</p> </desc> </func> @@ -601,10 +601,10 @@ struct ei_reg_stat { returned by this function, you can see whether the size of the registry is suitable for the amount of data it contains.</p> <list type="bulleted"> - <item><c><![CDATA[reg]]></c> is the registry to return information + <item><c>reg</c> is the registry to return information about.</item> - <item><c><![CDATA[obuf]]></c> is a pointer to an - <c><![CDATA[ei_reg_tabstat]]></c> structure, defined as follows: + <item><c>obuf</c> is a pointer to an + <c>ei_reg_tabstat</c> structure, defined as follows: </item> </list> <code type="none"><![CDATA[ @@ -615,21 +615,21 @@ struct ei_reg_tabstat { int collisions; }; ]]></code> - <p>Field <c><![CDATA[size]]></c> indicates the number of hash positions + <p>Field <c>size</c> indicates the number of hash positions in the registry. This is the number you provided when you created or last resized the registry, rounded up to the nearest prime number.</p> <list type="bulleted"> - <item><c><![CDATA[nelem]]></c> indicates the number of elements stored + <item><c>nelem</c> indicates the number of elements stored in the registry. It includes objects that are deleted but not purged.</item> - <item><c><![CDATA[npos]]></c> indicates the number of unique positions + <item><c>npos</c> indicates the number of unique positions that are occupied in the registry.</item> - <item><c><![CDATA[collisions]]></c> indicates how many elements are + <item><c>collisions</c> indicates how many elements are sharing positions in the registry.</item> </list> <p>On success, <c>0</c> is returned and - <c><![CDATA[obuf]]></c> is initialized to contain table statistics, + <c>obuf</c> is initialized to contain table statistics, otherwise <c>-1</c> is returned.</p> </desc> </func> |