1erl_marshal(3) C Library Functions erl_marshal(3)
2
6 erl_marshal - Encoding and decoding of Erlang terms.
7
9 Note:
10 The support for VxWorks is deprecated as of OTP 22, and will be removed
11 in OTP 23.
12 Note:
15 The old legacy erl_interface library (functions with prefix erl_) is
16 deprecated as of OTP 22, and will be removed in OTP 23. This does not
17 apply to the ei library. Reasonably new gcc compilers will issue depre‐
18 cation warnings. In order to disable these warnings, define the macro
19 EI_NO_DEPR_WARN.
20 This module contains functions for encoding Erlang terms into a
23 sequence of bytes, and for decoding Erlang terms from a sequence of
24 bytes.
25
27 int erl_compare_ext(bufp1, bufp2)
28 Types:
30 unsigned char *bufp1,*bufp2;
32 Compares two encoded terms.
34 * bufp1 is a buffer containing an encoded Erlang term term1.
36 * bufp2 is a buffer containing an encoded Erlang term term2.
38 Returns 0 if the terms are equal, -1 if term1 < term2, or 1 if
40 term2 < term1.
41 ETERM *erl_decode(bufp)
43 ETERM *erl_decode_buf(bufpp)
44 Types:
46 unsigned char *bufp;
48 unsigned char **bufpp;
49 erl_decode() and erl_decode_buf() decode the contents of a buf‐
51 fer and return the corresponding Erlang term. erl_decode_buf()
52 provides a simple mechanism for dealing with several encoded
53 terms stored consecutively in the buffer.
54 * bufp is a pointer to a buffer containing one or more encoded
56 Erlang terms.
57 * bufpp is the address of a buffer pointer. The buffer con‐
59 tains one or more consecutively encoded Erlang terms. Fol‐
60 lowing a successful call to erl_decode_buf(), bufpp is
61 updated so that it points to the next encoded term.
62 erl_decode() returns an Erlang term corresponding to the con‐
64 tents of bufp on success, otherwise NULL. erl_decode_buf()
65 returns an Erlang term corresponding to the first of the consec‐
66 utive terms in bufpp and moves bufpp forward to point to the
67 next term in the buffer. On failure, each of the functions
68 return NULL.
69 int erl_encode(term, bufp)
71 int erl_encode_buf(term, bufpp)
72 Types:
74 ETERM *term;
76 unsigned char *bufp;
77 unsigned char **bufpp;
78 erl_encode() and erl_encode_buf() encode Erlang terms into
80 external format for storage or transmission. erl_encode_buf()
81 provides a simple mechanism for encoding several terms consecu‐
82 tively in the same buffer.
83 * term is an Erlang term to be encoded.
85 * bufp is a pointer to a buffer containing one or more encoded
87 Erlang terms.
88 * bufpp is a pointer to a pointer to a buffer containing one
90 or more consecutively encoded Erlang terms. Following a suc‐
91 cessful call to erl_encode_buf(), bufpp is updated so that
92 it points to the position for the next encoded term.
93 These functions return the number of bytes written to buffer on
95 success, otherwise 0.
96 Notice that no bounds checking is done on the buffer. It is the
98 caller's responsibility to ensure that the buffer is large
99 enough to hold the encoded terms. You can either use a static
100 buffer that is large enough to hold the terms you expect to need
101 in your program, or use erl_term_len() to determine the exact
102 requirements for a given term.
103 The following can help you estimate the buffer requirements for
105 a term. Notice that this information is implementation-specific,
106 and can change in future versions. If you are unsure, use
107 erl_term_len().
108 Erlang terms are encoded with a 1 byte tag that identifies the
110 type of object, a 2- or 4-byte length field, and then the data
111 itself. Specifically:
112 Tuples:
114 Need 5 bytes, plus the space for each element.
115 Lists:
117 Need 5 bytes, plus the space for each element, and 1 more
118 byte for the empty list at the end.
119 Strings and atoms:
121 Need 3 bytes, plus 1 byte for each character (the terminat‐
122 ing 0 is not encoded). Really long strings (more than 64k
123 characters) are encoded as lists. Atoms cannot contain more
124 than 256 characters.
125 Integers:
127 Need 5 bytes.
128 Characters:
130 (Integers < 256) need 2 bytes.
131 Floating point numbers:
133 Need 32 bytes.
134 Pids:
136 Need 10 bytes, plus the space for the node name, which is an
137 atom.
138 Ports and Refs:
140 Need 6 bytes, plus the space for the node name, which is an
141 atom.
142 The total space required is the result calculated from the
144 information above, plus 1 more byte for a version identifier.
145 int erl_ext_size(bufp)
147 Types:
149 unsigned char *bufp;
151 Returns the number of elements in an encoded term.
153 unsigned char erl_ext_type(bufp)
155 Types:
157 unsigned char *bufp;
159 Identifies and returns the type of Erlang term encoded in a buf‐
161 fer. It skips a trailing magic identifier.
162 Returns 0 if the type cannot be determined or one of:
164 * ERL_INTEGER
166 * ERL_ATOM
168 * ERL_PID (Erlang process identifier)
170 * ERL_PORT
172 * ERL_REF (Erlang reference)
174 * ERL_EMPTY_LIST
176 * ERL_LIST
178 * ERL_TUPLE
180 * ERL_FLOAT
182 * ERL_BINARY
184 * ERL_FUNCTION
186 unsigned char *erl_peek_ext(bufp, pos)
188 Types:
190 unsigned char *bufp;
192 int pos;
193 This function is used for stepping over one or more encoded
195 terms in a buffer, to directly access later term.
196 * bufp is a pointer to a buffer containing one or more encoded
198 Erlang terms.
199 * pos indicates how many terms to step over in the buffer.
201 Returns a pointer to a subterm that can be used in a later call
203 to erl_decode() to retrieve the term at that position. If there
204 is no term, or pos would exceed the size of the terms in the
205 buffer, NULL is returned.
206 int erl_term_len(t)
208 Types:
210 ETERM *t;
212 Determines the buffer space that would be needed by t if it were
214 encoded into Erlang external format by erl_encode().
215 Returns the size in bytes.
217Ericsson AB erl_interface 3.13.2 erl_marshal(3)