1erl_marshal(3) C Library Functions erl_marshal(3)
2
6 erl_marshal - Encoding and decoding of Erlang terms.
7
9 This module contains functions for encoding Erlang terms into a
10 sequence of bytes, and for decoding Erlang terms from a sequence of
11 bytes.
12
14 int erl_compare_ext(bufp1, bufp2)
15 Types:
17 unsigned char *bufp1,*bufp2;
19 Compares two encoded terms.
21 * bufp1 is a buffer containing an encoded Erlang term term1.
23 * bufp2 is a buffer containing an encoded Erlang term term2.
25 Returns 0 if the terms are equal, -1 if term1 < term2, or 1 if
27 term2 < term1.
28 ETERM *erl_decode(bufp)
30 ETERM *erl_decode_buf(bufpp)
31 Types:
33 unsigned char *bufp;
35 unsigned char **bufpp;
36 erl_decode() and erl_decode_buf() decode the contents of a buf‐
38 fer and return the corresponding Erlang term. erl_decode_buf()
39 provides a simple mechanism for dealing with several encoded
40 terms stored consecutively in the buffer.
41 * bufp is a pointer to a buffer containing one or more encoded
43 Erlang terms.
44 * bufpp is the address of a buffer pointer. The buffer con‐
46 tains one or more consecutively encoded Erlang terms. Fol‐
47 lowing a successful call to erl_decode_buf(), bufpp is
48 updated so that it points to the next encoded term.
49 erl_decode() returns an Erlang term corresponding to the con‐
51 tents of bufp on success, otherwise NULL. erl_decode_buf()
52 returns an Erlang term corresponding to the first of the consec‐
53 utive terms in bufpp and moves bufpp forward to point to the
54 next term in the buffer. On failure, each of the functions
55 return NULL.
56 int erl_encode(term, bufp)
58 int erl_encode_buf(term, bufpp)
59 Types:
61 ETERM *term;
63 unsigned char *bufp;
64 unsigned char **bufpp;
65 erl_encode() and erl_encode_buf() encode Erlang terms into
67 external format for storage or transmission. erl_encode_buf()
68 provides a simple mechanism for encoding several terms consecu‐
69 tively in the same buffer.
70 * term is an Erlang term to be encoded.
72 * bufp is a pointer to a buffer containing one or more encoded
74 Erlang terms.
75 * bufpp is a pointer to a pointer to a buffer containing one
77 or more consecutively encoded Erlang terms. Following a suc‐
78 cessful call to erl_encode_buf(), bufpp is updated so that
79 it points to the position for the next encoded term.
80 These functions return the number of bytes written to buffer on
82 success, otherwise 0.
83 Notice that no bounds checking is done on the buffer. It is the
85 caller's responsibility to ensure that the buffer is large
86 enough to hold the encoded terms. You can either use a static
87 buffer that is large enough to hold the terms you expect to need
88 in your program, or use erl_term_len() to determine the exact
89 requirements for a given term.
90 The following can help you estimate the buffer requirements for
92 a term. Notice that this information is implementation-specific,
93 and can change in future versions. If you are unsure, use
94 erl_term_len().
95 Erlang terms are encoded with a 1 byte tag that identifies the
97 type of object, a 2- or 4-byte length field, and then the data
98 itself. Specifically:
99 Tuples:
101 Need 5 bytes, plus the space for each element.
102 Lists:
104 Need 5 bytes, plus the space for each element, and 1 more
105 byte for the empty list at the end.
106 Strings and atoms:
108 Need 3 bytes, plus 1 byte for each character (the terminat‐
109 ing 0 is not encoded). Really long strings (more than 64k
110 characters) are encoded as lists. Atoms cannot contain more
111 than 256 characters.
112 Integers:
114 Need 5 bytes.
115 Characters:
117 (Integers < 256) need 2 bytes.
118 Floating point numbers:
120 Need 32 bytes.
121 Pids:
123 Need 10 bytes, plus the space for the node name, which is an
124 atom.
125 Ports and Refs:
127 Need 6 bytes, plus the space for the node name, which is an
128 atom.
129 The total space required is the result calculated from the
131 information above, plus 1 more byte for a version identifier.
132 int erl_ext_size(bufp)
134 Types:
136 unsigned char *bufp;
138 Returns the number of elements in an encoded term.
140 unsigned char erl_ext_type(bufp)
142 Types:
144 unsigned char *bufp;
146 Identifies and returns the type of Erlang term encoded in a buf‐
148 fer. It skips a trailing magic identifier.
149 Returns 0 if the type cannot be determined or one of:
151 * ERL_INTEGER
153 * ERL_ATOM
155 * ERL_PID (Erlang process identifier)
157 * ERL_PORT
159 * ERL_REF (Erlang reference)
161 * ERL_EMPTY_LIST
163 * ERL_LIST
165 * ERL_TUPLE
167 * ERL_FLOAT
169 * ERL_BINARY
171 * ERL_FUNCTION
173 unsigned char *erl_peek_ext(bufp, pos)
175 Types:
177 unsigned char *bufp;
179 int pos;
180 This function is used for stepping over one or more encoded
182 terms in a buffer, to directly access later term.
183 * bufp is a pointer to a buffer containing one or more encoded
185 Erlang terms.
186 * pos indicates how many terms to step over in the buffer.
188 Returns a pointer to a subterm that can be used in a later call
190 to erl_decode() to retrieve the term at that position. If there
191 is no term, or pos would exceed the size of the terms in the
192 buffer, NULL is returned.
193 int erl_term_len(t)
195 Types:
197 ETERM *t;
199 Determines the buffer space that would be needed by t if it were
201 encoded into Erlang external format by erl_encode().
202 Returns the size in bytes.
204Ericsson AB erl_interface 3.11.3 erl_marshal(3)