← Back to branch summary

~rdoering/ubuntu/karmic/erlang/fix-535090

« back to all changes in this revision

Viewing changes to lib/erl_interface/doc/src/erl_marshal.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sergei Golovan
  • Date: 2009-02-15 16:42:52 UTC
  • mfrom: (1.1.13 upstream)
  • mto: (3.3.1 squeeze)
  • mto: This revision was merged to the branch mainline in revision 17.
  • Revision ID: james.westby@ubuntu.com-20090215164252-dxpjjuq108nz4noa
Upload to unstable after lenny is released.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/erl_interface/doc/src/erl_marshal.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE cref SYSTEM "cref.dtd">
 
3
 
 
4
<cref>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>1996</year>
 
8
      <year>2007</year>
 
9
      <holder>Ericsson AB, All Rights Reserved</holder>
 
10
    </copyright>
 
11
    <legalnotice>
 
12
  The contents of this file are subject to the Erlang Public License,
 
13
  Version 1.1, (the "License"); you may not use this file except in
 
14
  compliance with the License. You should have received a copy of the
 
15
  Erlang Public License along with this software. If not, it can be
 
16
  retrieved online at http://www.erlang.org/.
 
17
 
 
18
  Software distributed under the License is distributed on an "AS IS"
 
19
  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
20
  the License for the specific language governing rights and limitations
 
21
  under the License.
 
22
 
 
23
  The Initial Developer of the Original Code is Ericsson AB.
 
24
    </legalnotice>
 
25
 
 
26
    <title>erl_marshal</title>
 
27
    <prepared>Torbj&ouml;rn T&ouml;rnkvist</prepared>
 
28
    <responsible>Torbj&ouml;rn T&ouml;rnkvist</responsible>
 
29
    <docno></docno>
 
30
    <approved>Bjarne D&auml;cker</approved>
 
31
    <checked>Torbj&ouml;rn T&ouml;rnkvist</checked>
 
32
    <date>980703</date>
 
33
    <rev>A</rev>
 
34
    <file>erl_marshal.sgml</file>
 
35
  </header>
 
36
  <lib>erl_marshal</lib>
 
37
  <libsummary>Encoding and Decoding of Erlang terms</libsummary>
 
38
  <description>
 
39
    <p>This module contains functions for encoding Erlang terms into
 
40
      a sequence of bytes, and for decoding Erlang terms from a
 
41
      sequence of bytes.</p>
 
42
  </description>
 
43
  <funcs>
 
44
    <func>
 
45
      <name><ret>int</ret><nametext>erl_compare_ext(bufp1, bufp2)</nametext></name>
 
46
      <fsummary>Compares encoded byte sequences</fsummary>
 
47
      <type>
 
48
        <v>unsigned char *bufp1,*bufp2;</v>
 
49
      </type>
 
50
      <desc>
 
51
        <p>This function compares two encoded terms.
 
52
          </p>
 
53
        <p><c><![CDATA[bufp1]]></c> is a buffer containing an encoded Erlang
 
54
          term term1.
 
55
          </p>
 
56
        <p><c><![CDATA[bufp2]]></c> is a buffer containing an encoded Erlang
 
57
          term term2.
 
58
          </p>
 
59
        <p>The function returns 0 if the terms are equal, -1 if term1
 
60
          is less than term2, or 1 if term2 is less than term1. 
 
61
          </p>
 
62
      </desc>
 
63
    </func>
 
64
    <func>
 
65
      <name><ret>ETERM *</ret><nametext>erl_decode(bufp)</nametext></name>
 
66
      <name><ret>ETERM *</ret><nametext>erl_decode_buf(bufpp)</nametext></name>
 
67
      <fsummary>Converts a term from Erlang external format</fsummary>
 
68
      <type>
 
69
        <v>unsigned char *bufp;</v>
 
70
        <v>unsigned char **bufpp;</v>
 
71
      </type>
 
72
      <desc>
 
73
        <p><c><![CDATA[erl_decode()]]></c> and <c><![CDATA[erl_decode_buf()]]></c> decode
 
74
          the contents of a buffer and return the corresponding
 
75
          Erlang term.  <c><![CDATA[erl_decode_buf()]]></c> provides a simple
 
76
          mechanism for dealing with several encoded terms stored
 
77
          consecutively in the buffer.</p>
 
78
        <p><c><![CDATA[bufp]]></c> is a pointer to a buffer containing one or
 
79
          more encoded Erlang terms.
 
80
          </p>
 
81
        <p><c><![CDATA[bufpp]]></c> is the address of a buffer pointer. The buffer
 
82
          contains one or more consecutively encoded Erlang terms.
 
83
          Following a successful call to  <c><![CDATA[erl_decode_buf()]]></c>, 
 
