aboutsummaryrefslogtreecommitdiffstats
path: root/lib/erl_interface/doc/src/erl_marshal.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/erl_interface/doc/src/erl_marshal.xml')
-rw-r--r--lib/erl_interface/doc/src/erl_marshal.xml258
1 files changed, 127 insertions, 131 deletions
diff --git a/lib/erl_interface/doc/src/erl_marshal.xml b/lib/erl_interface/doc/src/erl_marshal.xml
index c70bdb53e1..30b7281a51 100644
--- a/lib/erl_interface/doc/src/erl_marshal.xml
+++ b/lib/erl_interface/doc/src/erl_marshal.xml
@@ -28,244 +28,240 @@
<docno></docno>
<approved>Bjarne D&auml;cker</approved>
<checked>Torbj&ouml;rn T&ouml;rnkvist</checked>
- <date>980703</date>
+ <date>1998-07-03</date>
<rev>A</rev>
<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><![CDATA[bufp1]]></c> is a buffer containing an encoded
+ Erlang term term1.</item>
+ <item><c><![CDATA[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> &lt; <c>term2</c>, or <c>1</c> if <c>term2</c> &lt;
+ 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>
+ <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><![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
+ 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>
+ <list type="bulleted">
+ <item>
+ <p><c><![CDATA[bufp]]></c> is a pointer to a buffer containing one
+ or more encoded Erlang terms.</p>
+ </item>
+ <item>
+ <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> is
+ updated so that it points to the next encoded term.</p>
+ </item>
+ </list>
<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
+ corresponding to the contents of <c><![CDATA[bufp]]></c> on success,
+ otherwise <c>NULL</c>. <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
+ <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>
+ 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><![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
+ 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><![CDATA[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><![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>
+ requirements for a term. Notice that this information is
+ implementation-specific, and can 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>
+ 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>
+ <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>
+ <item>Need 5 bytes, plus the space for each element, and 1
+ more 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>
+ <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>
+ <item>Need 5 bytes.</item>
<tag><c><![CDATA[Characters]]></c></tag>
- <item>(integers &lt; 256) need 2 bytes.</item>
+ <item>(Integers &lt; 256) need 2 bytes.</item>
<tag><c><![CDATA[Floating point numbers]]></c></tag>
- <item>need 32 bytes.</item>
+ <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>
+ <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>
+ <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><![CDATA[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><![CDATA[bufp]]></c> is a pointer to a buffer containing one
+ or more encoded Erlang terms.</item>
+ <item><c><![CDATA[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><![CDATA[erl_decode()]]></c> 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, <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
+ <p>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>
+ format by <c><![CDATA[erl_encode()]]></c>.</p>
+ <p>Returns the size in bytes.</p>
</desc>
</func>
</funcs>