File: ei.html

package info (click to toggle)
erlang-doc-html 1%3A11.b.2-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,284 kB
ctags: 10,724
sloc: erlang: 505; ansic: 323; makefile: 62; perl: 61; sh: 45
file content (891 lines) | stat: -rw-r--r-- 33,062 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
  <TITLE>ei</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
  <STYLE TYPE="text/css">
<!--
    .REFBODY     { margin-left: 13mm }
    .REFTYPES    { margin-left: 8mm }
-->
  </STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
  <IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>ei</H1>
</CENTER>

<H3>C LIBRARY</H3>
<DIV CLASS=REFBODY>
ei
</DIV>

<H3>C LIBRARY SUMMARY</H3>
<DIV CLASS=REFBODY>
 routines for handling the erlang binary term format

</DIV>

<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>

<P> The library <CODE>ei</CODE> contains macros and functions to encode
and decode the erlang binary term format.

<P> With <CODE>ei</CODE>, you can convert atoms, lists, numbers and
binaries to and from the binary format. This is useful when
writing port programs and drivers. <CODE>ei</CODE> uses a given
buffer, and no dynamic memory (with the exception of
<CODE>ei_decode_fun()</CODE>), and is often quite fast.

<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 <CODE>ei</CODE> and
<CODE>erl_interface</CODE> is that <CODE>ei</CODE> 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 <CODE>erl_interface</CODE> library is built on top of
<CODE>ei</CODE>, but of legacy reasons, it doesn't allow for multiple
C-nodes. In general, <CODE>ei</CODE> is the preferred way of doing
C-nodes.

<P> The decode and encode functions use a buffer 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> All functions takes two parameter, <CODE>buf</CODE> is a pointer to
the buffer where the binary data is / will be, <CODE>index</CODE> 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 <CODE>buf[*index]</CODE> when an <CODE>ei</CODE> function is
called.

<P> The encode functions all assumes that the <CODE>buf</CODE> and
<CODE>index</CODE> parameters points to a buffer big enough for the
data. To get the size of an encoded term, without encoding it,
pass <CODE>NULL</CODE> instead of a buffer pointer. The <CODE>index</CODE>
parameter will be incremented, but nothing will be encoded. This
is the way in <CODE>ei</CODE> to &#34;preflight&#34; term encoding.

<P> There are also encode-functions that uses a dynamic buffer. It
is often more convenient to use these to encode data. All encode
funcions comes in two versions: those starting with <CODE>ei_x</CODE>,
uses a dynamic buffer.

<P> All functions return <CODE>0</CODE> if successful, and <CODE>-1</CODE> 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> Some of the decode-functions needs a preallocated buffer. This
buffer must be allocated big enough, and for non compound types
the <CODE>ei_get_type()</CODE>
function returns the size required (note that for strings an
extra byte is needed for the 0 string terminator).

</DIV>

<H3>EXPORTS</H3>

<P><A NAME="ei_set_compat_rel/1"><STRONG><CODE>void ei_set_compat_rel(release_number)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>unsigned release_number;</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>
<A NAME="ei_set_compat_rel"><!-- Empty --></A>
<P>By default, the <CODE>ei</CODE> library is only guaranteed
        to be compatible with other Erlang/OTP components from the same
        release as the <CODE>ei</CODE> library itself. For example, <CODE>ei</CODE> from
        the OTP R10 release is not compatible with an Erlang emulator
        from the OTP R9 release by default.
        
<P>     A call to <CODE>ei_set_compat_rel(release_number)</CODE> sets the
        <CODE>ei</CODE> library in compatibility mode of release
        <CODE>release_number</CODE>. Valid range of <CODE>release_number</CODE>
        is [7, current release]. This makes it possible to
        communicate with Erlang/OTP components from earlier releases.
        
<P>
<TABLE CELLPADDING=4>
  <TR>
    <TD VALIGN=TOP><IMG ALT="Note!" SRC="note.gif"></TD>
    <TD>

<P>If this function is called, it may only be called once
        and must be called before any other functions in the <CODE>ei</CODE>
        library is called.
            </TD>
  </TR>
</TABLE>

