diff options
Diffstat (limited to 'lib/erl_interface/doc/src/erl_marshal.xml')
| -rw-r--r-- | lib/erl_interface/doc/src/erl_marshal.xml | 287 |
1 files changed, 141 insertions, 146 deletions
diff --git a/lib/erl_interface/doc/src/erl_marshal.xml b/lib/erl_interface/doc/src/erl_marshal.xml index 7c56089016..2ad658f78b 100644 --- a/lib/erl_interface/doc/src/erl_marshal.xml +++ b/lib/erl_interface/doc/src/erl_marshal.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 @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>erl_marshal</title> @@ -28,246 +28,241 @@ <docno></docno> <approved>Bjarne Däcker</approved> <checked>Torbjörn Törnkvist</checked> - <date>980703</date> + <date>1998-07-03</date> <rev>A</rev> - <file>erl_marshal.sgml</file> + <file>erl_marshal.xml</file> </header> <lib>erl_marshal</lib> - <libsummary>Encoding and Decoding of Erlang terms</libsummary> + <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> + <fsummary>Compare 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> + <p>Compares two encoded terms.</p> + <list type="bulleted"> + <item><c>bufp1</c> is a buffer containing an encoded + Erlang term term1.</item> + <item><c>bufp2</c> is a buffer containing an encoded + Erlang term term2.</item> + </list> + <p>Returns <c>0</c> if the terms are equal, <c>-1</c> if + <c>term1</c> < <c>term2</c>, or <c>1</c> if <c>term2</c> < + <c>term1</c>.</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> + <fsummary>Convert 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 + <p><c>erl_decode()</c> and + <c>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 + Erlang term. <c>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 + <list type="bulleted"> + <item> + <p><c>bufp</c> is a pointer to a buffer containing one + or more encoded Erlang terms.</p> + </item> + <item> + <p><c>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>erl_decode_buf()</c>, <c>bufpp</c> is + updated so that it points to the next encoded term.</p> + </item> + </list> + <p><c>erl_decode()</c> returns an Erlang term + corresponding to the contents of <c>bufp</c> on success, + otherwise <c>NULL</c>. <c>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 + <c>bufpp</c> and moves <c>bufpp</c> forward + to point to the next term in the buffer. On failure, each of the functions - returns NULL. - </p> + return <c>NULL</c>.</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> + <fsummary>Convert 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 + <p><c>erl_encode()</c> and + <c>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 + <c>erl_encode_buf()</c> provides a simple mechanism for + encoding several terms consecutively in the same buffer.</p> + <list type="bulleted"> + <item> + <p><c>term</c> is an Erlang term to be encoded.</p> + </item> + <item> + <p><c>bufp</c> is a pointer to a buffer containing one or + more encoded Erlang terms.</p> + </item> + <item> + <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>erl_encode_buf()</c>, <c>bufpp</c> is updated so + that it points to the + position for the next encoded term.</p> + </item> + </list> + <p>These functions return the number of bytes written to buffer + on success, otherwise <c>0</c>.</p> + <p>Notice that no bounds checking is done on the buffer. It is + the caller's responsibility to ensure 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> + static buffer that is large enough to hold the terms you expect + to need in your program, or use <c>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> + requirements for a term. Notice that this information is + implementation-specific, and can change in future versions. + If you are unsure, use <c>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> + 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> + <tag><c>Tuples</c></tag> + <item>Need 5 bytes, plus the space for each element.</item> + <tag><c>Lists</c></tag> + <item>Need 5 bytes, plus the space for each element, and 1 + more byte for the empty list at the end.</item> + <tag><c>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>Integers</c></tag> + <item>Need 5 bytes.</item> + <tag><c>Characters</c></tag> + <item>(Integers < 256) need 2 bytes.</item> + <tag><c>Floating point numbers</c></tag> + <item>Need 32 bytes.</item> + <tag><c>Pids</c></tag> + <item>Need 10 bytes, plus the space for the node name, which + is an atom.</item> + <tag><c>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> + <p>The total space required is the result calculated + from the information above, plus 1 more 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> + <fsummary>Count 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> + <p>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> + <fsummary>Determine 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> + <p>Identifies and returns the type of Erlang term encoded + in a buffer. It skips a trailing <em>magic</em> identifier.</p> + <p>Returns <c>0</c> if the type cannot be determined or + one of:</p> <list type="bulleted"> - <item> - <p>ERL_INTEGER</p> + <item><c>ERL_INTEGER</c> </item> - <item> - <p>ERL_ATOM</p> + <item><c>ERL_ATOM</c> </item> - <item> - <p>ERL_PID <c><![CDATA[/* Erlang process identifier */]]></c></p> + <item><c>ERL_PID</c> (Erlang process identifier) </item> - <item> - <p>ERL_PORT</p> + <item><c>ERL_PORT</c> </item> - <item> - <p>ERL_REF <c><![CDATA[/* Erlang reference */]]></c></p> + <item><c>ERL_REF</c> (Erlang reference) </item> - <item> - <p>ERL_EMPTY_LIST</p> + <item><c>ERL_EMPTY_LIST</c> </item> - <item> - <p>ERL_LIST</p> + <item><c>ERL_LIST</c> </item> - <item> - <p>ERL_TUPLE</p> + <item><c>ERL_TUPLE</c> </item> - <item> - <p>ERL_FLOAT</p> + <item><c>ERL_FLOAT</c> </item> - <item> - <p>ERL_BINARY</p> + <item><c>ERL_BINARY</c> </item> - <item> - <p>ERL_FUNCTION</p> + <item><c>ERL_FUNCTION</c> </item> </list> </desc> </func> + <func> <name><ret>unsigned char *</ret><nametext>erl_peek_ext(bufp, pos)</nametext></name> - <fsummary>Steps over encoded term</fsummary> + <fsummary>Step 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> + encoded terms in a buffer, to directly access later term.</p> + <list type="bulleted"> + <item><c>bufp</c> is a pointer to a buffer containing one + or more encoded Erlang terms.</item> + <item><c>pos</c> indicates how many terms to step over in + the buffer.</item> + </list> + <p>Returns a pointer to a subterm that can be + used in a later call to <c>erl_decode()</c> to retrieve + the term at that position. If there is no term, or + <c>pos</c> would exceed the size of the terms in the + buffer, <c>NULL</c> is returned.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>erl_term_len(t)</nametext></name> - <fsummary>Determines encoded size of term</fsummary> + <fsummary>Determine 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> + <p>Determines the buffer space that would be + needed by <c>t</c> if it were encoded into Erlang external + format by <c>erl_encode()</c>.</p> + <p>Returns the size in bytes.</p> </desc> </func> </funcs> </cref> - |