diff options
Diffstat (limited to 'lib/erl_interface/doc/src/ei.xml')
| -rw-r--r-- | lib/erl_interface/doc/src/ei.xml | 1181 |
1 files changed, 626 insertions, 555 deletions
diff --git a/lib/erl_interface/doc/src/ei.xml b/lib/erl_interface/doc/src/ei.xml index 1177954eb9..ddfb4d88a8 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,361 +30,508 @@ <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> + <libsummary>Routines for handling the Erlang binary term format.</libsummary> <description> - <p>The library <c><![CDATA[ei]]></c> contains macros and functions to encode - and decode the erlang binary term format.</p> - <p>With <c><![CDATA[ei]]></c>, you can convert atoms, lists, numbers and + <p>The library <c>ei</c> contains macros and functions to encode + and decode the Erlang binary term format.</p> + + <p><c>ei</c> allows you to convert atoms, lists, numbers, and binaries to and from the binary format. This is useful when - writing port programs and drivers. <c><![CDATA[ei]]></c> uses a given - buffer, and no dynamic memory (with the exception of - <c><![CDATA[ei_decode_fun()]]></c>), and is often quite fast.</p> - <p>It also handles C-nodes, C-programs that talks erlang - distribution with erlang nodes (or other C-nodes) using the - erlang distribution format. The difference between <c><![CDATA[ei]]></c> and - <c><![CDATA[erl_interface]]></c> is that <c><![CDATA[ei]]></c> uses the binary format - directly when sending and receiving terms. It is also thread - safe, and using threads, one process can handle multiple - C-nodes. The <c><![CDATA[erl_interface]]></c> library is built on top of - <c><![CDATA[ei]]></c>, but of legacy reasons, it doesn't allow for multiple - C-nodes. In general, <c><![CDATA[ei]]></c> is the preferred way of doing - C-nodes.</p> - <p>The decode and encode functions use a buffer an index into the + writing port programs and drivers. <c>ei</c> uses a given + buffer, no dynamic memory (except + <c>ei_decode_fun()</c>) and is often quite fast.</p> + + <p><c>ei</c> also handles C-nodes, C-programs that talks Erlang + distribution with Erlang nodes (or other C-nodes) using the + Erlang distribution format. The difference between <c>ei</c> + and <c>erl_interface</c> is that <c>ei</c> uses + the binary format directly when sending and receiving terms. It is also + thread safe, and using threads, one process can handle multiple + C-nodes. The <c>erl_interface</c> library is built on top of + <c>ei</c>, but of legacy reasons, it does not allow for + multiple C-nodes. In general, <c>ei</c> is the preferred way + of doing C-nodes.</p> + + <p>The decode and encode functions use a buffer and an index into the buffer, which points at the point where to encode and decode. The index is updated to point right after the term encoded/decoded. No checking is done whether the term fits in the buffer or not. If encoding goes outside the buffer, the - program may crash.</p> - <p>All functions takes two parameter, <c><![CDATA[buf]]></c> is a pointer to - the buffer where the binary data is / will be, <c><![CDATA[index]]></c> is a - pointer to an index into the buffer. This parameter will be - incremented with the size of the term decoded / encoded. The - data is thus at <c><![CDATA[buf[*index]]]></c> when an <c><![CDATA[ei]]></c> function is - called.</p> - <p>The encode functions all assumes that the <c><![CDATA[buf]]></c> and - <c><![CDATA[index]]></c> parameters points to a buffer big enough for the - data. To get the size of an encoded term, without encoding it, - pass <c><![CDATA[NULL]]></c> instead of a buffer pointer. The <c><![CDATA[index]]></c> - parameter will be incremented, but nothing will be encoded. This - is the way in <c><![CDATA[ei]]></c> to "preflight" term encoding.</p> - <p>There are also encode-functions that uses a dynamic buffer. It + program can crash.</p> + + <p>All functions take two parameters:</p> + + <list type="bulleted"> + <item><p><c>buf</c> is a pointer to + the buffer where the binary data is or will be.</p> + </item> + <item><p><c>index</c> is a pointer to an index into the + buffer. This parameter is incremented with the size of the term + decoded/encoded.</p> + </item> + </list> + + <p>The data is thus at <c>buf[*index]</c> when an + <c>ei</c> function is called.</p> + + <p>All encode functions assume that the <c>buf</c> and + <c>index</c> parameters point to a buffer large enough for + the data. To get the size of an encoded term, without encoding it, + pass <c>NULL</c> instead of a buffer pointer. Parameter + <c>index</c> is incremented, but nothing will be encoded. This + is the way in <c>ei</c> to "preflight" term encoding.</p> + + <p>There are also encode functions that use a dynamic buffer. It is often more convenient to use these to encode data. All encode - functions comes in two versions: those starting with <c><![CDATA[ei_x]]></c>, - uses a dynamic buffer.</p> - <p>All functions return <c><![CDATA[0]]></c> if successful, and <c><![CDATA[-1]]></c> if - not. (For instance, if a term is not of the expected type, or - the data to decode is not a valid erlang term.)</p> - <p>Some of the decode-functions needs a preallocated buffer. This - buffer must be allocated big enough, and for non compound types - the <c><![CDATA[ei_get_type()]]></c> - function returns the size required (note that for strings an - extra byte is needed for the 0 string terminator).</p> + functions comes in two versions; those starting with + <c>ei_x</c> use a dynamic buffer.</p> + + <p>All functions return <c>0</c> if successful, otherwise + <c>-1</c> (for example, if a term is not of the expected + type, or the data to decode is an invalid Erlang term).</p> + + <p>Some of the decode functions need a pre-allocated buffer. This + buffer must be allocated large enough, and for non-compound types + the <c>ei_get_type()</c> + function returns the size required (notice that for strings an + extra byte is needed for the <c>NULL</c>-terminator).</p> </description> - <section> - <title>DATA TYPES</title> + <section> + <title>Data Types</title> <taglist> <tag><marker id="erlang_char_encoding"/>erlang_char_encoding</tag> <item> - <p/> <code type="none"> typedef enum { ERLANG_ASCII = 1, ERLANG_LATIN1 = 2, ERLANG_UTF8 = 4 -}erlang_char_encoding; -</code> - <p>The character encodings used for atoms. <c>ERLANG_ASCII</c> represents 7-bit ASCII. - Latin1 and UTF8 are different extensions of 7-bit ASCII. All 7-bit ASCII characters - are valid Latin1 and UTF8 characters. ASCII and Latin1 both represent each character - by one byte. A UTF8 character can consist of one to four bytes. Note that these - constants are bit-flags and can be combined with bitwise-or.</p> +} erlang_char_encoding;</code> + <p>The character encodings used for atoms. <c>ERLANG_ASCII</c> + represents 7-bit ASCII. Latin-1 and UTF-8 are different extensions + of 7-bit ASCII. All 7-bit ASCII characters are valid Latin-1 and + UTF-8 characters. ASCII and Latin-1 both represent each character + by one byte. An UTF-8 character can consist of 1-4 bytes. + Notice that these constants are bit-flags and can be combined with + bitwise OR.</p> </item> </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>Decodes an atom from the binary format. The <c>NULL</c>-terminated + name of the atom is placed at <c>p</c>. At most + <c>MAXATOMLEN</c> bytes can be placed in the buffer.</p> + </desc> + </func> + + <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>Decodes an atom from the binary format. The <c>NULL</c>-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 (Latin-1 or UTF-8) can + be obtained from <c>*was</c>. The encoding of the resulting string + (7-bit ASCII, Latin-1, or UTF-8) can be obtained from <c>*result</c>. + Both <c>was</c> and <c>result</c> can be <c>NULL</c>. <c>*result</c> + can 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> turns out to be pure 7-bit ASCII + (compatible with both Latin-1 and UTF-8).</p> + <p>This function fails if the atom is too long for the buffer + or if it cannot be represented with encoding <c>want</c>.</p> + <p>This function was introduced in Erlang/OTP R16 as part of a first + step to support UTF-8 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>Decodes an integer in the binary format to a GMP + <c>mpz_t</c> integer. To use this function, the <c>ei</c> + library must be configured and compiled to use the GMP library.</p> + </desc> + </func> + + <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>Decodes a binary from the binary format. Parameter + <c>len</c> is set to the actual size of the + binary. Notice that <c>ei_decode_binary()</c> assumes that + there is enough room for the binary. The size required can be + fetched by <c>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>Decodes a boolean value from the binary format. + A boolean is actually an atom, <c>true</c> decodes 1 + and <c>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>Decodes a char (8-bit) integer between 0-255 from the binary format. + For historical reasons the returned integer is of + type <c>char</c>. Your C code is to consider the + returned value to be of type <c>unsigned char</c> even if + the C compilers and system can define <c>char</c> to be + signed.</p> + </desc> + </func> + + <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>Decodes a 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 previous knowledge of type.</fsummary> + <desc> + <p>Decodes any term, or at least tries to. If the term + pointed at by <c>*index</c> in <c>buf</c> fits + in the <c>term</c> union, it is decoded, and the + appropriate field in <c>term->value</c> is set, and + <c>*index</c> is incremented by the term size.</p> + <p>The function returns <c>1</c> on successful decoding, <c>-1</c> on + error, and <c>0</c> if the term seems alright, but does not fit in the + <c>term</c> structure. If <c>1</c> is returned, the + <c>index</c> is incremented, and <c>term</c> + contains the decoded term.</p> + <p>The <c>term</c> structure contains the arity for a tuple + or list, size for a binary, string, or atom. It contains + a term if it is any of the following: integer, float, atom, + pid, port, or ref.</p> + </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> <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>Decodes a fun from the binary format. Parameter + <c>p</c> is to be <c>NULL</c> or point to an + <c>erlang_fun</c> structure. This is the only decode + function that allocates memory. When the <c>erlang_fun</c> + is no longer needed, it is to be freed with + <c>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_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_list_header(const char *buf, int *index, int *arity)</nametext></name> + <fsummary>Decode a list.</fsummary> <desc> - <p>Encodes a version magic number for the binary format. Must - be the first token in a binary term.</p> + <p>Decodes a list header from the binary + format. The number of elements is returned in + <c>arity</c>. The <c>arity+1</c> elements + follow (the last one is the tail of the list, normally an empty list). + If <c>arity</c> is <c>0</c>, it is an empty + list.</p> + <p>Notice that lists are encoded as strings if they consist + entirely of integers in the range 0..255. This function do + not decode such strings, use <c>ei_decode_string()</c> + instead.</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_long(const char *buf, int *index, long *p)</nametext></name> + <fsummary>Decode integer.</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>Decodes a long integer from the binary format. + If the code is 64 bits, the function <c>ei_decode_long()</c> is + the same as <c>ei_decode_longlong()</c>.</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_longlong(const char *buf, int *index, long 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>Decodes a GCC <c>long long</c> or Visual C++ + <c>__int64</c> + (64-bit) integer from the binary format. This + function is missing in the VxWorks port.</p> </desc> </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_map_header(const char *buf, int *index, int *arity)</nametext></name> + <fsummary>Decode a map.</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>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 this 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 is an empty map. + A correctly encoded map does not have duplicate keys.</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_pid(const char *buf, int *index, erlang_pid *p)</nametext></name> + <fsummary>Decode a <c>pid</c>.</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>Decodes a process identifier (pid) from the binary format.</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_port(const char *buf, int *index, erlang_port *p)</nametext></name> + <fsummary>Decode a port.</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 port 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_ref(const char *buf, int *index, erlang_ref *p)</nametext></name> + <fsummary>Decode a reference.</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>Decodes a reference 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_string(const char *buf, int *index, char *p)</nametext></name> + <fsummary>Decode a string.</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>Decodes a string from the binary format. A + string in Erlang is a list of integers between 0 and + 255. Notice that as the string is just a list, sometimes + lists are encoded as strings by <c>term_to_binary/1</c>, + even if it was not intended.</p> + <p>The string is copied to <c>p</c>, and enough space must + be allocated. The returned string is <c>NULL</c>-terminated, so you + must add an extra byte to the memory requirement.</p> </desc> </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_term(const char *buf, int *index, void *t)</nametext></name> + <fsummary>Decode a <c>ETERM</c>.</fsummary> + <desc> + <p>Decodes a term from the binary format. The term + is return in <c>t</c> as a <c>ETERM*</c>, so + <c>t</c> is actually an <c>ETERM**</c> (see + <seealso marker="erl_eterm"><c>erl_eterm</c></seealso>). + The term is later to be deallocated.</p> + <p>Notice that this function is located in the <c>Erl_Interface</c> + 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>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>Decodes an Erlang trace token from the binary format.</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_tuple_header(const char *buf, int *index, int *arity)</nametext></name> + <fsummary>Decode a tuple.</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>Decodes a tuple header, the number of elements + is returned in <c>arity</c>. The tuple elements follow + 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>Decodes an unsigned long integer from the binary format. + If the code is 64 bits, the function <c>ei_decode_ulong()</c> is + the same as <c>ei_decode_ulonglong()</c>.</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>Decodes a GCC <c>unsigned long long</c> or Visual C++ + <c>unsigned __int64</c> (64-bit) integer from the binary + format. This function is missing in the VxWorks port.</p> </desc> </func> + + <func> + <name><ret>int</ret><nametext>ei_decode_version(const char *buf, int *index, int *version)</nametext></name> + <fsummary>Decode an empty list (<c>nil</c>).</fsummary> + <desc> + <p>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 - are encoded. The name should be zero-terminated, except for - the <c><![CDATA[ei_x_encode_atom_len()]]></c> function.</p> + <p>Encodes an atom in the binary format. Parameter <c>p</c> + is the name of the atom in Latin-1 encoding. Only up to + <c>MAXATOMLEN-1</c> bytes + are encoded. The name is to be <c>NULL</c>-terminated, except for + the <c>ei_x_encode_atom_len()</c> function.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>ei_encode_atom_as(char *buf, int *index, const char *p, erlang_char_encoding from_enc, erlang_char_encoding to_enc)</nametext></name> <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). - The <c>p</c> parameter is the name of the atom with character encoding - <seealso marker="#erlang_char_encoding"><c>from_enc</c></seealso> (ascii, latin1 or utf8). - The name must either be zero-terminated or a function variant with a <c>len</c> - parameter must be used. If <c>to_enc</c> is set to the bitwise-or'd combination - <c>(ERLANG_LATIN1|ERLANG_UTF8)</c>, utf8 encoding is only used if the atom string - can not be represented in latin1 encoding.</p> - <p>The encoding will fail if <c>p</c> is not a valid string in encoding <c>from_enc</c>, - if the string is too long or if it can not be represented with character encoding <c>to_enc</c>.</p> - <p>These functions were introduced in R16 release of Erlang/OTP as part of a first step - to support UTF8 atoms. Atoms encoded with <c>ERLANG_UTF8</c> - can not be decoded by earlier releases than R16.</p> - </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> + <seealso marker="#erlang_char_encoding"><c>to_enc</c></seealso> + (Latin-1 or UTF-8). Parameter <c>p</c> is the name of the atom with + character encoding + <seealso marker="#erlang_char_encoding"><c>from_enc</c></seealso> + (ASCII, Latin-1, or UTF-8). The name must either be <c>NULL</c>-terminated or + a function variant with a <c>len</c> parameter must be used. + If <c>to_enc</c> is set to the bitwise OR'd combination + <c>(ERLANG_LATIN1|ERLANG_UTF8)</c>, UTF-8 encoding is only used if the + atom string cannot be represented in Latin-1 encoding.</p> + <p>The encoding fails if <c>p</c> is an invalid string in encoding + <c>from_enc</c>, if the string is too long, or if it cannot be + represented with character encoding <c>to_enc</c>.</p> + <p>These functions were introduced in Erlang/OTP R16 as part of a first + step to support UTF-8 atoms. Atoms encoded with <c>ERLANG_UTF8</c> + cannot be decoded by earlier releases than R16.</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>mpz_t</c> integer to binary format. + To use this function, the <c>ei</c> library must be configured and + compiled to use the GMP library.</p> </desc> </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>p</c>, of <c>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>true</c> if + <c>p</c> is not zero, or <c>false</c> if <c>p</c> 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. For historical reasons the integer argument is of + type <c>char</c>. Your C code is to consider the specified + argument to be of type <c>unsigned char</c> even if + the C compilers and system may define <c>char</c> to be + signed.</p> </desc> </func> + <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>Returns <c>-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>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>Encodes an empty list. It is 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. Parameter <c>p</c> + points to an <c>erlang_fun</c> structure. The + <c>erlang_fun</c> is not freed automatically, the + <c>free_fun</c> is to be called if the fun is not needed + after encoding.</p> </desc> </func> + <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 - (actually its <c><![CDATA[arity]]></c> cons cells) and the tail of the + <p>Encodes a list header, with a specified + arity. The next <c>arity+1</c> terms are the elements + (actually its <c>arity</c> cons cells) and the tail of the list. Lists and tuples are encoded recursively, so that a - list may contain another list or tuple.</p> - <p>E.g. to encode the list <c><![CDATA[[c, d, [e | f]]]]></c>:</p> + list can contain another list or tuple.</p> + <p>For example, to encode the list + <c>[c, d, [e | f]]</c>:</p> <pre> ei_encode_list_header(buf, &i, 3); ei_encode_atom(buf, &i, "c"); @@ -392,14 +539,13 @@ ei_encode_atom(buf, &i, "d"); ei_encode_list_header(buf, &i, 1); ei_encode_atom(buf, &i, "e"); ei_encode_atom(buf, &i, "f"); -ei_encode_empty_list(buf, &i); - </pre> +ei_encode_empty_list(buf, &i);</pre> <note> <p>It may seem that there is no way to create a list without knowing the number of elements in advance. But indeed - there is a way. Note that the list <c><![CDATA[[a, b, c]]]></c> can be - written as <c><![CDATA[[a | [b | [c]]]]]></c>. Using this, a list can - be written as conses.</p> + there is a way. Notice that the list <c>[a, b, c]</c> + can be written as <c>[a | [b | [c]]]</c>. + Using this, a list can be written as conses.</p> </note> <p>To encode a list, without knowing the arity in advance:</p> <pre> @@ -407,425 +553,350 @@ while (something()) { ei_x_encode_list_header(&x, 1); ei_x_encode_ulong(&x, i); /* just an example */ } -ei_x_encode_empty_list(&x); - </pre> +ei_x_encode_empty_list(&x);</pre> </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. + If the code is 64 bits, the function <c>ei_encode_long()</c> is + the same as <c>ei_encode_longlong()</c>.</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>long long</c> or Visual C++ + <c>__int64</c> (64-bit) integer in the binary format. + This function is missing in the VxWorks port.</p> + </desc> + </func> + <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 + <p>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 encoded in the following order: <c>K1, V1, K2, V2, ..., Kn, Vn</c>. </p> - <p>E.g. to encode the map <c>#{a => "Apple", b => "Banana"}</c>:</p> + <p>For example, to encode the map <c>#{a => "Apple", b => + "Banana"}</c>:</p> <pre> ei_x_encode_map_header(&x, 2); ei_x_encode_atom(&x, "a"); ei_x_encode_string(&x, "Apple"); ei_x_encode_atom(&x, "b"); -ei_x_encode_string(&x, "Banana"); - </pre> - <p>A correctly encoded map can not have duplicate keys.</p> - </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> +ei_x_encode_string(&x, "Banana");</pre> + <p>A correctly encoded map cannot have duplicate keys.</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> + <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 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> + <p>Encodes an Erlang process identifier (pid) in the binary + format. Parameter <c>p</c> points to an + <c>erlang_pid</c> structure (which should have been + obtained earlier with <c>ei_decode_pid()</c>).</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_decode_string(const char *buf, int *index, char *p)</nametext></name> - <fsummary>Decode a string</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>Encode a port.</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> + <p>Encodes an Erlang port in the binary format. Parameter + <c>p</c> points to a <c>erlang_port</c> + structure (which should have been obtained earlier with + <c>ei_decode_port()</c>).</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> + <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>Encode a ref.</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> + <p>Encodes an Erlang reference in the binary format. Parameter + <c>p</c> points to a <c>erlang_ref</c> + structure (which should have been obtained earlier with + <c>ei_decode_ref()</c>).</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> + <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 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> + <p>Encodes a string in the binary format. (A string in Erlang + is a list, but is encoded as a character array in the binary + format.) The string is to be <c>NULL</c>-terminated, except for + the <c>ei_x_encode_string_len()</c> function.</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_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>erl_interface</c> term.</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 <c>ETERM</c>, as obtained from + <c>erl_interface</c>. Parameter <c>t</c> is + actually an <c>ETERM</c> pointer. This function + does not free the <c>ETERM</c>.</p> </desc> </func> <func> - <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_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>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 trace token in the binary format. + Parameter <c>p</c> points to a + <c>erlang_trace</c> structure (which should have been + obtained earlier with <c>ei_decode_trace()</c>).</p> </desc> </func> + <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_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>Decodes a pid, process identifier, from the binary format.</p> + <p>Encodes a tuple header, with a specified + arity. The next <c>arity</c> terms encoded will be the + elements of the tuple. Tuples and lists are encoded + recursively, so that a tuple can contain another tuple or list.</p> + <p>For example, to encode the tuple <c>{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_port(const char *buf, int *index, erlang_port *p)</nametext></name> - <fsummary>Decode a port</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 port identifier from the binary - format.</p> + <p>Encodes an unsigned long integer in the binary format. + If the code is 64 bits, the function <c>ei_encode_ulong()</c> is + the same as <c>ei_encode_ulonglong()</c>.</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_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 reference from the binary format.</p> + <p>Encodes a GCC <c>unsigned long long</c> or Visual C++ + <c>unsigned __int64</c> (64-bit) integer in the binary + format. This function is missing in the VxWorks port.</p> </desc> </func> + <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_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>Decodes an erlang trace token from the binary format.</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_tuple_header(const char *buf, int *index, int *arity)</nametext></name> - <fsummary>Decode a tuple</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 tuple header, the number of elements - is returned in <c><![CDATA[arity]]></c>. The tuple elements follows in order in - the buffer.</p> + <p>Returns the type in <c>type</c> and size in + <c>size</c> of the encoded term. For strings and atoms, + size is the number of characters <em>not</em> including the + terminating <c>NULL</c>. For binaries, <c>size</c> is the number of + bytes. For lists and tuples, <c>size</c> is the arity of + the object. For other types, <c>size</c> is 0. In all + cases, <c>index</c> is left unchanged.</p> </desc> </func> + <func> - <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>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> + <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> + <desc> + <p>Prints a term, in clear text, to the file + specified by <c>fp</c>, or the buffer pointed to by + <c>s</c>. It + tries to resemble the term printing in the Erlang shell.</p> + <p>In <c>ei_s_print_term()</c>, parameter + <c>s</c> is to + point to a dynamically (malloc) allocated string of + <c>BUFSIZ</c> bytes or a <c>NULL</c> pointer. The string + can be reallocated (and <c>*s</c> can be updated) by this + function if the result is more than <c>BUFSIZ</c> + characters. The string returned is <c>NULL</c>-terminated.</p> + <p>The return value is the number of characters written to the file + or string, or <c>-1</c> if <c>buf[index]</c> does not + contain a valid term. + Unfortunately, I/O errors on <c>fp</c> is not checked.</p> + <p>Argument <c>index</c> is updated, that is, this function + can be viewed as a decode function that decodes a term into a + human-readable format.</p> </desc> </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>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> - <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> + <marker id="ei_set_compat_rel"></marker> + <p>By default, the <c>ei</c> library is only guaranteed + to be compatible with other Erlang/OTP components from the same + release as the <c>ei</c> library itself. For example, + <c>ei</c> from + Erlang/OTP R10 is not compatible with an Erlang emulator + from Erlang/OTP R9 by default.</p> + <p>A call to <c>ei_set_compat_rel(release_number)</c> sets + the <c>ei</c> library in compatibility mode of release + <c>release_number</c>. Valid range of + <c>release_number</c> + is <c>[7, current release]</c>. This makes it possible to + communicate with Erlang/OTP components from earlier releases.</p> + <note> + <p>If this function is called, it can only be called once + and must be called before any other functions in the + <c>ei</c> library are called.</p> + </note> + <warning> + <p>You can run into trouble if this feature is used + carelessly. Always ensure that all communicating + components are either from the same Erlang/OTP release, or + from release X and release Y where all components + from release Y are in compatibility mode of release X.</p> + </warning> </desc> </func> + <func> - <name><ret>int</ret><nametext>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_skip_term(const char* buf, int* index)</nametext></name> + <fsummary>Skip a term.</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> - </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> - <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>Skips a term in the specified buffer; + 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>buf</c> is the buffer.</p> + <p><c>index</c> is updated to point right after the term + in the buffer.</p> + <note> + <p>This can be useful when you want to hold arbitrary + terms: skip them and copy the binary term data to some + buffer.</p> + </note> + <p>Returns <c>0</c> on success, otherwise + <c>-1</c>.</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> + <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>Append a buffer at the end.</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 - tries to resemble the term printing in the erlang shell.</p> - <p>In <c><![CDATA[ei_s_print_term()]]></c>, the parameter <c><![CDATA[s]]></c> should - point to a dynamically (malloc) allocated string of - <c><![CDATA[BUFSIZ]]></c> bytes or a NULL pointer. The string may be - reallocated (and <c><![CDATA[*s]]></c> may be updated) by this function - if the result is more than <c><![CDATA[BUFSIZ]]></c> characters. The - string returned is zero-terminated.</p> - <p>The return value is the number of characters written to the - file or string, or -1 if <c><![CDATA[buf[index]]]></c> doesn't contain a - valid term. Unfortunately, I/O errors on <c><![CDATA[fp]]></c> is not - checked.</p> - <p>The argument <c><![CDATA[index]]></c> is updated, i.e. this function can - be viewed as en decode function that decodes a term into a - human readable format.</p> + <p>Appends data at the end of buffer <c>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> <desc> - <p>Format a term, given as a string, to a buffer. This - functions works like a sprintf for erlang terms. The - <c><![CDATA[fmt]]></c> contains a format string, with arguments like - <c><![CDATA[~d]]></c>, to insert terms from variables. The following + <p>Formats a term, given as a string, to a buffer. + Works like a sprintf for Erlang terms. + <c>fmt</c> contains a format string, with arguments like + <c>~d</c>, to insert terms from variables. The following formats are supported (with the C types given):</p> - <p></p> <pre> -~a - an atom, char* -~c - a character, char -~s - a string, char* -~i - an integer, int -~l - a long integer, long int -~u - a unsigned long integer, unsigned long int -~f - a float, float -~d - a double float, double float -~p - an Erlang PID, erlang_pid* - </pre> - <p>For instance, to encode a tuple with some stuff:</p> +~a An atom, char* +~c A character, char +~s A string, char* +~i An integer, int +~l A long integer, long int +~u A unsigned long integer, unsigned long int +~f A float, float +~d A double float, double float +~p An Erlang pid, erlang_pid*</pre> + <p>For example, to encode a tuple with some stuff:</p> <pre> ei_x_format("{~a,~i,~d}", "numbers", 12, 3.14159) -encodes the tuple {numbers,12,3.14159} - </pre> - <p>The <c><![CDATA[ei_x_format_wo_ver()]]></c> formats into a buffer, without - the initial version byte.</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> - <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 - filled in, and a default buffer is allocated. The - <c><![CDATA[ei_x_new_with_version()]]></c> also puts an initial version - byte, that is used in the binary format. (So that - <c><![CDATA[ei_x_encode_version()]]></c> won't be needed.)</p> +encodes the tuple {numbers,12,3.14159}</pre> + <p><c>ei_x_format_wo_ver()</c> formats into a buffer, + without the initial version byte.</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> + <fsummary>Free a buffer.</fsummary> <desc> - <p>These functions appends data at the end of the buffer <c><![CDATA[x]]></c>.</p> + <p>Frees an <c>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_skip_term(const char* buf, int* index)</nametext></name> - <fsummary>skip a term</fsummary> + <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> <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> + <p>Allocates a new <c>ei_x_buff</c> buffer. The + fields of the structure pointed to by parameter <c>x</c> + is filled in, and a default buffer is allocated. + <c>ei_x_new_with_version()</c> also puts an initial + version byte, which is used in the binary format (so that + <c>ei_x_encode_version()</c> will not be needed.)</p> </desc> </func> </funcs> <section> <title>Debug Information</title> - <p>Some tips on what to check when the emulator doesn't seem to - receive the terms that you send.</p> + <p>Some tips on what to check when the emulator does not seem to + receive the terms that you send:</p> + <list type="bulleted"> - <item>be careful with the version header, use - <c><![CDATA[ei_x_new_with_version()]]></c> when appropriate</item> - <item>turn on distribution tracing on the erlang node</item> - <item>check the result codes from ei_decode_-calls</item> + <item>Be careful with the version header, use + <c>ei_x_new_with_version()</c> when appropriate.</item> + <item>Turn on distribution tracing on the Erlang node.</item> + <item>Check the result codes from <c>ei_decode_-calls</c>.</item> </list> </section> <section> <title>See Also</title> - <p>erl_interface(3)</p> + <p><seealso marker="erl_eterm"><c>erl_eterm</c></seealso></p> </section> </cref> - |