<P>
<TABLE CELLPADDING=4>
  <TR>
    <TD VALIGN=TOP><IMG ALT="Warning!" SRC="warning.gif"></TD>
    <TD>

<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.
            </TD>
  </TR>
</TABLE>

</DIV>

<P><A NAME="ei_encode_version/2"><STRONG><CODE>int ei_encode_version(char *buf, int *index)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_version/1"><STRONG><CODE>int ei_x_encode_version(ei_x_buff* x)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      Encodes a version magic number for the binary format. Must
         be the first token in a binary term.

</DIV>

<P><A NAME="ei_encode_long/3"><STRONG><CODE>int ei_encode_long(char *buf, int *index, long p)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_long/2"><STRONG><CODE>int ei_x_encode_long(ei_x_buff* x, long p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<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().

</DIV>

<P><A NAME="ei_encode_ulong/3"><STRONG><CODE>int ei_encode_ulong(char *buf, int *index, unsigned long p)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_ulong/2"><STRONG><CODE>int ei_x_encode_ulong(ei_x_buff* x, unsigned long p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<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().

</DIV>

<P><A NAME="ei_encode_longlong/3"><STRONG><CODE>int ei_encode_longlong(char *buf, int *index, long long p)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_longlong/2"><STRONG><CODE>int ei_x_encode_longlong(ei_x_buff* x, long long p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      Encodes a GCC <CODE>long long</CODE> or Visual C++ <CODE>__int64</CODE> (64 bit)
         integer in the binary format. Note that this function is missing
         in the VxWorks port.

</DIV>

<P><A NAME="ei_encode_ulonglong/3"><STRONG><CODE>int ei_encode_ulonglong(char *buf, int *index, unsigned long long p)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_ulonglong/2"><STRONG><CODE>int ei_x_encode_ulonglong(ei_x_buff* x, unsigned long long p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      Encodes a GCC <CODE>unsigned long long</CODE> or Visual C++ <CODE>unsigned
         __int64</CODE> (64 bit) integer in the binary format. Note that
         this function is missing in the VxWorks port.

</DIV>

<P><A NAME="ei_encode_bignum/3"><STRONG><CODE>int ei_encode_bignum(char *buf, int *index, mpz_t obj)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_bignum/2"><STRONG><CODE>int ei_x_encode_bignum(ei_x_buff *x, mpz_t obj)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      Encodes a GMP <CODE>mpz_t</CODE> integer to binary format.
         To use this function the ei library needs to be configured and compiled
         to use the GMP library. 

</DIV>

<P><A NAME="ei_encode_double/3"><STRONG><CODE>int ei_encode_double(char *buf, int *index, double p)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_double/2"><STRONG><CODE>int ei_x_encode_double(ei_x_buff* x, double p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      Encodes a double-precision (64 bit) floating point number in
         the binary format.

</DIV>

<P><A NAME="ei_encode_boolean/3"><STRONG><CODE>int ei_encode_boolean(char *buf, int *index, int p)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_boolean/2"><STRONG><CODE>int ei_x_encode_boolean(ei_x_buff* x, int p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      Encodes a boolean value, as the atom <CODE>true</CODE> if p is not
         zero or <CODE>false</CODE> if p is zero.

</DIV>

<P><A NAME="ei_encode_char/3"><STRONG><CODE>int ei_encode_char(char *buf, int *index, char p)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_char/2"><STRONG><CODE>int ei_x_encode_char(ei_x_buff* x, char p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<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 <CODE>char</CODE>. Your C code should consider the
         given argument to be of type <CODE>unsigned char</CODE> even if
         the C compilers and system may define <CODE>char</CODE> to be
         signed.

</DIV>

<P><A NAME="ei_encode_string/3"><STRONG><CODE>int ei_encode_string(char *buf, int *index, const char *p)</CODE></STRONG></A><BR>
<A NAME="ei_encode_string_len/4"><STRONG><CODE>int ei_encode_string_len(char *buf, int *index, const char *p, int len)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_string/2"><STRONG><CODE>int ei_x_encode_string(ei_x_buff* x, const char *p)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_string_len/3"><STRONG><CODE>int ei_x_encode_string_len(ei_x_buff* x, const char* s, int len)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<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 <CODE>ei_x_encode_string_len()</CODE> function.

