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
15 ei_decode_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 format.
19 The difference between ei and erl_interface is that ei uses the binary
20 format directly when sending and receiving terms. It is also thread
21 safe, and using threads, one process can handle multiple C-nodes. The
22 erl_interface library is built on top of ei, but of legacy reasons, it
23 does not allow for multiple C-nodes. In general, ei is the preferred
24 way of doing C-nodes.
25 The decode and encode functions use a buffer and an index into the buf‐
27 fer, which points at the point where to encode and decode. The index is
28 updated to point right after the term encoded/decoded. No checking is
29 done whether the term fits in the buffer or not. If encoding goes out‐
30 side the buffer, the program can crash.
31 All functions take two parameters:
33 * buf is a pointer to the buffer where the binary data is or will be.
35 * index is a pointer to an index into the buffer. This parameter is
37 incremented with the size of the term decoded/encoded.
38 The data is thus at buf[*index] when an ei function is called.
40 All encode functions assume that the buf and index parameters point to
42 a buffer large enough for the data. To get the size of an encoded term,
43 without encoding it, pass NULL instead of a buffer pointer. Parameter
44 index is incremented, but nothing will be encoded. This is the way in
45 ei to "preflight" term encoding.
46 There are also encode functions that use a dynamic buffer. It is often
48 more convenient to use these to encode data. All encode functions comes
49 in two versions; those starting with ei_x use a dynamic buffer.
50 All functions return 0 if successful, otherwise -1 (for example, if a
52 term is not of the expected type, or the data to decode is an invalid
53 Erlang term).
54 Some of the decode functions need a pre-allocated buffer. This buffer
56 must be allocated large enough, and for non-compound types the
57 ei_get_type() function returns the size required (notice that for
58 strings an extra byte is needed for the NULL-terminator).
59
61 erlang_char_encoding:
62 typedef enum {
65 ERLANG_ASCII = 1,
66 ERLANG_LATIN1 = 2,
67 ERLANG_UTF8 = 4
68 } erlang_char_encoding;
69 The character encodings used for atoms. ERLANG_ASCII represents
71 7-bit ASCII. Latin-1 and UTF-8 are different extensions of 7-bit
72 ASCII. All 7-bit ASCII characters are valid Latin-1 and UTF-8 char‐
73 acters. ASCII and Latin-1 both represent each character by one
74 byte. An UTF-8 character can consist of 1-4 bytes. Notice that
75 these constants are bit-flags and can be combined with bitwise OR.
76
78 int ei_decode_atom(const char *buf, int *index, char *p)
79 Decodes an atom from the binary format. The NULL-terminated name
81 of the atom is placed at p. At most MAXATOMLEN bytes can be
82 placed in the buffer.
83 int ei_decode_atom_as(const char *buf, int *index, char *p, int plen,
85 erlang_char_encoding want, erlang_char_encoding* was,
86 erlang_char_encoding* result)
87 Decodes an atom from the binary format. The NULL-terminated name
89 of the atom is placed in buffer at p of length plen bytes.
90 The wanted string encoding is specified by want. The original
92 encoding used in the binary format (Latin-1 or UTF-8) can be
93 obtained from *was. The encoding of the resulting string (7-bit
94 ASCII, Latin-1, or UTF-8) can be obtained from *result. Both was
95 and result can be NULL. *result can differ from want if want is
96 a bitwise OR'd combination like ERLANG_LATIN1|ERLANG_UTF8 or if
97 *result turns out to be pure 7-bit ASCII (compatible with both
98 Latin-1 and UTF-8).
99 This function fails if the atom is too long for the buffer or if
101 it cannot be represented with encoding want.
102 This function was introduced in Erlang/OTP R16 as part of a
104 first step to support UTF-8 atoms.
105 int ei_decode_bignum(const char *buf, int *index, mpz_t obj)
107 Decodes an integer in the binary format to a GMP mpz_t integer.
109 To use this function, the ei library must be configured and com‐
110 piled to use the GMP library.
111 int ei_decode_binary(const char *buf, int *index, void *p, long *len)
113 Decodes a binary from the binary format. Parameter len is set to
115 the actual size of the binary. Notice that ei_decode_binary()
116 assumes that there is enough room for the binary. The size
117 required can be fetched by ei_get_type().
118 int ei_decode_boolean(const char *buf, int *index, int *p)
120 Decodes a boolean value from the binary format. A boolean is
122 actually an atom, true decodes 1 and false decodes 0.
123 int ei_decode_char(const char *buf, int *index, char *p)
125 Decodes a char (8-bit) integer between 0-255 from the binary
127 format. For historical reasons the returned integer is of type
128 char. Your C code is to consider the returned value to be of
129 type unsigned char even if the C compilers and system can define
130 char to be signed.
131 int ei_decode_double(const char *buf, int *index, double *p)
133 Decodes a double-precision (64-bit) floating point number from
135 the binary format.
136 int ei_decode_ei_term(const char* buf, int* index, ei_term* term)
138 Decodes any term, or at least tries to. If the term pointed at
140 by *index in buf fits in the term union, it is decoded, and the
141 appropriate field in term->value is set, and *index is incre‐
142 mented by the term size.
143 The function returns 1 on successful decoding, -1 on error, and
145 0 if the term seems alright, but does not fit in the term struc‐
146 ture. If 1 is returned, the index is incremented, and term con‐
147 tains the decoded term.
148 The term structure contains the arity for a tuple or list, size
150 for a binary, string, or atom. It contains a term if it is any
151 of the following: integer, float, atom, pid, port, or ref.
152 int ei_decode_fun(const char *buf, int *index, erlang_fun *p)
154 void free_fun(erlang_fun* f)
155 Decodes a fun from the binary format. Parameter p is to be NULL
157 or point to an erlang_fun structure. This is the only decode
158 function that allocates memory. When the erlang_fun is no longer
159 needed, it is to be freed with free_fun. (This has to do with
160 the arbitrary size of the environment for a fun.)
161 int ei_decode_list_header(const char *buf, int *index, int *arity)
163 Decodes a list header from the binary format. The number of ele‐
165 ments is returned in arity. The arity+1 elements follow (the
166 last one is the tail of the list, normally an empty list). If
167 arity is 0, it is an empty list.
168 Notice that lists are encoded as strings if they consist
170 entirely of integers in the range 0..255. This function do not
171 decode such strings, use ei_decode_string() instead.
172 int ei_decode_long(const char *buf, int *index, long *p)
174 Decodes a long integer from the binary format. If the code is 64
176 bits, the function ei_decode_long() is the same as
177 ei_decode_longlong().
178 int ei_decode_longlong(const char *buf, int *index, long long *p)
180 Decodes a GCC long long or Visual C++ __int64 (64-bit) integer
182 from the binary format. This function is missing in the VxWorks
183 port.
184 int ei_decode_map_header(const char *buf, int *index, int *arity)
186 Decodes a map header from the binary format. The number of key-
188 value pairs is returned in *arity. Keys and values follow in
189 this order: K1, V1, K2, V2, ..., Kn, Vn. This makes a total of
190 arity*2 terms. If arity is zero, it is an empty map. A correctly
191 encoded map does not have duplicate keys.
192 int ei_decode_pid(const char *buf, int *index, erlang_pid *p)
194 Decodes a process identifier (pid) from the binary format.
196 int ei_decode_port(const char *buf, int *index, erlang_port *p)
198 Decodes a port identifier from the binary format.
200 int ei_decode_ref(const char *buf, int *index, erlang_ref *p)
202 Decodes a reference from the binary format.
204 int ei_decode_string(const char *buf, int *index, char *p)
206 Decodes a string from the binary format. A string in Erlang is a
208 list of integers between 0 and 255. Notice that as the string is
209 just a list, sometimes lists are encoded as strings by
210 term_to_binary/1, even if it was not intended.
211 The string is copied to p, and enough space must be allocated.
213 The returned string is NULL-terminated, so you must add an extra
214 byte to the memory requirement.
215 int ei_decode_term(const char *buf, int *index, void *t)
217 Decodes a term from the binary format. The term is return in t
219 as a ETERM*, so t is actually an ETERM** (see erl_eterm). The
220 term is later to be deallocated.
221 Notice that this function is located in the Erl_Interface
223 library.
224 int ei_decode_trace(const char *buf, int *index, erlang_trace *p)
226 Decodes an Erlang trace token from the binary format.
228 int ei_decode_tuple_header(const char *buf, int *index, int *arity)
230 Decodes a tuple header, the number of elements is returned in
232 arity. The tuple elements follow in order in the buffer.
233 int ei_decode_ulong(const char *buf, int *index, unsigned long *p)
235 Decodes an unsigned long integer from the binary format. If the
237 code is 64 bits, the function ei_decode_ulong() is the same as
238 ei_decode_ulonglong().
239 int ei_decode_ulonglong(const char *buf, int *index, unsigned long long
241 *p)
242 Decodes a GCC unsigned long long or Visual C++ unsigned __int64
244 (64-bit) integer from the binary format. This function is miss‐
245 ing in the VxWorks port.
246 int ei_decode_version(const char *buf, int *index, int *version)
248 Decodes the version magic number for the Erlang binary term for‐
250 mat. It must be the first token in a binary term.
251 int ei_encode_atom(char *buf, int *index, const char *p)
253 int ei_encode_atom_len(char *buf, int *index, const char *p, int len)
254 int ei_x_encode_atom(ei_x_buff* x, const char *p)
255 int ei_x_encode_atom_len(ei_x_buff* x, const char *p, int len)
256 Encodes an atom in the binary format. Parameter p is the name of
258 the atom in Latin-1 encoding. Only up to MAXATOMLEN-1 bytes are
259 encoded. The name is to be NULL-terminated, except for the
260 ei_x_encode_atom_len() function.
261 int ei_encode_atom_as(char *buf, int *index, const char *p,
263 erlang_char_encoding from_enc, erlang_char_encoding to_enc)
264 int ei_encode_atom_len_as(char *buf, int *index, const char *p, int
265 len, erlang_char_encoding from_enc, erlang_char_encoding to_enc)
266 int ei_x_encode_atom_as(ei_x_buff* x, const char *p, erlang_char_encod‐
267 ing from_enc, erlang_char_encoding to_enc)
268 int ei_x_encode_atom_len_as(ei_x_buff* x, const char *p, int len,
269 erlang_char_encoding from_enc, erlang_char_encoding to_enc)
270 Encodes an atom in the binary format. Parameter p is the name of
272 the atom with character encoding from_enc (ASCII, Latin-1, or
273 UTF-8). The name must either be NULL-terminated or a function
274 variant with a len parameter must be used.
275 The encoding fails if p is not a valid string in encoding
277 from_enc.
278 Argument to_enc is ignored. As from Erlang/OTP 20 the encoding
280 is always done in UTF-8 which is readable by nodes as old as
281 Erlang/OTP R16.
282 int ei_encode_bignum(char *buf, int *index, mpz_t obj)
284 int ei_x_encode_bignum(ei_x_buff *x, mpz_t obj)
285 Encodes a GMP mpz_t integer to binary format. To use this func‐
287 tion, the ei library must be configured and compiled to use the
288 GMP library.
289 int ei_encode_binary(char *buf, int *index, const void *p, long len)
291 int ei_x_encode_binary(ei_x_buff* x, const void *p, long len)
292 Encodes a binary in the binary format. The data is at p, of len
294 bytes length.
295 int ei_encode_boolean(char *buf, int *index, int p)
297 int ei_x_encode_boolean(ei_x_buff* x, int p)
298 Encodes a boolean value as the atom true if p is not zero, or
300 false if p is zero.
301 int ei_encode_char(char *buf, int *index, char p)
303 int ei_x_encode_char(ei_x_buff* x, char p)
304 Encodes a char (8-bit) as an integer between 0-255 in the binary
306 format. For historical reasons the integer argument is of type
307 char. Your C code is to consider the specified argument to be of
308 type unsigned char even if the C compilers and system may define
309 char to be signed.
310 int ei_encode_double(char *buf, int *index, double p)
312 int ei_x_encode_double(ei_x_buff* x, double p)
313 Encodes a double-precision (64-bit) floating point number in the
315 binary format.
316 Returns -1 if the floating point number is not finite.
318 int ei_encode_empty_list(char* buf, int* index)
320 int ei_x_encode_empty_list(ei_x_buff* x)
321 Encodes an empty list. It is often used at the tail of a list.
323 int ei_encode_fun(char *buf, int *index, const erlang_fun *p)
325 int ei_x_encode_fun(ei_x_buff* x, const erlang_fun* fun)
326 Encodes a fun in the binary format. Parameter p points to an
328 erlang_fun structure. The erlang_fun is not freed automatically,
329 the free_fun is to be called if the fun is not needed after
330 encoding.
331 int ei_encode_list_header(char *buf, int *index, int arity)
333 int ei_x_encode_list_header(ei_x_buff* x, int arity)
334 Encodes a list header, with a specified arity. The next arity+1
336 terms are the elements (actually its arity cons cells) and the
337 tail of the list. Lists and tuples are encoded recursively, so
338 that a list can contain another list or tuple.
339 For example, to encode the list [c, d, [e | f]]:
341 ei_encode_list_header(buf, &i, 3);
343 ei_encode_atom(buf, &i, "c");
344 ei_encode_atom(buf, &i, "d");
345 ei_encode_list_header(buf, &i, 1);
346 ei_encode_atom(buf, &i, "e");
347 ei_encode_atom(buf, &i, "f");
348 ei_encode_empty_list(buf, &i);
349 Note:
351 It may seem that there is no way to create a list without know‐
352 ing the number of elements in advance. But indeed there is a
353 way. Notice that the list [a, b, c] can be written as [a | [b |
354 [c]]]. Using this, a list can be written as conses.
355 To encode a list, without knowing the arity in advance:
358 while (something()) {
360 ei_x_encode_list_header(&x, 1);
361 ei_x_encode_ulong(&x, i); /* just an example */
362 }
363 ei_x_encode_empty_list(&x);
364 int ei_encode_long(char *buf, int *index, long p)
366 int ei_x_encode_long(ei_x_buff* x, long p)
367 Encodes a long integer in the binary format. If the code is 64
369 bits, the function ei_encode_long() is the same as
370 ei_encode_longlong().
371 int ei_encode_longlong(char *buf, int *index, long long p)
373 int ei_x_encode_longlong(ei_x_buff* x, long long p)
374 Encodes a GCC long long or Visual C++ __int64 (64-bit) integer
376 in the binary format. This function is missing in the VxWorks
377 port.
378 int ei_encode_map_header(char *buf, int *index, int arity)
380 int ei_x_encode_map_header(ei_x_buff* x, int arity)
381 Encodes a map header, with a specified arity. The next arity*2
383 terms encoded will be the keys and values of the map encoded in
384 the following order: K1, V1, K2, V2, ..., Kn, Vn.
385 For example, to encode the map #{a => "Apple", b => "Banana"}:
387 ei_x_encode_map_header(&x, 2);
389 ei_x_encode_atom(&x, "a");
390 ei_x_encode_string(&x, "Apple");
391 ei_x_encode_atom(&x, "b");
392 ei_x_encode_string(&x, "Banana");
393 A correctly encoded map cannot have duplicate keys.
395 int ei_encode_pid(char *buf, int *index, const erlang_pid *p)
397 int ei_x_encode_pid(ei_x_buff* x, const erlang_pid *p)
398 Encodes an Erlang process identifier (pid) in the binary format.
400 Parameter p points to an erlang_pid structure (which should have
401 been obtained earlier with ei_decode_pid()).
402 int ei_encode_port(char *buf, int *index, const erlang_port *p)
404 int ei_x_encode_port(ei_x_buff* x, const erlang_port *p)
405 Encodes an Erlang port in the binary format. Parameter p points
407 to a erlang_port structure (which should have been obtained ear‐
408 lier with ei_decode_port()).
409 int ei_encode_ref(char *buf, int *index, const erlang_ref *p)
411 int ei_x_encode_ref(ei_x_buff* x, const erlang_ref *p)
412 Encodes an Erlang reference in the binary format. Parameter p
414 points to a erlang_ref structure (which should have been
415 obtained earlier with ei_decode_ref()).
416 int ei_encode_string(char *buf, int *index, const char *p)
418 int ei_encode_string_len(char *buf, int *index, const char *p, int len)
419 int ei_x_encode_string(ei_x_buff* x, const char *p)
420 int ei_x_encode_string_len(ei_x_buff* x, const char* s, int len)
421 Encodes a string in the binary format. (A string in Erlang is a
423 list, but is encoded as a character array in the binary format.)
424 The string is to be NULL-terminated, except for the
425 ei_x_encode_string_len() function.
426 int ei_encode_term(char *buf, int *index, void *t)
428 int ei_x_encode_term(ei_x_buff* x, void *t)
429 Encodes an ETERM, as obtained from erl_interface. Parameter t is
431 actually an ETERM pointer. This function does not free the
432 ETERM.
433 int ei_encode_trace(char *buf, int *index, const erlang_trace *p)
435 int ei_x_encode_trace(ei_x_buff* x, const erlang_trace *p)
436 Encodes an Erlang trace token in the binary format. Parameter p
438 points to a erlang_trace structure (which should have been
439 obtained earlier with ei_decode_trace()).
440 int ei_encode_tuple_header(char *buf, int *index, int arity)
442 int ei_x_encode_tuple_header(ei_x_buff* x, int arity)
443 Encodes a tuple header, with a specified arity. The next arity
445 terms encoded will be the elements of the tuple. Tuples and
446 lists are encoded recursively, so that a tuple can contain
447 another tuple or list.
448 For example, to encode the tuple {a, {b, {}}}:
450 ei_encode_tuple_header(buf, &i, 2);
452 ei_encode_atom(buf, &i, "a");
453 ei_encode_tuple_header(buf, &i, 2);
454 ei_encode_atom(buf, &i, "b");
455 ei_encode_tuple_header(buf, &i, 0);
456 int ei_encode_ulong(char *buf, int *index, unsigned long p)
458 int ei_x_encode_ulong(ei_x_buff* x, unsigned long p)
459 Encodes an unsigned long integer in the binary format. If the
461 code is 64 bits, the function ei_encode_ulong() is the same as
462 ei_encode_ulonglong().
463 int ei_encode_ulonglong(char *buf, int *index, unsigned long long p)
465 int ei_x_encode_ulonglong(ei_x_buff* x, unsigned long long p)
466 Encodes a GCC unsigned long long or Visual C++ unsigned __int64
468 (64-bit) integer in the binary format. This function is missing
469 in the VxWorks port.
470 int ei_encode_version(char *buf, int *index)
472 int ei_x_encode_version(ei_x_buff* x)
473 Encodes a version magic number for the binary format. Must be
475 the first token in a binary term.
476 int ei_get_type(const char *buf, const int *index, int *type, int
478 *size)
479 Returns the type in type and size in size of the encoded term.
481 For strings and atoms, size is the number of characters not
482 including the terminating NULL. For binaries, size is the number
483 of bytes. For lists and tuples, size is the arity of the object.
484 For other types, size is 0. In all cases, index is left
485 unchanged.
486 int ei_init(void)
488 Initialize the ei library. This function should be called once
490 (and only once) before calling any other functionality in the ei
491 library. However, note the exception below.
492 If the ei library is used together with the erl_interface
494 library, this function should not be called directly. It will be
495 called by the erl_init() function which should be used to ini‐
496 tialize the combination of the two libraries instead.
497 On success zero is returned. On failure a posix error code is
499 returned.
500 int ei_print_term(FILE* fp, const char* buf, int* index)
502 int ei_s_print_term(char** s, const char* buf, int* index)
503 Prints a term, in clear text, to the file specified by fp, or
505 the buffer pointed to by s. It tries to resemble the term print‐
506 ing in the Erlang shell.
507 In ei_s_print_term(), parameter s is to point to a dynamically
509 (malloc) allocated string of BUFSIZ bytes or a NULL pointer. The
510 string can be reallocated (and *s can be updated) by this func‐
511 tion if the result is more than BUFSIZ characters. The string
512 returned is NULL-terminated.
513 The return value is the number of characters written to the file
515 or string, or -1 if buf[index] does not contain a valid term.
516 Unfortunately, I/O errors on fp is not checked.
517 Argument index is updated, that is, this function can be viewed
519 as a decode function that decodes a term into a human-readable
520 format.
521 void ei_set_compat_rel(release_number)
523 Types:
525 unsigned release_number;
527 By default, the ei library is only guaranteed to be compatible
529 with other Erlang/OTP components from the same release as the ei
530 library itself. For example, ei from Erlang/OTP R10 is not com‐
531 patible with an Erlang emulator from Erlang/OTP R9 by default.
532 A call to ei_set_compat_rel(release_number) sets the ei library
534 in compatibility mode of release release_number. Valid range of
535 release_number is [7, current release]. This makes it possible
536 to communicate with Erlang/OTP components from earlier releases.
537 Note:
539 If this function is called, it can only be called once and must
540 be called before any other functions in the ei library are
541 called.
542 Warning:
545 You can run into trouble if this feature is used carelessly.
546 Always ensure that all communicating components are either from
547 the same Erlang/OTP release, or from release X and release Y
548 where all components from release Y are in compatibility mode of
549 release X.
550 int ei_skip_term(const char* buf, int* index)
553 Skips a term in the specified buffer; recursively skips elements
555 of lists and tuples, so that a full term is skipped. This is a
556 way to get the size of an Erlang term.
557 buf is the buffer.
559 index is updated to point right after the term in the buffer.
561 Note:
563 This can be useful when you want to hold arbitrary terms: skip
564 them and copy the binary term data to some buffer.
565 Returns 0 on success, otherwise -1.
568 int ei_x_append(ei_x_buff* x, const ei_x_buff* x2)
570 int ei_x_append_buf(ei_x_buff* x, const char* buf, int len)
571 Appends data at the end of buffer x.
573 int ei_x_format(ei_x_buff* x, const char* fmt, ...)
575 int ei_x_format_wo_ver(ei_x_buff* x, const char *fmt, ... )
576 Formats a term, given as a string, to a buffer. Works like a
578 sprintf for Erlang terms. fmt contains a format string, with
579 arguments like ~d, to insert terms from variables. The following
580 formats are supported (with the C types given):
581 ~a An atom, char*
583 ~c A character, char
584 ~s A string, char*
585 ~i An integer, int
586 ~l A long integer, long int
587 ~u A unsigned long integer, unsigned long int
588 ~f A float, float
589 ~d A double float, double float
590 ~p An Erlang pid, erlang_pid*
591 For example, to encode a tuple with some stuff:
593 ei_x_format("{~a,~i,~d}", "numbers", 12, 3.14159)
595 encodes the tuple {numbers,12,3.14159}
596 ei_x_format_wo_ver() formats into a buffer, without the initial
598 version byte.
599 int ei_x_free(ei_x_buff* x)
601 Frees an ei_x_buff buffer. The memory used by the buffer is
603 returned to the OS.
604 int ei_x_new(ei_x_buff* x)
606 int ei_x_new_with_version(ei_x_buff* x)
607 Allocates a new ei_x_buff buffer. The fields of the structure
609 pointed to by parameter x is filled in, and a default buffer is
610 allocated. ei_x_new_with_version() also puts an initial version
611 byte, which is used in the binary format (so that
612 ei_x_encode_version() will not be needed.)
613
615 Some tips on what to check when the emulator does not seem to receive
616 the terms that you send:
617 * Be careful with the version header, use ei_x_new_with_version()
619 when appropriate.
620 * Turn on distribution tracing on the Erlang node.
622 * Check the result codes from ei_decode_-calls.
624
626 erl_eterm
627Ericsson AB erl_interface 3.11.3 ei(3)