aboutsummaryrefslogtreecommitdiffstats
path: root/lib/erl_interface/doc/src/ei.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/erl_interface/doc/src/ei.xml')
-rw-r--r--lib/erl_interface/doc/src/ei.xml869
1 files changed, 435 insertions, 434 deletions
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, &amp;i, 2);
-ei_encode_atom(buf, &amp;i, "a");
-ei_encode_tuple_header(buf, &amp;i, 2);
-ei_encode_atom(buf, &amp;i, "b");
-ei_encode_tuple_header(buf, &amp;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(&amp;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(&amp;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, &amp;i, 2);
+ei_encode_atom(buf, &amp;i, "a");
+ei_encode_tuple_header(buf, &amp;i, 2);
+ei_encode_atom(buf, &amp;i, "b");
+ei_encode_tuple_header(buf, &amp;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(&amp;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>
-