diff options
| -rw-r--r-- | lib/erl_interface/doc/src/book.xml | 11 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/ei.xml | 869 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/ei_connect.xml | 515 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/ei_users_guide.xml | 9 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/erl_call.xml | 35 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/erl_connect.xml | 373 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/erl_error.xml | 21 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/erl_eterm.xml | 169 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/erl_format.xml | 13 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/erl_global.xml | 19 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/erl_malloc.xml | 59 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/erl_marshal.xml | 35 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/ref_man.xml | 5 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/registry.xml | 617 |
14 files changed, 1369 insertions, 1381 deletions
diff --git a/lib/erl_interface/doc/src/book.xml b/lib/erl_interface/doc/src/book.xml index c9194d96ff..94bfef7455 100644 --- a/lib/erl_interface/doc/src/book.xml +++ b/lib/erl_interface/doc/src/book.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,19 +19,19 @@ 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>Erlang Interface</title> + <title>Erl_Interface</title> <prepared>Gordon Beaton</prepared> <docno></docno> <date>1998-11-30</date> <rev>1.2</rev> - <file>book.sgml</file> + <file>book.xml</file> </header> <insidecover> </insidecover> - <pagetext>Erlang Interface</pagetext> + <pagetext>Erl_Interface</pagetext> <preamble> <contents level="2"></contents> </preamble> @@ -47,4 +47,3 @@ <listofterms></listofterms> <index></index> </book> - diff --git a/lib/erl_interface/doc/src/ei.xml b/lib/erl_interface/doc/src/ei.xml index 1177954eb9..7928e4f5d1 100644 --- a/lib/erl_interface/doc/src/ei.xml +++ b/lib/erl_interface/doc/src/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 @@ -30,7 +30,7 @@ <checked></checked> <date>2000-11-27</date> <rev>PA1</rev> - <file>ei.sgml</file> + <file>ei.xml</file> </header> <lib>ei</lib> <libsummary>routines for handling the erlang binary term format</libsummary> @@ -106,149 +106,265 @@ typedef enum { </taglist> </section> <funcs> + <func> + <name><ret>int</ret><nametext>ei_decode_atom(const char *buf, int *index, char *p)</nametext></name> + <fsummary>Decode an atom.</fsummary> + <desc> + <p>This function decodes an atom from the binary format. The + null terminated name of the atom is placed at <c><![CDATA[p]]></c>. There can be at most + <c><![CDATA[MAXATOMLEN]]></c> bytes placed in the buffer.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_decode_atom_as(const char *buf, int *index, char *p, int plen, erlang_char_encoding want, erlang_char_encoding* was, erlang_char_encoding* result)</nametext></name> + <fsummary>Decode an atom.</fsummary> + <desc> + <p>This function decodes an atom from the binary format. The + null terminated name of the atom is placed in buffer at <c>p</c> of length + <c>plen</c> bytes.</p> + <p>The wanted string encoding is specified by <seealso marker="#erlang_char_encoding"> + <c>want</c></seealso>. The original encoding used in the + binary format (latin1 or utf8) can be obtained from <c>*was</c>. The actual encoding of the resulting string + (7-bit ascii, latin1 or utf8) can be obtained from <c>*result</c>. Both <c>was</c> and <c>result</c> can be <c>NULL</c>. + + <c>*result</c> may differ from <c>want</c> if <c>want</c> is a bitwise-or'd combination like + <c>ERLANG_LATIN1|ERLANG_UTF8</c> or if <c>*result</c> turn out to be pure 7-bit ascii + (compatible with both latin1 and utf8).</p> + <p>This function fails if the atom is too long for the buffer + or if it can not be represented with encoding <c>want</c>.</p> + <p>This function was introduced in R16 release of Erlang/OTP as part of a first step + to support UTF8 atoms.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_decode_bignum(const char *buf, int *index, mpz_t obj)</nametext></name> + <fsummary>Decode a GMP arbitrary precision integer.</fsummary> + <desc> + <p>This function decodes an integer in the binary format to a GMP <c><![CDATA[mpz_t]]></c> integer. + To use this function the ei library needs to be configured and compiled + to use the GMP library. </p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_decode_binary(const char *buf, int *index, void *p, long *len)</nametext></name> + <fsummary>Decode a binary.</fsummary> + <desc> + <p>This function decodes a binary from the binary format. The + <c><![CDATA[len]]></c> parameter is set to the actual size of the + binary. Note that <c><![CDATA[ei_decode_binary()]]></c> assumes that there + are enough room for the binary. The size required can be + fetched by <c><![CDATA[ei_get_type()]]></c>.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_decode_boolean(const char *buf, int *index, int *p)</nametext></name> + <fsummary>Decode a boolean.</fsummary> + <desc> + <p>This function 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> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_decode_char(const char *buf, int *index, char *p)</nametext></name> + <fsummary>Decode an 8-bit integer between 0-255.</fsummary> + <desc> + <p>This function decodes a char (8-bit) integer between 0-255 + from the binary format. + Note that for historical reasons the returned integer is of + type <c><![CDATA[char]]></c>. Your C code should consider the + returned value to be of type <c><![CDATA[unsigned char]]></c> even if + the C compilers and system may define <c><![CDATA[char]]></c> to be + signed.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_decode_double(const char *buf, int *index, double *p)</nametext></name> + <fsummary>Decode a double.</fsummary> + <desc> + <p>This function decodes an double-precision (64 bit) floating + point number from the binary format.</p> + </desc> + </func> <func> - <name><ret>void</ret><nametext>ei_set_compat_rel(release_number)</nametext></name> - <fsummary>Set the ei library in compatibility mode</fsummary> - <type> - <v>unsigned release_number;</v> - </type> + <name><ret>int</ret><nametext>ei_decode_ei_term(const char* buf, int* index, ei_term* term)</nametext></name> + <fsummary>Decode a term, without prior knowledge of type.</fsummary> <desc> - <marker id="ei_set_compat_rel"></marker> - <p>By default, the <c><![CDATA[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 - the OTP R10 release is not compatible with an Erlang emulator - from the OTP R9 release by default.</p> - <p>A call to <c><![CDATA[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> - is [7, current release]. This makes it possible to - communicate with Erlang/OTP components from earlier releases.</p> - <note> - <p>If this function is called, it may only be called once - and must be called before any other functions in the <c><![CDATA[ei]]></c> - library is called.</p> - </note> - <warning> - <p>You may run into trouble if this feature is used - carelessly. Always make sure that all communicating - components are either from the same Erlang/OTP release, or - from release X and release Y where all components - from release Y are in compatibility mode of release X.</p> - </warning> + <p>This function 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> + <p>The function returns 1 on successful decoding, -1 on error, + and 0 if the term seems alright, but does not fit in the + <c><![CDATA[term]]></c> structure. If it returns 1, the <c><![CDATA[index]]></c> + will be incremented, and the <c><![CDATA[term]]></c> contains the + decoded term.</p> + <p>The <c><![CDATA[term]]></c> structure will contain the arity for a tuple + or list, size for a binary, string or atom. It will contains + a term if it's any of the following: integer, float, atom, + pid, port or ref.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_encode_version(char *buf, int *index)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_version(ei_x_buff* x)</nametext></name> - <fsummary>Encode version</fsummary> + <name><ret>int</ret><nametext>ei_decode_fun(const char *buf, int *index, erlang_fun *p)</nametext></name> + <name><ret>void</ret><nametext>free_fun(erlang_fun* f)</nametext></name> + <fsummary>Decode a fun.</fsummary> <desc> - <p>Encodes a version magic number for the binary format. Must - be the first token in a binary term.</p> + <p>This function decodes a fun from the binary format. The + <c><![CDATA[p]]></c> parameter should be NULL 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> + is no longer needed, it should be freed with + <c><![CDATA[free_fun]]></c>. (This has to do with the arbitrary size of + the environment for a fun.)</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_encode_long(char *buf, int *index, long p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_long(ei_x_buff* x, long p)</nametext></name> - <fsummary>Encode integer</fsummary> + <name><ret>int</ret><nametext>ei_decode_list_header(const char *buf, int *index, int *arity)</nametext></name> + <fsummary>Decode a list.</fsummary> <desc> - <p>Encodes a long integer in the binary format. - Note that if the code is 64 bits the function ei_encode_long() is - exactly the same as ei_encode_longlong().</p> + <p>This function 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 follows (the last + one is the tail of the list, normally an empty list.) If + <c><![CDATA[arity]]></c> is <c><![CDATA[0]]></c>, it's an empty list.</p> + <p>Note that lists are encoded as strings, if they consist + entirely of integers in the range 0..255. This function will + not decode such strings, use <c><![CDATA[ei_decode_string()]]></c> + instead.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_encode_ulong(char *buf, int *index, unsigned long p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_ulong(ei_x_buff* x, unsigned long p)</nametext></name> - <fsummary>Encode unsigned integer</fsummary> + <name><ret>int</ret><nametext>ei_decode_long(const char *buf, int *index, long *p)</nametext></name> + <fsummary>Decode integer.</fsummary> <desc> - <p>Encodes an unsigned long integer in the binary format. - Note that if the code is 64 bits the function ei_encode_ulong() is - exactly the same as ei_encode_ulonglong().</p> + <p>This function decodes a long integer from the binary format. + Note that if the code is 64 bits the function ei_decode_long() is + exactly the same as ei_decode_longlong().</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_encode_longlong(char *buf, int *index, long long p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_longlong(ei_x_buff* x, long long p)</nametext></name> - <fsummary>Encode integer</fsummary> + <name><ret>int</ret><nametext>ei_decode_longlong(const char *buf, int *index, long long *p)</nametext></name> + <fsummary>Decode 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. Note that this function is missing - in the VxWorks port.</p> + <p>This function decodes a GCC <c><![CDATA[long long]]></c> or Visual C++ <c><![CDATA[__int64]]></c> + (64 bit) integer from the binary format. Note that this + function is missing in the VxWorks port.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_encode_ulonglong(char *buf, int *index, unsigned long long p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_ulonglong(ei_x_buff* x, unsigned long long p)</nametext></name> - <fsummary>Encode unsigned integer</fsummary> + <name><ret>int</ret><nametext>ei_decode_map_header(const char *buf, int *index, int *arity)</nametext></name> + <fsummary>Decode a map.</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 format. Note that - this function is missing in the VxWorks port.</p> + <p>This function decodes a map header from the binary + format. The number of key-value pairs is returned in + <c>*arity</c>. Keys and values follow in the following order: + <c>K1, V1, K2, V2, ..., Kn, Vn</c>. This makes a total of + <c>arity*2</c> terms. If <c>arity</c> is zero, it's an empty map. + A correctly encoded map does not have duplicate keys.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_encode_bignum(char *buf, int *index, mpz_t obj)</nametext></name> - <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> + <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> <desc> - <p>Encodes a GMP <c><![CDATA[mpz_t]]></c> integer to binary format. - To use this function the ei library needs to be configured and compiled - to use the GMP library. </p> + <p>Decodes a pid, process identifier, from the binary format.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_encode_double(char *buf, int *index, double p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_double(ei_x_buff* x, double p)</nametext></name> - <fsummary>Encode a double float</fsummary> + <name><ret>int</ret><nametext>ei_decode_port(const char *buf, int *index, erlang_port *p)</nametext></name> + <fsummary>Decode a port.</fsummary> <desc> - <p>Encodes a double-precision (64 bit) floating point number in - the binary format.</p> - <p> - The function returns <c><![CDATA[-1]]></c> if the floating point number is not finite. - </p> + <p>This function decodes a port identifier from the binary + format.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_encode_boolean(char *buf, int *index, int p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_boolean(ei_x_buff* x, int p)</nametext></name> - <fsummary>Encode a boolean</fsummary> + <name><ret>int</ret><nametext>ei_decode_ref(const char *buf, int *index, erlang_ref *p)</nametext></name> + <fsummary>Decode a reference.</fsummary> <desc> - <p>Encodes a boolean value, as the atom <c><![CDATA[true]]></c> if p is not - zero or <c><![CDATA[false]]></c> if p is zero.</p> + <p>This function decodes a reference from the binary format.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_encode_char(char *buf, int *index, char p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_char(ei_x_buff* x, char p)</nametext></name> - <fsummary>Encode an 8-bit integer between 0-255</fsummary> + <name><ret>int</ret><nametext>ei_decode_string(const char *buf, int *index, char *p)</nametext></name> + <fsummary>Decode a string.</fsummary> <desc> - <p>Encodes a char (8-bit) as an integer between 0-255 in the binary format. - Note that for historical reasons the integer argument is of - type <c><![CDATA[char]]></c>. Your C code should consider the - given 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 - signed.</p> + <p>This function decodes a string from the binary format. A + string in erlang is a list of integers between 0 and + 255. Note that since the string is just a list, sometimes + lists are encoded as strings by <c><![CDATA[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 be + allocated. The returned string is null terminated so you + need to add an extra byte to the memory requirement.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_encode_string(char *buf, int *index, const char *p)</nametext></name> - <name><ret>int</ret><nametext>ei_encode_string_len(char *buf, int *index, const char *p, int len)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_string(ei_x_buff* x, const char *p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_string_len(ei_x_buff* x, const char* s, int len)</nametext></name> - <fsummary>Encode a string</fsummary> + <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> <desc> - <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 should be zero-terminated, except for - the <c><![CDATA[ei_x_encode_string_len()]]></c> function.</p> + <p>This function 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 + <c><![CDATA[erl_interface(3)]]></c>. The term should later be + deallocated.</p> + <p>Note that this function is located in the erl_interface + library.</p> </desc> </func> <func> + <name><ret>int</ret><nametext>ei_decode_trace(const char *buf, int *index, erlang_trace *p)</nametext></name> + <fsummary>Decode a trace token.</fsummary> + <desc> + <p>Decodes an erlang trace token from the binary format.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_decode_tuple_header(const char *buf, int *index, int *arity)</nametext></name> + <fsummary>Decode a tuple.</fsummary> + <desc> + <p>This function decodes a tuple header, the number of elements + is returned in <c><![CDATA[arity]]></c>. The tuple elements follows in order in + the buffer.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_decode_ulong(const char *buf, int *index, unsigned long *p)</nametext></name> + <fsummary>Decode unsigned integer.</fsummary> + <desc> + <p>This function decodes an unsigned long integer from + the binary format. + Note that if the code is 64 bits the function ei_decode_ulong() is + exactly the same as ei_decode_ulonglong().</p> + </desc> + </func> + <func> + <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>This function decodes a GCC <c><![CDATA[unsigned long long]]></c> or Visual C++ + <c><![CDATA[unsigned __int64]]></c> (64 bit) integer from the binary format. + Note that 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>Encode an empty list (<c><![CDATA[nil]]></c>).</fsummary> + <desc> + <p>This function decodes the version magic number for the + erlang binary term format. It must be the first token in a + binary term.</p> + </desc> + </func> + + <func> <name><ret>int</ret><nametext>ei_encode_atom(char *buf, int *index, const char *p)</nametext></name> <name><ret>int</ret><nametext>ei_encode_atom_len(char *buf, int *index, const char *p, int len)</nametext></name> <name><ret>int</ret><nametext>ei_x_encode_atom(ei_x_buff* x, const char *p)</nametext></name> <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> + <fsummary>Encode an atom.</fsummary> <desc> <p>Encodes an atom in the binary format. The <c><![CDATA[p]]></c> parameter is the name of the atom in latin1 encoding. Only upto <c>MAXATOMLEN-1</c> bytes @@ -261,7 +377,7 @@ typedef enum { <name><ret>int</ret><nametext>ei_encode_atom_len_as(char *buf, int *index, const char *p, int len, erlang_char_encoding from_enc, erlang_char_encoding to_enc)</nametext></name> <name><ret>int</ret><nametext>ei_x_encode_atom_as(ei_x_buff* x, const char *p, erlang_char_encoding from_enc, erlang_char_encoding to_enc)</nametext></name> <name><ret>int</ret><nametext>ei_x_encode_atom_len_as(ei_x_buff* x, const char *p, int len, erlang_char_encoding from_enc, erlang_char_encoding to_enc)</nametext></name> - <fsummary>Encode an atom</fsummary> + <fsummary>Encode an atom.</fsummary> <desc> <p>Encodes an atom in the binary format with character encoding <seealso marker="#erlang_char_encoding"><c>to_enc</c></seealso> (latin1 or utf8). @@ -279,105 +395,83 @@ typedef enum { </desc> </func> <func> - <name><ret>int</ret><nametext>ei_encode_binary(char *buf, int *index, const void *p, long len)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_binary(ei_x_buff* x, const void *p, long len)</nametext></name> - <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> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_encode_pid(char *buf, int *index, const erlang_pid *p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_pid(ei_x_buff* x, const erlang_pid *p)</nametext></name> - <fsummary>Encode a pid</fsummary> + <name><ret>int</ret><nametext>ei_encode_bignum(char *buf, int *index, mpz_t obj)</nametext></name> + <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 an erlang process identifier, pid, in the binary - format. The <c><![CDATA[p]]></c> parameter points to an - <c><![CDATA[erlang_pid]]></c> structure (which should have been obtained - earlier with <c><![CDATA[ei_decode_pid()]]></c>).</p> + <p>Encodes a GMP <c><![CDATA[mpz_t]]></c> integer to binary format. + To use this function the ei library needs to be configured and compiled + to use the GMP library. </p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_encode_fun(char *buf, int *index, const erlang_fun *p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_fun(ei_x_buff* x, const erlang_fun* fun)</nametext></name> - <fsummary>Encode a fun</fsummary> + <name><ret>int</ret><nametext>ei_encode_binary(char *buf, int *index, const void *p, long len)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_binary(ei_x_buff* x, const void *p, long len)</nametext></name> + <fsummary>Encode a binary.</fsummary> <desc> - <p>Encodes a fun in the binary format. The <c><![CDATA[p]]></c> parameter - 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> should be called if the fun is not needed - after encoding.</p> + <p>Encodes a binary in the binary format. The data is at + <c><![CDATA[p]]></c>, of <c><![CDATA[len]]></c> bytes length.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_encode_port(char *buf, int *index, const erlang_port *p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_port(ei_x_buff* x, const erlang_port *p)</nametext></name> - <fsummary>Encodes a port</fsummary> + <name><ret>int</ret><nametext>ei_encode_boolean(char *buf, int *index, int p)</nametext></name> + <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 an erlang port in the binary format. The <c><![CDATA[p]]></c> - parameter points to a <c><![CDATA[erlang_port]]></c> structure (which - should have been obtained earlier with - <c><![CDATA[ei_decode_port()]]></c>.</p> + <p>Encodes a boolean value, as the atom <c><![CDATA[true]]></c> if p is not + zero or <c><![CDATA[false]]></c> if p is zero.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_encode_ref(char *buf, int *index, const erlang_ref *p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_ref(ei_x_buff* x, const erlang_ref *p)</nametext></name> - <fsummary>Encodes a ref</fsummary> + <name><ret>int</ret><nametext>ei_encode_char(char *buf, int *index, char p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_char(ei_x_buff* x, char p)</nametext></name> + <fsummary>Encode an 8-bit integer between 0-255.</fsummary> <desc> - <p>Encodes an erlang reference in the binary format. The - <c><![CDATA[p]]></c> parameter points to a <c><![CDATA[erlang_ref]]></c> structure - (which should have been obtained earlier with - <c><![CDATA[ei_decode_ref()]]></c>.</p> + <p>Encodes a char (8-bit) as an integer between 0-255 in the binary format. + Note that for historical reasons the integer argument is of + type <c><![CDATA[char]]></c>. Your C code should consider the + given 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 + signed.</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> + <name><ret>int</ret><nametext>ei_encode_double(char *buf, int *index, double p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_double(ei_x_buff* x, double p)</nametext></name> + <fsummary>Encode a double float.</fsummary> <desc> - <p>This function encodes an <c><![CDATA[ETERM]]></c>, as obtained from - <c><![CDATA[erl_interface]]></c>. The <c><![CDATA[t]]></c> parameter is actually an - <c><![CDATA[ETERM]]></c> pointer. This function doesn't free the - <c><![CDATA[ETERM]]></c>.</p> + <p>Encodes a double-precision (64 bit) floating point number in + the binary format.</p> + <p> + The function returns <c><![CDATA[-1]]></c> if the floating point number is not finite. + </p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_encode_trace(char *buf, int *index, const erlang_trace *p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_trace(ei_x_buff* x, const erlang_trace *p)</nametext></name> - <fsummary>Encode a trace token</fsummary> + <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> <desc> - <p>This function encodes an erlang trace token in the binary - format. The <c><![CDATA[p]]></c> parameter points to a - <c><![CDATA[erlang_trace]]></c> structure (which should have been - obtained earlier with <c><![CDATA[ei_decode_trace()]]></c>.</p> + <p>This function encodes an empty list. It's often used at the + tail of a list.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_encode_tuple_header(char *buf, int *index, int arity)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_tuple_header(ei_x_buff* x, int arity)</nametext></name> - <fsummary>Encode a tuple</fsummary> + <name><ret>int</ret><nametext>ei_encode_fun(char *buf, int *index, const erlang_fun *p)</nametext></name> + <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>This function encodes a tuple header, with a specified - arity. The next <c><![CDATA[arity]]></c> terms encoded will be the - elements of the tuple. Tuples and lists are encoded - recursively, so that a tuple may contain another tuple or - list.</p> - <p>E.g. to encode the tuple <c><![CDATA[{a, {b, {}}}]]></c>:</p> - <pre> -ei_encode_tuple_header(buf, &i, 2); -ei_encode_atom(buf, &i, "a"); -ei_encode_tuple_header(buf, &i, 2); -ei_encode_atom(buf, &i, "b"); -ei_encode_tuple_header(buf, &i, 0); - </pre> + <p>Encodes a fun in the binary format. The <c><![CDATA[p]]></c> parameter + 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> should be called if the fun is not needed + after encoding.</p> </desc> </func> <func> <name><ret>int</ret><nametext>ei_encode_list_header(char *buf, int *index, int arity)</nametext></name> <name><ret>int</ret><nametext>ei_x_encode_list_header(ei_x_buff* x, int arity)</nametext></name> - <fsummary>Encode a list</fsummary> + <fsummary>Encode a list.</fsummary> <desc> <p>This function encodes a list header, with a specified arity. The next <c><![CDATA[arity+1]]></c> terms are the elements @@ -412,18 +506,29 @@ ei_x_encode_empty_list(&x); </desc> </func> <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> + <name><ret>int</ret><nametext>ei_encode_long(char *buf, int *index, long p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_long(ei_x_buff* x, long p)</nametext></name> + <fsummary>Encode integer.</fsummary> <desc> - <p>This function encodes an empty list. It's often used at the - tail of a list.</p> + <p>Encodes a long integer in the binary format. + Note that if the code is 64 bits the function ei_encode_long() is + exactly the same as ei_encode_longlong().</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_encode_longlong(char *buf, int *index, long long p)</nametext></name> + <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. Note that this function is missing + in the VxWorks port.</p> </desc> </func> <func> <name><ret>int</ret><nametext>ei_encode_map_header(char *buf, int *index, int arity)</nametext></name> <name><ret>int</ret><nametext>ei_x_encode_map_header(ei_x_buff* x, int arity)</nametext></name> - <fsummary>Encode a map</fsummary> + <fsummary>Encode a map.</fsummary> <desc> <p>This function encodes a map header, with a specified arity. The next <c>arity*2</c> terms encoded will be the keys and values of the map @@ -441,275 +546,139 @@ ei_x_encode_string(&x, "Banana"); </desc> </func> <func> - <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>This function returns the type in <c><![CDATA[type]]></c> and size in - <c><![CDATA[size]]></c> of the encoded term. - For strings and atoms, size - is the number of characters <em>not</em> including the - terminating 0. 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> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_decode_version(const char *buf, int *index, int *version)</nametext></name> - <fsummary>Encode an empty list (<c><![CDATA[nil]]></c>)</fsummary> - <desc> - <p>This function decodes the version magic number for the - erlang binary term format. It must be the first token in a - binary term.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_decode_long(const char *buf, int *index, long *p)</nametext></name> - <fsummary>Decode integer</fsummary> - <desc> - <p>This function decodes a long integer from the binary format. - Note that if the code is 64 bits the function ei_decode_long() is - exactly the same as ei_decode_longlong().</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_decode_ulong(const char *buf, int *index, unsigned long *p)</nametext></name> - <fsummary>Decode unsigned integer</fsummary> - <desc> - <p>This function decodes an unsigned long integer from - the binary format. - Note that if the code is 64 bits the function ei_decode_ulong() is - exactly the same as ei_decode_ulonglong().</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_decode_longlong(const char *buf, int *index, long long *p)</nametext></name> - <fsummary>Decode integer</fsummary> - <desc> - <p>This function decodes a GCC <c><![CDATA[long long]]></c> or Visual C++ <c><![CDATA[__int64]]></c> - (64 bit) integer from the binary format. Note that this - function is missing in the VxWorks port.</p> - </desc> - </func> - <func> - <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>This function decodes a GCC <c><![CDATA[unsigned long long]]></c> or Visual C++ - <c><![CDATA[unsigned __int64]]></c> (64 bit) integer from the binary format. - Note that this function is missing in the VxWorks port.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_decode_bignum(const char *buf, int *index, mpz_t obj)</nametext></name> - <fsummary>Decode a GMP arbitrary precision integer</fsummary> - <desc> - <p>This function decodes an integer in the binary format to a GMP <c><![CDATA[mpz_t]]></c> integer. - To use this function the ei library needs to be configured and compiled - to use the GMP library. </p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_decode_double(const char *buf, int *index, double *p)</nametext></name> - <fsummary>Decode a double</fsummary> - <desc> - <p>This function decodes an double-precision (64 bit) floating - point number from the binary format.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_decode_boolean(const char *buf, int *index, int *p)</nametext></name> - <fsummary>Decode a boolean</fsummary> - <desc> - <p>This function 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> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_decode_char(const char *buf, int *index, char *p)</nametext></name> - <fsummary>Decode an 8-bit integer between 0-255</fsummary> - <desc> - <p>This function decodes a char (8-bit) integer between 0-255 - from the binary format. - Note that for historical reasons the returned integer is of - type <c><![CDATA[char]]></c>. Your C code should consider the - returned value to be of type <c><![CDATA[unsigned char]]></c> even if - the C compilers and system may define <c><![CDATA[char]]></c> to be - signed.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_decode_string(const char *buf, int *index, char *p)</nametext></name> - <fsummary>Decode a string</fsummary> - <desc> - <p>This function decodes a string from the binary format. A - string in erlang is a list of integers between 0 and - 255. Note that since the string is just a list, sometimes - lists are encoded as strings by <c><![CDATA[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 be - allocated. The returned string is null terminated so you - need to add an extra byte to the memory requirement.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_decode_atom(const char *buf, int *index, char *p)</nametext></name> - <fsummary>Decode an atom</fsummary> - <desc> - <p>This function decodes an atom from the binary format. The - null terminated name of the atom is placed at <c><![CDATA[p]]></c>. There can be at most - <c><![CDATA[MAXATOMLEN]]></c> bytes placed in the buffer.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_decode_atom_as(const char *buf, int *index, char *p, int plen, erlang_char_encoding want, erlang_char_encoding* was, erlang_char_encoding* result)</nametext></name> - <fsummary>Decode an atom</fsummary> - <desc> - <p>This function decodes an atom from the binary format. The - null terminated name of the atom is placed in buffer at <c>p</c> of length - <c>plen</c> bytes.</p> - <p>The wanted string encoding is specified by <seealso marker="#erlang_char_encoding"> - <c>want</c></seealso>. The original encoding used in the - binary format (latin1 or utf8) can be obtained from <c>*was</c>. The actual encoding of the resulting string - (7-bit ascii, latin1 or utf8) can be obtained from <c>*result</c>. Both <c>was</c> and <c>result</c> can be <c>NULL</c>. - - <c>*result</c> may differ from <c>want</c> if <c>want</c> is a bitwise-or'd combination like - <c>ERLANG_LATIN1|ERLANG_UTF8</c> or if <c>*result</c> turn out to be pure 7-bit ascii - (compatible with both latin1 and utf8).</p> - <p>This function fails if the atom is too long for the buffer - or if it can not be represented with encoding <c>want</c>.</p> - <p>This function was introduced in R16 release of Erlang/OTP as part of a first step - to support UTF8 atoms.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_decode_binary(const char *buf, int *index, void *p, long *len)</nametext></name> - <fsummary>Decode a binary</fsummary> + <name><ret>int</ret><nametext>ei_encode_pid(char *buf, int *index, const erlang_pid *p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_pid(ei_x_buff* x, const erlang_pid *p)</nametext></name> + <fsummary>Encode a pid.</fsummary> <desc> - <p>This function decodes a binary from the binary format. The - <c><![CDATA[len]]></c> parameter is set to the actual size of the - binary. Note that <c><![CDATA[ei_decode_binary()]]></c> assumes that there - are enough room for the binary. The size required can be - fetched by <c><![CDATA[ei_get_type()]]></c>.</p> + <p>Encodes an erlang process identifier, pid, in the binary + format. The <c><![CDATA[p]]></c> parameter points to an + <c><![CDATA[erlang_pid]]></c> structure (which should have been obtained + earlier with <c><![CDATA[ei_decode_pid()]]></c>).</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_decode_fun(const char *buf, int *index, erlang_fun *p)</nametext></name> - <name><ret>void</ret><nametext>free_fun(erlang_fun* f)</nametext></name> - <fsummary>Decode a fun</fsummary> + <name><ret>int</ret><nametext>ei_encode_port(char *buf, int *index, const erlang_port *p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_port(ei_x_buff* x, const erlang_port *p)</nametext></name> + <fsummary>Encodes a port.</fsummary> <desc> - <p>This function decodes a fun from the binary format. The - <c><![CDATA[p]]></c> parameter should be NULL 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> - is no longer needed, it should be freed with - <c><![CDATA[free_fun]]></c>. (This has to do with the arbitrary size of - the environment for a fun.)</p> + <p>Encodes an erlang port in the binary format. The <c><![CDATA[p]]></c> + parameter points to a <c><![CDATA[erlang_port]]></c> structure (which + should have been obtained earlier with + <c><![CDATA[ei_decode_port()]]></c>.</p> </desc> </func> <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> + <name><ret>int</ret><nametext>ei_encode_ref(char *buf, int *index, const erlang_ref *p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_ref(ei_x_buff* x, const erlang_ref *p)</nametext></name> + <fsummary>Encodes a ref.</fsummary> <desc> - <p>Decodes a pid, process identifier, from the binary format.</p> + <p>Encodes an erlang reference in the binary format. The + <c><![CDATA[p]]></c> parameter points to a <c><![CDATA[erlang_ref]]></c> structure + (which should have been obtained earlier with + <c><![CDATA[ei_decode_ref()]]></c>.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_decode_port(const char *buf, int *index, erlang_port *p)</nametext></name> - <fsummary>Decode a port</fsummary> + <name><ret>int</ret><nametext>ei_encode_string(char *buf, int *index, const char *p)</nametext></name> + <name><ret>int</ret><nametext>ei_encode_string_len(char *buf, int *index, const char *p, int len)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_string(ei_x_buff* x, const char *p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_string_len(ei_x_buff* x, const char* s, int len)</nametext></name> + <fsummary>Encode a string.</fsummary> <desc> - <p>This function decodes a port identifier from the binary - format.</p> + <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 should be zero-terminated, except for + the <c><![CDATA[ei_x_encode_string_len()]]></c> function.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_decode_ref(const char *buf, int *index, erlang_ref *p)</nametext></name> - <fsummary>Decode a reference</fsummary> + <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> <desc> - <p>This function decodes a reference from the binary format.</p> + <p>This function encodes an <c><![CDATA[ETERM]]></c>, as obtained from + <c><![CDATA[erl_interface]]></c>. The <c><![CDATA[t]]></c> parameter is actually an + <c><![CDATA[ETERM]]></c> pointer. This function doesn't free the + <c><![CDATA[ETERM]]></c>.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_decode_trace(const char *buf, int *index, erlang_trace *p)</nametext></name> - <fsummary>Decode a trace token</fsummary> + <name><ret>int</ret><nametext>ei_encode_trace(char *buf, int *index, const erlang_trace *p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_trace(ei_x_buff* x, const erlang_trace *p)</nametext></name> + <fsummary>Encode a trace token.</fsummary> <desc> - <p>Decodes an erlang trace token from the binary format.</p> + <p>This function encodes an erlang trace token in the binary + format. The <c><![CDATA[p]]></c> parameter points to a + <c><![CDATA[erlang_trace]]></c> structure (which should have been + obtained earlier with <c><![CDATA[ei_decode_trace()]]></c>.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_decode_tuple_header(const char *buf, int *index, int *arity)</nametext></name> - <fsummary>Decode a tuple</fsummary> + <name><ret>int</ret><nametext>ei_encode_tuple_header(char *buf, int *index, int arity)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_tuple_header(ei_x_buff* x, int arity)</nametext></name> + <fsummary>Encode a tuple.</fsummary> <desc> - <p>This function decodes a tuple header, the number of elements - is returned in <c><![CDATA[arity]]></c>. The tuple elements follows in order in - the buffer.</p> + <p>This function encodes a tuple header, with a specified + arity. The next <c><![CDATA[arity]]></c> terms encoded will be the + elements of the tuple. Tuples and lists are encoded + recursively, so that a tuple may contain another tuple or + list.</p> + <p>E.g. to encode the tuple <c><![CDATA[{a, {b, {}}}]]></c>:</p> + <pre> +ei_encode_tuple_header(buf, &i, 2); +ei_encode_atom(buf, &i, "a"); +ei_encode_tuple_header(buf, &i, 2); +ei_encode_atom(buf, &i, "b"); +ei_encode_tuple_header(buf, &i, 0); + </pre> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_decode_list_header(const char *buf, int *index, int *arity)</nametext></name> - <fsummary>Decode a list</fsummary> + <name><ret>int</ret><nametext>ei_encode_ulong(char *buf, int *index, unsigned long p)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_ulong(ei_x_buff* x, unsigned long p)</nametext></name> + <fsummary>Encode unsigned integer.</fsummary> <desc> - <p>This function 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 follows (the last - one is the tail of the list, normally an empty list.) If - <c><![CDATA[arity]]></c> is <c><![CDATA[0]]></c>, it's an empty list.</p> - <p>Note that lists are encoded as strings, if they consist - entirely of integers in the range 0..255. This function will - not decode such strings, use <c><![CDATA[ei_decode_string()]]></c> - instead.</p> + <p>Encodes an unsigned long integer in the binary format. + Note that if the code is 64 bits the function ei_encode_ulong() is + exactly the same as ei_encode_ulonglong().</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_decode_map_header(const char *buf, int *index, int *arity)</nametext></name> - <fsummary>Decode a map</fsummary> + <name><ret>int</ret><nametext>ei_encode_ulonglong(char *buf, int *index, unsigned long long p)</nametext></name> + <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>This function decodes a map header from the binary - format. The number of key-value pairs is returned in - <c>*arity</c>. Keys and values follow in the following order: - <c>K1, V1, K2, V2, ..., Kn, Vn</c>. This makes a total of - <c>arity*2</c> terms. If <c>arity</c> is zero, it's an empty map. - A correctly encoded map does not have duplicate keys.</p> + <p>Encodes a GCC <c><![CDATA[unsigned long long]]></c> or Visual C++ <c><![CDATA[unsigned __int64]]></c> (64 bit) integer in the binary format. Note that + this function is missing in the VxWorks port.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_decode_ei_term(const char* buf, int* index, ei_term* term)</nametext></name> - <fsummary>Decode a term, without prior knowledge of type</fsummary> + <name><ret>int</ret><nametext>ei_encode_version(char *buf, int *index)</nametext></name> + <name><ret>int</ret><nametext>ei_x_encode_version(ei_x_buff* x)</nametext></name> + <fsummary>Encode version.</fsummary> <desc> - <p>This function 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> - <p>The function returns 1 on successful decoding, -1 on error, - and 0 if the term seems alright, but does not fit in the - <c><![CDATA[term]]></c> structure. If it returns 1, the <c><![CDATA[index]]></c> - will be incremented, and the <c><![CDATA[term]]></c> contains the - decoded term.</p> - <p>The <c><![CDATA[term]]></c> structure will contain the arity for a tuple - or list, size for a binary, string or atom. It will contains - a term if it's any of the following: integer, float, atom, - pid, port or ref.</p> + <p>Encodes a version magic number for the binary format. Must + be the first token in a binary term.</p> </desc> </func> <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> + <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>This function 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 - <c><![CDATA[erl_interface(3)]]></c>. The term should later be - deallocated.</p> - <p>Note that this function is located in the erl_interface - library.</p> + <p>This function returns the type in <c><![CDATA[type]]></c> and size in + <c><![CDATA[size]]></c> of the encoded term. + For strings and atoms, size + is the number of characters <em>not</em> including the + terminating 0. 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> </desc> </func> <func> <name><ret>int</ret><nametext>ei_print_term(FILE* fp, const char* buf, int* index)</nametext></name> <name><ret>int</ret><nametext>ei_s_print_term(char** s, const char* buf, int* index)</nametext></name> - <fsummary>Print a term in clear text</fsummary> + <fsummary>Print a term in clear text.</fsummary> <desc> <p>This function prints a term, in clear text, to the file given by <c><![CDATA[fp]]></c>, or the buffer pointed to by <c><![CDATA[s]]></c>. It @@ -730,6 +699,67 @@ ei_x_encode_string(&x, "Banana"); </desc> </func> <func> + <name><ret>void</ret><nametext>ei_set_compat_rel(release_number)</nametext></name> + <fsummary>Set the ei library in compatibility mode.</fsummary> + <type> + <v>unsigned release_number;</v> + </type> + <desc> + <marker id="ei_set_compat_rel"></marker> + <p>By default, the <c><![CDATA[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 + the OTP R10 release is not compatible with an Erlang emulator + from the OTP R9 release by default.</p> + <p>A call to <c><![CDATA[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> + is [7, current release]. This makes it possible to + communicate with Erlang/OTP components from earlier releases.</p> + <note> + <p>If this function is called, it may only be called once + and must be called before any other functions in the <c><![CDATA[ei]]></c> + library is called.</p> + </note> + <warning> + <p>You may run into trouble if this feature is used + carelessly. Always make sure that all communicating + components are either from the same Erlang/OTP release, or + from release X and release Y where all components + from release Y are in compatibility mode of release X.</p> + </warning> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_skip_term(const char* buf, int* index)</nametext></name> + <fsummary>skip a term.</fsummary> + <desc> + <p>This function skips a term in the given buffer, it + 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 in the + buffer.</p> + <note> + <p>This can be useful when you want to hold arbitrary + terms: just skip them and copy the binary term data to some + buffer.</p> + </note> + <p>The function returns <c><![CDATA[0]]></c> on success and <c><![CDATA[-1]]></c> on + failure.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_x_append(ei_x_buff* x, const ei_x_buff* x2)</nametext></name> + <name><ret>int</ret><nametext>ei_x_append_buf(ei_x_buff* x, const char* buf, int len)</nametext></name> + <fsummary>Appends a buffer at the end.</fsummary> + <desc> + <p>These functions appends data at the end of the buffer <c><![CDATA[x]]></c>.</p> + </desc> + </func> + + <func> <name><ret>int</ret><nametext>ei_x_format(ei_x_buff* x, const char* fmt, ...)</nametext></name> <name><ret>int</ret><nametext>ei_x_format_wo_ver(ei_x_buff* x, const char *fmt, ... )</nametext></name> <fsummary>Format a term from a format string and parameters.</fsummary> @@ -761,9 +791,17 @@ encodes the tuple {numbers,12,3.14159} </desc> </func> <func> + <name><ret>int</ret><nametext>ei_x_free(ei_x_buff* x)</nametext></name> + <fsummary>Frees a buffer.</fsummary> + <desc> + <p>This function frees an <c><![CDATA[ei_x_buff]]></c> buffer. The memory + used by the buffer is returned to the OS.</p> + </desc> + </func> + <func> <name><ret>int</ret><nametext>ei_x_new(ei_x_buff* x)</nametext></name> <name><ret>int</ret><nametext>ei_x_new_with_version(ei_x_buff* x)</nametext></name> - <fsummary>Allocate a new buffer</fsummary> + <fsummary>Allocate a new buffer.</fsummary> <desc> <p>This function allocates a new <c><![CDATA[ei_x_buff]]></c> buffer. The fields of the structure pointed to by <c><![CDATA[x]]></c> parameter is @@ -773,43 +811,7 @@ encodes the tuple {numbers,12,3.14159} <c><![CDATA[ei_x_encode_version()]]></c> won't be needed.)</p> </desc> </func> - <func> - <name><ret>int</ret><nametext>ei_x_free(ei_x_buff* x)</nametext></name> - <fsummary>Frees a buffer</fsummary> - <desc> - <p>This function frees an <c><![CDATA[ei_x_buff]]></c> buffer. The memory - used by the buffer is returned to the OS.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_x_append(ei_x_buff* x, const ei_x_buff* x2)</nametext></name> - <name><ret>int</ret><nametext>ei_x_append_buf(ei_x_buff* x, const char* buf, int len)</nametext></name> - <fsummary>Appends a buffer at the end</fsummary> - <desc> - <p>These functions appends data at the end of the buffer <c><![CDATA[x]]></c>.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_skip_term(const char* buf, int* index)</nametext></name> - <fsummary>skip a term</fsummary> - <desc> - <p>This function skips a term in the given buffer, it - 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 in the - buffer.</p> - <note> - <p>This can be useful when you want to hold arbitrary - terms: just skip them and copy the binary term data to some - buffer.</p> - </note> - <p>The function returns <c><![CDATA[0]]></c> on success and <c><![CDATA[-1]]></c> on - failure.</p> - </desc> - </func> - </funcs> + </funcs> <section> <title>Debug Information</title> @@ -828,4 +830,3 @@ encodes the tuple {numbers,12,3.14159} <p>erl_interface(3)</p> </section> </cref> - diff --git a/lib/erl_interface/doc/src/ei_connect.xml b/lib/erl_interface/doc/src/ei_connect.xml index 516357b6a3..8cc08f86cd 100644 --- a/lib/erl_interface/doc/src/ei_connect.xml +++ b/lib/erl_interface/doc/src/ei_connect.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_connect</title> @@ -29,7 +29,7 @@ <checked>?</checked> <date>2001-09-01</date> <rev>A</rev> - <file>ei_connect.sgml</file> + <file>ei_connect.xml</file> </header> <lib>ei_connect</lib> <libsummary>Communicate with distributed erlang</libsummary> @@ -72,12 +72,97 @@ the operations are completed (regardless of the result). To avoid problems, leave the socket options alone. Ei will handle any socket options that need modification.</p> - <p>In all other senses, the <c><![CDATA[_tmo]]></c> functions inherit all - the return values and the semantics from the functions without + <p>In all other senses, the <c><![CDATA[_tmo]]></c> functions inherit all + the return values and the semantics from the functions without the <c><![CDATA[_tmo]]></c> suffix.</p> </section> <funcs> <func> + <name><ret>struct hostent</ret><nametext>*ei_gethostbyaddr(const char *addr, int len, int type)</nametext></name> + <name><ret>struct hostent</ret><nametext>*ei_gethostbyaddr_r(const char *addr, int length, int type, struct hostent *hostp, char *buffer, int buflen, int *h_errnop)</nametext></name> + <name><ret>struct hostent</ret><nametext>*ei_gethostbyname(const char *name)</nametext></name> + <name><ret>struct hostent</ret><nametext>*ei_gethostbyname_r(const char *name, struct hostent *hostp, char *buffer, int buflen, int *h_errnop)</nametext></name> + <fsummary>Name lookup functions.</fsummary> + <desc> + <p>These are convenience functions for some common name lookup functions.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_accept(ei_cnode *ec, int listensock, ErlConnect *conp)</nametext></name> + <fsummary>Accept a connection from another node.</fsummary> + <desc> + <p>This function is used by a server process to accept a + connection from a client process.</p> + <p><c><![CDATA[ec]]></c> is the C-node structure.</p> + <p><c><![CDATA[listensock]]></c> is an open socket descriptor on which + <c><![CDATA[listen()]]></c> has previously been called.</p> + <p><c><![CDATA[conp]]></c> is a pointer to an <c><![CDATA[ErlConnect]]></c> struct, + described as follows:</p> + <code type="none"><![CDATA[ +typedef struct { + char ipadr[4]; + char nodename[MAXNODELEN]; +} ErlConnect; + ]]></code> + <p>On success, <c><![CDATA[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> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_accept_tmo(ei_cnode *ec, int listensock, ErlConnect *conp, unsigned timeout_ms)</nametext></name> + <fsummary>Accept a connection from another node with optional timeout.</fsummary> + <desc> + <p>ei_accept with an optional timeout argument, + see the description at the beginning of this document.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_connect(ei_cnode* ec, char *nodename)</nametext></name> + <name><ret>int</ret><nametext>ei_xconnect(ei_cnode* ec, Erl_IpAddr adr, char *alivename)</nametext></name> + <fsummary>Establishe a connection to an Erlang node.</fsummary> + <desc> + <p>These functions set up a connection to an Erlang node.</p> + <p><c><![CDATA[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 + interface, and determines the information from the node name + provided.</p> + <p><c><![CDATA[addr]]></c> is the 32-bit IP address of the remote host.</p> + <p><c><![CDATA[alive]]></c> is the alivename of the remote node.</p> + <p><c><![CDATA[node]]></c> is the name of the remote node.</p> + <p>These functions return an open file descriptor on success, or + a negative value indicating that an error occurred --- in + which case they will set <c><![CDATA[erl_errno]]></c> 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> + <item>No more memory available.</item> + <tag><c><![CDATA[EIO]]></c></tag> + <item>I/O error.</item> + </taglist> + <p>Additionally, <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>Example:</p> + <code type="none"><![CDATA[ +#define NODE "[email protected]" +#define ALIVE "madonna" +#define IP_ADDR "150.236.14.75" + +/*** Variant 1 ***/ +int fd = ei_connect(&ec, NODE); + +/*** Variant 2 ***/ +struct in_addr addr; +addr.s_addr = inet_addr(IP_ADDR); +fd = ei_xconnect(&ec, &addr, ALIVE); + ]]></code> + </desc> + </func> + <func> <name><ret>int</ret><nametext>ei_connect_init(ei_cnode* ec, const char* this_node_name, const char *cookie, short creation)</nametext></name> <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> @@ -140,61 +225,58 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { </desc> </func> <func> - <name><ret>int</ret><nametext>ei_connect(ei_cnode* ec, char *nodename)</nametext></name> - <name><ret>int</ret><nametext>ei_xconnect(ei_cnode* ec, Erl_IpAddr adr, char *alivename)</nametext></name> - <fsummary>Establishe a connection to an Erlang node</fsummary> + <name><ret>int</ret><nametext>ei_connect_tmo(ei_cnode* ec, char *nodename, unsigned timeout_ms)</nametext></name> + <name><ret>int</ret><nametext>ei_xconnect_tmo(ei_cnode* ec, Erl_IpAddr adr, char *alivename, unsigned timeout_ms)</nametext></name> + <fsummary>Establish a connection to an Erlang node with optional timeout.</fsummary> <desc> - <p>These functions set up a connection to an Erlang node.</p> - <p><c><![CDATA[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 - interface, and determines the information from the node name - provided.</p> - <p><c><![CDATA[addr]]></c> is the 32-bit IP address of the remote host.</p> - <p><c><![CDATA[alive]]></c> is the alivename of the remote node.</p> - <p><c><![CDATA[node]]></c> is the name of the remote node.</p> - <p>These functions return an open file descriptor on success, or - a negative value indicating that an error occurred --- in - which case they will set <c><![CDATA[erl_errno]]></c> 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> - <item>No more memory available.</item> - <tag><c><![CDATA[EIO]]></c></tag> - <item>I/O error.</item> - </taglist> - <p>Additionally, <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>Example:</p> - <code type="none"><![CDATA[ -#define NODE "[email protected]" -#define ALIVE "madonna" -#define IP_ADDR "150.236.14.75" - -/*** Variant 1 ***/ -int fd = ei_connect(&ec, NODE); - -/*** Variant 2 ***/ -struct in_addr addr; -addr.s_addr = inet_addr(IP_ADDR); -fd = ei_xconnect(&ec, &addr, ALIVE); - ]]></code> + <p>ei_connect and ei_xconnect with an optional timeout argument, + see the description at the beginning of this document.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_connect_tmo(ei_cnode* ec, char *nodename, unsigned timeout_ms)</nametext></name> - <name><ret>int</ret><nametext>ei_xconnect_tmo(ei_cnode* ec, Erl_IpAddr adr, char *alivename, unsigned timeout_ms)</nametext></name> - <fsummary>Establish a connection to an Erlang node with optional timeout</fsummary> + <name><ret>int</ret><nametext>ei_get_tracelevel(void)</nametext></name> + <name><ret>void</ret><nametext>ei_set_tracelevel(int level)</nametext></name> + <fsummary>Get and set functions for tracing.</fsummary> <desc> - <p>ei_connect and ei_xconnect with an optional timeout argument, + <p>These functions are used to set tracing on the distribution. The levels are different verbosity levels. A higher level means more information. + See also Debug Information and <c><![CDATA[EI_TRACELEVEL]]></c> below. </p> + <p> <c><![CDATA[ei_set_tracelevel]]></c> and <c><![CDATA[ei_get_tracelevel]]></c> are not thread safe. </p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_publish(ei_cnode *ec, int port)</nametext></name> + <fsummary>Publish a node name.</fsummary> + <desc> + <p>These functions are used by a server process to register + with the local name server <em>epmd</em>, 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> on an open socket.</p> + <p><c><![CDATA[ec]]></c> is the C-node structure.</p> + <p><c><![CDATA[port]]></c> is the local name to register, and should be the + same as the port number that was previously bound to the socket.</p> + <p><c><![CDATA[addr]]></c> is the 32-bit IP address of the local host.</p> + <p>To unregister with epmd, simply close the returned + descriptor. Do not use <c><![CDATA[ei_unpublish()]]></c>, which is deprecated anyway.</p> + <p>On success, the functions return a descriptor connecting the + calling process to epmd. On failure, they return -1 and set + <c><![CDATA[erl_errno]]></c> to <c><![CDATA[EIO]]></c>.</p> + <p>Additionally, <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> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_publish_tmo(ei_cnode *ec, int port, unsigned timeout_ms)</nametext></name> + <fsummary>Publish a node name with optional timeout.</fsummary> + <desc> + <p>ei_publish with an optional timeout argument, see the description at the beginning of this document.</p> </desc> </func> <func> <name><ret>int</ret><nametext>ei_receive(int fd, unsigned char* bufp, int bufsize)</nametext></name> - <fsummary>Receive a message</fsummary> + <fsummary>Receive a message.</fsummary> <desc> <p>This function receives a message consisting of a sequence of bytes in the Erlang external format.</p> @@ -224,17 +306,44 @@ fd = ei_xconnect(&ec, &addr, ALIVE); </desc> </func> <func> - <name><ret>int</ret><nametext>ei_receive_tmo(int fd, unsigned char* bufp, int bufsize, unsigned timeout_ms)</nametext></name> - <fsummary>Receive a message with optional timeout</fsummary> + <name><ret>int</ret><nametext>ei_receive_encoded(int fd, char **mbufp, int *bufsz, erlang_msg *msg, int *msglen)</nametext></name> + <fsummary>Obsolete function for receiving a message.</fsummary> <desc> - <p>ei_receive with an optional timeout argument, + <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>In essence the function performs the same operation as + <c><![CDATA[ei_xreceive_msg]]></c>, but instead of using an ei_x_buff, the + function expects a pointer to a character pointer + (<c><![CDATA[mbufp]]></c>), where the character pointer should point to a + memory area allocated by <c><![CDATA[malloc]]></c>. The argument + <c><![CDATA[bufsz]]></c> should 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> + <p>Furthermore the function returns either ERL_TICK or the + <c><![CDATA[msgtype]]></c> field of the <c><![CDATA[erlang_msg *msg]]></c>. The actual + length of the message is put in <c><![CDATA[*msglen]]></c>. On error it + will return a value <c><![CDATA[< 0]]></c>.</p> + <p>It is recommended to use ei_xreceive_msg instead when + possible, for the sake of readability. The function will + however be retained in the interface for compatibility and + will <em>not</em> be removed not be removed in future releases + without notice.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_receive_encoded_tmo(int fd, char **mbufp, int *bufsz, erlang_msg *msg, int *msglen, unsigned timeout_ms)</nametext></name> + <fsummary>Obsolete function for receiving a message with timeout.</fsummary> + <desc> + <p>ei_receive_encoded with an optional timeout argument, see the description at the beginning of this document.</p> </desc> </func> <func> <name><ret>int</ret><nametext>ei_receive_msg(int fd, erlang_msg* msg, ei_x_buff* x)</nametext></name> <name><ret>int</ret><nametext>ei_xreceive_msg(int fd, erlang_msg* msg, ei_x_buff* x)</nametext></name> - <fsummary>Receive a message</fsummary> + <fsummary>Receive a message.</fsummary> <desc> <p>These functions receives a message to the buffer in <c><![CDATA[x]]></c>. <c><![CDATA[ei_xreceive_msg]]></c> allows the buffer in @@ -279,90 +388,23 @@ typedef struct { <func> <name><ret>int</ret><nametext>ei_receive_msg_tmo(int fd, erlang_msg* msg, ei_x_buff* x, unsigned imeout_ms)</nametext></name> <name><ret>int</ret><nametext>ei_xreceive_msg_tmo(int fd, erlang_msg* msg, ei_x_buff* x, unsigned timeout_ms)</nametext></name> - <fsummary>Receive a message with optional timeout</fsummary> + <fsummary>Receive a message with optional timeout.</fsummary> <desc> <p>ei_receive_msg and ei_xreceive_msg with an optional timeout argument, see the description at the beginning of this document.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_receive_encoded(int fd, char **mbufp, int *bufsz, erlang_msg *msg, int *msglen)</nametext></name> - <fsummary>Obsolete function for receiving a message</fsummary> - <desc> - <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>In essence the function performs the same operation as - <c><![CDATA[ei_xreceive_msg]]></c>, but instead of using an ei_x_buff, the - function expects a pointer to a character pointer - (<c><![CDATA[mbufp]]></c>), where the character pointer should point to a - memory area allocated by <c><![CDATA[malloc]]></c>. The argument - <c><![CDATA[bufsz]]></c> should 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> - <p>Furthermore the function returns either ERL_TICK or the - <c><![CDATA[msgtype]]></c> field of the <c><![CDATA[erlang_msg *msg]]></c>. The actual - length of the message is put in <c><![CDATA[*msglen]]></c>. On error it - will return a value <c><![CDATA[< 0]]></c>.</p> - <p>It is recommended to use ei_xreceive_msg instead when - possible, for the sake of readability. The function will - however be retained in the interface for compatibility and - will <em>not</em> be removed not be removed in future releases - without notice.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_receive_encoded_tmo(int fd, char **mbufp, int *bufsz, erlang_msg *msg, int *msglen, unsigned timeout_ms)</nametext></name> - <fsummary>Obsolete function for receiving a message with timeout</fsummary> - <desc> - <p>ei_receive_encoded with an optional timeout argument, - see the description at the beginning of this document.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_send(int fd, erlang_pid* to, char* buf, int len)</nametext></name> - <fsummary>Send a message</fsummary> - <desc> - <p>This function sends an Erlang term to a process.</p> - <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.</p> - <p><c><![CDATA[to]]></c> is the Pid of the intended recipient of the - message.</p> - <p><c><![CDATA[buf]]></c> is the buffer containing the term in binary - format.</p> - <p><c><![CDATA[len]]></c> is the length of the message in bytes.</p> - <p>The function returns 0 if successful, otherwise -1, in the - latter case it will set <c><![CDATA[erl_errno]]></c> to <c><![CDATA[EIO]]></c>.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_send_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms)</nametext></name> - <fsummary>Send a message with optional timeout</fsummary> - <desc> - <p>ei_send with an optional timeout argument, - see the description at the beginning of this document.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_send_encoded(int fd, erlang_pid* to, char* buf, int len)</nametext></name> - <fsummary>Obsolete function to send a message</fsummary> - <desc> - <p>Works exactly as ei_send, the alternative name retained for - backward compatibility. The function will <em>not</em> be - removed without notice.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_send_encoded_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms)</nametext></name> - <fsummary>Obsolete function to send a message with optional timeout</fsummary> + <name><ret>int</ret><nametext>ei_receive_tmo(int fd, unsigned char* bufp, int bufsize, unsigned timeout_ms)</nametext></name> + <fsummary>Receive a message with optional timeout.</fsummary> <desc> - <p>ei_send_encoded with an optional timeout argument, + <p>ei_receive with an optional timeout argument, see the description at the beginning of this document.</p> </desc> </func> <func> <name><ret>int</ret><nametext>ei_reg_send(ei_cnode* ec, int fd, char* server_name, char* buf, int len)</nametext></name> - <fsummary>Send a message to a registered name</fsummary> + <fsummary>Send a message to a registered name.</fsummary> <desc> <p>This function sends an Erlang term to a registered process. </p> @@ -387,49 +429,17 @@ if (ei_reg_send(&ec, fd, x.buff, x.index) < 0) </func> <func> <name><ret>int</ret><nametext>ei_reg_send_tmo(ei_cnode* ec, int fd, char* server_name, char* buf, int len, unsigned timeout_ms)</nametext></name> - <fsummary>Send a message to a registered name with optional timeout</fsummary> + <fsummary>Send a message to a registered name with optional timeout.</fsummary> <desc> <p>ei_reg_send with an optional timeout argument, see the description at the beginning of this document.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_send_reg_encoded(int fd, const erlang_pid *from, const char *to, const char *buf, int len)</nametext></name> - <fsummary>Obsolete function to send a message to a registered name</fsummary> - <desc> - <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 the <c><![CDATA[ei_cnode]]></c> as a first - argument, it takes a second argument, an <c><![CDATA[erlang_pid]]></c> - which should 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 code:</p> - <code type="none"><![CDATA[ - ei_cnode ec; - erlang_pid *self; - int fd; /* the connection fd */ - ... - self = ei_self(&ec); - self->num = fd; - ]]></code> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_send_reg_encoded_tmo(int fd, const erlang_pid *from, const char *to, const char *buf, int len)</nametext></name> - <fsummary>Obsolete function to send a message to a registered name with timeout</fsummary> - <desc> - <p>ei_send_reg_encoded with an optional timeout argument, - see the description at the beginning of this document.</p> - </desc> - </func> - <func> <name><ret>int</ret><nametext>ei_rpc(ei_cnode *ec, int fd, char *mod, char *fun, const char *argbuf, int argbuflen, ei_x_buff *x)</nametext></name> <name><ret>int</ret><nametext>ei_rpc_to(ei_cnode *ec, int fd, char *mod, char *fun, const char *argbuf, int argbuflen)</nametext></name> <name><ret>int</ret><nametext>ei_rpc_from(ei_cnode *ec, int fd, int timeout, erlang_msg *msg, ei_x_buff *x)</nametext></name> - <fsummary>Remote Procedure Call from C to Erlang</fsummary> + <fsummary>Remote Procedure Call from C to Erlang.</fsummary> <desc> <p>These functions support calling Erlang functions on remote nodes. <c><![CDATA[ei_rpc_to()]]></c> sends an rpc request to a remote node and @@ -496,95 +506,85 @@ if (ei_decode_version(result.buff, &index) < 0 </desc> </func> <func> - <name><ret>int</ret><nametext>ei_publish(ei_cnode *ec, int port)</nametext></name> - <fsummary>Publish a node name</fsummary> + <name><ret>erlang_pid *</ret><nametext>ei_self(ei_cnode *ec)</nametext></name> + <fsummary>Retrieve the Pid of the C-node.</fsummary> <desc> - <p>These functions are used by a server process to register - with the local name server <em>epmd</em>, 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> on an open socket.</p> - <p><c><![CDATA[ec]]></c> is the C-node structure.</p> - <p><c><![CDATA[port]]></c> is the local name to register, and should be the - same as the port number that was previously bound to the socket.</p> - <p><c><![CDATA[addr]]></c> is the 32-bit IP address of the local host.</p> - <p>To unregister with epmd, simply close the returned - descriptor. Do not use <c><![CDATA[ei_unpublish()]]></c>, which is deprecated anyway.</p> - <p>On success, the functions return a descriptor connecting the - calling process to epmd. On failure, they return -1 and set - <c><![CDATA[erl_errno]]></c> to <c><![CDATA[EIO]]></c>.</p> - <p>Additionally, <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>This function 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> + structure. It will be safe for a long time to fetch this + field directly from the <c><![CDATA[ei_cnode]]></c> structure.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_publish_tmo(ei_cnode *ec, int port, unsigned timeout_ms)</nametext></name> - <fsummary>Publish a node name with optional timeout</fsummary> + <name><ret>int</ret><nametext>ei_send(int fd, erlang_pid* to, char* buf, int len)</nametext></name> + <fsummary>Send a message.</fsummary> <desc> - <p>ei_publish with an optional timeout argument, - see the description at the beginning of this document.</p> + <p>This function sends an Erlang term to a process.</p> + <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.</p> + <p><c><![CDATA[to]]></c> is the Pid of the intended recipient of the + message.</p> + <p><c><![CDATA[buf]]></c> is the buffer containing the term in binary + format.</p> + <p><c><![CDATA[len]]></c> is the length of the message in bytes.</p> + <p>The function returns 0 if successful, otherwise -1, in the + latter case it will set <c><![CDATA[erl_errno]]></c> to <c><![CDATA[EIO]]></c>.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_accept(ei_cnode *ec, int listensock, ErlConnect *conp)</nametext></name> - <fsummary>Accept a connection from another node</fsummary> + <name><ret>int</ret><nametext>ei_send_encoded(int fd, erlang_pid* to, char* buf, int len)</nametext></name> + <fsummary>Obsolete function to send a message.</fsummary> <desc> - <p>This function is used by a server process to accept a - connection from a client process.</p> - <p><c><![CDATA[ec]]></c> is the C-node structure.</p> - <p><c><![CDATA[listensock]]></c> is an open socket descriptor on which - <c><![CDATA[listen()]]></c> has previously been called.</p> - <p><c><![CDATA[conp]]></c> is a pointer to an <c><![CDATA[ErlConnect]]></c> struct, - described as follows:</p> - <code type="none"><![CDATA[ -typedef struct { - char ipadr[4]; - char nodename[MAXNODELEN]; -} ErlConnect; - ]]></code> - <p>On success, <c><![CDATA[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> + <p>Works exactly as ei_send, the alternative name retained for + backward compatibility. The function will <em>not</em> be + removed without notice.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_accept_tmo(ei_cnode *ec, int listensock, ErlConnect *conp, unsigned timeout_ms)</nametext></name> - <fsummary>Accept a connection from another node with optional timeout</fsummary> + <name><ret>int</ret><nametext>ei_send_encoded_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms)</nametext></name> + <fsummary>Obsolete function to send a message with optional timeout.</fsummary> <desc> - <p>ei_accept with an optional timeout argument, + <p>ei_send_encoded with an optional timeout argument, see the description at the beginning of this document.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_unpublish(ei_cnode *ec)</nametext></name> - <fsummary>Forcefully unpublish a node name</fsummary> + <name><ret>int</ret><nametext>ei_send_reg_encoded(int fd, const erlang_pid *from, const char *to, const char *buf, int len)</nametext></name> + <fsummary>Obsolete function to send a message to a registered name.</fsummary> <desc> - <p>This function can be called by a process to unregister a - specified node from epmd on the localhost. This is however usually not - allowed, unless epmd was started with the -relaxed_command_check - flag, which it normally isn't.</p> - - <p>To unregister a node you have published, you should - close the descriptor that was returned by - <c><![CDATA[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 unregister.</p> - <p>If the node was successfully unregistered from epmd, the - function returns 0. Otherwise, it returns -1 and sets - <c><![CDATA[erl_errno]]></c> is to <c><![CDATA[EIO]]></c>.</p> + <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 the <c><![CDATA[ei_cnode]]></c> as a first + argument, it takes a second argument, an <c><![CDATA[erlang_pid]]></c> + which should 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 code:</p> + <code type="none"><![CDATA[ + ei_cnode ec; + erlang_pid *self; + int fd; /* the connection fd */ + ... + self = ei_self(&ec); + self->num = fd; + ]]></code> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_unpublish_tmo(ei_cnode *ec, unsigned timeout_ms)</nametext></name> - <fsummary>Unpublish a node name with optional timeout</fsummary> + <name><ret>int</ret><nametext>ei_send_reg_encoded_tmo(int fd, const erlang_pid *from, const char *to, const char *buf, int len)</nametext></name> + <fsummary>Obsolete function to send a message to a registered name with timeout.</fsummary> <desc> - <p>ei_unpublish with an optional timeout argument, + <p>ei_send_reg_encoded with an optional timeout argument, + see the description at the beginning of this document.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_send_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms)</nametext></name> + <fsummary>Send a message with optional timeout.</fsummary> + <desc> + <p>ei_send with an optional timeout argument, see the description at the beginning of this document.</p> </desc> </func> @@ -592,7 +592,7 @@ typedef struct { <name><ret>const char *</ret><nametext>ei_thisnodename(ei_cnode *ec)</nametext></name> <name><ret>const char *</ret><nametext>ei_thishostname(ei_cnode *ec)</nametext></name> <name><ret>const char *</ret><nametext>ei_thisalivename(ei_cnode *ec)</nametext></name> - <fsummary>Retrieve some values</fsummary> + <fsummary>Retrieve some values.</fsummary> <desc> <p>These functions can be used to retrieve information about the C Node. These values are initially set with @@ -603,37 +603,37 @@ typedef struct { </desc> </func> <func> - <name><ret>erlang_pid *</ret><nametext>ei_self(ei_cnode *ec)</nametext></name> - <fsummary>Retrieve the Pid of the C-node</fsummary> - <desc> - <p>This function 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> - structure. It will be safe for a long time to fetch this - field directly from the <c><![CDATA[ei_cnode]]></c> structure.</p> - </desc> - </func> - <func> - <name><ret>struct hostent</ret><nametext>*ei_gethostbyname(const char *name)</nametext></name> - <name><ret>struct hostent</ret><nametext>*ei_gethostbyaddr(const char *addr, int len, int type)</nametext></name> - <name><ret>struct hostent</ret><nametext>*ei_gethostbyname_r(const char *name, struct hostent *hostp, char *buffer, int buflen, int *h_errnop)</nametext></name> - <name><ret>struct hostent</ret><nametext>*ei_gethostbyaddr_r(const char *addr, int length, int type, struct hostent *hostp, char *buffer, int buflen, int *h_errnop)</nametext></name> - <fsummary>Name lookup functions</fsummary> + <name><ret>int</ret><nametext>ei_unpublish(ei_cnode *ec)</nametext></name> + <fsummary>Forcefully unpublish a node name.</fsummary> <desc> - <p>These are convenience functions for some common name lookup functions.</p> + <p>This function can be called by a process to unregister a + specified node from epmd on the localhost. This is however usually not + allowed, unless epmd was started with the -relaxed_command_check + flag, which it normally isn't.</p> + + <p>To unregister a node you have published, you should + close the descriptor that was returned by + <c><![CDATA[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 unregister.</p> + <p>If the node was successfully unregistered from epmd, the + function returns 0. Otherwise, it returns -1 and sets + <c><![CDATA[erl_errno]]></c> is to <c><![CDATA[EIO]]></c>.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_get_tracelevel(void)</nametext></name> - <name><ret>void</ret><nametext>ei_set_tracelevel(int level)</nametext></name> - <fsummary>Get and set functions for tracing.</fsummary> + <name><ret>int</ret><nametext>ei_unpublish_tmo(ei_cnode *ec, unsigned timeout_ms)</nametext></name> + <fsummary>Unpublish a node name with optional timeout.</fsummary> <desc> - <p>These functions are used to set tracing on the distribution. The levels are different verbosity levels. A higher level means more information. - See also Debug Information and <c><![CDATA[EI_TRACELEVEL]]></c> below. </p> - <p> <c><![CDATA[ei_set_tracelevel]]></c> and <c><![CDATA[ei_get_tracelevel]]></c> are not thread safe. </p> + <p>ei_unpublish with an optional timeout argument, + see the description at the beginning of this document.</p> </desc> </func> - </funcs> + </funcs> <section> <title>Debug Information</title> @@ -652,13 +652,12 @@ typedef struct { <c><![CDATA[ei_set_tracelevel]]></c> or by setting the environment variable <c><![CDATA[EI_TRACELEVEL]]></c>. The different tracelevels has the following messages:</p> <list> - <item>1: Verbose error messages</item> - <item>2: Above messages and verbose warning messages </item> - <item>3: Above messages and progress reports for connection handling</item> - <item>4: Above messages and progress reports for communication</item> - <item>5: Above messages and progress reports for data conversion</item> + <item>1: Verbose error messages</item> + <item>2: Above messages and verbose warning messages</item> + <item>3: Above messages and progress reports for connection handling</item> + <item>4: Above messages and progress reports for communication</item> + <item>5: Above messages and progress reports for data conversion</item> </list> </section> </cref> - diff --git a/lib/erl_interface/doc/src/ei_users_guide.xml b/lib/erl_interface/doc/src/ei_users_guide.xml index 4b9809aee4..4beb4c6c73 100644 --- a/lib/erl_interface/doc/src/ei_users_guide.xml +++ b/lib/erl_interface/doc/src/ei_users_guide.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>The El Library User's Guide</title> @@ -77,7 +77,7 @@ Eshell V4.7.4 (abort with ^G) 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 - the version of the Erl_interface application, for example + the version of the Erl_interface application, for example <c><![CDATA[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> @@ -147,7 +147,7 @@ i = erl_encode(tuple, buf); ]]></code> <section> <title>Building Terms and Patterns</title> - <p>The previous example can be simplified by using + <p>The previous example can be simplified by using <c><![CDATA[erl_format()]]></c> to create an Erlang term.</p> <code type="none"><![CDATA[ @@ -610,4 +610,3 @@ ei_reg_restore(fd, reg, "mtab"); ]]></code> </section> </section> </chapter> - diff --git a/lib/erl_interface/doc/src/erl_call.xml b/lib/erl_interface/doc/src/erl_call.xml index 46015621ac..f8fe409560 100644 --- a/lib/erl_interface/doc/src/erl_call.xml +++ b/lib/erl_interface/doc/src/erl_call.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 @@ -30,14 +30,14 @@ <checked>Torbjörn Törnkvist</checked> <date>97-05-16</date> <rev>B</rev> - <file>erl_call.sgml</file> + <file>erl_call.xml</file> </header> <com>erl_call</com> - <comsummary>Call/Start a Distributed Erlang Node</comsummary> + <comsummary>Call/start a distributed Erlang node.</comsummary> <description> - <p><c><![CDATA[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. Its purpose is to use an Unix shell script to interact with a distributed Erlang node. It performs all + <p><c><![CDATA[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. Its purpose is to use an 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 require any special software to be run at the Erlang target node.</p> <p>The main use is to either start a distributed Erlang node @@ -46,17 +46,17 @@ 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 with - advantage - as scripts from within (Unix) shell scripts. Another + 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> </description> <funcs> <func> <name>erl_call <options></name> - <fsummary>Start/Call Erlang</fsummary> + <fsummary>Start/call Erlang.</fsummary> <desc> <p>Each option flag is described below with its name, type and - meaning. </p> + meaning.</p> <taglist> <tag>-a [Mod [Fun [Args]]]]</tag> <item> @@ -85,7 +85,7 @@ <item> <p>(<em>optional</em>): Reads a sequence of Erlang expressions, separated by '<em>,</em>' and ended with a '<em>.</em>', from <c><![CDATA[stdin]]></c> until - EOF (Control-D). Evaluates the expressions and returns the result from + EOF (Control-D). Evaluates the expressions and returns the result from the last expression. Returns <c><![CDATA[{ok,Result}]]></c> if successful.</p> <p></p> </item> @@ -103,18 +103,18 @@ </item> <tag>-n Node</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 used for + <p>(one of <c><![CDATA[-n, -name, -sname]]></c> is required): + Has the same meaning as <c><![CDATA[-name]]></c> and can still be used for backwards compatibility reasons.</p> <p></p> </item> <tag>-name Node</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 -name]]></c>, which means that fully - qualified long node names are used. - If the <c><![CDATA[-s]]></c> option is given, an Erlang node will (if necessary) + started or communicated with. It is assumed that + <c><![CDATA[Node]]></c> is started with <c><![CDATA[erl -name]]></c>, which means that fully + qualified long node names are used. + If the <c><![CDATA[-s]]></c> option is given, an Erlang node will (if necessary) be started with <c><![CDATA[erl -name]]></c>.</p> <p></p> </item> @@ -238,4 +238,3 @@ start() -> ]]></code> </section> </comref> - diff --git a/lib/erl_interface/doc/src/erl_connect.xml b/lib/erl_interface/doc/src/erl_connect.xml index 0fad98cd17..0799e30905 100644 --- a/lib/erl_interface/doc/src/erl_connect.xml +++ b/lib/erl_interface/doc/src/erl_connect.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>erl_connect</title> @@ -30,7 +30,7 @@ <checked>Torbjörn Törnkvist</checked> <date>980703</date> <rev>A</rev> - <file>erl_connect.sgml</file> + <file>erl_connect.xml</file> </header> <lib>erl_connect</lib> <libsummary>Communicate with Distributed Erlang</libsummary> @@ -47,9 +47,98 @@ </description> <funcs> <func> + <name><ret>int</ret><nametext>erl_accept(listensock, conp)</nametext></name> + <fsummary>Accept a connection.</fsummary> + <type> + <v>int listensock;</v> + <v>ErlConnect *conp;</v> + </type> + <desc> + <p>This function is used by a server process to accept a + connection from a client process.</p> + <p><c><![CDATA[listensock]]></c> is an open socket descriptor on which + <c><![CDATA[listen()]]></c> has previously been called.</p> + <p><c><![CDATA[conp]]></c> is a pointer to an <c><![CDATA[ErlConnect]]></c> struct, + described as follows:</p> + <code type="none"><![CDATA[ +typedef struct { + char ipadr[4]; + char nodename[MAXNODELEN]; +} ErlConnect; + ]]></code> + <p>On success, <c><![CDATA[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> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>erl_close_connection(fd)</nametext></name> + <fsummary>Close a connection to an Erlang node.</fsummary> + <type> + <v>int fd;</v> + </type> + <desc> + <p>This function 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>On success, 0 is returned. 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> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>erl_connect(node)</nametext></name> + <name><ret>int</ret><nametext>erl_xconnect(addr, alive)</nametext></name> + <fsummary>Establishe a connection to an Erlang node.</fsummary> + <type> + <v>char *node, *alive;</v> + <v>struct in_addr *addr;</v> + </type> + <desc> + <p>These functions set up a connection to an Erlang node.</p> + <p><c><![CDATA[erl_xconnect()]]></c> requires the IP address of the remote + host and the alive name of the remote node + to be specified. <c><![CDATA[erl_connect()]]></c> provides an alternative + interface, and determines the information from the node name + provided.</p> + <p><c><![CDATA[addr]]></c> is the 32-bit IP address of the remote host.</p> + <p><c><![CDATA[alive]]></c> is the alivename of the remote node.</p> + <p><c><![CDATA[node]]></c> is the name of the remote node.</p> + <p>These functions return an open file descriptor on success, or + a negative value indicating that an error occurred --- in + which case they will set <c><![CDATA[erl_errno]]></c> 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> + <item>No more memory available.</item> + <tag><c><![CDATA[EIO]]></c></tag> + <item>I/O error.</item> + </taglist> + <p>Additionally, <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> + <code type="none"><![CDATA[ +#define NODE "[email protected]" +#define ALIVE "madonna" +#define IP_ADDR "150.236.14.75" + +/*** Variant 1 ***/ +erl_connect( NODE ); + +/*** Variant 2 ***/ +struct in_addr addr; +addr = inet_addr(IP_ADDR); +erl_xconnect( &addr , ALIVE ); + ]]></code> + </desc> + </func> + <func> <name><ret>int</ret><nametext>erl_connect_init(number, cookie, creation)</nametext></name> <name><ret>int</ret><nametext>erl_connect_xinit(host, alive, node, addr, cookie, creation)</nametext></name> - <fsummary>Initialize communication</fsummary> + <fsummary>Initialize communication.</fsummary> <type> <v>int number;</v> <v>char *cookie;</v> @@ -61,7 +150,7 @@ <p>These functions initialize the <c><![CDATA[erl_connect]]></c> module. In particular, they 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 erl_connect + be called before any of the other functions in the erl_connect module are used.</p> <p><c><![CDATA[erl_connect_xinit()]]></c> stores for later use information about the node's host name <c><![CDATA[host]]></c>, alive name <c><![CDATA[alive]]></c>, node @@ -69,12 +158,12 @@ and creation number <c><![CDATA[creation]]></c>. <c><![CDATA[erl_connect_init()]]></c> provides an alternative interface which 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. + uses <c><![CDATA[gethostbyname()]]></c> to obtain default values. </p> <p>If you use <c><![CDATA[erl_connect_init()]]></c> your node will have a short name, i.e., it will not be fully qualified. If you need to use fully qualified (a.k.a. long) names, use - <c><![CDATA[erl_connect_xinit()]]></c> instead. + <c><![CDATA[erl_connect_xinit()]]></c> instead. </p> <p><c><![CDATA[host]]></c> is the name of the host on which the node is running.</p> <p><c><![CDATA[alive]]></c> is the alivename of the node.</p> @@ -118,71 +207,38 @@ if (!erl_connect_init(17, "samplecookiestring...", 0)) </desc> </func> <func> - <name><ret>int</ret><nametext>erl_connect(node)</nametext></name> - <name><ret>int</ret><nametext>erl_xconnect(addr, alive)</nametext></name> - <fsummary>Establishe a connection to an Erlang node</fsummary> + <name><ret>int</ret><nametext>erl_publish(port)</nametext></name> + <fsummary>Publish a node name.</fsummary> <type> - <v>char *node, *alive;</v> - <v>struct in_addr *addr;</v> + <v>int port;</v> </type> <desc> - <p>These functions set up a connection to an Erlang node.</p> - <p><c><![CDATA[erl_xconnect()]]></c> requires the IP address of the remote - host and the alive name of the remote node - to be specified. <c><![CDATA[erl_connect()]]></c> provides an alternative - interface, and determines the information from the node name - provided.</p> - <p><c><![CDATA[addr]]></c> is the 32-bit IP address of the remote host.</p> - <p><c><![CDATA[alive]]></c> is the alivename of the remote node.</p> - <p><c><![CDATA[node]]></c> is the name of the remote node.</p> - <p>These functions return an open file descriptor on success, or - a negative value indicating that an error occurred --- in - which case they will set <c><![CDATA[erl_errno]]></c> to one of:</p> + <p>These functions are used by a server process to register + with the local name server <em>epmd</em>, 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> on an open socket.</p> + <p><c><![CDATA[port]]></c> is the local name to register, and should 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, the functions return a descriptor connecting the + calling process to epmd. On failure, they return -1 and set + <c><![CDATA[erl_errno]]></c> to:</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> - <item>No more memory available.</item> <tag><c><![CDATA[EIO]]></c></tag> - <item>I/O error.</item> + <item>I/O error</item> </taglist> - <p>Additionally, <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> - <code type="none"><![CDATA[ -#define NODE "[email protected]" -#define ALIVE "madonna" -#define IP_ADDR "150.236.14.75" - -/*** Variant 1 ***/ -erl_connect( NODE ); - -/*** Variant 2 ***/ -struct in_addr addr; -addr = inet_addr(IP_ADDR); -erl_xconnect( &addr , ALIVE ); - ]]></code> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>erl_close_connection(fd)</nametext></name> - <fsummary>Close a connection to an Erlang node</fsummary> - <type> - <v>int fd;</v> - </type> - <desc> - <p>This function 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>On success, 0 is returned. 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> + <p>Additionally, <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> </desc> </func> <func> <name><ret>int</ret><nametext>erl_receive(fd, bufp, bufsize)</nametext></name> - <fsummary>Receive a message</fsummary> + <fsummary>Receive a message.</fsummary> <type> <v>int fd;</v> <v>char *bufp;</v> @@ -216,7 +272,7 @@ erl_xconnect( &addr , ALIVE ); </func> <func> <name><ret>int</ret><nametext>erl_receive_msg(fd, bufp, bufsize, emsg)</nametext></name> - <fsummary>Receive and decodes a message</fsummary> + <fsummary>Receive and decodes a message.</fsummary> <type> <v>int fd;</v> <v>unsigned char *bufp;</v> @@ -224,7 +280,7 @@ erl_xconnect( &addr , ALIVE ); <v>ErlMessage *emsg;</v> </type> <desc> - <p>This function receives the message into the specified buffer, + <p>This function receives the message into the specified buffer, and decodes into the <c><![CDATA[(ErlMessage *) emsg]]></c>.</p> <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.</p> <p><c><![CDATA[bufp]]></c> is a buffer large enough to hold the expected message.</p> @@ -245,9 +301,9 @@ typedef struct { <p>The definition of <c><![CDATA[ErlMessage]]></c> has changed since earlier versions of Erl_Interface.</p> </note> - <p><c><![CDATA[type]]></c> identifies the type of message, one of + <p><c><![CDATA[type]]></c> identifies the type of message, one of <c><![CDATA[ERL_SEND]]></c>, <c><![CDATA[ERL_REG_SEND]]></c>, <c><![CDATA[ERL_LINK]]></c>, - <c><![CDATA[ERL_UNLINK]]></c> and <c><![CDATA[ERL_EXIT]]></c>. + <c><![CDATA[ERL_UNLINK]]></c> and <c><![CDATA[ERL_EXIT]]></c>. </p> <p>If <c><![CDATA[type]]></c> contains <c><![CDATA[ERL_SEND]]></c> this indicates that an ordinary send operation has taken @@ -295,65 +351,8 @@ typedef struct { </desc> </func> <func> - <name><ret>int</ret><nametext>erl_xreceive_msg(fd, bufpp, bufsizep, emsg)</nametext></name> - <fsummary>Receive and decodes a message</fsummary> - <type> - <v>int fd;</v> - <v>unsigned char **bufpp;</v> - <v>int *bufsizep;</v> - <v>ErlMessage *emsg;</v> - </type> - <desc> - <p>This function is 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 if the received - message does not fit into the original buffer. For that reason, - both buffer and buffer length are given as pointers - their values - may change by the call. - </p> - <p>On success, the function returns <c><![CDATA[ERL_MSG]]></c> and the - <c><![CDATA[Emsg]]></c> struct will be 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 will set - <c><![CDATA[erl_errno]]></c> to one of:</p> - <taglist> - <tag><c><![CDATA[EMSGSIZE]]></c></tag> - <item>Buffer too small.</item> - <tag><c><![CDATA[ENOMEM]]></c></tag> - <item>No more memory available.</item> - <tag><c><![CDATA[EIO]]></c></tag> - <item>I/O error.</item> - </taglist> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>erl_send(fd, to, msg)</nametext></name> - <fsummary>Send a message</fsummary> - <type> - <v>int fd;</v> - <v>ETERM *to, *msg;</v> - </type> - <desc> - <p>This function sends an Erlang term to a process.</p> - <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.</p> - <p><c><![CDATA[to]]></c> is an Erlang term containing the Pid of the - intended recipient of the message.</p> - <p><c><![CDATA[msg]]></c> is the Erlang term to be sent.</p> - <p>The function returns 1 if successful, otherwise 0 --- in - which case it will set <c><![CDATA[erl_errno]]></c> to one of:</p> - <taglist> - <tag><c><![CDATA[EINVAL]]></c></tag> - <item>Invalid argument: <c><![CDATA[to]]></c> is not a valid Erlang pid.</item> - <tag><c><![CDATA[ENOMEM]]></c></tag> - <item>No more memory available.</item> - <tag><c><![CDATA[EIO]]></c></tag> - <item>I/O error.</item> - </taglist> - </desc> - </func> - <func> <name><ret>int</ret><nametext>erl_reg_send(fd, to, msg)</nametext></name> - <fsummary>Send a message to a registered name</fsummary> + <fsummary>Send a message to a registered name.</fsummary> <type> <v>int fd;</v> <v>char *to;</v> @@ -377,9 +376,9 @@ typedef struct { </func> <func> <name><ret>ETERM *</ret><nametext>erl_rpc(fd, mod, fun, args)</nametext></name> - <name><ret>int</ret><nametext>erl_rpc_to(fd, mod, fun, args)</nametext></name> <name><ret>int</ret><nametext>erl_rpc_from(fd, timeout, emsg)</nametext></name> - <fsummary>Remote Procedure Call</fsummary> + <name><ret>int</ret><nametext>erl_rpc_to(fd, mod, fun, args)</nametext></name> + <fsummary>Remote Procedure Call.</fsummary> <type> <v>int fd, timeout;</v> <v>char *mod, *fun;</v> @@ -438,68 +437,37 @@ typedef struct { </desc> </func> <func> - <name><ret>int</ret><nametext>erl_publish(port)</nametext></name> - <fsummary>Publish a node name</fsummary> + <name><ret>int</ret><nametext>erl_send(fd, to, msg)</nametext></name> + <fsummary>Send a message.</fsummary> <type> - <v>int port;</v> + <v>int fd;</v> + <v>ETERM *to, *msg;</v> </type> <desc> - <p>These functions are used by a server process to register - with the local name server <em>epmd</em>, 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> on an open socket.</p> - <p><c><![CDATA[port]]></c> is the local name to register, and should 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, the functions return a descriptor connecting the - calling process to epmd. On failure, they return -1 and set - <c><![CDATA[erl_errno]]></c> to:</p> + <p>This function sends an Erlang term to a process.</p> + <p><c><![CDATA[fd]]></c> is an open descriptor to an Erlang connection.</p> + <p><c><![CDATA[to]]></c> is an Erlang term containing the Pid of the + intended recipient of the message.</p> + <p><c><![CDATA[msg]]></c> is the Erlang term to be sent.</p> + <p>The function returns 1 if successful, otherwise 0 --- in + which case it will set <c><![CDATA[erl_errno]]></c> to one of:</p> <taglist> + <tag><c><![CDATA[EINVAL]]></c></tag> + <item>Invalid argument: <c><![CDATA[to]]></c> is not a valid Erlang pid.</item> + <tag><c><![CDATA[ENOMEM]]></c></tag> + <item>No more memory available.</item> <tag><c><![CDATA[EIO]]></c></tag> - <item>I/O error</item> + <item>I/O error.</item> </taglist> - <p>Additionally, <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> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>erl_accept(listensock, conp)</nametext></name> - <fsummary>Accept a connection</fsummary> - <type> - <v>int listensock;</v> - <v>ErlConnect *conp;</v> - </type> - <desc> - <p>This function is used by a server process to accept a - connection from a client process.</p> - <p><c><![CDATA[listensock]]></c> is an open socket descriptor on which - <c><![CDATA[listen()]]></c> has previously been called.</p> - <p><c><![CDATA[conp]]></c> is a pointer to an <c><![CDATA[ErlConnect]]></c> struct, - described as follows:</p> - <code type="none"><![CDATA[ -typedef struct { - char ipadr[4]; - char nodename[MAXNODELEN]; -} ErlConnect; - ]]></code> - <p>On success, <c><![CDATA[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> </desc> </func> <func> - <name><ret>const char *</ret><nametext>erl_thiscookie()</nametext></name> - <name><ret>const char *</ret><nametext>erl_thisnodename()</nametext></name> - <name><ret>const char *</ret><nametext>erl_thishostname()</nametext></name> <name><ret>const char *</ret><nametext>erl_thisalivename()</nametext></name> + <name><ret>const char *</ret><nametext>erl_thiscookie()</nametext></name> <name><ret>short</ret><nametext>erl_thiscreation()</nametext></name> - <fsummary>Retrieve some values</fsummary> + <name><ret>const char *</ret><nametext>erl_thishostname()</nametext></name> + <name><ret>const char *</ret><nametext>erl_thisnodename()</nametext></name> + <fsummary>Retrieve some values.</fsummary> <desc> <p>These functions can be used to retrieve information about the C Node. These values are initially set with @@ -508,22 +476,22 @@ typedef struct { </func> <func> <name><ret>int</ret><nametext>erl_unpublish(alive)</nametext></name> - <fsummary>Forcefully unpublish a node name</fsummary> + <fsummary>Forcefully unpublish a node name.</fsummary> <type> <v>char *alive;</v> </type> <desc> <p>This function can be called by a process to unregister a - specified node from epmd on the localhost. This is however usually not - allowed, unless epmd was started with the -relaxed_command_check + specified node from epmd on the localhost. This is however usually not + allowed, unless epmd was started with the -relaxed_command_check flag, which it normally isn't.</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> + close the descriptor that was returned by + <c><![CDATA[ei_publish()]]></c>.</p> <warning> - <p>This function is deprecated and will be removed in a future + <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, i.e., the @@ -534,11 +502,43 @@ typedef struct { </desc> </func> <func> - <name><ret>struct hostent</ret><nametext>*erl_gethostbyname(name)</nametext></name> + <name><ret>int</ret><nametext>erl_xreceive_msg(fd, bufpp, bufsizep, emsg)</nametext></name> + <fsummary>Receive and decodes a message.</fsummary> + <type> + <v>int fd;</v> + <v>unsigned char **bufpp;</v> + <v>int *bufsizep;</v> + <v>ErlMessage *emsg;</v> + </type> + <desc> + <p>This function is 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 if the received + message does not fit into the original buffer. For that reason, + both buffer and buffer length are given as pointers - their values + may change by the call. + </p> + <p>On success, the function returns <c><![CDATA[ERL_MSG]]></c> and the + <c><![CDATA[Emsg]]></c> struct will be 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 will set + <c><![CDATA[erl_errno]]></c> to one of:</p> + <taglist> + <tag><c><![CDATA[EMSGSIZE]]></c></tag> + <item>Buffer too small.</item> + <tag><c><![CDATA[ENOMEM]]></c></tag> + <item>No more memory available.</item> + <tag><c><![CDATA[EIO]]></c></tag> + <item>I/O error.</item> + </taglist> + </desc> + </func> + <func> <name><ret>struct hostent</ret><nametext>*erl_gethostbyaddr(addr, length, type)</nametext></name> - <name><ret>struct hostent</ret><nametext>*erl_gethostbyname_r(name, hostp, buffer, buflen, h_errnop)</nametext></name> <name><ret>struct hostent</ret><nametext>*erl_gethostbyaddr_r(addr, length, type, hostp, buffer, buflen, h_errnop)</nametext></name> - <fsummary>Name lookup functions</fsummary> + <name><ret>struct hostent</ret><nametext>*erl_gethostbyname(name)</nametext></name> + <name><ret>struct hostent</ret><nametext>*erl_gethostbyname_r(name, hostp, buffer, buflen, h_errnop)</nametext></name> + <fsummary>Name lookup functions.</fsummary> <type> <v>const char *name;</v> <v>const char *addr;</v> @@ -567,4 +567,3 @@ typedef struct { </list> </section> </cref> - diff --git a/lib/erl_interface/doc/src/erl_error.xml b/lib/erl_interface/doc/src/erl_error.xml index abe84780e1..5b8d546e12 100644 --- a/lib/erl_interface/doc/src/erl_error.xml +++ b/lib/erl_interface/doc/src/erl_error.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>erl_error</title> @@ -30,13 +30,13 @@ <checked>Torbjörn Törnkvist</checked> <date>961014</date> <rev>A</rev> - <file>erl_error.sgml</file> + <file>erl_error.xml</file> </header> <lib>erl_error</lib> <libsummary>Error Print Routines</libsummary> <description> <p>This module contains some error printing routines taken - from <em>Advanced Programming in the UNIX Environment</em> + from <em>Advanced Programming in the UNIX Environment</em> by W. Richard Stevens. </p> <p>These functions are all called in the same manner as <c><![CDATA[printf()]]></c>, i.e. with a string containing format specifiers @@ -46,7 +46,7 @@ <funcs> <func> <name><ret>void</ret><nametext>erl_err_msg(FormatStr, ... )</nametext></name> - <fsummary>Non-fatal error, and not system call error</fsummary> + <fsummary>Non-fatal error, and not system call error.</fsummary> <type> <v>const char *FormatStr;</v> </type> @@ -57,7 +57,7 @@ </func> <func> <name><ret>void</ret><nametext>erl_err_quit(FormatStr, ... )</nametext></name> - <fsummary>Fatal error, but not system call error</fsummary> + <fsummary>Fatal error, but not system call error.</fsummary> <type> <v>const char *FormatStr;</v> </type> @@ -70,19 +70,19 @@ </func> <func> <name><ret>void</ret><nametext>erl_err_ret(FormatStr, ... )</nametext></name> - <fsummary>Non-fatal system call error</fsummary> + <fsummary>Non-fatal system call error.</fsummary> <type> <v>const char *FormatStr;</v> </type> <desc> <p>Use this function after a failed system call. The message provided by the caller is printed followed by a string - describing the reason for failure. </p> + describing the reason for failure.</p> </desc> </func> <func> <name><ret>void</ret><nametext>erl_err_sys(FormatStr, ... )</nametext></name> - <fsummary>Fatal system call error</fsummary> + <fsummary>Fatal system call error.</fsummary> <type> <v>const char *FormatStr;</v> </type> @@ -107,7 +107,7 @@ <funcs> <func> <name><ret>volatile int</ret><nametext>erl_errno</nametext></name> - <fsummary>The variable <c><![CDATA[erl_errno]]></c>contains the erl_interface error number. You can change the value if you wish. </fsummary> + <fsummary>The variable <c><![CDATA[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 and is then set by many erl_interface functions on failure to a @@ -134,4 +134,3 @@ </func> </funcs> </cref> - diff --git a/lib/erl_interface/doc/src/erl_eterm.xml b/lib/erl_interface/doc/src/erl_eterm.xml index 800f8a3207..e5207a271e 100644 --- a/lib/erl_interface/doc/src/erl_eterm.xml +++ b/lib/erl_interface/doc/src/erl_eterm.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>erl_eterm</title> @@ -30,7 +30,7 @@ <checked>Torbjörn Törnkvist</checked> <date>980703</date> <rev>A</rev> - <file>erl_eterm.sgml</file> + <file>erl_eterm.xml</file> </header> <lib>erl_eterm</lib> <libsummary>Functions for Erlang Term Construction</libsummary> @@ -167,18 +167,18 @@ erl_free_compound(list); </func> <func> <name><ret>ETERM *</ret><nametext>erl_copy_term(term)</nametext></name> - <fsummary>Creates a copy of an Erlang term</fsummary> + <fsummary>Creates a copy of an Erlang term.</fsummary> <type> <v>ETERM *term;</v> </type> <desc> - <p>This function creates and returns a copy of the Erlang term + <p>This function creates and returns a copy of the Erlang term <c><![CDATA[term]]></c>.</p> </desc> </func> <func> <name><ret>ETERM *</ret><nametext>erl_element(position, tuple)</nametext></name> - <fsummary>Extracts an element from an Erlang tuple</fsummary> + <fsummary>Extracts an element from an Erlang tuple.</fsummary> <type> <v>int position;</v> <v>ETERM *tuple;</v> @@ -196,37 +196,53 @@ erl_free_compound(list); </desc> </func> <func> + <name><ret>ETERM *</ret><nametext>erl_hd(list)</nametext></name> + <fsummary>Extracts the first element from a list.</fsummary> + <type> + <v>ETERM *list;</v> + </type> + <desc> + <p>Extracts the first element from a list.</p> + <p><c><![CDATA[list]]></c> is an Erlang term containing a list.</p> + <p>The function returns an Erlang term corresponding to the + head element in the list, or a NULL pointer if <c><![CDATA[list]]></c> was + not a list.</p> + </desc> + </func> + <func> <name><ret>void</ret><nametext>erl_init(NULL, 0)</nametext></name> - <fsummary>Initialization routine</fsummary> + <fsummary>Initialization routine.</fsummary> <type> <v>void *NULL;</v> <v>int 0;</v> </type> <desc> <marker id="erl_init"></marker> - <p>This function must be called before any of the others in + <p>This function must be called before any of the others in the <c><![CDATA[erl_interface]]></c> library in order to initialize the - library functions. The arguments must be specified as + library functions. The arguments must be specified as <c><![CDATA[erl_init(NULL,0)]]></c>.</p> </desc> </func> <func> - <name><ret>ETERM *</ret><nametext>erl_hd(list)</nametext></name> - <fsummary>Extracts the first element from a list</fsummary> + <name><ret>int</ret><nametext>erl_iolist_length(list)</nametext></name> + <fsummary>Return the length of an IO list.</fsummary> <type> <v>ETERM *list;</v> </type> <desc> - <p>Extracts the first element from a list.</p> - <p><c><![CDATA[list]]></c> is an Erlang term containing a list.</p> - <p>The function returns an Erlang term corresponding to the - head element in the list, or a NULL pointer if <c><![CDATA[list]]></c> was - not a list.</p> + <p>Returns the length of an IO list. + </p> + <p><c><![CDATA[list]]></c> is an Erlang term containing an IO list. </p> + <p>The function returns the length of <c><![CDATA[list]]></c>, or -1 if + <c><![CDATA[list]]></c> is not an IO list.</p> + <p>Refer to <c><![CDATA[erl_iolist_to_binary()]]></c> for the definition of + an IO list. </p> </desc> </func> <func> <name><ret>ETERM *</ret><nametext>erl_iolist_to_binary(term)</nametext></name> - <fsummary>Converts an IO list to a binary</fsummary> + <fsummary>Converts an IO list to a binary.</fsummary> <type> <v>ETERM *list;</v> </type> @@ -252,7 +268,7 @@ iohead ::= Binary </func> <func> <name><ret>char *</ret><nametext>erl_iolist_to_string(list)</nametext></name> - <fsummary>Converts an IO list to a zero terminated string</fsummary> + <fsummary>Converts an IO list to a zero terminated string.</fsummary> <type> <v>ETERM *list;</v> </type> @@ -272,24 +288,8 @@ iohead ::= Binary </desc> </func> <func> - <name><ret>int</ret><nametext>erl_iolist_length(list)</nametext></name> - <fsummary>Return the length of an IO list</fsummary> - <type> - <v>ETERM *list;</v> - </type> - <desc> - <p>Returns the length of an IO list. - </p> - <p><c><![CDATA[list]]></c> is an Erlang term containing an IO list. </p> - <p>The function returns the length of <c><![CDATA[list]]></c>, or -1 if - <c><![CDATA[list]]></c> is not an IO list.</p> - <p>Refer to <c><![CDATA[erl_iolist_to_binary()]]></c> for the definition of - an IO list. </p> - </desc> - </func> - <func> <name><ret>int</ret><nametext>erl_length(list)</nametext></name> - <fsummary>Determines the length of a list</fsummary> + <fsummary>Determines the length of a list.</fsummary> <type> <v>ETERM *list;</v> </type> @@ -303,7 +303,7 @@ iohead ::= Binary </func> <func> <name><ret>ETERM *</ret><nametext>erl_mk_atom(string)</nametext></name> - <fsummary>Creates an atom</fsummary> + <fsummary>Creates an atom.</fsummary> <type> <v>const char *string;</v> </type> @@ -324,7 +324,7 @@ iohead ::= Binary </func> <func> <name><ret>ETERM *</ret><nametext>erl_mk_binary(bptr, size)</nametext></name> - <fsummary>Creates a binary object</fsummary> + <fsummary>Creates a binary object.</fsummary> <type> <v>char *bptr;</v> <v>int size;</v> @@ -336,13 +336,13 @@ iohead ::= Binary <p><c><![CDATA[size]]></c> indicates the length of <c><![CDATA[bptr]]></c>.</p> <p>The function returns an Erlang binary object.</p> <p><c><![CDATA[ERL_BIN_PTR(bin)]]></c> retrieves a pointer to - the binary data. <c><![CDATA[ERL_BIN_SIZE(bin)]]></c> retrieves the + the binary data. <c><![CDATA[ERL_BIN_SIZE(bin)]]></c> retrieves the size. </p> </desc> </func> <func> <name><ret>ETERM *</ret><nametext>erl_mk_empty_list()</nametext></name> - <fsummary>Creates an empty Erlang list</fsummary> + <fsummary>Creates an empty Erlang list.</fsummary> <desc> <p>This function creates and returns an empty Erlang list. Note that NULL is not used to represent an empty list; @@ -351,7 +351,7 @@ iohead ::= Binary </func> <func> <name><ret>ETERM *</ret><nametext>erl_mk_estring(string, len)</nametext></name> - <fsummary>Creates an Erlang string</fsummary> + <fsummary>Creates an Erlang string.</fsummary> <type> <v>char *string;</v> <v>int len;</v> @@ -367,7 +367,7 @@ iohead ::= Binary </func> <func> <name><ret>ETERM *</ret><nametext>erl_mk_float(f)</nametext></name> - <fsummary>Creates an Erlang float</fsummary> + <fsummary>Creates an Erlang float.</fsummary> <type> <v>double f;</v> </type> @@ -385,7 +385,7 @@ iohead ::= Binary </func> <func> <name><ret>ETERM *</ret><nametext>erl_mk_int(n)</nametext></name> - <fsummary>Creates an Erlang integer</fsummary> + <fsummary>Creates an Erlang integer.</fsummary> <type> <v>int n;</v> </type> @@ -395,13 +395,13 @@ iohead ::= Binary <p></p> <p>The function returns an Erlang integer object with the value specified in <c><![CDATA[n]]></c>.</p> - <p><c><![CDATA[ERL_INT_VALUE(t)]]></c> can be used to retrieve the value + <p><c><![CDATA[ERL_INT_VALUE(t)]]></c> can be used to retrieve the value value from an Erlang integer.</p> </desc> </func> <func> <name><ret>ETERM *</ret><nametext>erl_mk_list(array, arrsize)</nametext></name> - <fsummary>Creates a list from an array</fsummary> + <fsummary>Creates a list from an array.</fsummary> <type> <v>ETERM **array;</v> <v>int arrsize;</v> @@ -418,8 +418,35 @@ iohead ::= Binary </desc> </func> <func> + <name><ret>ETERM *</ret><nametext>erl_mk_long_ref(node, n1, n2, n3, creation)</nametext></name> + <fsummary>Creates an Erlang reference.</fsummary> + <type> + <v>const char *node;</v> + <v>unsigned int n1, n2, n3;</v> + <v>unsigned int creation;</v> + </type> + <desc> + <p>This function creates an Erlang reference, with 82 bits.</p> + <p><c><![CDATA[node]]></c> is the name of the C node.</p> + <p><c><![CDATA[n1]]></c>, <c><![CDATA[n2]]></c> and <c><![CDATA[n3]]></c> can be seen as one big number + <c><![CDATA[n1*2^64+n2*2^32+n3]]></c> which should be chosen uniquely for + each reference + created for a given C node.</p> + <p><c><![CDATA[creation]]></c> is an arbitrary number.</p> + <p>Note that <c><![CDATA[n3]]></c> and <c><![CDATA[creation]]></c> are limited in + precision, so only the low 18 and 2 bits of these numbers + are actually used. + </p> + <p>The function returns an Erlang reference object.</p> + <p><c><![CDATA[ERL_REF_NODE(ref)]]></c>, <c><![CDATA[ERL_REF_NUMBERS(ref)]]></c>, + <c><![CDATA[ERL_REF_LEN(ref)]]></c> and + <c><![CDATA[ERL_REF_CREATION(ref)]]></c> to retrieve the values used + to create the reference. </p> + </desc> + </func> + <func> <name><ret>ETERM *</ret><nametext>erl_mk_pid(node, number, serial, creation)</nametext></name> - <fsummary>Creates a process identifier</fsummary> + <fsummary>Creates a process identifier.</fsummary> <type> <v>const char *node;</v> <v>unsigned int number;</v> @@ -443,7 +470,7 @@ iohead ::= Binary </func> <func> <name><ret>ETERM *</ret><nametext>erl_mk_port(node, number, creation)</nametext></name> - <fsummary>Creates a port identifier</fsummary> + <fsummary>Creates a port identifier.</fsummary> <type> <v>const char *node;</v> <v>unsigned int number;</v> @@ -464,7 +491,7 @@ iohead ::= Binary </func> <func> <name><ret>ETERM *</ret><nametext>erl_mk_ref(node, number, creation)</nametext></name> - <fsummary>Creates an old Erlang reference</fsummary> + <fsummary>Creates an old Erlang reference.</fsummary> <type> <v>const char *node;</v> <v>unsigned int number;</v> @@ -488,35 +515,8 @@ iohead ::= Binary </desc> </func> <func> - <name><ret>ETERM *</ret><nametext>erl_mk_long_ref(node, n1, n2, n3, creation)</nametext></name> - <fsummary>Creates an Erlang reference</fsummary> - <type> - <v>const char *node;</v> - <v>unsigned int n1, n2, n3;</v> - <v>unsigned int creation;</v> - </type> - <desc> - <p>This function creates an Erlang reference, with 82 bits.</p> - <p><c><![CDATA[node]]></c> is the name of the C node.</p> - <p><c><![CDATA[n1]]></c>, <c><![CDATA[n2]]></c> and <c><![CDATA[n3]]></c> can be seen as one big number - <c><![CDATA[n1*2^64+n2*2^32+n3]]></c> which should be chosen uniquely for - each reference - created for a given C node.</p> - <p><c><![CDATA[creation]]></c> is an arbitrary number.</p> - <p>Note that <c><![CDATA[n3]]></c> and <c><![CDATA[creation]]></c> are limited in - precision, so only the low 18 and 2 bits of these numbers - are actually used. - </p> - <p>The function returns an Erlang reference object.</p> - <p><c><![CDATA[ERL_REF_NODE(ref)]]></c>, <c><![CDATA[ERL_REF_NUMBERS(ref)]]></c>, - <c><![CDATA[ERL_REF_LEN(ref)]]></c> and - <c><![CDATA[ERL_REF_CREATION(ref)]]></c> to retrieve the values used - to create the reference. </p> - </desc> - </func> - <func> <name><ret>ETERM *</ret><nametext>erl_mk_string(string)</nametext></name> - <fsummary>Creates a string</fsummary> + <fsummary>Creates a string.</fsummary> <type> <v>char *string;</v> </type> @@ -529,7 +529,7 @@ iohead ::= Binary </func> <func> <name><ret>ETERM *</ret><nametext>erl_mk_tuple(array, arrsize)</nametext></name> - <fsummary>Creates an Erlang tuple from an array</fsummary> + <fsummary>Creates an Erlang tuple from an array.</fsummary> <type> <v>ETERM **array;</v> <v>int arrsize;</v> @@ -553,7 +553,7 @@ iohead ::= Binary </func> <func> <name><ret>ETERM *</ret><nametext>erl_mk_uint(n)</nametext></name> - <fsummary>Creates an unsigned integer</fsummary> + <fsummary>Creates an unsigned integer.</fsummary> <type> <v>unsigned int n;</v> </type> @@ -570,7 +570,7 @@ iohead ::= Binary </func> <func> <name><ret>ETERM *</ret><nametext>erl_mk_var(name)</nametext></name> - <fsummary>Creates an Erlang variable</fsummary> + <fsummary>Creates an Erlang variable.</fsummary> <type> <v>char *name;</v> </type> @@ -584,7 +584,7 @@ iohead ::= Binary </func> <func> <name><ret>int</ret><nametext>erl_print_term(stream, term)</nametext></name> - <fsummary>Prints an Erlang term</fsummary> + <fsummary>Prints an Erlang term.</fsummary> <type> <v>FILE *stream;</v> <v>ETERM *term;</v> @@ -601,7 +601,7 @@ iohead ::= Binary </func> <func> <name><ret>void</ret><nametext>erl_set_compat_rel(release_number)</nametext></name> - <fsummary>Set the erl_interface library in compatibility mode</fsummary> + <fsummary>Set the erl_interface library in compatibility mode.</fsummary> <type> <v>unsigned release_number;</v> </type> @@ -633,7 +633,7 @@ iohead ::= Binary </func> <func> <name><ret>int</ret><nametext>erl_size(term)</nametext></name> - <fsummary>Return the arity of a tuple or binary</fsummary> + <fsummary>Return the arity of a tuple or binary.</fsummary> <type> <v>ETERM *term;</v> </type> @@ -648,7 +648,7 @@ iohead ::= Binary </func> <func> <name><ret>ETERM *</ret><nametext>erl_tl(list)</nametext></name> - <fsummary>Extracts the tail from a list</fsummary> + <fsummary>Extracts the tail from a list.</fsummary> <type> <v>ETERM *list;</v> </type> @@ -662,14 +662,14 @@ iohead ::= Binary </func> <func> <name><ret>ETERM *</ret><nametext>erl_var_content(term, name)</nametext></name> - <fsummary>Extracts the content of a variable</fsummary> + <fsummary>Extracts the content of a variable.</fsummary> <type> <v>ETERM *term;</v> <v>char *name;</v> </type> <desc> <p>This function returns the contents of the specified - variable in an Erlang term. + variable in an Erlang term. </p> <p><c><![CDATA[term]]></c> is an Erlang term. In order for this function to succeed, <c><![CDATA[term]]></c> must be an Erlang variable with the @@ -685,4 +685,3 @@ iohead ::= Binary </func> </funcs> </cref> - diff --git a/lib/erl_interface/doc/src/erl_format.xml b/lib/erl_interface/doc/src/erl_format.xml index 6e3ac4f0c9..ce5163fbc7 100644 --- a/lib/erl_interface/doc/src/erl_format.xml +++ b/lib/erl_interface/doc/src/erl_format.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>erl_format</title> @@ -30,7 +30,7 @@ <checked>Torbjörn Törnkvist</checked> <date>961016</date> <rev>A</rev> - <file>erl_format.sgml</file> + <file>erl_format.xml</file> </header> <lib>erl_format</lib> <libsummary>Create and Match Erlang Terms</libsummary> @@ -41,7 +41,7 @@ <funcs> <func> <name><ret>ETERM *</ret><nametext>erl_format(FormatStr, ... )</nametext></name> - <fsummary>Creates an Erlang term</fsummary> + <fsummary>Creates an Erlang term.</fsummary> <type> <v>char *FormatStr;</v> </type> @@ -81,7 +81,7 @@ erl_format("[{name,~a},{age,~i},{data,~w}]", erl_format("[{adr,~s,~i}]","E-street",42)); ]]></code> <p>This will create an <c><![CDATA[(ETERM *)]]></c> structure corresponding - to the Erlang term: + to the Erlang term: <c><![CDATA[[{name,madonna},{age,21},{data,[{adr,"E-street",42}]}]]]></c></p> <p>The function returns an Erlang term, or NULL if <c><![CDATA[FormatStr]]></c> does not describe a valid Erlang term.</p> @@ -89,7 +89,7 @@ erl_format("[{name,~a},{age,~i},{data,~w}]", </func> <func> <name><ret>int</ret><nametext>erl_match(Pattern, Term)</nametext></name> - <fsummary>Performs pattern matching</fsummary> + <fsummary>Performs pattern matching.</fsummary> <type> <v>ETERM *Pattern,*Term;</v> </type> @@ -139,4 +139,3 @@ if (erl_match(pattern2, term2)) { </func> </funcs> </cref> - diff --git a/lib/erl_interface/doc/src/erl_global.xml b/lib/erl_interface/doc/src/erl_global.xml index d6bfffc69d..69f303722d 100644 --- a/lib/erl_interface/doc/src/erl_global.xml +++ b/lib/erl_interface/doc/src/erl_global.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>erl_global</title> @@ -30,7 +30,7 @@ <checked>Gordon Beaton</checked> <date>980703</date> <rev>A</rev> - <file>erl_global.sgml</file> + <file>erl_global.xml</file> </header> <lib>erl_global</lib> <libsummary>Access globally registered names</libsummary> @@ -39,14 +39,14 @@ up and unregistering names in the Erlang Global module. For more information, see the description of Global in the reference manual.</p> <p>Note that the functions below perform an RPC using an open file - descriptor provided by the caller. This file descriptor must - not be used for other traffic during the global operation or the + descriptor provided by the caller. This file descriptor must + not be used for other traffic during the global operation or the function may receive unexpected data and fail.</p> </description> <funcs> <func> <name><ret>char **</ret><nametext>erl_global_names(fd,count)</nametext></name> - <fsummary>Obtain list of Global names</fsummary> + <fsummary>Obtain list of Global names.</fsummary> <type> <v>int fd;</v> <v>int *count;</v> @@ -76,7 +76,7 @@ </func> <func> <name><ret>int</ret><nametext>erl_global_register(fd,name,pid)</nametext></name> - <fsummary>Register a name in Global</fsummary> + <fsummary>Register a name in Global.</fsummary> <type> <v>int fd;</v> <v>const char *name;</v> @@ -98,7 +98,7 @@ </func> <func> <name><ret>int</ret><nametext>erl_global_unregister(fd,name)</nametext></name> - <fsummary>Unregister a name in Global</fsummary> + <fsummary>Unregister a name in Global.</fsummary> <type> <v>int fd;</v> <v>const char *name;</v> @@ -115,7 +115,7 @@ </func> <func> <name><ret>ETERM *</ret><nametext>erl_global_whereis(fd,name,node)</nametext></name> - <fsummary>Look up a name in global</fsummary> + <fsummary>Look up a name in global.</fsummary> <type> <v>int fd;</v> <v>const char *name;</v> @@ -139,4 +139,3 @@ </func> </funcs> </cref> - diff --git a/lib/erl_interface/doc/src/erl_malloc.xml b/lib/erl_interface/doc/src/erl_malloc.xml index 799c903b1a..ba1f59a492 100644 --- a/lib/erl_interface/doc/src/erl_malloc.xml +++ b/lib/erl_interface/doc/src/erl_malloc.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>erl_malloc</title> @@ -30,7 +30,7 @@ <checked>Torbjörn Törnkvist</checked> <date>980703</date> <rev>A</rev> - <file>erl_malloc.sgml</file> + <file>erl_malloc.xml</file> </header> <lib>erl_malloc</lib> <libsummary>Memory Allocation Functions</libsummary> @@ -41,7 +41,7 @@ <funcs> <func> <name><ret>ETERM *</ret><nametext>erl_alloc_eterm(etype)</nametext></name> - <fsummary>Allocates an ETERM structure</fsummary> + <fsummary>Allocates an ETERM structure.</fsummary> <type> <v>unsigned char etype;</v> </type> @@ -101,9 +101,9 @@ </func> <func> <name><ret>void</ret><nametext>erl_eterm_release(void)</nametext></name> - <fsummary>Clears the ETERM freelist</fsummary> + <fsummary>Clears the ETERM freelist.</fsummary> <desc> - <p>Clears the + <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> @@ -111,7 +111,7 @@ </func> <func> <name><ret>void</ret><nametext>erl_eterm_statistics(allocated, freed)</nametext></name> - <fsummary>Reports term allocation statistics</fsummary> + <fsummary>Reports term allocation statistics.</fsummary> <type> <v>long *allocated;</v> <v>long *freed;</v> @@ -127,8 +127,19 @@ </desc> </func> <func> + <name><ret>void</ret><nametext>erl_free(ptr)</nametext></name> + <fsummary>Frees some memory.</fsummary> + <type> + <v>void *ptr;</v> + </type> + <desc> + <p>This function calls the standard + <c><![CDATA[free()]]></c> function. </p> + </desc> + </func> + <func> <name><ret>void</ret><nametext>erl_free_array(array, size)</nametext></name> - <fsummary>Frees an array of ETERM structures</fsummary> + <fsummary>Frees an array of ETERM structures.</fsummary> <type> <v>ETERM **array;</v> <v>int size;</v> @@ -141,18 +152,8 @@ </desc> </func> <func> - <name><ret>void</ret><nametext>erl_free_term(t)</nametext></name> - <fsummary>Frees an ETERM structure</fsummary> - <type> - <v>ETERM *t;</v> - </type> - <desc> - <p>Use this function to free an Erlang term.</p> - </desc> - </func> - <func> <name><ret>void</ret><nametext>erl_free_compound(t)</nametext></name> - <fsummary>Frees an array of ETERM structures</fsummary> + <fsummary>Frees an array of ETERM structures.</fsummary> <type> <v>ETERM *t;</v> </type> @@ -175,27 +176,25 @@ </desc> </func> <func> - <name><ret>void</ret><nametext>erl_malloc(size)</nametext></name> - <fsummary>Allocates some memory</fsummary> + <name><ret>void</ret><nametext>erl_free_term(t)</nametext></name> + <fsummary>Frees an ETERM structure.</fsummary> <type> - <v>long size;</v> + <v>ETERM *t;</v> </type> <desc> - <p>This function calls the standard - <c><![CDATA[malloc()]]></c> function. </p> + <p>Use this function to free an Erlang term.</p> </desc> </func> <func> - <name><ret>void</ret><nametext>erl_free(ptr)</nametext></name> - <fsummary>Frees some memory</fsummary> + <name><ret>void</ret><nametext>erl_malloc(size)</nametext></name> + <fsummary>Allocates some memory.</fsummary> <type> - <v>void *ptr;</v> + <v>long size;</v> </type> <desc> - <p>This function calls the standard - <c><![CDATA[free()]]></c> function. </p> + <p>This function calls the standard + <c><![CDATA[malloc()]]></c> function. </p> </desc> </func> </funcs> </cref> - diff --git a/lib/erl_interface/doc/src/erl_marshal.xml b/lib/erl_interface/doc/src/erl_marshal.xml index 7c56089016..c70bdb53e1 100644 --- a/lib/erl_interface/doc/src/erl_marshal.xml +++ b/lib/erl_interface/doc/src/erl_marshal.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>erl_marshal</title> @@ -30,7 +30,7 @@ <checked>Torbjörn Törnkvist</checked> <date>980703</date> <rev>A</rev> - <file>erl_marshal.sgml</file> + <file>erl_marshal.xml</file> </header> <lib>erl_marshal</lib> <libsummary>Encoding and Decoding of Erlang terms</libsummary> @@ -42,7 +42,7 @@ <funcs> <func> <name><ret>int</ret><nametext>erl_compare_ext(bufp1, bufp2)</nametext></name> - <fsummary>Compares encoded byte sequences</fsummary> + <fsummary>Compares encoded byte sequences.</fsummary> <type> <v>unsigned char *bufp1,*bufp2;</v> </type> @@ -56,14 +56,14 @@ term term2. </p> <p>The function returns 0 if the terms are equal, -1 if term1 - is less than term2, or 1 if term2 is less than term1. + is less than term2, or 1 if term2 is less than term1. </p> </desc> </func> <func> <name><ret>ETERM *</ret><nametext>erl_decode(bufp)</nametext></name> <name><ret>ETERM *</ret><nametext>erl_decode_buf(bufpp)</nametext></name> - <fsummary>Converts a term from Erlang external format</fsummary> + <fsummary>Converts a term from Erlang external format.</fsummary> <type> <v>unsigned char *bufp;</v> <v>unsigned char **bufpp;</v> @@ -79,7 +79,7 @@ </p> <p><c><![CDATA[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>, + Following a successful call to <c><![CDATA[erl_decode_buf()]]></c>, <c><![CDATA[bufpp]]></c> will be updated so that it points to the next encoded term. </p> @@ -96,14 +96,14 @@ <func> <name><ret>int</ret><nametext>erl_encode(term, bufp)</nametext></name> <name><ret>int</ret><nametext>erl_encode_buf(term, bufpp)</nametext></name> - <fsummary>Converts a term into Erlang external format</fsummary> + <fsummary>Converts a term into Erlang external format.</fsummary> <type> <v>ETERM *term;</v> <v>unsigned char *bufp;</v> <v>unsigned char **bufpp;</v> </type> <desc> - <p><c><![CDATA[erl_encode()]]></c> and <c><![CDATA[erl_encode_buf()]]></c> encode + <p><c><![CDATA[erl_encode()]]></c> and <c><![CDATA[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 encoding several terms consecutively in the same @@ -116,13 +116,13 @@ </p> <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>, + Following a successful call to <c><![CDATA[erl_encode_buf()]]></c>, <c>bufpp</c> will be updated so that it points to the position for the next encoded term. </p> <p> These functions returns the number of bytes written to buffer - if successful, otherwise returns 0. + if successful, otherwise returns 0. </p> <p>Note that no bounds checking is done on the buffer. It is the caller's responsibility to make sure that the buffer is @@ -165,14 +165,14 @@ is an atom.</item> </taglist> <p>The total space required will be the result calculated - from the information above, plus 1 additional byte for a + from the information above, plus 1 additional byte for a version identifier. </p> </desc> </func> <func> <name><ret>int</ret><nametext>erl_ext_size(bufp)</nametext></name> - <fsummary>Counts elements in encoded term</fsummary> + <fsummary>Counts elements in encoded term.</fsummary> <type> <v>unsigned char *bufp;</v> </type> @@ -183,7 +183,7 @@ </func> <func> <name><ret>unsigned char</ret><nametext>erl_ext_type(bufp)</nametext></name> - <fsummary>Determines type of an encoded byte sequence</fsummary> + <fsummary>Determines type of an encoded byte sequence.</fsummary> <type> <v>unsigned char *bufp;</v> </type> @@ -230,7 +230,7 @@ </func> <func> <name><ret>unsigned char *</ret><nametext>erl_peek_ext(bufp, pos)</nametext></name> - <fsummary>Steps over encoded term</fsummary> + <fsummary>Steps over encoded term.</fsummary> <type> <v>unsigned char *bufp;</v> <v>int pos;</v> @@ -244,7 +244,7 @@ more encoded Erlang terms. </p> <p><c><![CDATA[pos]]></c> indicates how many terms to step over in the - buffer. + buffer. </p> <p>The function returns a pointer to a sub-term that can be used in a subsequent call to <c><![CDATA[erl_decode()]]></c> in order to retrieve @@ -255,7 +255,7 @@ </func> <func> <name><ret>int</ret><nametext>erl_term_len(t)</nametext></name> - <fsummary>Determines encoded size of term</fsummary> + <fsummary>Determines encoded size of term.</fsummary> <type> <v>ETERM *t;</v> </type> @@ -270,4 +270,3 @@ </func> </funcs> </cref> - diff --git a/lib/erl_interface/doc/src/ref_man.xml b/lib/erl_interface/doc/src/ref_man.xml index 0cf060829b..e23f00956a 100644 --- a/lib/erl_interface/doc/src/ref_man.xml +++ b/lib/erl_interface/doc/src/ref_man.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>Erl_Interface Command Reference</title> <prepared>Gordon Beaton</prepared> @@ -53,4 +53,3 @@ <xi:include href="erl_marshal.xml"/> <xi:include href="erl_call.xml"/> </application> - diff --git a/lib/erl_interface/doc/src/registry.xml b/lib/erl_interface/doc/src/registry.xml index 285a2402b8..fd3e29c30f 100644 --- a/lib/erl_interface/doc/src/registry.xml +++ b/lib/erl_interface/doc/src/registry.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>registry</title> @@ -30,10 +30,10 @@ <checked>Gordon Beaton</checked> <date>980707</date> <rev>A</rev> - <file>registry.sgml</file> + <file>registry.xml</file> </header> <lib>registry</lib> - <libsummary>Store and backup key-value pairs</libsummary> + <libsummary>Store and backup key-value pairs.</libsummary> <description> <p>This module provides support for storing key-value pairs in a table known as a registry, backing up registries to @@ -42,51 +42,8 @@ </description> <funcs> <func> - <name><ret>ei_reg *</ret><nametext>ei_reg_open(size)</nametext></name> - <fsummary>Create and open a registry</fsummary> - <type> - <v>int size;</v> - </type> - <desc> - <p>Open (create) a registry. The registry will be - initially empty. Use <c><![CDATA[ei_reg_close()]]></c> to close the registry - later. - </p> - <p><c><![CDATA[size]]></c> is the approximate number of objects you intend - to store in the registry. Since the registry uses a hash table - with collision chaining, there is no absolute upper limit 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. It is possible to use - <c><![CDATA[ei_reg_resize()]]></c> to change the size later. Note that the - number you provide will be increased to the nearest larger prime - number. - </p> - <p>On success, an empty registry will be returned. On failure, NULL - will be returned.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_reg_resize(reg,newsize)</nametext></name> - <fsummary>Resize a registry</fsummary> - <type> - <v>ei_reg *reg;</v> - <v>int newsize;</v> - </type> - <desc> - <p>Change the size of a registry. - </p> - <p><c><![CDATA[newsize]]></c> is the new size to make the registry. The - number will be increased to the nearest larger prime number. - </p> - <p>On success, the registry will be resized, all contents - rehashed, and the function will return 0. On failure, the - registry will be left unchanged and the function will return -1.</p> - </desc> - </func> - <func> <name><ret>int</ret><nametext>ei_reg_close(reg)</nametext></name> - <fsummary>Close a registry </fsummary> + <fsummary>Close a registry.</fsummary> <type> <v>ei_reg *reg;</v> </type> @@ -101,153 +58,83 @@ </desc> </func> <func> - <name><ret>int</ret><nametext>ei_reg_setival(reg,key,i)</nametext></name> - <fsummary>Assign an integer object</fsummary> - <type> - <v>ei_reg *reg;</v> - <v>const char *key;</v> - <v>int i;</v> - </type> - <desc> - <p>Create a key-value pair with the specified <c><![CDATA[key]]></c> and integer - value <c><![CDATA[i]]></c>. If an object already existed with the same - <c><![CDATA[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> - <p><c><![CDATA[reg]]></c> is the registry where the object should be placed. - </p> - <p><c><![CDATA[key]]></c> is the name of the object. - </p> - <p><c><![CDATA[i]]></c> is the integer value to assign. - </p> - <p>The function returns 0 on success, or -1 on failure.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_reg_setfval(reg,key,f)</nametext></name> - <fsummary>Assign a floating point object</fsummary> - <type> - <v>ei_reg *reg;</v> - <v>const char *key;</v> - <v>double f;</v> - </type> - <desc> - <p>Create a key-value pair with the specified <c><![CDATA[key]]></c> and - floating point value <c><![CDATA[f]]></c>. If an object already existed with - the same <c><![CDATA[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> - <p><c><![CDATA[reg]]></c> is the registry where the object should be placed. - </p> - <p><c><![CDATA[key]]></c> is the name of the object. - </p> - <p><c><![CDATA[f]]></c> is the floating point value to assign. - </p> - <p>The function returns 0 on success, or -1 on failure.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_reg_setsval(reg,key,s)</nametext></name> - <fsummary>Assign a string object</fsummary> - <type> - <v>ei_reg *reg;</v> - <v>const char *key;</v> - <v>const char *s;</v> - </type> - <desc> - <p>Create 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 - existed with the same <c><![CDATA[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> - <p><c><![CDATA[reg]]></c> is the registry where the object should be placed. - </p> - <p><c><![CDATA[key]]></c> is the name of the object. - </p> - <p><c><![CDATA[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 function, so that the registry can later delete it if - necessary by calling <c><![CDATA[free()]]></c>. - </p> - <p>The function returns 0 on success, or -1 on failure.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_reg_setpval(reg,key,p,size)</nametext></name> - <fsummary>Assign a binary object</fsummary> + <name><ret>int</ret><nametext>ei_reg_delete(reg,key)</nametext></name> + <fsummary>Delete an object from the registry.</fsummary> <type> <v>ei_reg *reg;</v> <v>const char *key;</v> - <v>const void *p;</v> - <v>int size;</v> </type> <desc> - <p>Create 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 existed with the same <c><![CDATA[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> - <p><c><![CDATA[reg]]></c> is the registry where the object should be placed. + <p>Delete an object from the registry. The object is not + actually removed from the registry, it is only marked for later + removal so that on subsequent backups to Mnesia, the + corresponding object can be removed from the Mnesia table as + well. If another object is later created with the same key, the + object will be reused. </p> - <p><c><![CDATA[key]]></c> is the name of the object. + <p>The object will be removed from the registry after a call to + <c><![CDATA[ei_reg_dump()]]></c> or <c><![CDATA[ei_reg_purge()]]></c>. </p> - <p><c><![CDATA[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 - similar function, so that the registry can later delete it if - necessary by calling <c><![CDATA[free()]]></c>. + <p><c><![CDATA[reg]]></c> is the registry containing <c><![CDATA[key]]></c>. </p> - <p><c><![CDATA[size]]></c> is the length in bytes of the binary object. + <p><c><![CDATA[key]]></c> is the object to remove. </p> - <p>The function returns 0 on success, or -1 on failure.</p> + <p>If the object was found, the function returns 0 indicating + success. Otherwise the function returns -1.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_reg_setval(reg,key,flags,v,...)</nametext></name> - <fsummary>Assign a value to any object type</fsummary> + <name><ret>int</ret><nametext>ei_reg_dump(fd,reg,mntab,flags)</nametext></name> + <fsummary>Back up a registry to Mnesia.</fsummary> <type> + <v>int fd;</v> <v>ei_reg *reg;</v> - <v>const char *key;</v> + <v>const char *mntab;</v> <v>int flags;</v> - <v>v (see below)</v> </type> <desc> - <p>Create a key-value pair with the specified <c><![CDATA[key]]></c> whose - value is specified by <c><![CDATA[v]]></c>. If an object already - existed with the same <c><![CDATA[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>Dump the contents of a registry to a Mnesia table in an + atomic manner, i.e. either all data will be updated, or none of + it will. If any errors are encountered while backing up + the data, the entire operation is aborted. </p> - <p><c><![CDATA[reg]]></c> is the registry where the object should be placed. + <p><c><![CDATA[fd]]></c> is an open connection to Erlang. + Mnesia 3.0 or later must be running on the Erlang node. </p> - <p><c><![CDATA[key]]></c> is the name of the object. + <p><c><![CDATA[reg]]></c> is the registry to back up. </p> - <p><c><![CDATA[flags]]></c> indicates the type of the object specified by - <c><![CDATA[v]]></c>. Flags must be one of EI_INT, EI_FLT, EI_STR and - EI_BIN, indicating whether <c><![CDATA[v]]></c> is <c><![CDATA[int]]></c>, <c><![CDATA[double]]></c>, - <c><![CDATA[char*]]></c> or <c><![CDATA[void*]]></c>. If <c><![CDATA[flags]]></c> is EI_BIN, then 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><![CDATA[mntab]]></c> is the name of the Mnesia table where the backed + up data should be placed. If the table does not exist, it will + be created automatically using configurable defaults. See your + Mnesia documentation for information about configuring this + behaviour. </p> - <p>If you wish to store an arbitrary pointer in the registry, - specify a <c><![CDATA[size]]></c> of 0. In this case, the object itself will - not be transferred by an <c><![CDATA[ei_reg_dump()]]></c> operation, just - the pointer value. + <p>If <c><![CDATA[flags]]></c> is 0, the backup will include only those + objects which have been created, modified or deleted since the + last backup or restore (i.e. an incremental backup). After the + backup, any objects that were marked dirty are now clean, and any + objects that had been marked for deletion are deleted. + </p> + <p>Alternatively, setting flags to EI_FORCE will cause a full + backup to be done, and EI_NOPURGE will cause the deleted objects + to be left in the registry afterwards. These can be bitwise ORed + together if both behaviours are desired. If EI_NOPURGE was + specified, you can use <c><![CDATA[ei_reg_purge()]]></c> to explicitly remove + the deleted items from the registry later. </p> <p>The function returns 0 on success, or -1 on failure.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_reg_getival(reg,key)</nametext></name> - <fsummary>Get an integer object</fsummary> + <name><ret>double</ret><nametext>ei_reg_getfval(reg,key)</nametext></name> + <fsummary>Get a floating point object.</fsummary> <type> <v>ei_reg *reg;</v> <v>const char *key;</v> </type> <desc> <p>Get the value associated with <c><![CDATA[key]]></c> in the - registry. The value must be an integer. + registry. The value must be a floating point type. </p> <p><c><![CDATA[reg]]></c> is the registry where the object will be looked up. @@ -255,23 +142,23 @@ <p><c><![CDATA[key]]></c> is the name of the object to look up. </p> <p>On success, the function returns the value associated with <c><![CDATA[key]]></c>. - If the object was not found or it was not an integer - object, -1 is returned. To avoid problems with in-band error - reporting (i.e. if you cannot distinguish between -1 and a + If the object was not found or it was not a floating point + object, -1.0 is returned. To avoid problems with in-band error + reporting (i.e. if you cannot distinguish between -1.0 and a valid result) use the more general function <c><![CDATA[ei_reg_getval()]]></c> instead.</p> </desc> </func> <func> - <name><ret>double</ret><nametext>ei_reg_getfval(reg,key)</nametext></name> - <fsummary>Get a floating point object</fsummary> + <name><ret>int</ret><nametext>ei_reg_getival(reg,key)</nametext></name> + <fsummary>Get an integer object.</fsummary> <type> <v>ei_reg *reg;</v> <v>const char *key;</v> </type> <desc> <p>Get the value associated with <c><![CDATA[key]]></c> in the - registry. The value must be a floating point type. + registry. The value must be an integer. </p> <p><c><![CDATA[reg]]></c> is the registry where the object will be looked up. @@ -279,31 +166,36 @@ <p><c><![CDATA[key]]></c> is the name of the object to look up. </p> <p>On success, the function returns the value associated with <c><![CDATA[key]]></c>. - If the object was not found or it was not a floating point - object, -1.0 is returned. To avoid problems with in-band error - reporting (i.e. if you cannot distinguish between -1.0 and a + If the object was not found or it was not an integer + object, -1 is returned. To avoid problems with in-band error + reporting (i.e. if you cannot distinguish between -1 and a valid result) use the more general function <c><![CDATA[ei_reg_getval()]]></c> instead.</p> </desc> </func> <func> - <name><ret>const char *</ret><nametext>ei_reg_getsval(reg,key)</nametext></name> - <fsummary>Get a string object</fsummary> + <name><ret>const void *</ret><nametext>ei_reg_getpval(reg,key,size)</nametext></name> + <fsummary>Get a binary object.</fsummary> <type> <v>ei_reg *reg;</v> <v>const char *key;</v> + <v>int size;</v> </type> <desc> <p>Get the value associated with <c><![CDATA[key]]></c> in the - registry. The value must be a string. + registry. The value must be a binary (pointer) type. </p> <p><c><![CDATA[reg]]></c> is the registry where the object will be looked up. </p> <p><c><![CDATA[key]]></c> is the name of the object to look up. </p> + <p><c><![CDATA[size]]></c> will be initialized to contain the length in + bytes of the object, if it is found. + </p> <p>On success, the function returns the value associated with - <c><![CDATA[key]]></c>. If the object was not found or it was not a string, + <c><![CDATA[key]]></c> and indicates its length in <c><![CDATA[size]]></c>. + If the object was not found or it was not a binary object, NULL is returned. To avoid problems with in-band error reporting (i.e. if you cannot distinguish between NULL and a valid result) use the more general function <c><![CDATA[ei_reg_getval()]]></c> @@ -311,28 +203,23 @@ </desc> </func> <func> - <name><ret>const void *</ret><nametext>ei_reg_getpval(reg,key,size)</nametext></name> - <fsummary>Get a binary object</fsummary> + <name><ret>const char *</ret><nametext>ei_reg_getsval(reg,key)</nametext></name> + <fsummary>Get a string object.</fsummary> <type> <v>ei_reg *reg;</v> <v>const char *key;</v> - <v>int size;</v> </type> <desc> <p>Get the value associated with <c><![CDATA[key]]></c> in the - registry. The value must be a binary (pointer) type. + registry. The value must be a string. </p> <p><c><![CDATA[reg]]></c> is the registry where the object will be looked up. </p> <p><c><![CDATA[key]]></c> is the name of the object to look up. </p> - <p><c><![CDATA[size]]></c> will be initialized to contain the length in - bytes of the object, if it is found. - </p> <p>On success, the function returns the value associated with - <c><![CDATA[key]]></c> and indicates its length in <c><![CDATA[size]]></c>. - If the object was not found or it was not a binary object, + <c><![CDATA[key]]></c>. If the object was not found or it was not a string, NULL is returned. To avoid problems with in-band error reporting (i.e. if you cannot distinguish between NULL and a valid result) use the more general function <c><![CDATA[ei_reg_getval()]]></c> @@ -341,7 +228,7 @@ </func> <func> <name><ret>int</ret><nametext>ei_reg_getval(reg,key,flags,v,...)</nametext></name> - <fsummary>Get any object</fsummary> + <fsummary>Get any object.</fsummary> <type> <v>ei_reg *reg;</v> <v>const char *key;</v> @@ -350,7 +237,7 @@ </type> <desc> <p>This is a general function for retrieving any kind of - object from the registry. + object from the registry. </p> <p><c><![CDATA[reg]]></c> is the registry where the object will be looked up. @@ -376,7 +263,7 @@ </func> <func> <name><ret>int</ret><nametext>ei_reg_markdirty(reg,key)</nametext></name> - <fsummary>Mark an object as dirty </fsummary> + <fsummary>Mark an object as dirty.</fsummary> <type> <v>ei_reg *reg;</v> <v>const char *key;</v> @@ -390,7 +277,7 @@ registry and modified the contents, then the change will be invisible to the registry and the object will be assumed to be unmodified. This function allows you to make such modifications - and then let the registry know about them. + and then let the registry know about them. </p> <p><c><![CDATA[reg]]></c> is the registry containing the object. </p> @@ -400,34 +287,248 @@ </desc> </func> <func> - <name><ret>int</ret><nametext>ei_reg_delete(reg,key)</nametext></name> - <fsummary>Delete an object from the registry</fsummary> + <name><ret>ei_reg *</ret><nametext>ei_reg_open(size)</nametext></name> + <fsummary>Create and open a registry.</fsummary> + <type> + <v>int size;</v> + </type> + <desc> + <p>Open (create) a registry. The registry will be + initially empty. Use <c><![CDATA[ei_reg_close()]]></c> to close the registry + later. + </p> + <p><c><![CDATA[size]]></c> is the approximate number of objects you intend + to store in the registry. Since the registry uses a hash table + with collision chaining, there is no absolute upper limit 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. It is possible to use + <c><![CDATA[ei_reg_resize()]]></c> to change the size later. Note that the + number you provide will be increased to the nearest larger prime + number. + </p> + <p>On success, an empty registry will be returned. On failure, NULL + will be returned.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_purge(reg)</nametext></name> + <fsummary>Remove deleted objects.</fsummary> + <type> + <v>ei_reg *reg;</v> + </type> + <desc> + <p>Remove all objects marked for deletion. When objects + are deleted with <c><![CDATA[ei_reg_delete()]]></c> they are not actually + removed from the registry, only marked for later removal. This + is so that on a subsequent backup to Mnesia, the + objects can also be removed from the Mnesia table. If you are + not backing up to Mnesia then you may wish to remove the objects + manually with this function. + </p> + <p><c><![CDATA[reg]]></c> is a registry containing objects marked for + deletion. + </p> + <p>The function returns 0 on success, or -1 on failure.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_resize(reg,newsize)</nametext></name> + <fsummary>Resize a registry.</fsummary> + <type> + <v>ei_reg *reg;</v> + <v>int newsize;</v> + </type> + <desc> + <p>Change the size of a registry. + </p> + <p><c><![CDATA[newsize]]></c> is the new size to make the registry. The + number will be increased to the nearest larger prime number. + </p> + <p>On success, the registry will be resized, all contents + rehashed, and the function will return 0. On failure, the + registry will be left unchanged and the function will return -1.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_restore(fd,reg,mntab)</nametext></name> + <fsummary>Restore a registry from Mnesia.</fsummary> + <type> + <v>int fd;</v> + <v>ei_reg *reg;</v> + <v>const char *mntab;</v> + </type> + <desc> + <p>The contents of a Mnesia table are read into the + registry. + </p> + <p><c><![CDATA[fd]]></c> is an open connection to Erlang. + Mnesia 3.0 or later must be running on the Erlang node. + </p> + <p><c><![CDATA[reg]]></c> is the registry where the data should be placed. + </p> + <p><c><![CDATA[mntab]]></c> is the name of the Mnesia table to read data + from. + </p> + <p>Note that only tables of a certain format can be + restored, i.e. those that have been created and backed up to + with <c><![CDATA[ei_reg_dump()]]></c>. If the registry was not empty before + the operation, then 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 + will be overwritten with the new values. If the registry + contains objects that were not in the table, they will be + unchanged by this operation. + </p> + <p>After the restore operation, the entire contents of the + registry is marked as unmodified. Note that this includes any + objects that were modified before the restore and not + overwritten by the restore. + </p> + <p>The function returns 0 on success, or -1 on failure.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_setfval(reg,key,f)</nametext></name> + <fsummary>Assign a floating point object.</fsummary> <type> <v>ei_reg *reg;</v> <v>const char *key;</v> + <v>double f;</v> </type> <desc> - <p>Delete an object from the registry. The object is not - actually removed from the registry, it is only marked for later - removal so that on subsequent backups to Mnesia, the - corresponding object can be removed from the Mnesia table as - well. If another object is later created with the same key, the - object will be reused. + <p>Create a key-value pair with the specified <c><![CDATA[key]]></c> and + floating point value <c><![CDATA[f]]></c>. If an object already existed with + the same <c><![CDATA[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> - <p>The object will be removed from the registry after a call to - <c><![CDATA[ei_reg_dump()]]></c> or <c><![CDATA[ei_reg_purge()]]></c>. + <p><c><![CDATA[reg]]></c> is the registry where the object should be placed. </p> - <p><c><![CDATA[reg]]></c> is the registry containing <c><![CDATA[key]]></c>. + <p><c><![CDATA[key]]></c> is the name of the object. </p> - <p><c><![CDATA[key]]></c> is the object to remove. + <p><c><![CDATA[f]]></c> is the floating point value to assign. </p> - <p>If the object was found, the function returns 0 indicating - success. Otherwise the function returns -1.</p> + <p>The function returns 0 on success, or -1 on failure.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_setival(reg,key,i)</nametext></name> + <fsummary>Assign an integer object.</fsummary> + <type> + <v>ei_reg *reg;</v> + <v>const char *key;</v> + <v>int i;</v> + </type> + <desc> + <p>Create a key-value pair with the specified <c><![CDATA[key]]></c> and integer + value <c><![CDATA[i]]></c>. If an object already existed with the same + <c><![CDATA[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> + <p><c><![CDATA[reg]]></c> is the registry where the object should be placed. + </p> + <p><c><![CDATA[key]]></c> is the name of the object. + </p> + <p><c><![CDATA[i]]></c> is the integer value to assign. + </p> + <p>The function returns 0 on success, or -1 on failure.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_setpval(reg,key,p,size)</nametext></name> + <fsummary>Assign a binary object.</fsummary> + <type> + <v>ei_reg *reg;</v> + <v>const char *key;</v> + <v>const void *p;</v> + <v>int size;</v> + </type> + <desc> + <p>Create 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 existed with the same <c><![CDATA[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> + <p><c><![CDATA[reg]]></c> is the registry where the object should be placed. + </p> + <p><c><![CDATA[key]]></c> is the name of the object. + </p> + <p><c><![CDATA[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 + similar function, so that the registry can later delete it if + necessary by calling <c><![CDATA[free()]]></c>. + </p> + <p><c><![CDATA[size]]></c> is the length in bytes of the binary object. + </p> + <p>The function returns 0 on success, or -1 on failure.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_setsval(reg,key,s)</nametext></name> + <fsummary>Assign a string object.</fsummary> + <type> + <v>ei_reg *reg;</v> + <v>const char *key;</v> + <v>const char *s;</v> + </type> + <desc> + <p>Create 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 + existed with the same <c><![CDATA[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> + <p><c><![CDATA[reg]]></c> is the registry where the object should be placed. + </p> + <p><c><![CDATA[key]]></c> is the name of the object. + </p> + <p><c><![CDATA[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 function, so that the registry can later delete it if + necessary by calling <c><![CDATA[free()]]></c>. + </p> + <p>The function returns 0 on success, or -1 on failure.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_setval(reg,key,flags,v,...)</nametext></name> + <fsummary>Assign a value to any object type.</fsummary> + <type> + <v>ei_reg *reg;</v> + <v>const char *key;</v> + <v>int flags;</v> + <v>v (see below)</v> + </type> + <desc> + <p>Create a key-value pair with the specified <c><![CDATA[key]]></c> whose + value is specified by <c><![CDATA[v]]></c>. If an object already + existed with the same <c><![CDATA[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> + <p><c><![CDATA[reg]]></c> is the registry where the object should be placed. + </p> + <p><c><![CDATA[key]]></c> is the name of the object. + </p> + <p><c><![CDATA[flags]]></c> indicates the type of the object specified by + <c><![CDATA[v]]></c>. Flags must be one of EI_INT, EI_FLT, EI_STR and + EI_BIN, indicating whether <c><![CDATA[v]]></c> is <c><![CDATA[int]]></c>, <c><![CDATA[double]]></c>, + <c><![CDATA[char*]]></c> or <c><![CDATA[void*]]></c>. If <c><![CDATA[flags]]></c> is EI_BIN, then 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> + <p>If you wish to store an arbitrary pointer in the registry, + specify a <c><![CDATA[size]]></c> of 0. In this case, the object itself will + not be transferred by an <c><![CDATA[ei_reg_dump()]]></c> operation, just + the pointer value. + </p> + <p>The function returns 0 on success, or -1 on failure.</p> </desc> </func> <func> <name><ret>int</ret><nametext>ei_reg_stat(reg,key,obuf)</nametext></name> - <fsummary>Get object information</fsummary> + <fsummary>Get object information.</fsummary> <type> <v>ei_reg *reg;</v> <v>const char *key;</v> @@ -452,7 +553,7 @@ struct ei_reg_stat { <p>In <c><![CDATA[attr]]></c> the object's attributes are stored as the logical OR of its type (one of EI_INT, EI_FLT, EI_BIN and EI_STR), whether it is marked for deletion (EI_DELET) and whether it has - been modified since the last backup to Mnesia (EI_DIRTY). + been modified since the last backup to Mnesia (EI_DIRTY). </p> <p>The <c><![CDATA[size]]></c> field indicates the size in bytes required to store EI_STR (including the terminating 0) and EI_BIN objects, or 0 @@ -464,7 +565,7 @@ struct ei_reg_stat { </func> <func> <name><ret>int</ret><nametext>ei_reg_tabstat(reg,obuf)</nametext></name> - <fsummary>Get registry information</fsummary> + <fsummary>Get registry information.</fsummary> <type> <v>ei_reg *reg;</v> <v>struct ei_reg_tabstat *obuf;</v> @@ -496,7 +597,7 @@ struct ei_reg_tabstat { registry. It includes objects that are deleted but not purged. </p> <p><c><![CDATA[npos]]></c> indicates the number of unique positions that are - occupied in the registry. + occupied in the registry. </p> <p><c><![CDATA[collisions]]></c> indicates how many elements are sharing positions in the registry. @@ -506,107 +607,5 @@ struct ei_reg_tabstat { returns -1.</p> </desc> </func> - <func> - <name><ret>int</ret><nametext>ei_reg_dump(fd,reg,mntab,flags)</nametext></name> - <fsummary>Back up a registry to Mnesia</fsummary> - <type> - <v>int fd;</v> - <v>ei_reg *reg;</v> - <v>const char *mntab;</v> - <v>int flags;</v> - </type> - <desc> - <p>Dump the contents of a registry to a Mnesia table in an - atomic manner, i.e. either all data will be updated, or none of - it will. If any errors are encountered while backing up - the data, the entire operation is aborted. - </p> - <p><c><![CDATA[fd]]></c> is an open connection to Erlang. - Mnesia 3.0 or later must be running on the Erlang node. - </p> - <p><c><![CDATA[reg]]></c> is the registry to back up. - </p> - <p><c><![CDATA[mntab]]></c> is the name of the Mnesia table where the backed - up data should be placed. If the table does not exist, it will - be created automatically using configurable defaults. See your - Mnesia documentation for information about configuring this - behaviour. - </p> - <p>If <c><![CDATA[flags]]></c> is 0, the backup will include only those - objects which have been created, modified or deleted since the - last backup or restore (i.e. an incremental backup). After the - backup, any objects that were marked dirty are now clean, and any - objects that had been marked for deletion are deleted. - </p> - <p>Alternatively, setting flags to EI_FORCE will cause a full - backup to be done, and EI_NOPURGE will cause the deleted objects - to be left in the registry afterwards. These can be bitwise ORed - together if both behaviours are desired. If EI_NOPURGE was - specified, you can use <c><![CDATA[ei_reg_purge()]]></c> to explicitly remove - the deleted items from the registry later. - </p> - <p>The function returns 0 on success, or -1 on failure.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_reg_restore(fd,reg,mntab)</nametext></name> - <fsummary>Restore a registry from Mnesia</fsummary> - <type> - <v>int fd;</v> - <v>ei_reg *reg;</v> - <v>const char *mntab;</v> - </type> - <desc> - <p>The contents of a Mnesia table are read into the - registry. - </p> - <p><c><![CDATA[fd]]></c> is an open connection to Erlang. - Mnesia 3.0 or later must be running on the Erlang node. - </p> - <p><c><![CDATA[reg]]></c> is the registry where the data should be placed. - </p> - <p><c><![CDATA[mntab]]></c> is the name of the Mnesia table to read data - from. - </p> - <p>Note that only tables of a certain format can be - restored, i.e. those that have been created and backed up to - with <c><![CDATA[ei_reg_dump()]]></c>. If the registry was not empty before - the operation, then 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 - will be overwritten with the new values. If the registry - contains objects that were not in the table, they will be - unchanged by this operation. - </p> - <p>After the restore operation, the entire contents of the - registry is marked as unmodified. Note that this includes any - objects that were modified before the restore and not - overwritten by the restore. - </p> - <p>The function returns 0 on success, or -1 on failure.</p> - </desc> - </func> - <func> - <name><ret>int</ret><nametext>ei_reg_purge(reg)</nametext></name> - <fsummary>Remove deleted objects</fsummary> - <type> - <v>ei_reg *reg;</v> - </type> - <desc> - <p>Remove all objects marked for deletion. When objects - are deleted with <c><![CDATA[ei_reg_delete()]]></c> they are not actually - removed from the registry, only marked for later removal. This - is so that on a subsequent backup to Mnesia, the - objects can also be removed from the Mnesia table. If you are - not backing up to Mnesia then you may wish to remove the objects - manually with this function. - </p> - <p><c><![CDATA[reg]]></c> is a registry containing objects marked for - deletion. - </p> - <p>The function returns 0 on success, or -1 on failure.</p> - </desc> - </func> </funcs> </cref> - |