</DIV>

<P><A NAME="ei_encode_atom/3"><STRONG><CODE>int ei_encode_atom(char *buf, int *index, const char *p)</CODE></STRONG></A><BR>
<A NAME="ei_encode_atom_len/4"><STRONG><CODE>int ei_encode_atom_len(char *buf, int *index, const char *p, int len)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_atom/2"><STRONG><CODE>int ei_x_encode_atom(ei_x_buff* x, const char *p)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_atom_len/3"><STRONG><CODE>int ei_x_encode_atom_len(ei_x_buff* x, const char *p, int len)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      Encodes an atom in the binary format. The <CODE>p</CODE> parameter
         is the name of the atom. Only upto <CODE>MAXATOMLEN</CODE> bytes
         are encoded. The name should be zero-terminated, except for
         the <CODE>ei_x_encode_atom_len()</CODE> function.

</DIV>

<P><A NAME="ei_encode_binary/4"><STRONG><CODE>int ei_encode_binary(char *buf, int *index, const void *p, long len)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_binary/3"><STRONG><CODE>int ei_x_encode_binary(ei_x_buff* x, const void *p, long len)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      Encodes a binary in the binary format. The data is at
         <CODE>p</CODE>, of <CODE>len</CODE> bytes length.

</DIV>

<P><A NAME="ei_encode_pid/3"><STRONG><CODE>int ei_encode_pid(char *buf, int *index,
        const erlang_pid *p)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_pid/2"><STRONG><CODE>int ei_x_encode_pid(ei_x_buff* x,
        const erlang_pid *p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      Encodes an erlang process identifier, pid, in the binary
         format. The <CODE>p</CODE> parameter points to an
         <CODE>erlang_pid</CODE> structure (which should have been obtained
         earlier with <CODE>ei_decode_pid()</CODE>).

</DIV>

<P><A NAME="ei_encode_fun/3"><STRONG><CODE>int ei_encode_fun(char *buf, int *index, const erlang_fun *p)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_fun/2"><STRONG><CODE>int ei_x_encode_fun(ei_x_buff* x, const erlang_fun* fun)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      Encodes a fun in the binary format. The <CODE>p</CODE> parameter
         points to an <CODE>erlang_fun</CODE> structure. The
         <CODE>erlang_fun</CODE> is not freed automatically, the
         <CODE>free_fun</CODE> should be called if the fun is not needed
         after encoding.

</DIV>