84
          <c><![CDATA[bufpp]]></c> will be updated so that it points to the next
 
85
          encoded term.
 
86
          </p>
 
87
        <p><c><![CDATA[erl_decode()]]></c> returns an Erlang term
 
88
          corresponding to the contents of <c><![CDATA[bufp]]></c> on success, or
 
89
          NULL on failure. <c><![CDATA[erl_decode_buf()]]></c> returns an Erlang
 
90
          term corresponding to the first of the consecutive terms in
 
91
          <c><![CDATA[bufpp]]></c> and moves <c><![CDATA[bufpp]]></c> forward to point to the
 
92
          next term in the buffer. On failure, each of the functions
 
93
          returns NULL.
 
94
          </p>
 
95
      </desc>
 
96
    </func>
 
97
    <func>
 
98
      <name><ret>int</ret><nametext>erl_encode(term, bufp)</nametext></name>
 
99
      <name><ret>int</ret><nametext>erl_encode_buf(term, bufpp)</nametext></name>
 
100
      <fsummary>Converts a term into Erlang external format</fsummary>
 
101
      <type>
 
102
        <v>ETERM *term;</v>
 
103
        <v>unsigned char *bufp;</v>
 
104
        <v>unsigned char **bufpp;</v>
 
105
      </type>
 
106
      <desc>
 
107
        <p><c><![CDATA[erl_encode()]]></c> and  <c><![CDATA[erl_encode_buf()]]></c> encode 
 
108
          Erlang terms into external format for storage or transmission.
 
109
          <c><![CDATA[erl_encode_buf()]]></c> provides a simple mechanism for
 
110
          encoding several terms consecutively in the same
 
111
          buffer.
 
112
          </p>
 
113
        <p><c>term</c> is an Erlang term to be encoded.
 
114
          </p>
 
115
        <p><c>bufp</c> is a pointer to a buffer containing one or
 
116
          more encoded Erlang terms.
 
117
          </p>
 
118
        <p><c>bufpp</c> is a pointer to a pointer to a buffer
 
119
          containing one or more consecutively encoded Erlang terms.
 
120
          Following a successful call to  <c><![CDATA[erl_encode_buf()]]></c>, 
 
121
          <c>bufpp</c> will be updated so that it points to the
 
122
          position for the next encoded term.
 
123
          </p>
 
124
        <p>
 
125
          These functions returns the number of bytes written to buffer
 
126
          if successful, otherwise returns 0.  
 
127
        </p>
 
128
        <p>Note that no bounds checking is done on the buffer. It is
 
129
          the caller's responsibility to make sure that the buffer is
 
130
          large enough to hold the encoded terms. You can either use a
 
131
          static buffer that is large enough to hold the terms you
 
132
          expect to need in your program, or use <c><![CDATA[erl_term_len()]]></c>
 
133
          to determine the exact requirements for a given term.
 
134
          </p>
 
135
        <p>The following can help you estimate the buffer
 
136
          requirements for a term. Note that this information is
 
137
          implementation specific, and may change in future versions.
 
138
          If you are unsure, use <c><![CDATA[erl_term_len()]]></c>.
 
139
          </p>
 
140
        <p>Erlang terms are encoded with a 1 byte tag that
 
141
          identifies the type of object, a 2- or 4-byte length field,
 
142
          and then the data itself. Specifically:
 
143
          </p>
 
144
        <taglist>
 
145
          <tag><c><![CDATA[Tuples]]></c></tag>
 
146
          <item>need 5 bytes, plus the space for each element.</item>
 
147
          <tag><c><![CDATA[Lists]]></c></tag>
 
148
          <item>need 5 bytes, plus the space for each element, and 1
 
149
           additional byte for the empty list at the end.</item>
 
150
          <tag><c><![CDATA[Strings and atoms]]></c></tag>
 
151
          <item>need 3 bytes, plus 1 byte for each character (the
 
152
           terminating 0 is not encoded). Really long strings (more
 
153
           than 64k characters) are encoded as lists. Atoms cannot
 
154
           contain more than 256 characters.</item>
 
155
          <tag><c><![CDATA[Integers]]></c></tag>
 
156
          <item>need 5 bytes.</item>
 
157
          <tag><c><![CDATA[Characters]]></c></tag>
 
158
          <item>(integers &lt; 256) need 2 bytes.</item>
 
159
          <tag><c><![CDATA[Floating point numbers]]></c></tag>
 
160
          <item>need 32 bytes.</item>
 
161
          <tag><c><![CDATA[Pids]]></c></tag>
 
162
          <item>need 10 bytes, plus the space for the node name, which
 
163
           is an atom.</item>
 
