1ei(3)                         C Library Functions                        ei(3)
2
3
4

NAME

6       ei - Routines for handling the Erlang binary term format.
7

DESCRIPTION

9   Note:
10       The support for VxWorks is deprecated as of OTP 22, and will be removed
11       in OTP 23.
12
13
14       The library ei contains macros and functions to encode and  decode  the
15       Erlang binary term format.
16
17       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
22       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
31       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
37       All functions take two parameters:
38
39         * buf is a pointer to the buffer where the binary data is or will be.
40
41         * index  is  a pointer to an index into the buffer. This parameter is
42           incremented with the size of the term decoded/encoded.
43
44       The data is thus at buf[*index] when an ei function is called.
45
46       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
52       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
56       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
60       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

DATA TYPES

66         erlang_char_encoding:
67
68
69         typedef enum {
70             ERLANG_ASCII = 1,
71             ERLANG_LATIN1 = 2,
72             ERLANG_UTF8 = 4
73         } erlang_char_encoding;
74
75           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

EXPORTS

83       int ei_decode_atom(const char *buf, int *index, char *p)
84
85              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
89       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
93              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
96              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
105              This function fails if the atom is too long for the buffer or if
106              it cannot be represented with encoding want.
107
108              This  function  was  introduced  in  Erlang/OTP R16 as part of a
109              first step to support UTF-8 atoms.
110
111       int ei_decode_bignum(const char *buf, int *index, mpz_t obj)
112
113              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
117       int ei_decode_binary(const char *buf, int *index, void *p, long *len)
118
119              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
124       int  ei_decode_bitstring(const  char *buf, int *index, const char **pp,
125       unsigned int *bitoffsp, size_t *nbitsp)
126
127              Decodes a bit string from the binary format.
128
129                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
135                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
141                nbitsp:
142                  Either NULL or *nbitsp returns the length of the bit  string
143                  in bits.
144
145              Returns 0 if it was a bit string term.
146
147              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
153              The  values  of unused bits in the first and last byte are unde‐
154              fined and cannot be relied on.
155
156              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
160       int ei_decode_boolean(const char *buf, int *index, int *p)
161
162              Decodes a boolean value from the binary  format.  A  boolean  is
163              actually an atom, true decodes 1 and false decodes 0.
164
165       int ei_decode_char(const char *buf, int *index, char *p)
166
167              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
173       int ei_decode_double(const char *buf, int *index, double *p)
174
175              Decodes  a  double-precision (64-bit) floating point number from
176              the binary format.
177
178       int ei_decode_ei_term(const char* buf, int* index, ei_term* term)
179
180              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
185              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
190              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
194       int ei_decode_fun(const char *buf, int *index, erlang_fun *p)
195       void free_fun(erlang_fun* f)
196
197              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
203       int ei_decode_list_header(const char *buf, int *index, int *arity)
204
205              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
210              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
214       int ei_decode_long(const char *buf, int *index, long *p)
215
216              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
220       int ei_decode_longlong(const char *buf, int *index, long long *p)
221
222              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
226       int ei_decode_map_header(const char *buf, int *index, int *arity)
227
228              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
234       int ei_decode_pid(const char *buf, int *index, erlang_pid *p)
235
236              Decodes a process identifier (pid) from the binary format.
237
238       int ei_decode_port(const char *buf, int *index, erlang_port *p)
239
240              Decodes a port identifier from the binary format.
241
242       int ei_decode_ref(const char *buf, int *index, erlang_ref *p)
243
244              Decodes a reference from the binary format.
245
246       int ei_decode_string(const char *buf, int *index, char *p)
247
248              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
253              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
257       int ei_decode_term(const char *buf, int *index, void *t)
258
259              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
263          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
268
269       int ei_decode_trace(const char *buf, int *index, erlang_trace *p)
270
271              Decodes an Erlang trace token from the binary format.
272
273       int ei_decode_tuple_header(const char *buf, int *index, int *arity)
274
275              Decodes a tuple header, the number of elements  is  returned  in
276              arity. The tuple elements follow in order in the buffer.
277
278       int ei_decode_ulong(const char *buf, int *index, unsigned long *p)
279
280              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
284       int ei_decode_ulonglong(const char *buf, int *index, unsigned long long
285       *p)
286
287              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
291       int ei_decode_version(const char *buf, int *index, int *version)
292
293              Decodes the version magic number for the Erlang binary term for‐
294              mat. It must be the first token in a binary term.
295
296       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
301              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
306       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
315              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
320              The  encoding  fails  if  p  is  not  a valid string in encoding
321              from_enc.
322
323              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
327       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
330              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
334       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
337              Encodes a binary in the binary format. The data is at p, of  len
338              bytes length.
339
340       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
345              Encodes a bit string in the binary format.
346
347              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
353              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
358              The values of unused bits are disregarded and does not  need  to
359              be cleared.
360
361       int ei_encode_boolean(char *buf, int *index, int p)
362       int ei_x_encode_boolean(ei_x_buff* x, int p)
363
364              Encodes  a  boolean  value as the atom true if p is not zero, or
365              false if p is zero.
366
367       int ei_encode_char(char *buf, int *index, char p)
368       int ei_x_encode_char(ei_x_buff* x, char p)
369
370              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
376       int ei_encode_double(char *buf, int *index, double p)
377       int ei_x_encode_double(ei_x_buff* x, double p)
378
379              Encodes a double-precision (64-bit) floating point number in the
380              binary format.
381
382              Returns -1 if the floating point number is not finite.
383
384       int ei_encode_empty_list(char* buf, int* index)
385       int ei_x_encode_empty_list(ei_x_buff* x)
386
387              Encodes an empty list. It is often used at the tail of a list.
388
389       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
392              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
397       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
400              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
405              For example, to encode the list [c, d, [e | f]]:
406
407              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
415          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
421
422              To encode a list, without knowing the arity in advance:
423
424              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
430       int ei_encode_long(char *buf, int *index, long p)
431       int ei_x_encode_long(ei_x_buff* x, long p)
432
433              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
437       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
440              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
444       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
447              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
451              For example, to encode the map #{a => "Apple", b => "Banana"}:
452
453              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
459              A correctly encoded map cannot have duplicate keys.
460
461       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
464              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
468       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
471              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
475       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
478              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
482       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
487              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
492       int ei_encode_term(char *buf, int *index, void *t)
493       int ei_x_encode_term(ei_x_buff* x, void *t)
494
495              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
499          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
504
505       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
508              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
512       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
515              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
520              For example, to encode the tuple {a, {b, {}}}:
521
522              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
528       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
531              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
535       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
538              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
542       int ei_encode_version(char *buf, int *index)
543       int ei_x_encode_version(ei_x_buff* x)
544
545              Encodes a version magic number for the binary  format.  Must  be
546              the first token in a binary term.
547
548       int  ei_get_type(const  char  *buf,  const  int  *index, int *type, int
549       *size)
550
551              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
558       int ei_init(void)
559
560              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
564              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
569              On success zero is returned. On failure a posix  error  code  is
570              returned.
571
572       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
575              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
579              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
585              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
589              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
593       void ei_set_compat_rel(release_number)
594
595              Types:
596
597                 unsigned release_number;
598
599              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
603              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
608              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
615                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
622                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
626              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
634          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
639
640       int ei_skip_term(const char* buf, int* index)
641
642              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
646              buf is the buffer.
647
648              index is updated to point right after the term in the buffer.
649
650          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
654
655              Returns 0 on success, otherwise -1.
656
657       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
660              Appends data at the end of buffer x.
661
662       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
665              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
670              ~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
680              For example, to encode a tuple with some stuff:
681
682              ei_x_format("{~a,~i,~d}", "numbers", 12, 3.14159)
683              encodes the tuple {numbers,12,3.14159}
684
685              ei_x_format_wo_ver() formats into a buffer, without the  initial
686              version byte.
687
688       int ei_x_free(ei_x_buff* x)
689
690              Frees  an  ei_x_buff  buffer.  The  memory used by the buffer is
691              returned to the OS.
692
693       int ei_x_new(ei_x_buff* x)
694       int ei_x_new_with_version(ei_x_buff* x)
695
696              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

DEBUG INFORMATION

703       Some tips on what to check when the emulator does not seem  to  receive
704       the terms that you send:
705
706         * Be  careful  with  the  version header, use ei_x_new_with_version()
707           when appropriate.
708
709         * Turn on distribution tracing on the Erlang node.
710
711         * Check the result codes from ei_decode_-calls.
712

SEE ALSO

714       erl_eterm
715
716
717
718Ericsson AB                   erl_interface 3.13                         ei(3)
Impressum