diff options
Diffstat (limited to 'lib/erl_interface/doc/src/erl_marshal.xml')
| -rw-r--r-- | lib/erl_interface/doc/src/erl_marshal.xml | 272 |
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örn Törnkvist</prepared> + <responsible>Torbjörn Törnkvist</responsible> + <docno></docno> + <approved>Bjarne Däcker</approved> + <checked>Torbjörn Tö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 < 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> + |