<P><A NAME="ei_encode_port/3"><STRONG><CODE>int ei_encode_port(char *buf, int *index, const
erlang_port *p)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_port/2"><STRONG><CODE>int ei_x_encode_port(ei_x_buff* x, const erlang_port *p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      Encodes an erlang port in the binary format. The <CODE>p</CODE>
         parameter points to a <CODE>erlang_port</CODE> structure (which
         should have been obtained earlier with
         <CODE>ei_decode_port()</CODE>.

</DIV>

<P><A NAME="ei_encode_ref/3"><STRONG><CODE>int ei_encode_ref(char *buf, int *index, const erlang_ref *p)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_ref/2"><STRONG><CODE>int ei_x_encode_ref(ei_x_buff* x, const erlang_ref *p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      Encodes an erlang reference in the binary format. The
         <CODE>p</CODE> parameter points to a <CODE>erlang_ref</CODE> structure
         (which should have been obtained earlier with
         <CODE>ei_decode_ref()</CODE>.

</DIV>

<P><A NAME="ei_encode_term/3"><STRONG><CODE>int ei_encode_term(char *buf, int *index, void *t)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_term/2"><STRONG><CODE>int ei_x_encode_term(ei_x_buff* x, void *t)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function encodes an <CODE>ETERM</CODE>, as obtained from
         <CODE>erl_interface</CODE>. The <CODE>t</CODE> parameter is actually an
         <CODE>ETERM</CODE> pointer. This function doesn't free the
         <CODE>ETERM</CODE>.

</DIV>

<P><A NAME="ei_encode_trace/3"><STRONG><CODE>int ei_encode_trace(char *buf, int *index, const erlang_trace *p)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_trace/2"><STRONG><CODE>int ei_x_encode_trace(ei_x_buff* x, const erlang_trace *p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function encodes an erlang trace token in the binary
         format. The <CODE>p</CODE> parameter points to a
         <CODE>erlang_trace</CODE> structure (which should have been
         obtained earlier with <CODE>ei_decode_trace()</CODE>.

</DIV>

<P><A NAME="ei_encode_tuple_header/3"><STRONG><CODE>int ei_encode_tuple_header(char *buf, int *index, int arity)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_tuple_header/2"><STRONG><CODE>int ei_x_encode_tuple_header(ei_x_buff* x, int arity)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function encodes a tuple header, with a specified
         arity. The next <CODE>arity</CODE> 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>      E.g. to encode the tuple <CODE>{a, {b, {}}}</CODE>:
        
<PRE>
ei_encode_tuple_header(buf, &#38;i, 2);
ei_encode_atom(buf, &#38;i, &#34;a&#34;);
ei_encode_tuple_header(buf, &#38;i, 2);
ei_encode_atom(buf, &#38;i, &#34;b&#34;);
ei_encode_tuple_header(buf, &#38;i, 0);
        
</PRE>

</DIV>

<P><A NAME="ei_encode_list_header/3"><STRONG><CODE>int ei_encode_list_header(char *buf, int *index, int arity)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_list_header/2"><STRONG><CODE>int ei_x_encode_list_header(ei_x_buff* x, int arity)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function encodes a list header, with a specified
         arity. The next <CODE>arity+1</CODE> terms are the elements
         (actually it's <CODE>arity</CODE> 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>      E.g. to encode the list <CODE>[c, d, [e | f]]</CODE>:
        
<PRE>
ei_encode_list_header(buf, &#38;i, 3);
ei_encode_atom(buf, &#38;i, &#34;c&#34;);
ei_encode_atom(buf, &#38;i, &#34;d&#34;);
ei_encode_list_header(buf, &#38;i, 1);
ei_encode_atom(buf, &#38;i, &#34;e&#34;);
ei_encode_atom(buf, &#38;i, &#34;f&#34;);
ei_encode_empty_list(buf, &#38;i);
        
</PRE>

<P>
<TABLE CELLPADDING=4>
  <TR>
    <TD VALIGN=TOP><IMG ALT="Note!" SRC="note.gif"></TD>
    <TD>

<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 <CODE>[a, b, c]</CODE> can be
         written as <CODE>[a | [b | [c]]]</CODE>. Using this, a list can
         be written as conses.
            </TD>
  </TR>
</TABLE>

<P>      To encode a list, without knowing the arity in advance:
        
<PRE>
while (something()) {
    ei_x_encode_list_header(&#38;x, 1);
    ei_x_encode_ulong(&#38;x, i); /* just an example */
}
ei_x_encode_empty_list(&#38;x);
        
</PRE>

</DIV>

<P><A NAME="ei_encode_empty_list/2"><STRONG><CODE>int ei_encode_empty_list(char* buf, int* index)</CODE></STRONG></A><BR>
<A NAME="ei_x_encode_empty_list/1"><STRONG><CODE>int ei_x_encode_empty_list(ei_x_buff* x)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function encodes an empty list. It's often used at the
         tail of a list.

</DIV>

<P><A NAME="ei_get_type/4"><STRONG><CODE>intei_get_type(const char *buf, const int *index, int *type, int *size)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function returns the type in <CODE>type</CODE> and size in
         <CODE>size</CODE> of the encoded term.

         For strings and atoms, size
         is the number of characters <STRONG>not</STRONG> including the
         terminating 0. For binaries, <CODE>size</CODE> is the number of
         bytes. For lists and tuples, <CODE>size</CODE> is the arity of the
         object. For other types, <CODE>size</CODE> is 0. In all cases,
         <CODE>index</CODE> is left unchanged.
        
</DIV>

<P><A NAME="ei_decode_version/3"><STRONG><CODE>int ei_decode_version(const char *buf, int *index, int *version)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function decodes the version magic number for the
         erlang binary term format. It must be the first token in a
         binary term.

</DIV>

<P><A NAME="ei_decode_long/3"><STRONG><CODE>int ei_decode_long(const char *buf, int *index, long *p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<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().

</DIV>

<P><A NAME="ei_decode_ulong/3"><STRONG><CODE>int ei_decode_ulong(const char *buf, int *index, unsigned long *p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<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().

</DIV>

<P><A NAME="ei_decode_longlong/3"><STRONG><CODE>int ei_decode_longlong(const char *buf, int *index, long long *p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function decodes a GCC <CODE>long long</CODE> or Visual C++ <CODE>__int64</CODE>
         (64 bit) integer from the binary format. Note that this
         function is missing in the VxWorks port.

</DIV>

<P><A NAME="ei_decode_ulonglong/3"><STRONG><CODE>int ei_decode_ulonglong(const char *buf, int *index, unsigned long long *p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function decodes a GCC <CODE>unsigned long long</CODE> or Visual C++
         <CODE>unsigned __int64</CODE> (64 bit) integer from the binary format.
         Note that this function is missing in the VxWorks port.

</DIV>

<P><A NAME="ei_decode_bignum/3"><STRONG><CODE>int ei_decode_bignum(const char *buf, int *index, mpz_t obj)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function decodes an integer in the binary format to a GMP <CODE>mpz_t</CODE> integer.
         To use this function the ei library needs to be configured and compiled
         to use the GMP library. 

</DIV>

<P><A NAME="ei_decode_double/3"><STRONG><CODE>int ei_decode_double(const char *buf, int *index, double *p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function decodes an double-precision (64 bit) floating
         point number from the binary format.

</DIV>

<P><A NAME="ei_decode_boolean/3"><STRONG><CODE>int ei_decode_boolean(const char *buf, int *index, int *p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function decodes a boolean value from the binary
         format. A boolean is actually an atom, <CODE>true</CODE> decodes 1
         and <CODE>false</CODE> decodes 0.

</DIV>

<P><A NAME="ei_decode_char/3"><STRONG><CODE>int ei_decode_char(const char *buf, int *index, char *p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<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 <CODE>char</CODE>. Your C code should consider the
         returned value to be of type <CODE>unsigned char</CODE> even if
         the C compilers and system may define <CODE>char</CODE> to be
         signed.

</DIV>

<P><A NAME="ei_decode_string/3"><STRONG><CODE>int ei_decode_string(const char *buf, int *index, char *p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<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 <CODE>term_to_binary/1</CODE>,
         even if it was not intended.
        
<P>      The string is copied to <CODE>p</CODE>, and enough space must be
         allocated. The returned string is null terminated so you
         need to add an extra byte to the memory requirement.

</DIV>

<P><A NAME="ei_decode_atom/3"><STRONG><CODE>int ei_decode_atom(const char *buf, int *index, char *p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function decodes an atom from the binary format. The
         name of the atom is placed at <CODE>p</CODE>. There can be at most
         <CODE>MAXATOMLEN</CODE> bytes placed in the buffer.

</DIV>

<P><A NAME="ei_decode_binary/4"><STRONG><CODE>int ei_decode_binary(const char *buf, int *index, void *p, long *len)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function decodes a binary from the binary format. The
         <CODE>len</CODE> parameter is set to the actual size of the
         binary. Note that <CODE>ei_decode_binary()</CODE> assumes that there
         are enough room for the binary. The size required can be
         fetched by <CODE>ei_get_type()</CODE>.

</DIV>

<P><A NAME="ei_decode_fun/3"><STRONG><CODE>int ei_decode_fun(const char *buf, int *index, erlang_fun *p)</CODE></STRONG></A><BR>
<A NAME="free_fun/1"><STRONG><CODE>void free_fun(erlang_fun* f)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function decodes a fun from the binary format. The
         <CODE>p</CODE> parameter should be NULL or point to an
         <CODE>erlang_fun</CODE> structure. This is the only decode
         function that allocates memory; when the <CODE>erlang_fun</CODE>
         is no longer needed, it should be freed with
         <CODE>free_fun</CODE>. (This has to do with the arbitrary size of
         the environment for a fun.)

</DIV>

<P><A NAME="ei_decode_pid/3"><STRONG><CODE>int ei_decode_pid(const char *buf, int *index, erlang_pid *p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      Decodes a pid, process identifier, from the binary format.

</DIV>

<P><A NAME="ei_decode_port/3"><STRONG><CODE>int ei_decode_port(const char *buf, int *index, erlang_port *p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function decodes a port identifier from the binary
         format.

</DIV>

<P><A NAME="ei_decode_ref/3"><STRONG><CODE>int ei_decode_ref(const char *buf, int *index, erlang_ref *p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function decodes a reference from the binary format.

</DIV>

<P><A NAME="ei_decode_trace/3"><STRONG><CODE>int ei_decode_trace(const char *buf, int *index, erlang_trace *p)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      Decodes an erlang trace token from the binary format.

</DIV>

<P><A NAME="ei_decode_tuple_header/3"><STRONG><CODE>int ei_decode_tuple_header(const char *buf, int *index, int *arity)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function decodes a tuple header, the number of elements
         is returned in <CODE>arity</CODE>. The tuple elements follows in order in
         the buffer.

</DIV>

<P><A NAME="ei_decode_list_header/3"><STRONG><CODE>int ei_decode_list_header(const char *buf, int *index, int *arity)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function decodes a list header from the binary
         format. The number of elements is returned in
         <CODE>arity</CODE>. The <CODE>arity+1</CODE> elements follows (the last
         one is the tail of the list, normally an empty list.) If
         <CODE>arity</CODE> is <CODE>0</CODE>, it's an empty list.
        
<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 <CODE>ei_decode_string()</CODE>
         instead.

</DIV>

<P><A NAME="ei_decode_ei_term/3"><STRONG><CODE>int ei_decode_ei_term(const char* buf, int* index,
ei_term* term)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function decodes any term, or at least tries to. If the
         term pointed at by <CODE>*index</CODE> in <CODE>buf</CODE> fits in the
         <CODE>term</CODE> union, it is decoded, and the appropriate field
         in <CODE>term-&#62;value</CODE> is set, and <CODE>*index</CODE> is
         incremented by the term size.
        
<P>      The function returns 0 on successful encoding, -1 on error,
         and 1 if the term seems alright, but does not fit in the
         <CODE>term</CODE> structure. If it returns 0, the <CODE>index</CODE>
         will be incremented, and the <CODE>term</CODE> contains the
         decoded term.
        
<P>      The <CODE>term</CODE> 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.

</DIV>

<P><A NAME="ei_decode_term/3"><STRONG><CODE>int ei_decode_term(const char *buf, int *index, void *t)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function decodes a term from the binary format. The
         term is return in <CODE>t</CODE> as a <CODE>ETERM*</CODE>, so <CODE>t</CODE>
         is actually an <CODE>ETERM**</CODE> (see
         <CODE>erl_interface(3)</CODE>. The term should later be
         deallocated.
        
<P>      Note that this function is located in the erl_interface
         library.
        
</DIV>

<P><A NAME="ei_print_term/3"><STRONG><CODE>int ei_print_term(FILE* fp, const char* buf, int* index)</CODE></STRONG></A><BR>
<A NAME="ei_s_print_term/3"><STRONG><CODE>int ei_s_print_term(char** s, const char* buf, int* index)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P> This function prints a term, in clear text, to the file
         given by <CODE>fp</CODE>, or the buffer pointed to by <CODE>s</CODE>. It
         tries to resemble the term printing in the erlang shell.
        
<P>      In <CODE>ei_s_print_term()</CODE>, the parameter <CODE>s</CODE> should
         point to a dynamically (malloc) allocated string of
         <CODE>BUFSIZ</CODE> bytes or a NULL pointer. The string may be
         reallocated (and <CODE>*s</CODE> may be updated) by this function
         if the result is more than <CODE>BUFSIZ</CODE> characters. The
         string returned is zero-terminated.
        
<P>      The return value is the number of characters written to the
         file or string, or -1 if <CODE>buf[index]</CODE> doesn't contain a
         valid term. Unfortunately, I/O errors on <CODE>fp</CODE> is not
         checked.
        
<P>      The argument <CODE>index</CODE> is updated, i.e. this function can
         be viewed as en decode function that decodes a term into a
         human readable format.

</DIV>

<P><A NAME="ei_x_format/3"><STRONG><CODE>int ei_x_format(ei_x_buff* x, const char* fmt, ...)</CODE></STRONG></A><BR>
<A NAME="ei_x_format_wo_ver/3"><STRONG><CODE>int ei_x_format_wo_ver(ei_x_buff* x, const char *fmt, ... )</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      Format a term, given as a string, to a buffer. This
         functions works like a sprintf for erlang terms. The
         <CODE>fmt</CODE> contains a format string, with arguments like
         <CODE>~d</CODE>, to insert terms from variables. The following
         formats are supported (with the C types given):
        
<P>      
<PRE>
~a - an atom, 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
          
</PRE>

<P>      For instance, to encode a tuple with some stuff:
        
<PRE>
ei_x_format(&#34;{~a,~i,~d}&#34;, &#34;numbers&#34;, 12, 3.14159)
encodes the tuple {numbers,12,3.14159}
        
</PRE>

<P>      The <CODE>ei_x_format_wo_ver()</CODE> formats into a buffer, without
         the initial version byte.

</DIV>

<P><A NAME="ei_x_new/1"><STRONG><CODE>int ei_x_new(ei_x_buff* x)</CODE></STRONG></A><BR>
<A NAME="ei_x_new_with_version/1"><STRONG><CODE>int ei_x_new_with_version(ei_x_buff* x)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function allocates a new <CODE>ei_x_buff</CODE> buffer. The
         fields of the structure pointed to by <CODE>x</CODE> parameter is
         filled in, and a default buffer is allocated. The
         <CODE>ei_x_new_with_version()</CODE> also puts an initial version
         byte, that is used in the binary format. (So that
         <CODE>ei_x_encode_version()</CODE> won't be needed.)

</DIV>

<P><A NAME="ei_x_free/1"><STRONG><CODE>int ei_x_free(ei_x_buff* x)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      This function frees an <CODE>ei_x_buff</CODE> buffer. The memory
         used by the buffer is returned to the OS.

</DIV>

<P><A NAME="ei_x_append/2"><STRONG><CODE>int ei_x_append(ei_x_buff* x, const ei_x_buff* x2)</CODE></STRONG></A><BR>
<A NAME="ei_x_append_buf/3"><STRONG><CODE>int ei_x_append_buf(ei_x_buff* x, const char* buf, int len)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>      These functions appends data at the end of the buffer <CODE>x</CODE>.

</DIV>

<P><A NAME="ei_skip_term/2"><STRONG><CODE>int ei_skip_term(const char* buf, int* index)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<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>      <CODE>buf</CODE> is the buffer.
        
<P>      <CODE>index</CODE> is updated to point right after the term in the
         buffer.
        
<P>
<TABLE CELLPADDING=4>
  <TR>
    <TD VALIGN=TOP><IMG ALT="Note!" SRC="note.gif"></TD>
    <TD>

<P>      This can be useful when you want to hold arbitrary
         terms: just skip them and copy the binary term data to some
         buffer.
            </TD>
  </TR>
</TABLE>

<P>      The function returns <CODE>0</CODE> on success and <CODE>-1</CODE> on
         failure.

</DIV>

<H3>Debug Information</H3>
<DIV CLASS=REFBODY>

<P> Some tips on what to check when the emulator doesn't seem to
receive the terms that you send.

<P>
<UL>

<LI>
be careful with the version header, use
        <CODE>ei_x_new_with_version()</CODE> when appropriate
</LI>


<LI>
turn on distribution tracing on the erlang node
</LI>


<LI>
check the result codes from ei_decode_-calls
</LI>


</UL>

</DIV>

<H3>See Also</H3>
<DIV CLASS=REFBODY>

<P>erl_interface(3)

</DIV>

<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
Kenneth Lundin - support@erlang.ericsson.se<BR>
Jakob Cederlund - support@erlang.ericsson.se<BR>

</DIV>
<CENTER>
<HR>
<SMALL>erl_interface 3.5.5.2<BR>
Copyright &copy; 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>