1ei(3) C Library Functions ei(3)
2
6 ei - Routines for handling the Erlang binary term format.
7
9 The library ei contains macros and functions to encode and decode the
10 Erlang binary term format.
11 ei allows you to convert atoms, lists, numbers, and binaries to and
13 from the binary format. This is useful when writing port programs and
14 drivers. ei uses a given buffer, no dynamic memory (except ei_de‐
15 code_fun()) and is often quite fast.
16 ei also handles C-nodes, C-programs that talks Erlang distribution with
18 Erlang nodes (or other C-nodes) using the Erlang distribution for‐
19 mat.The ei library is thread safe, and using threads, one process can
20 handle multiple C-nodes.
21 The decode and encode functions use a buffer and an index into the buf‐
23 fer, which points at the point where to encode and decode. The index is
24 updated to point right after the term encoded/decoded. No checking is
25 done whether the term fits in the buffer or not. If encoding goes out‐
26 side the buffer, the program can crash.
27 All functions take two parameters:
29 * buf is a pointer to the buffer where the binary data is or will be.
31 * index is a pointer to an index into the buffer. This parameter is
33 incremented with the size of the term decoded/encoded.
34 The data is thus at buf[*index] when an ei function is called.
36 All encode functions assume that the buf and index parameters point to
38 a buffer large enough for the data. To get the size of an encoded term,
39 without encoding it, pass NULL instead of a buffer pointer. Parameter
40 index is incremented, but nothing will be encoded. This is the way in
41 ei to "preflight" term encoding.
42 There are also encode functions that use a dynamic buffer. It is often
44 more convenient to use these to encode data. All encode functions comes
45 in two versions; those starting with ei_x_ use a dynamic buffer of type
46 ei_x_buff.
47 All functions return 0 if successful, otherwise -1 (for example, if a
49 term is not of the expected type, or the data to decode is an invalid
50 Erlang term).
51 Some of the decode functions need a pre-allocated buffer. This buffer
53 must be allocated large enough, and for non-compound types the
54 ei_get_type() function returns the size required (notice that for
55 strings an extra byte is needed for the NULL-terminator).
56
58 ei_term:
59 typedef struct {
62 char ei_type;
63 int arity;
64 int size;
65 union {
66 long i_val;
67 double d_val;
68 char atom_name[MAXATOMLEN_UTF8];
69 erlang_pid pid;
70 erlang_port port;
71 erlang_ref ref;
72 } value;
73 } ei_term;
74 Structure written by ei_decode_ei_term(). The ei_type field is the
76 type of the term which equals to what ei_get_type() sets *type to.
77 ei_x_buff:
79 A dynamically resized buffer. It is a struct with two fields of in‐
80 terest for the user:
81 char *buff:
83 Pointer to the dynamically allocated buffer.
84 int index:
86 Offset to the next byte to write which also equals the amount of
87 bytes currently written.
88 An ei_x_buff is initialized by calling either ei_x_new() or
90 ei_x_new_with_version(). The memory used by an initialized
91 ei_x_buff is released by calling ei_x_free().
92 erlang_char_encoding:
94 typedef enum {
97 ERLANG_ASCII = 1,
98 ERLANG_LATIN1 = 2,
99 ERLANG_UTF8 = 4
100 } erlang_char_encoding;
101 The character encodings used for atoms. ERLANG_ASCII represents
103 7-bit ASCII. Latin-1 and UTF-8 are different extensions of 7-bit
104 ASCII. All 7-bit ASCII characters are valid Latin-1 and UTF-8 char‐
105 acters. ASCII and Latin-1 both represent each character by one
106 byte. An UTF-8 character can consist of 1-4 bytes. Notice that
107 these constants are bit-flags and can be combined with bitwise OR.
108 erlang_fun:
110 Opaque data type representing an Erlang fun.
111 erlang_pid:
113 Opaque data type representing an Erlang process identifier.
114 erlang_port:
116 Opaque data type representing an Erlang port identifier.
117 erlang_ref:
119 Opaque data type representing an Erlang reference.
120 erlang_trace:
122 Opaque data type representing an Erlang sequential trace token.
123
125 int ei_cmp_pids(erlang_pid *a, erlang_pid *b)
126 Types:
128 erlang_pid
130 Compare two process identifiers. The comparison is done the same
132 way as Erlang does.
133 Returns 0 if a and b are equal. Returns a value less than 0 if a
135 compares as less than b. Returns a value larger than 0 if a com‐
136 pares as larger than b.
137 int ei_cmp_ports(erlang_port *a, erlang_port *b)
139 Types:
141 erlang_port
143 Compare two port identifiers. The comparison is done the same
145 way as Erlang does.
146 Returns 0 if a and b are equal. Returns a value less than 0 if a
148 compares as less than b. Returns a value larger than 0 if a com‐
149 pares as larger than b.
150 int ei_cmp_refs(erlang_ref *a, erlang_ref *b)
152 Types:
154 erlang_ref
156 Compare two references. The comparison is done the same way as
158 Erlang does.
159 Returns 0 if a and b are equal. Returns a value less than 0 if a
161 compares as less than b. Returns a value larger than 0 if a com‐
162 pares as larger than b.
163 int ei_decode_atom(const char *buf, int *index, char *p)
165 Decodes an atom from the binary format. The NULL-terminated name
167 of the atom is placed at p. At most MAXATOMLEN bytes can be
168 placed in the buffer.
169 int ei_decode_atom_as(const char *buf, int *index, char *p, int plen,
171 erlang_char_encoding want, erlang_char_encoding* was, erlang_char_en‐
172 coding* result)
173 Types:
175 erlang_char_encoding
177 Decodes an atom from the binary format. The NULL-terminated name
179 of the atom is placed in buffer at p of length plen bytes.
180 The wanted string encoding is specified by want. The original
182 encoding used in the binary format (Latin-1 or UTF-8) can be ob‐
183 tained from *was. The encoding of the resulting string (7-bit
184 ASCII, Latin-1, or UTF-8) can be obtained from *result. Both was
185 and result can be NULL. *result can differ from want if want is
186 a bitwise OR'd combination like ERLANG_LATIN1|ERLANG_UTF8 or if
187 *result turns out to be pure 7-bit ASCII (compatible with both
188 Latin-1 and UTF-8).
189 This function fails if the atom is too long for the buffer or if
191 it cannot be represented with encoding want.
192 This function was introduced in Erlang/OTP R16 as part of a
194 first step to support UTF-8 atoms.
195 int ei_decode_bignum(const char *buf, int *index, mpz_t obj)
197 Decodes an integer in the binary format to a GMP mpz_t integer.
199 To use this function, the ei library must be configured and com‐
200 piled to use the GMP library.
201 int ei_decode_binary(const char *buf, int *index, void *p, long *len)
203 Decodes a binary from the binary format. Parameter len is set to
205 the actual size of the binary. Notice that ei_decode_binary()
206 assumes that there is enough room for the binary. The size re‐
207 quired can be fetched by ei_get_type().
208 int ei_decode_bitstring(const char *buf, int *index, const char **pp,
210 unsigned int *bitoffsp, size_t *nbitsp)
211 Decodes a bit string from the binary format.
213 pp:
215 Either NULL or *pp returns a pointer to the first byte of
216 the bit string. The returned bit string is readable as long
217 as the buffer pointed to by buf is readable and not written
218 to.
219 bitoffsp:
221 Either NULL or *bitoffsp returns the number of unused bits
222 in the first byte pointed to by *pp. The value of *bitoffsp
223 is between 0 and 7. Unused bits in the first byte are the
224 most significant bits.
225 nbitsp:
227 Either NULL or *nbitsp returns the length of the bit string
228 in bits.
229 Returns 0 if it was a bit string term.
231 The number of bytes pointed to by *pp, which are part of the bit
233 string, is (*bitoffsp + *nbitsp + 7)/8. If (*bitoffsp +
234 *bitsp)%8 > 0 then only (*bitoffsp + *bitsp)%8 bits of the last
235 byte are used. Unused bits in the last byte are the least sig‐
236 nificant bits.
237 The values of unused bits in the first and last byte are unde‐
239 fined and cannot be relied on.
240 Number of bits may be divisible by 8, which means a binary de‐
242 codable by ei_decode_binary is also decodable by ei_decode_bit‐
243 string.
244 int ei_decode_boolean(const char *buf, int *index, int *p)
246 Decodes a boolean value from the binary format. A boolean is ac‐
248 tually an atom, true decodes 1 and false decodes 0.
249 int ei_decode_char(const char *buf, int *index, char *p)
251 Decodes a char (8-bit) integer between 0-255 from the binary
253 format. For historical reasons the returned integer is of type
254 char. Your C code is to consider the returned value to be of
255 type unsigned char even if the C compilers and system can define
256 char to be signed.
257 int ei_decode_double(const char *buf, int *index, double *p)
259 Decodes a double-precision (64-bit) floating point number from
261 the binary format.
262 int ei_decode_ei_term(const char* buf, int* index, ei_term* term)
264 Types:
266 ei_term
268 Decodes any term, or at least tries to. If the term pointed at
270 by *index in buf fits in the term union, it is decoded, and the
271 appropriate field in term->value is set, and *index is incre‐
272 mented by the term size.
273 The function returns 1 on successful decoding, -1 on error, and
275 0 if the term seems alright, but does not fit in the term struc‐
276 ture. If 1 is returned, the index is incremented, and term con‐
277 tains the decoded term.
278 The term structure contains the arity for a tuple or list, size
280 for a binary, string, or atom. It contains a term if it is any
281 of the following: integer, float, atom, pid, port, or ref.
282 int ei_decode_fun(const char *buf, int *index, erlang_fun *p)
284 void free_fun(erlang_fun* f)
285 Types:
287 erlang_fun
289 Decodes a fun from the binary format. Parameter p is to be NULL
291 or point to an erlang_fun structure. This is the only decode
292 function that allocates memory. When the erlang_fun is no longer
293 needed, it is to be freed with free_fun. (This has to do with
294 the arbitrary size of the environment for a fun.)
295 int ei_decode_iodata(const char *buf, int *index, int *size, char *out‐
297 buf)
298 Decodes a term of the type iodata(). The iodata() term will be
300 flattened an written into the buffer pointed to by the outbuf
301 argument. The byte size of the iodata is written into the inte‐
302 ger variable pointed to by the size argument. Both size and out‐
303 buf can be set to NULL. The integer pointed to by the index ar‐
304 gument is updated to refer to the term following after the io‐
305 data() term regardless of the the state of the size and the out‐
306 buf arguments.
307 Note that the buffer pointed to by the outbuf argument must be
309 large enough if a non NULL value is passed as outbuf. You typi‐
310 cally want to call ei_decode_iodata() twice. First with a non
311 NULL size argument and a NULL outbuf argument in order to deter‐
312 mine the size of the buffer needed, and then once again in order
313 to do the actual decoding. Note that the integer pointed to by
314 index will be updated by the call determining the size as well,
315 so you need to reset it before the second call doing the actual
316 decoding.
317 Returns 0 on success and -1 on failure. Failure might be either
319 due to invalid encoding of the term or due to the term not being
320 of the type iodata(). On failure, the integer pointed to by the
321 index argument will be updated to refer to the sub term where
322 the failure was detected.
323 int ei_decode_list_header(const char *buf, int *index, int *arity)
325 Decodes a list header from the binary format. The number of ele‐
327 ments is returned in arity. The arity+1 elements follow (the
328 last one is the tail of the list, normally an empty list). If
329 arity is 0, it is an empty list.
330 Notice that lists are encoded as strings if they consist en‐
332 tirely of integers in the range 0..255. This function do not de‐
333 code such strings, use ei_decode_string() instead.
334 int ei_decode_long(const char *buf, int *index, long *p)
336 Decodes a long integer from the binary format. If the code is 64
338 bits, the function ei_decode_long() is the same as ei_de‐
339 code_longlong().
340 int ei_decode_longlong(const char *buf, int *index, long long *p)
342 Decodes a GCC long long or Visual C++ __int64 (64-bit) integer
344 from the binary format.
345 int ei_decode_map_header(const char *buf, int *index, int *arity)
347 Decodes a map header from the binary format. The number of key-
349 value pairs is returned in *arity. Keys and values follow in
350 this order: K1, V1, K2, V2, ..., Kn, Vn. This makes a total of
351 arity*2 terms. If arity is zero, it is an empty map. A correctly
352 encoded map does not have duplicate keys.
353 int ei_decode_pid(const char *buf, int *index, erlang_pid *p)
355 Types:
357 erlang_pid
359 Decodes a process identifier (pid) from the binary format.
361 int ei_decode_port(const char *buf, int *index, erlang_port *p)
363 Types:
365 erlang_port
367 Decodes a port identifier from the binary format.
369 int ei_decode_ref(const char *buf, int *index, erlang_ref *p)
371 Types:
373 erlang_ref
375 Decodes a reference from the binary format.
377 int ei_decode_string(const char *buf, int *index, char *p)
379 Decodes a string from the binary format. A string in Erlang is a
381 list of integers between 0 and 255. Notice that as the string is
382 just a list, sometimes lists are encoded as strings by
383 term_to_binary/1, even if it was not intended.
384 The string is copied to p, and enough space must be allocated.
386 The returned string is NULL-terminated, so you must add an extra
387 byte to the memory requirement.
388 int ei_decode_trace(const char *buf, int *index, erlang_trace *p)
390 Types:
392 erlang_trace
394 Decodes an Erlang trace token from the binary format.
396 int ei_decode_tuple_header(const char *buf, int *index, int *arity)
398 Decodes a tuple header, the number of elements is returned in
400 arity. The tuple elements follow in order in the buffer.
401 int ei_decode_ulong(const char *buf, int *index, unsigned long *p)
403 Decodes an unsigned long integer from the binary format. If the
405 code is 64 bits, the function ei_decode_ulong() is the same as
406 ei_decode_ulonglong().
407 int ei_decode_ulonglong(const char *buf, int *index, unsigned long long
409 *p)
410 Decodes a GCC unsigned long long or Visual C++ unsigned __int64
412 (64-bit) integer from the binary format.
413 int ei_decode_version(const char *buf, int *index, int *version)
415 Decodes the version magic number for the Erlang binary term for‐
417 mat. It must be the first token in a binary term.
418 int ei_encode_atom(char *buf, int *index, const char *p)
420 int ei_encode_atom_len(char *buf, int *index, const char *p, int len)
421 int ei_x_encode_atom(ei_x_buff* x, const char *p)
422 int ei_x_encode_atom_len(ei_x_buff* x, const char *p, int len)
423 Types:
425 ei_x_buff
427 Encodes an atom in the binary format. Parameter p is the name of
429 the atom in Latin-1 encoding. Only up to MAXATOMLEN-1 bytes are
430 encoded. The name is to be NULL-terminated, except for the
431 ei_x_encode_atom_len() function.
432 int ei_encode_atom_as(char *buf, int *index, const char *p, er‐
434 lang_char_encoding from_enc, erlang_char_encoding to_enc)
435 int ei_encode_atom_len_as(char *buf, int *index, const char *p, int
436 len, erlang_char_encoding from_enc, erlang_char_encoding to_enc)
437 int ei_x_encode_atom_as(ei_x_buff* x, const char *p, erlang_char_encod‐
438 ing from_enc, erlang_char_encoding to_enc)
439 int ei_x_encode_atom_len_as(ei_x_buff* x, const char *p, int len, er‐
440 lang_char_encoding from_enc, erlang_char_encoding to_enc)
441 Types:
443 ei_x_buff
445 erlang_char_encoding
446 Encodes an atom in the binary format. Parameter p is the name of
448 the atom with character encoding from_enc (ASCII, Latin-1, or
449 UTF-8). The name must either be NULL-terminated or a function
450 variant with a len parameter must be used.
451 The encoding fails if p is not a valid string in encoding
453 from_enc.
454 Argument to_enc is ignored. As from Erlang/OTP 20 the encoding
456 is always done in UTF-8 which is readable by nodes as old as Er‐
457 lang/OTP R16.
458 int ei_encode_bignum(char *buf, int *index, mpz_t obj)
460 int ei_x_encode_bignum(ei_x_buff *x, mpz_t obj)
461 Types:
463 ei_x_buff
465 Encodes a GMP mpz_t integer to binary format. To use this func‐
467 tion, the ei library must be configured and compiled to use the
468 GMP library.
469 int ei_encode_binary(char *buf, int *index, const void *p, long len)
471 int ei_x_encode_binary(ei_x_buff* x, const void *p, long len)
472 Types:
474 ei_x_buff
476 Encodes a binary in the binary format. The data is at p, of len
478 bytes length.
479 int ei_encode_bitstring(char *buf, int *index, const char *p, size_t
481 bitoffs, size_t nbits)
482 int ei_x_encode_bitstring(ei_x_buff* x, const char *p, size_t bitoffs,
483 size_t nbits)
484 Types:
486 ei_x_buff
488 Encodes a bit string in the binary format.
490 The data is at p. The length of the bit string is nbits bits.
492 The first bitoffs bits of the data at p are unused. The first
493 byte which is part of the bit string is p[bitoffs/8]. The
494 bitoffs%8 most significant bits of the first byte p[bitoffs/8]
495 are unused.
496 The number of bytes which is part of the bit string is (bitoffs
498 + nbits + 7)/8. If (bitoffs + nbits)%8 > 0 then only (bitoffs +
499 nbits)%8 bits of the last byte are used. Unused bits in the last
500 byte are the least significant bits.
501 The values of unused bits are disregarded and does not need to
503 be cleared.
504 int ei_encode_boolean(char *buf, int *index, int p)
506 int ei_x_encode_boolean(ei_x_buff* x, int p)
507 Types:
509 ei_x_buff
511 Encodes a boolean value as the atom true if p is not zero, or
513 false if p is zero.
514 int ei_encode_char(char *buf, int *index, char p)
516 int ei_x_encode_char(ei_x_buff* x, char p)
517 Types:
519 ei_x_buff
521 Encodes a char (8-bit) as an integer between 0-255 in the binary
523 format. For historical reasons the integer argument is of type
524 char. Your C code is to consider the specified argument to be of
525 type unsigned char even if the C compilers and system may define
526 char to be signed.
527 int ei_encode_double(char *buf, int *index, double p)
529 int ei_x_encode_double(ei_x_buff* x, double p)
530 Types:
532 ei_x_buff
534 Encodes a double-precision (64-bit) floating point number in the
536 binary format.
537 Returns -1 if the floating point number is not finite.
539 int ei_encode_empty_list(char* buf, int* index)
541 int ei_x_encode_empty_list(ei_x_buff* x)
542 Types:
544 ei_x_buff
546 Encodes an empty list. It is often used at the tail of a list.
548 int ei_encode_fun(char *buf, int *index, const erlang_fun *p)
550 int ei_x_encode_fun(ei_x_buff* x, const erlang_fun* fun)
551 Types:
553 ei_x_buff
555 erlang_fun
556 Encodes a fun in the binary format. Parameter p points to an er‐
558 lang_fun structure. The erlang_fun is not freed automatically,
559 the free_fun is to be called if the fun is not needed after en‐
560 coding.
561 int ei_encode_list_header(char *buf, int *index, int arity)
563 int ei_x_encode_list_header(ei_x_buff* x, int arity)
564 Types:
566 ei_x_buff
568 Encodes a list header, with a specified arity. The next arity+1
570 terms are the elements (actually its arity cons cells) and the
571 tail of the list. Lists and tuples are encoded recursively, so
572 that a list can contain another list or tuple.
573 For example, to encode the list [c, d, [e | f]]:
575 ei_encode_list_header(buf, &i, 3);
577 ei_encode_atom(buf, &i, "c");
578 ei_encode_atom(buf, &i, "d");
579 ei_encode_list_header(buf, &i, 1);
580 ei_encode_atom(buf, &i, "e");
581 ei_encode_atom(buf, &i, "f");
582 ei_encode_empty_list(buf, &i);
583 Note:
585 It may seem that there is no way to create a list without know‐
586 ing the number of elements in advance. But indeed there is a
587 way. Notice that the list [a, b, c] can be written as [a | [b |
588 [c]]]. Using this, a list can be written as conses.
589 To encode a list, without knowing the arity in advance:
592 while (something()) {
594 ei_x_encode_list_header(&x, 1);
595 ei_x_encode_ulong(&x, i); /* just an example */
596 }
597 ei_x_encode_empty_list(&x);
598 int ei_encode_long(char *buf, int *index, long p)
600 int ei_x_encode_long(ei_x_buff* x, long p)
601 Types:
603 ei_x_buff
605 Encodes a long integer in the binary format. If the code is 64
607 bits, the function ei_encode_long() is the same as ei_en‐
608 code_longlong().
609 int ei_encode_longlong(char *buf, int *index, long long p)
611 int ei_x_encode_longlong(ei_x_buff* x, long long p)
612 Types:
614 ei_x_buff
616 Encodes a GCC long long or Visual C++ __int64 (64-bit) integer
618 in the binary format.
619 int ei_encode_map_header(char *buf, int *index, int arity)
621 int ei_x_encode_map_header(ei_x_buff* x, int arity)
622 Types:
624 ei_x_buff
626 Encodes a map header, with a specified arity. The next arity*2
628 terms encoded will be the keys and values of the map encoded in
629 the following order: K1, V1, K2, V2, ..., Kn, Vn.
630 For example, to encode the map #{a => "Apple", b => "Banana"}:
632 ei_x_encode_map_header(&x, 2);
634 ei_x_encode_atom(&x, "a");
635 ei_x_encode_string(&x, "Apple");
636 ei_x_encode_atom(&x, "b");
637 ei_x_encode_string(&x, "Banana");
638 A correctly encoded map cannot have duplicate keys.
640 int ei_encode_pid(char *buf, int *index, const erlang_pid *p)
642 int ei_x_encode_pid(ei_x_buff* x, const erlang_pid *p)
643 Types:
645 ei_x_buff
647 erlang_pid
648 Encodes an Erlang process identifier (pid) in the binary format.
650 Parameter p points to an erlang_pid structure which should ei‐
651 ther have been obtained earlier with ei_decode_pid(), ei_self()
652 or created by ei_make_pid().
653 int ei_encode_port(char *buf, int *index, const erlang_port *p)
655 int ei_x_encode_port(ei_x_buff* x, const erlang_port *p)
656 Types:
658 ei_x_buff
660 erlang_port
661 Encodes an Erlang port in the binary format. Parameter p points
663 to an erlang_port structure which should have been obtained ear‐
664 lier with ei_decode_port(),
665 int ei_encode_ref(char *buf, int *index, const erlang_ref *p)
667 int ei_x_encode_ref(ei_x_buff* x, const erlang_ref *p)
668 Types:
670 ei_x_buff
672 erlang_ref
673 Encodes an Erlang reference in the binary format. Parameter p
675 points to an erlang_ref structure which either should have been
676 obtained earlier with ei_decode_ref(), or created by
677 ei_make_ref().
678 int ei_encode_string(char *buf, int *index, const char *p)
680 int ei_encode_string_len(char *buf, int *index, const char *p, int len)
681 int ei_x_encode_string(ei_x_buff* x, const char *p)
682 int ei_x_encode_string_len(ei_x_buff* x, const char* s, int len)
683 Types:
685 ei_x_buff
687 Encodes a string in the binary format. (A string in Erlang is a
689 list, but is encoded as a character array in the binary format.)
690 The string is to be NULL-terminated, except for the ei_x_en‐
691 code_string_len() function.
692 int ei_encode_trace(char *buf, int *index, const erlang_trace *p)
694 int ei_x_encode_trace(ei_x_buff* x, const erlang_trace *p)
695 Types:
697 ei_x_buff
699 erlang_trace
700 Encodes an Erlang trace token in the binary format. Parameter p
702 points to a erlang_trace structure which should have been ob‐
703 tained earlier with ei_decode_trace().
704 int ei_encode_tuple_header(char *buf, int *index, int arity)
706 int ei_x_encode_tuple_header(ei_x_buff* x, int arity)
707 Types:
709 ei_x_buff
711 Encodes a tuple header, with a specified arity. The next arity
713 terms encoded will be the elements of the tuple. Tuples and
714 lists are encoded recursively, so that a tuple can contain an‐
715 other tuple or list.
716 For example, to encode the tuple {a, {b, {}}}:
718 ei_encode_tuple_header(buf, &i, 2);
720 ei_encode_atom(buf, &i, "a");
721 ei_encode_tuple_header(buf, &i, 2);
722 ei_encode_atom(buf, &i, "b");
723 ei_encode_tuple_header(buf, &i, 0);
724 int ei_encode_ulong(char *buf, int *index, unsigned long p)
726 int ei_x_encode_ulong(ei_x_buff* x, unsigned long p)
727 Types:
729 ei_x_buff
731 Encodes an unsigned long integer in the binary format. If the
733 code is 64 bits, the function ei_encode_ulong() is the same as
734 ei_encode_ulonglong().
735 int ei_encode_ulonglong(char *buf, int *index, unsigned long long p)
737 int ei_x_encode_ulonglong(ei_x_buff* x, unsigned long long p)
738 Types:
740 ei_x_buff
742 Encodes a GCC unsigned long long or Visual C++ unsigned __int64
744 (64-bit) integer in the binary format.
745 int ei_encode_version(char *buf, int *index)
747 int ei_x_encode_version(ei_x_buff* x)
748 Types:
750 ei_x_buff
752 Encodes a version magic number for the binary format. Must be
754 the first token in a binary term.
755 int ei_get_type(const char *buf, const int *index, int *type, int
757 *size)
758 Returns the type in *type and size in *size of the encoded term.
760 For strings and atoms, size is the number of characters not in‐
761 cluding the terminating NULL. For binaries and bitstrings, *size
762 is the number of bytes. For lists, tuples and maps, *size is the
763 arity of the object. For bignum integers, *size is the number of
764 bytes for the absolute value of the bignum. For other types,
765 *size is 0. In all cases, index is left unchanged.
766 Currently *type is one of:
768 ERL_ATOM_EXT:
770 Decode using either ei_decode_atom(), ei_decode_atom_as(),
771 or ei_decode_boolean().
772 ERL_BINARY_EXT:
774 Decode using either ei_decode_binary(), ei_decode_bit‐
775 string(), or ei_decode_iodata().
776 ERL_BIT_BINARY_EXT:
778 Decode using ei_decode_bitstring().
779 ERL_FLOAT_EXT:
781 Decode using ei_decode_double().
782 ERL_NEW_FUN_EXT
784 ERL_FUN_EXT
785 ERL_EXPORT_EXT: Decode using ei_decode_fun().
786 ERL_SMALL_INTEGER_EXT
788 ERL_INTEGER_EXT
789 ERL_SMALL_BIG_EXT
790 ERL_LARGE_BIG_EXT: Decode using either ei_decode_char(),
791 ei_decode_long(), ei_decode_longlong(), ei_decode_ulong(),
792 ei_decode_ulonglong(), or ei_decode_bignum().
793 ERL_LIST_EXT
795 ERL_NIL_EXT: Decode using either ei_decode_list_header(), or
796 ei_decode_iodata().
797 ERL_STRING_EXT:
799 Decode using either ei_decode_string(), or ei_decode_io‐
800 data().
801 ERL_MAP_EXT:
803 Decode using ei_decode_map_header().
804 ERL_PID_EXT:
806 Decode using ei_decode_pid().
807 ERL_PORT_EXT:
809 Decode using ei_decode_port().
810 ERL_NEW_REFERENCE_EXT:
812 Decode using ei_decode_ref().
813 ERL_SMALL_TUPLE_EXT
815 ERL_LARGE_TUPLE_EXT: Decode using ei_decode_tuple_header().
816 Instead of decoding a term you can also skipped past it if you
818 are not interested in the data by usage of ei_skip_term().
819 int ei_init(void)
821 Initialize the ei library. This function should be called once
823 (and only once) before calling any other functionality in the ei
824 library.
825 On success zero is returned. On failure a posix error code is
827 returned.
828 int ei_print_term(FILE* fp, const char* buf, int* index)
830 int ei_s_print_term(char** s, const char* buf, int* index)
831 Prints a term, in clear text, to the file specified by fp, or
833 the buffer pointed to by s. It tries to resemble the term print‐
834 ing in the Erlang shell.
835 In ei_s_print_term(), parameter s is to point to a dynamically
837 (malloc) allocated string of BUFSIZ bytes or a NULL pointer. The
838 string can be reallocated (and *s can be updated) by this func‐
839 tion if the result is more than BUFSIZ characters. The string
840 returned is NULL-terminated.
841 The return value is the number of characters written to the file
843 or string, or -1 if buf[index] does not contain a valid term.
844 Unfortunately, I/O errors on fp is not checked.
845 Argument index is updated, that is, this function can be viewed
847 as a decode function that decodes a term into a human-readable
848 format.
849 void ei_set_compat_rel(unsigned release_number)
851 In general, the ei library is guaranteed to be compatible with
853 other Erlang/OTP components that are 2 major releases older or
854 newer than the ei library itself.
855 Sometimes an exception to the above rule has to be made to make
857 new features (or even bug fixes) possible. A call to ei_set_com‐
858 pat_rel(release_number) sets the ei library in compatibility
859 mode of OTP release release_number.
860 The only useful value for release_number is currently 21. This
862 will only be useful and have an effect if bit strings or export
863 funs are received from a connected node. Before OTP 22, bit
864 strings and export funs were not supported by ei. They were in‐
865 stead encoded using an undocumented fallback tuple format when
866 sent from the emulator to ei:
867 Bit string:
869 The term <<42, 1:1>> was encoded as {<<42, 128>>, 1}. The
870 first element of the tuple is a binary and the second ele‐
871 ment denotes how many bits of the last bytes are part of the
872 bit string. In this example only the most significant bit of
873 the last byte (128) is part of the bit string.
874 Export fun:
876 The term fun lists:map/2 was encoded as {lists,map}. A tuple
877 with the module, function and a missing arity.
878 If ei_set_compat_rel(21) is not called then a connected emulator
880 will send bit strings and export funs correctly encoded. The
881 functions ei_decode_bitstring and ei_decode_fun has to be used
882 to decode such terms. Calling ei_set_compat_rel(21) should only
883 be done as a workaround to keep an old implementation alive,
884 which expects to receive the undocumented tuple formats for bit
885 strings and/or export funs.
886 Note:
888 If this function is called, it can only be called once and must
889 be called before any other functions in the ei library are
890 called.
891 int ei_skip_term(const char* buf, int* index)
894 Skips a term in the specified buffer; recursively skips elements
896 of lists and tuples, so that a full term is skipped. This is a
897 way to get the size of an Erlang term.
898 buf is the buffer.
900 index is updated to point right after the term in the buffer.
902 Note:
904 This can be useful when you want to hold arbitrary terms: skip
905 them and copy the binary term data to some buffer.
906 Returns 0 on success, otherwise -1.
909 int ei_x_append(ei_x_buff* x, const ei_x_buff* x2)
911 int ei_x_append_buf(ei_x_buff* x, const char* buf, int len)
912 Types:
914 ei_x_buff
916 Appends data at the end of buffer x.
918 int ei_x_format(ei_x_buff* x, const char* fmt, ...)
920 int ei_x_format_wo_ver(ei_x_buff* x, const char *fmt, ... )
921 Types:
923 ei_x_buff
925 erlang_pid
926 Formats a term, given as a string, to a buffer. Works like a
928 sprintf for Erlang terms. fmt contains a format string, with ar‐
929 guments like ~d, to insert terms from variables. The following
930 formats are supported (with the C types given):
931 ~a An atom, char*
933 ~c A character, char
934 ~s A string, char*
935 ~i An integer, int
936 ~l A long integer, long int
937 ~u A unsigned long integer, unsigned long int
938 ~f A float, float
939 ~d A double float, double float
940 ~p An Erlang pid, erlang_pid*
941 For example, to encode a tuple with some stuff:
943 ei_x_format("{~a,~i,~d}", "numbers", 12, 3.14159)
945 encodes the tuple {numbers,12,3.14159}
946 ei_x_format_wo_ver() formats into a buffer, without the initial
948 version byte.
949 int ei_x_free(ei_x_buff* x)
951 Types:
953 ei_x_buff
955 Deallocates the dynamically allocated content of the buffer re‐
957 ferred by x. After deallocation, the buff field is set to NULL.
958 int ei_x_new(ei_x_buff* x)
960 int ei_x_new_with_version(ei_x_buff* x)
961 Types:
963 ei_x_buff
965 Initialize the dynamically realizable buffer referred to by x.
967 The fields of the structure pointed to by parameter x is filled
968 in, and a default buffer is allocated. ei_x_new_with_version()
969 also puts an initial version byte, which is used in the binary
970 format (so that ei_x_encode_version() will not be needed.)
971
973 Some tips on what to check when the emulator does not seem to receive
974 the terms that you send:
975 * Be careful with the version header, use ei_x_new_with_version()
977 when appropriate.
978 * Turn on distribution tracing on the Erlang node.
980 * Check the result codes from ei_decode_-calls.
982Ericsson AB erl_interface 5.1 ei(3)