The R13B03 release.OTP_R13B03

1 files changed, 272 insertions, 0 deletions

diff --git a/lib/erl_interface/doc/src/erl_marshal.xml b/lib/erl_interface/doc/src/erl_marshal.xml
new file mode 100644
index 0000000000..a7eaf78f35
--- /dev/null
+++ b/lib/erl_interface/doc/src/erl_marshal.xml
@@ -0,0 +1,272 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE cref SYSTEM "cref.dtd">
+
+<cref>
+  <header>
+    <copyright>
+      <year>1996</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>erl_marshal</title>
+    <prepared>Torbj&ouml;rn T&ouml;rnkvist</prepared>
+    <responsible>Torbj&ouml;rn T&ouml;rnkvist</responsible>
+    <docno></docno>
+    <approved>Bjarne D&auml;cker</approved>
+    <checked>Torbj&ouml;rn T&ouml;rnkvist</checked>
+    <date>980703</date>
+    <rev>A</rev>
+    <file>erl_marshal.sgml</file>
+  </header>
+  <lib>erl_marshal</lib>
+  <libsummary>Encoding and Decoding of Erlang terms</libsummary>
+  <description>
+    <p>This module contains functions for encoding Erlang terms into
+      a sequence of bytes, and for decoding Erlang terms from a
+      sequence of bytes.</p>
+  </description>
+  <funcs>
+    <func>
+      <name><ret>int</ret><nametext>erl_compare_ext(bufp1, bufp2)</nametext></name>
+      <fsummary>Compares encoded byte sequences</fsummary>
+      <type>
+        <v>unsigned char *bufp1,*bufp2;</v>
+      </type>
+      <desc>
+        <p>This function compares two encoded terms.
+          </p>
+        <p><c><![CDATA[bufp1]]></c> is a buffer containing an encoded Erlang
+          term term1.
+          </p>
+        <p><c><![CDATA[bufp2]]></c> is a buffer containing an encoded Erlang
+          term term2.
+          </p>
+        <p>The function returns 0 if the terms are equal, -1 if term1
+          is less than term2, or 1 if term2 is less than term1. 
+          </p>
+      </desc>
+    </func>
+    <func>
+      <name><ret>ETERM *</ret><nametext>erl_decode(bufp)</nametext></name>
+      <name><ret>ETERM *</ret><nametext>erl_decode_buf(bufpp)</nametext></name>
+      <fsummary>Converts a term from Erlang external format</fsummary>
+      <type>
+        <v>unsigned char *bufp;</v>
+        <v>unsigned char **bufpp;</v>
+      </type>
+      <desc>
+        <p><c><![CDATA[erl_decode()]]></c> and <c><![CDATA[erl_decode_buf()]]></c> decode
+          the contents of a buffer and return the corresponding
+          Erlang term.  <c><![CDATA[erl_decode_buf()]]></c> provides a simple
+          mechanism for dealing with several encoded terms stored
+          consecutively in the buffer.</p>
+        <p><c><![CDATA[bufp]]></c> is a pointer to a buffer containing one or
+          more encoded Erlang terms.
+          </p>
+        <p><c><![CDATA[bufpp]]></c> is the address of a buffer pointer. The buffer
+          contains one or more consecutively encoded Erlang terms.
+          Following a successful call to  <c><![CDATA[erl_decode_buf()]]></c>, 
+          <c><![CDATA[bufpp]]></c> will be updated so that it points to the next
+          encoded term.
+          </p>
+        <p><c><![CDATA[erl_decode()]]></c> returns an Erlang term
+          corresponding to the contents of <c><![CDATA[bufp]]></c> on success, or
+          NULL on failure. <c><![CDATA[erl_decode_buf()]]></c> returns an Erlang
+          term corresponding to the first of the consecutive terms in
+          <c><![CDATA[bufpp]]></c> and moves <c><![CDATA[bufpp]]></c> forward to point to the
+          next term in the buffer. On failure, each of the functions
+          returns NULL.
+          </p>
+      </desc>
+    </func>
+    <func>
+      <name><ret>int</ret><nametext>erl_encode(term, bufp)</nametext></name>
+      <name><ret>int</ret><nametext>erl_encode_buf(term, bufpp)</nametext></name>
+      <fsummary>Converts a term into Erlang external format</fsummary>
+      <type>
+        <v>ETERM *term;</v>
+        <v>unsigned char *bufp;</v>
+        <v>unsigned char **bufpp;</v>
+      </type>
+      <desc>
+        <p><c><![CDATA[erl_encode()]]></c> and  <c><![CDATA[erl_encode_buf()]]></c> encode 
+          Erlang terms into external format for storage or transmission.
+          <c><![CDATA[erl_encode_buf()]]></c> provides a simple mechanism for
+          encoding several terms consecutively in the same
+          buffer.
+          </p>
+        <p><c>term</c> is an Erlang term to be encoded.
+          </p>
+        <p><c>bufp</c> is a pointer to a buffer containing one or
+          more encoded Erlang terms.
+          </p>
+        <p><c>bufpp</c> is a pointer to a pointer to a buffer
+          containing one or more consecutively encoded Erlang terms.
+          Following a successful call to  <c><![CDATA[erl_encode_buf()]]></c>, 
+          <c>bufpp</c> will be updated so that it points to the
+          position for the next encoded term.
+          </p>
+        <p>
+	  These functions returns the number of bytes written to buffer
+	  if successful, otherwise returns 0.  
+	</p>
+        <p>Note that no bounds checking is done on the buffer. It is
+          the caller's responsibility to make sure that the buffer is
+          large enough to hold the encoded terms. You can either use a
+          static buffer that is large enough to hold the terms you
+          expect to need in your program, or use <c><![CDATA[erl_term_len()]]></c>
+          to determine the exact requirements for a given term.
+          </p>
+        <p>The following can help you estimate the buffer
+          requirements for a term. Note that this information is
+          implementation specific, and may change in future versions.
+          If you are unsure, use <c><![CDATA[erl_term_len()]]></c>.
+          </p>
+        <p>Erlang terms are encoded with a 1 byte tag that
+          identifies the type of object, a 2- or 4-byte length field,
+          and then the data itself. Specifically:
+          </p>
+        <taglist>
+          <tag><c><![CDATA[Tuples]]></c></tag>
+          <item>need 5 bytes, plus the space for each element.</item>
+          <tag><c><![CDATA[Lists]]></c></tag>
+          <item>need 5 bytes, plus the space for each element, and 1
+           additional byte for the empty list at the end.</item>
+          <tag><c><![CDATA[Strings and atoms]]></c></tag>
+          <item>need 3 bytes, plus 1 byte for each character (the
+           terminating 0 is not encoded). Really long strings (more
+           than 64k characters) are encoded as lists. Atoms cannot
+           contain more than 256 characters.</item>
+          <tag><c><![CDATA[Integers]]></c></tag>
+          <item>need 5 bytes.</item>
+          <tag><c><![CDATA[Characters]]></c></tag>
+          <item>(integers &lt; 256) need 2 bytes.</item>
+          <tag><c><![CDATA[Floating point numbers]]></c></tag>
+          <item>need 32 bytes.</item>
+          <tag><c><![CDATA[Pids]]></c></tag>
+          <item>need 10 bytes, plus the space for the node name, which
+           is an atom.</item>
+          <tag><c><![CDATA[Ports and Refs]]></c></tag>
+          <item>need 6 bytes, plus the space for the node name, which
+           is an atom.</item>
+        </taglist>
+        <p>The total space required will be the result calculated
+          from the information above, plus 1 additional byte for a 
+          version identifier.
+          </p>
+      </desc>
+    </func>
+    <func>
+      <name><ret>int</ret><nametext>erl_ext_size(bufp)</nametext></name>
+      <fsummary>Counts elements in encoded term</fsummary>
+      <type>
+        <v>unsigned char *bufp;</v>
+      </type>
+      <desc>
+        <p>This function returns the number of elements in an
+          encoded term.</p>
+      </desc>
+    </func>
+    <func>
+      <name><ret>unsigned char</ret><nametext>erl_ext_type(bufp)</nametext></name>
+      <fsummary>Determines type of an encoded byte sequence</fsummary>
+      <type>
+        <v>unsigned char *bufp;</v>
+      </type>
+      <desc>
+        <p>This function identifies and returns the type of Erlang term encoded
+          in a buffer. It will skip a trailing <em>magic</em> identifier.
+          Returns <c><![CDATA[0]]></c> if the type can't be determined or one of</p>
+        <list type="bulleted">
+          <item>
+            <p>ERL_INTEGER</p>
+          </item>
+          <item>
+            <p>ERL_ATOM</p>
+          </item>
+          <item>
+            <p>ERL_PID <c><![CDATA[/* Erlang process identifier */]]></c></p>
+          </item>
+          <item>
+            <p>ERL_PORT</p>
+          </item>
+          <item>
+            <p>ERL_REF <c><![CDATA[/* Erlang reference */]]></c></p>
+          </item>
+          <item>
+            <p>ERL_EMPTY_LIST</p>
+          </item>
+          <item>
+            <p>ERL_LIST</p>
+          </item>
+          <item>
+            <p>ERL_TUPLE</p>
+          </item>
+          <item>
+            <p>ERL_FLOAT</p>
+          </item>
+          <item>
+            <p>ERL_BINARY</p>
+          </item>
+          <item>
+            <p>ERL_FUNCTION</p>
+          </item>
+        </list>
+      </desc>
+    </func>
+    <func>
+      <name><ret>unsigned char *</ret><nametext>erl_peek_ext(bufp, pos)</nametext></name>
+      <fsummary>Steps over encoded term</fsummary>
+      <type>
+        <v>unsigned char *bufp;</v>
+        <v>int pos;</v>
+      </type>
+      <desc>
+        <p>This function is used for stepping over one or more
+          encoded terms in a buffer, in order to directly access a
+          later term.
+          </p>
+        <p><c><![CDATA[bufp]]></c> is a pointer to a buffer containing one or
+          more encoded Erlang terms.
+          </p>
+        <p><c><![CDATA[pos]]></c> indicates how many terms to step over in the
+          buffer. 
+          </p>
+        <p>The function returns a pointer to a sub-term that can be
+          used in a subsequent call to <c><![CDATA[erl_decode()]]></c> in order to retrieve
+          the term at that position. If there is no term, or <c><![CDATA[pos]]></c>
+          would exceed the size of the terms in the buffer, NULL is returned.
+          </p>
+      </desc>
+    </func>
+    <func>
+      <name><ret>int</ret><nametext>erl_term_len(t)</nametext></name>
+      <fsummary>Determines encoded size of term</fsummary>
+      <type>
+        <v>ETERM *t;</v>
+      </type>
+      <desc>
+        <p>This function determines the buffer space that would be
+          needed by <c><![CDATA[t]]></c> if it were encoded into Erlang external
+          format by <c><![CDATA[erl_encode()]]></c>.
+          </p>
+        <p>The size in bytes is returned.
+          </p>
+      </desc>
+    </func>
+  </funcs>
+</cref>
+