aboutsummaryrefslogtreecommitdiffstats
path: root/lib/erl_interface/doc/src/erl_marshal.xml
blob: a7eaf78f354deba22dc58724d858e2ab4c341d8c (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
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>