164
          <tag><c><![CDATA[Ports and Refs]]></c></tag>
 
165
          <item>need 6 bytes, plus the space for the node name, which
 
166
           is an atom.</item>
 
167
        </taglist>
 
168
        <p>The total space required will be the result calculated
 
169
          from the information above, plus 1 additional byte for a 
 
170
          version identifier.
 
171
          </p>
 
172
      </desc>
 
173
    </func>
 
174
    <func>
 
175
      <name><ret>int</ret><nametext>erl_ext_size(bufp)</nametext></name>
 
176
      <fsummary>Counts elements in encoded term</fsummary>
 
177
      <type>
 
178
        <v>unsigned char *bufp;</v>
 
179
      </type>
 
180
      <desc>
 
181
        <p>This function returns the number of elements in an
 
182
          encoded term.</p>
 
183
      </desc>
 
184
    </func>
 
185
    <func>
 
186
      <name><ret>unsigned char</ret><nametext>erl_ext_type(bufp)</nametext></name>
 
187
      <fsummary>Determines type of an encoded byte sequence</fsummary>
 
188
      <type>
 
189
        <v>unsigned char *bufp;</v>
 
190
      </type>
 
191
      <desc>
 
192
        <p>This function identifies and returns the type of Erlang term encoded
 
193
          in a buffer. It will skip a trailing <em>magic</em> identifier.
 
194
          Returns <c><![CDATA[0]]></c> if the type can't be determined or one of</p>
 
195
        <list type="bulleted">
 
196
          <item>
 
197
            <p>ERL_INTEGER</p>
 
198
          </item>
 
199
          <item>
 
200
            <p>ERL_ATOM</p>
 
201
          </item>
 
202
          <item>
 
203
            <p>ERL_PID <c><![CDATA[/* Erlang process identifier */]]></c></p>
 
204
          </item>
 
205
          <item>
 
206
            <p>ERL_PORT</p>
 
207
          </item>
 
208
          <item>
 
209
            <p>ERL_REF <c><![CDATA[/* Erlang reference */]]></c></p>
 
210
          </item>
 
211
          <item>
 
212
            <p>ERL_EMPTY_LIST</p>
 
213
          </item>
 
214
          <item>
 
215
            <p>ERL_LIST</p>
 
216
          </item>
 
217
          <item>
 
218
            <p>ERL_TUPLE</p>
 
219
          </item>
 
220
          <item>
 
221
            <p>ERL_FLOAT</p>
 
222
          </item>
 
223
          <item>
 
224
            <p>ERL_BINARY</p>
 
225
          </item>
 
226
          <item>
 
227
            <p>ERL_FUNCTION</p>
 
228
          </item>
 
229
        </list>
 
230
      </desc>
 
231
    </func>
 
232
    <func>
 
233
      <name><ret>unsigned char *</ret><nametext>erl_peek_ext(bufp, pos)</nametext></name>
 
234
      <fsummary>Steps over encoded term</fsummary>
 
235
      <type>
 
236
        <v>unsigned char *bufp;</v>
 
237
        <v>int pos;</v>
 
238
      </type>
 
239
      <desc>
 
240
        <p>This function is used for stepping over one or more
 
241
          encoded terms in a buffer, in order to directly access a
 
242
          later term.
 
243
          </p>
 
244
        <p><c><![CDATA[bufp]]></c> is a pointer to a buffer containing one or
 
245
          more encoded Erlang terms.
 
246
          </p>
 
247
        <p><c><![CDATA[pos]]></c> indicates how many terms to step over in the
 
248
          buffer. 
 
249
          </p>
 
250
        <p>The function returns a pointer to a sub-term that can be
 
251
          used in a subsequent call to <c><![CDATA[erl_decode()]]></c> in order to retrieve
 
252
          the term at that position. If there is no term, or <c><![CDATA[pos]]></c>
 
253
          would exceed the size of the terms in the buffer, NULL is returned.
 
254
          </p>
 
255
      </desc>
 
256
    </func>
 
257
    <func>
 
258
      <name><ret>int</ret><nametext>erl_term_len(t)</nametext></name>
 
259
      <fsummary>Determines encoded size of term</fsummary>
 
260
      <type>
 
261
        <v>ETERM *t;</v>
 
262
      </type>
 
263
      <desc>
 
264
        <p>This function determines the buffer space that would be
 
265
          needed by <c><![CDATA[t]]></c> if it were encoded into Erlang external
 
266
          format by <c><![CDATA[erl_encode()]]></c>.
 
267
          </p>
 
268
        <p>The size in bytes is returned.
 
269
          </p>
 
270
      </desc>
 
271
    </func>
 
272
  </funcs>
 
273
</cref>
 
274