1ei(3) C Library Functions ei(3)
2
6 ei - Routines for handling the Erlang binary term format.
7
9 Note:
10 The support for VxWorks is deprecated as of OTP 22, and will be removed
11 in OTP 23.
12 The library ei contains macros and functions to encode and decode the
15 Erlang binary term format.
16 ei allows you to convert atoms, lists, numbers, and binaries to and
18 from the binary format. This is useful when writing port programs and
19 drivers. ei uses a given buffer, no dynamic memory (except
20 ei_decode_fun()) and is often quite fast.
21 ei also handles C-nodes, C-programs that talks Erlang distribution with
23 Erlang nodes (or other C-nodes) using the Erlang distribution format.
24 The difference between ei and erl_interface is that ei uses the binary
25 format directly when sending and receiving terms. It is also thread
26 safe, and using threads, one process can handle multiple C-nodes. The
27 erl_interface library is built on top of ei, but of legacy reasons, it
28 does not allow for multiple C-nodes. In general, ei is the preferred
29 way of doing C-nodes.
30 The decode and encode functions use a buffer and an index into the buf‐
32 fer, which points at the point where to encode and decode. The index is
33 updated to point right after the term encoded/decoded. No checking is
34 done whether the term fits in the buffer or not. If encoding goes out‐
35 side the buffer, the program can crash.
36 All functions take two parameters:
38 * buf is a pointer to the buffer where the binary data is or will be.
40 * index is a pointer to an index into the buffer. This parameter is
42 incremented with the size of the term decoded/encoded.
43 The data is thus at buf[*index] when an ei function is called.
45 All encode functions assume that the buf and index parameters point to
47 a buffer large enough for the data. To get the size of an encoded term,
48 without encoding it, pass NULL instead of a buffer pointer. Parameter
49 index is incremented, but nothing will be encoded. This is the way in
50 ei to "preflight" term encoding.
51 There are also encode functions that use a dynamic buffer. It is often
53 more convenient to use these to encode data. All encode functions comes
54 in two versions; those starting with ei_x use a dynamic buffer.
55 All functions return 0 if successful, otherwise -1 (for example, if a
57 term is not of the expected type, or the data to decode is an invalid
58 Erlang term).
59 Some of the decode functions need a pre-allocated buffer. This buffer
61 must be allocated large enough, and for non-compound types the
62 ei_get_type() function returns the size required (notice that for
63 strings an extra byte is needed for the NULL-terminator).
64
66 erlang_char_encoding:
67 typedef enum {
70 ERLANG_ASCII = 1,
71 ERLANG_LATIN1 = 2,
72 ERLANG_UTF8 = 4
73 } erlang_char_encoding;
74 The character encodings used for atoms. ERLANG_ASCII represents
76 7-bit ASCII. Latin-1 and UTF-8 are different extensions of 7-bit
77 ASCII. All 7-bit ASCII characters are valid Latin-1 and UTF-8 char‐
78 acters. ASCII and Latin-1 both represent each character by one
79 byte. An UTF-8 character can consist of 1-4 bytes. Notice that
80 these constants are bit-flags and can be combined with bitwise OR.
81
83 int ei_decode_atom(const char *buf, int *index, char *p)
84 Decodes an atom from the binary format. The NULL-terminated name
86 of the atom is placed at p. At most MAXATOMLEN bytes can be
87 placed in the buffer.
88 int ei_decode_atom_as(const char *buf, int *index, char *p, int plen,
90 erlang_char_encoding want, erlang_char_encoding* was,
91 erlang_char_encoding* result)
92 Decodes an atom from the binary format. The NULL-terminated name
94 of the atom is placed in buffer at p of length plen bytes.
95 The wanted string encoding is specified by want. The original
97 encoding used in the binary format (Latin-1 or UTF-8) can be
98 obtained from *was. The encoding of the resulting string (7-bit
99 ASCII, Latin-1, or UTF-8) can be obtained from *result. Both was
100 and result can be NULL. *result can differ from want if want is
101 a bitwise OR'd combination like ERLANG_LATIN1|ERLANG_UTF8 or if
102 *result turns out to be pure 7-bit ASCII (compatible with both
103 Latin-1 and UTF-8).
104 This function fails if the atom is too long for the buffer or if
106 it cannot be represented with encoding want.
107 This function was introduced in Erlang/OTP R16 as part of a
109 first step to support UTF-8 atoms.
110 int ei_decode_bignum(const char *buf, int *index, mpz_t obj)
112 Decodes an integer in the binary format to a GMP mpz_t integer.
114 To use this function, the ei library must be configured and com‐
115 piled to use the GMP library.
116 int ei_decode_binary(const char *buf, int *index, void *p, long *len)
118 Decodes a binary from the binary format. Parameter len is set to
120 the actual size of the binary. Notice that ei_decode_binary()
121 assumes that there is enough room for the binary. The size
122 required can be fetched by ei_get_type().
123 int ei_decode_bitstring(const char *buf, int *index, const char **pp,
125 unsigned int *bitoffsp, size_t *nbitsp)
126 Decodes a bit string from the binary format.
128 pp:
130 Either NULL or *pp returns a pointer to the first byte of
131 the bit string. The returned bit string is readable as long
132 as the buffer pointed to by buf is readable and not written
133 to.
134 bitoffsp:
136 Either NULL or *bitoffsp returns the number of unused bits
137 in the first byte pointed to by *pp. The value of *bitoffsp
138 is between 0 and 7. Unused bits in the first byte are the
139 most significant bits.
140 nbitsp:
142 Either NULL or *nbitsp returns the length of the bit string
143 in bits.
144 Returns 0 if it was a bit string term.
146 The number of bytes pointed to by *pp, which are part of the bit
148 string, is (*bitoffsp + *nbitsp + 7)/8. If (*bitoffsp +
149 *bitsp)%8 > 0 then only (*bitoffsp + *bitsp)%8 bits of the last
150 byte are used. Unused bits in the last byte are the least sig‐
151 nificant bits.
152 The values of unused bits in the first and last byte are unde‐
154 fined and cannot be relied on.
155 Number of bits may be divisible by 8, which means a binary
157 decodable by ei_decode_binary is also decodable by
158 ei_decode_bitstring.
159 int ei_decode_boolean(const char *buf, int *index, int *p)
161 Decodes a boolean value from the binary format. A boolean is
163 actually an atom, true decodes 1 and false decodes 0.
164 int ei_decode_char(const char *buf, int *index, char *p)
166 Decodes a char (8-bit) integer between 0-255 from the binary
168 format. For historical reasons the returned integer is of type
169 char. Your C code is to consider the returned value to be of
170 type unsigned char even if the C compilers and system can define
171 char to be signed.
172 int ei_decode_double(const char *buf, int *index, double *p)
174 Decodes a double-precision (64-bit) floating point number from
176 the binary format.
177 int ei_decode_ei_term(const char* buf, int* index, ei_term* term)
179 Decodes any term, or at least tries to. If the term pointed at
181 by *index in buf fits in the term union, it is decoded, and the
182 appropriate field in term->value is set, and *index is incre‐
183 mented by the term size.
184 The function returns 1 on successful decoding, -1 on error, and
186 0 if the term seems alright, but does not fit in the term struc‐
187 ture. If 1 is returned, the index is incremented, and term con‐
188 tains the decoded term.
189 The term structure contains the arity for a tuple or list, size
191 for a binary, string, or atom. It contains a term if it is any
192 of the following: integer, float, atom, pid, port, or ref.
193 int ei_decode_fun(const char *buf, int *index, erlang_fun *p)
195 void free_fun(erlang_fun* f)
196 Decodes a fun from the binary format. Parameter p is to be NULL
198 or point to an erlang_fun structure. This is the only decode
199 function that allocates memory. When the erlang_fun is no longer
200 needed, it is to be freed with free_fun. (This has to do with
201 the arbitrary size of the environment for a fun.)
202 int ei_decode_list_header(const char *buf, int *index, int *arity)
204 Decodes a list header from the binary format. The number of ele‐
206 ments is returned in arity. The arity+1 elements follow (the
207 last one is the tail of the list, normally an empty list). If
208 arity is 0, it is an empty list.
209 Notice that lists are encoded as strings if they consist
211 entirely of integers in the range 0..255. This function do not
212 decode such strings, use ei_decode_string() instead.
213 int ei_decode_long(const char *buf, int *index, long *p)
215 Decodes a long integer from the binary format. If the code is 64
217 bits, the function ei_decode_long() is the same as
218 ei_decode_longlong().
219 int ei_decode_longlong(const char *buf, int *index, long long *p)
221 Decodes a GCC long long or Visual C++ __int64 (64-bit) integer
223 from the binary format. This function is missing in the VxWorks
224 port.
225 int ei_decode_map_header(const char *buf, int *index, int *arity)
227 Decodes a map header from the binary format. The number of key-
229 value pairs is returned in *arity. Keys and values follow in
230 this order: K1, V1, K2, V2, ..., Kn, Vn. This makes a total of
231 arity*2 terms. If arity is zero, it is an empty map. A correctly
232 encoded map does not have duplicate keys.
233 int ei_decode_pid(const char *buf, int *index, erlang_pid *p)
235 Decodes a process identifier (pid) from the binary format.
237 int ei_decode_port(const char *buf, int *index, erlang_port *p)
239 Decodes a port identifier from the binary format.
241 int ei_decode_ref(const char *buf, int *index, erlang_ref *p)
243 Decodes a reference from the binary format.
245 int ei_decode_string(const char *buf, int *index, char *p)
247 Decodes a string from the binary format. A string in Erlang is a
249 list of integers between 0 and 255. Notice that as the string is
250 just a list, sometimes lists are encoded as strings by
251 term_to_binary/1, even if it was not intended.
252 The string is copied to p, and enough space must be allocated.
254 The returned string is NULL-terminated, so you must add an extra
255 byte to the memory requirement.
256 int ei_decode_term(const char *buf, int *index, void *t)
258 Decodes a term from the binary format. The term is return in t
260 as a ETERM*, so t is actually an ETERM** (see erl_eterm). The
261 term is later to be deallocated.
262 Note:
264 This function is deprecated as of OTP 22 and will be removed in
265 OTP 23 together with the old legacy erl_interface library (func‐
266 tions with prefix erl_).
267 int ei_decode_trace(const char *buf, int *index, erlang_trace *p)
270 Decodes an Erlang trace token from the binary format.
272 int ei_decode_tuple_header(const char *buf, int *index, int *arity)
274 Decodes a tuple header, the number of elements is returned in
276 arity. The tuple elements follow in order in the buffer.
277 int ei_decode_ulong(const char *buf, int *index, unsigned long *p)
279 Decodes an unsigned long integer from the binary format. If the
281 code is 64 bits, the function ei_decode_ulong() is the same as
282 ei_decode_ulonglong().
283 int ei_decode_ulonglong(const char *buf, int *index, unsigned long long
285 *p)
286 Decodes a GCC unsigned long long or Visual C++ unsigned __int64
288 (64-bit) integer from the binary format. This function is miss‐
289 ing in the VxWorks port.
290 int ei_decode_version(const char *buf, int *index, int *version)
292 Decodes the version magic number for the Erlang binary term for‐
294 mat. It must be the first token in a binary term.
295 int ei_encode_atom(char *buf, int *index, const char *p)
297 int ei_encode_atom_len(char *buf, int *index, const char *p, int len)
298 int ei_x_encode_atom(ei_x_buff* x, const char *p)
299 int ei_x_encode_atom_len(ei_x_buff* x, const char *p, int len)
300 Encodes an atom in the binary format. Parameter p is the name of
302 the atom in Latin-1 encoding. Only up to MAXATOMLEN-1 bytes are
303 encoded. The name is to be NULL-terminated, except for the
304 ei_x_encode_atom_len() function.
305 int ei_encode_atom_as(char *buf, int *index, const char *p,
307 erlang_char_encoding from_enc, erlang_char_encoding to_enc)
308 int ei_encode_atom_len_as(char *buf, int *index, const char *p, int
309 len, erlang_char_encoding from_enc, erlang_char_encoding to_enc)
310 int ei_x_encode_atom_as(ei_x_buff* x, const char *p, erlang_char_encod‐
311 ing from_enc, erlang_char_encoding to_enc)
312 int ei_x_encode_atom_len_as(ei_x_buff* x, const char *p, int len,
313 erlang_char_encoding from_enc, erlang_char_encoding to_enc)
314 Encodes an atom in the binary format. Parameter p is the name of
316 the atom with character encoding from_enc (ASCII, Latin-1, or
317 UTF-8). The name must either be NULL-terminated or a function
318 variant with a len parameter must be used.
319 The encoding fails if p is not a valid string in encoding
321 from_enc.
322 Argument to_enc is ignored. As from Erlang/OTP 20 the encoding
324 is always done in UTF-8 which is readable by nodes as old as
325 Erlang/OTP R16.
326 int ei_encode_bignum(char *buf, int *index, mpz_t obj)
328 int ei_x_encode_bignum(ei_x_buff *x, mpz_t obj)
329 Encodes a GMP mpz_t integer to binary format. To use this func‐
331 tion, the ei library must be configured and compiled to use the
332 GMP library.
333 int ei_encode_binary(char *buf, int *index, const void *p, long len)
335 int ei_x_encode_binary(ei_x_buff* x, const void *p, long len)
336 Encodes a binary in the binary format. The data is at p, of len
338 bytes length.
339 int ei_encode_bitstring(char *buf, int *index, const char *p, size_t
341 bitoffs, size_t nbits)
342 int ei_x_encode_bitstring(ei_x_buff* x, const char *p, size_t bitoffs,
343 size_t nbits)
344 Encodes a bit string in the binary format.
346 The data is at p. The length of the bit string is nbits bits.
348 The first bitoffs bits of the data at p are unused. The first
349 byte which is part of the bit string is p[bitoffs/8]. The
350 bitoffs%8 most significant bits of the first byte p[bitoffs/8]
351 are unused.
352 The number of bytes which is part of the bit string is (bitoffs
354 + nbits + 7)/8. If (bitoffs + nbits)%8 > 0 then only (bitoffs +
355 nbits)%8 bits of the last byte are used. Unused bits in the last
356 byte are the least significant bits.
357 The values of unused bits are disregarded and does not need to
359 be cleared.
360 int ei_encode_boolean(char *buf, int *index, int p)
362 int ei_x_encode_boolean(ei_x_buff* x, int p)
363 Encodes a boolean value as the atom true if p is not zero, or
365 false if p is zero.
366 int ei_encode_char(char *buf, int *index, char p)
368 int ei_x_encode_char(ei_x_buff* x, char p)
369 Encodes a char (8-bit) as an integer between 0-255 in the binary
371 format. For historical reasons the integer argument is of type
372 char. Your C code is to consider the specified argument to be of
373 type unsigned char even if the C compilers and system may define
374 char to be signed.
375 int ei_encode_double(char *buf, int *index, double p)
377 int ei_x_encode_double(ei_x_buff* x, double p)
378 Encodes a double-precision (64-bit) floating point number in the
380 binary format.
381 Returns -1 if the floating point number is not finite.
383 int ei_encode_empty_list(char* buf, int* index)
385 int ei_x_encode_empty_list(ei_x_buff* x)
386 Encodes an empty list. It is often used at the tail of a list.
388 int ei_encode_fun(char *buf, int *index, const erlang_fun *p)
390 int ei_x_encode_fun(ei_x_buff* x, const erlang_fun* fun)
391 Encodes a fun in the binary format. Parameter p points to an
393 erlang_fun structure. The erlang_fun is not freed automatically,
394 the free_fun is to be called if the fun is not needed after
395 encoding.
396 int ei_encode_list_header(char *buf, int *index, int arity)
398 int ei_x_encode_list_header(ei_x_buff* x, int arity)
399 Encodes a list header, with a specified arity. The next arity+1
401 terms are the elements (actually its arity cons cells) and the
402 tail of the list. Lists and tuples are encoded recursively, so
403 that a list can contain another list or tuple.
404 For example, to encode the list [c, d, [e | f]]:
406 ei_encode_list_header(buf, &i, 3);
408 ei_encode_atom(buf, &i, "c");
409 ei_encode_atom(buf, &i, "d");
410 ei_encode_list_header(buf, &i, 1);
411 ei_encode_atom(buf, &i, "e");
412 ei_encode_atom(buf, &i, "f");
413 ei_encode_empty_list(buf, &i);
414 Note:
416 It may seem that there is no way to create a list without know‐
417 ing the number of elements in advance. But indeed there is a
418 way. Notice that the list [a, b, c] can be written as [a | [b |
419 [c]]]. Using this, a list can be written as conses.
420 To encode a list, without knowing the arity in advance:
423 while (something()) {
425 ei_x_encode_list_header(&x, 1);
426 ei_x_encode_ulong(&x, i); /* just an example */
427 }
428 ei_x_encode_empty_list(&x);
429 int ei_encode_long(char *buf, int *index, long p)
431 int ei_x_encode_long(ei_x_buff* x, long p)
432 Encodes a long integer in the binary format. If the code is 64
434 bits, the function ei_encode_long() is the same as
435 ei_encode_longlong().
436 int ei_encode_longlong(char *buf, int *index, long long p)
438 int ei_x_encode_longlong(ei_x_buff* x, long long p)
439 Encodes a GCC long long or Visual C++ __int64 (64-bit) integer
441 in the binary format. This function is missing in the VxWorks
442 port.
443 int ei_encode_map_header(char *buf, int *index, int arity)
445 int ei_x_encode_map_header(ei_x_buff* x, int arity)
446 Encodes a map header, with a specified arity. The next arity*2
448 terms encoded will be the keys and values of the map encoded in
449 the following order: K1, V1, K2, V2, ..., Kn, Vn.
450 For example, to encode the map #{a => "Apple", b => "Banana"}:
452 ei_x_encode_map_header(&x, 2);
454 ei_x_encode_atom(&x, "a");
455 ei_x_encode_string(&x, "Apple");
456 ei_x_encode_atom(&x, "b");
457 ei_x_encode_string(&x, "Banana");
458 A correctly encoded map cannot have duplicate keys.
460 int ei_encode_pid(char *buf, int *index, const erlang_pid *p)
462 int ei_x_encode_pid(ei_x_buff* x, const erlang_pid *p)
463 Encodes an Erlang process identifier (pid) in the binary format.
465 Parameter p points to an erlang_pid structure (which should have
466 been obtained earlier with ei_decode_pid()).
467 int ei_encode_port(char *buf, int *index, const erlang_port *p)
469 int ei_x_encode_port(ei_x_buff* x, const erlang_port *p)
470 Encodes an Erlang port in the binary format. Parameter p points
472 to a erlang_port structure (which should have been obtained ear‐
473 lier with ei_decode_port()).
474 int ei_encode_ref(char *buf, int *index, const erlang_ref *p)
476 int ei_x_encode_ref(ei_x_buff* x, const erlang_ref *p)
477 Encodes an Erlang reference in the binary format. Parameter p
479 points to a erlang_ref structure (which should have been
480 obtained earlier with ei_decode_ref()).
481 int ei_encode_string(char *buf, int *index, const char *p)
483 int ei_encode_string_len(char *buf, int *index, const char *p, int len)
484 int ei_x_encode_string(ei_x_buff* x, const char *p)
485 int ei_x_encode_string_len(ei_x_buff* x, const char* s, int len)
486 Encodes a string in the binary format. (A string in Erlang is a
488 list, but is encoded as a character array in the binary format.)
489 The string is to be NULL-terminated, except for the
490 ei_x_encode_string_len() function.
491 int ei_encode_term(char *buf, int *index, void *t)
493 int ei_x_encode_term(ei_x_buff* x, void *t)
494 Encodes an ETERM, as obtained from erl_interface. Parameter t is
496 actually an ETERM pointer. This function does not free the
497 ETERM.
498 Note:
500 These functions are deprecated as of OTP 22 and will be removed
501 in OTP 23 together with the old legacy erl_interface library
502 (functions with prefix erl_).
503 int ei_encode_trace(char *buf, int *index, const erlang_trace *p)
506 int ei_x_encode_trace(ei_x_buff* x, const erlang_trace *p)
507 Encodes an Erlang trace token in the binary format. Parameter p
509 points to a erlang_trace structure (which should have been
510 obtained earlier with ei_decode_trace()).
511 int ei_encode_tuple_header(char *buf, int *index, int arity)
513 int ei_x_encode_tuple_header(ei_x_buff* x, int arity)
514 Encodes a tuple header, with a specified arity. The next arity
516 terms encoded will be the elements of the tuple. Tuples and
517 lists are encoded recursively, so that a tuple can contain
518 another tuple or list.
519 For example, to encode the tuple {a, {b, {}}}:
521 ei_encode_tuple_header(buf, &i, 2);
523 ei_encode_atom(buf, &i, "a");
524 ei_encode_tuple_header(buf, &i, 2);
525 ei_encode_atom(buf, &i, "b");
526 ei_encode_tuple_header(buf, &i, 0);
527 int ei_encode_ulong(char *buf, int *index, unsigned long p)
529 int ei_x_encode_ulong(ei_x_buff* x, unsigned long p)
530 Encodes an unsigned long integer in the binary format. If the
532 code is 64 bits, the function ei_encode_ulong() is the same as
533 ei_encode_ulonglong().
534 int ei_encode_ulonglong(char *buf, int *index, unsigned long long p)
536 int ei_x_encode_ulonglong(ei_x_buff* x, unsigned long long p)
537 Encodes a GCC unsigned long long or Visual C++ unsigned __int64
539 (64-bit) integer in the binary format. This function is missing
540 in the VxWorks port.
541 int ei_encode_version(char *buf, int *index)
543 int ei_x_encode_version(ei_x_buff* x)
544 Encodes a version magic number for the binary format. Must be
546 the first token in a binary term.
547 int ei_get_type(const char *buf, const int *index, int *type, int
549 *size)
550 Returns the type in *type and size in *size of the encoded term.
552 For strings and atoms, size is the number of characters not
553 including the terminating NULL. For binaries and bitstrings,
554 *size is the number of bytes. For lists, tuples and maps, *size
555 is the arity of the object. For other types, *size is 0. In all
556 cases, index is left unchanged.
557 int ei_init(void)
559 Initialize the ei library. This function should be called once
561 (and only once) before calling any other functionality in the ei
562 library. However, note the exception below.
563 If the ei library is used together with the erl_interface
565 library, this function should not be called directly. It will be
566 called by the erl_init() function which should be used to ini‐
567 tialize the combination of the two libraries instead.
568 On success zero is returned. On failure a posix error code is
570 returned.
571 int ei_print_term(FILE* fp, const char* buf, int* index)
573 int ei_s_print_term(char** s, const char* buf, int* index)
574 Prints a term, in clear text, to the file specified by fp, or
576 the buffer pointed to by s. It tries to resemble the term print‐
577 ing in the Erlang shell.
578 In ei_s_print_term(), parameter s is to point to a dynamically
580 (malloc) allocated string of BUFSIZ bytes or a NULL pointer. The
581 string can be reallocated (and *s can be updated) by this func‐
582 tion if the result is more than BUFSIZ characters. The string
583 returned is NULL-terminated.
584 The return value is the number of characters written to the file
586 or string, or -1 if buf[index] does not contain a valid term.
587 Unfortunately, I/O errors on fp is not checked.
588 Argument index is updated, that is, this function can be viewed
590 as a decode function that decodes a term into a human-readable
591 format.
592 void ei_set_compat_rel(release_number)
594 Types:
596 unsigned release_number;
598 In general, the ei library is guaranteed to be compatible with
600 other Erlang/OTP components that are 2 major releases older or
601 newer than the ei library itself.
602 Sometimes an exception to the above rule has to be made to make
604 new features (or even bug fixes) possible. A call to ei_set_com‐
605 pat_rel(release_number) sets the ei library in compatibility
606 mode of OTP release release_number.
607 The only useful value for release_number is currently 21. This
609 will only be useful and have an effect if bit strings or export
610 funs are received from a connected node. Before OTP 22, bit
611 strings and export funs were not supported by ei. They were
612 instead encoded using an undocumented fallback tuple format when
613 sent from the emulator to ei:
614 Bit string:
616 The term <<42, 1:1>> was encoded as {<<42, 128>>, 1}. The
617 first element of the tuple is a binary and the second ele‐
618 ment denotes how many bits of the last bytes are part of the
619 bit string. In this example only the most significant bit of
620 the last byte (128) is part of the bit string.
621 Export fun:
623 The term fun lists:map/2 was encoded as {lists,map}. A tuple
624 with the module, function and a missing arity.
625 If ei_set_compat_rel(21) is not called then a connected emulator
627 will send bit strings and export funs correctly encoded. The
628 functions ei_decode_bitstring and ei_decode_fun has to be used
629 to decode such terms. Calling ei_set_compat_rel(21) should only
630 be done as a workaround to keep an old implementation alive,
631 which expects to receive the undocumented tuple formats for bit
632 strings and/or export funs.
633 Note:
635 If this function is called, it can only be called once and must
636 be called before any other functions in the ei library are
637 called.
638 int ei_skip_term(const char* buf, int* index)
641 Skips a term in the specified buffer; recursively skips elements
643 of lists and tuples, so that a full term is skipped. This is a
644 way to get the size of an Erlang term.
645 buf is the buffer.
647 index is updated to point right after the term in the buffer.
649 Note:
651 This can be useful when you want to hold arbitrary terms: skip
652 them and copy the binary term data to some buffer.
653 Returns 0 on success, otherwise -1.
656 int ei_x_append(ei_x_buff* x, const ei_x_buff* x2)
658 int ei_x_append_buf(ei_x_buff* x, const char* buf, int len)
659 Appends data at the end of buffer x.
661 int ei_x_format(ei_x_buff* x, const char* fmt, ...)
663 int ei_x_format_wo_ver(ei_x_buff* x, const char *fmt, ... )
664 Formats a term, given as a string, to a buffer. Works like a
666 sprintf for Erlang terms. fmt contains a format string, with
667 arguments like ~d, to insert terms from variables. The following
668 formats are supported (with the C types given):
669 ~a An atom, char*
671 ~c A character, char
672 ~s A string, char*
673 ~i An integer, int
674 ~l A long integer, long int
675 ~u A unsigned long integer, unsigned long int
676 ~f A float, float
677 ~d A double float, double float
678 ~p An Erlang pid, erlang_pid*
679 For example, to encode a tuple with some stuff:
681 ei_x_format("{~a,~i,~d}", "numbers", 12, 3.14159)
683 encodes the tuple {numbers,12,3.14159}
684 ei_x_format_wo_ver() formats into a buffer, without the initial
686 version byte.
687 int ei_x_free(ei_x_buff* x)
689 Frees an ei_x_buff buffer. The memory used by the buffer is
691 returned to the OS.
692 int ei_x_new(ei_x_buff* x)
694 int ei_x_new_with_version(ei_x_buff* x)
695 Allocates a new ei_x_buff buffer. The fields of the structure
697 pointed to by parameter x is filled in, and a default buffer is
698 allocated. ei_x_new_with_version() also puts an initial version
699 byte, which is used in the binary format (so that
700 ei_x_encode_version() will not be needed.)
701
703 Some tips on what to check when the emulator does not seem to receive
704 the terms that you send:
705 * Be careful with the version header, use ei_x_new_with_version()
707 when appropriate.
708 * Turn on distribution tracing on the Erlang node.
710 * Check the result codes from ei_decode_-calls.
712
714 erl_eterm
715Ericsson AB erl_interface 3.13 ei(3)