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

NAME

6       erl_eterm - Functions for Erlang term construction.
7

DESCRIPTION

9       This  module  provides  functions  for creating and manipulating Erlang
10       terms.
11
12       An Erlang term is represented by a C structure of type ETERM.  Applica‐
13       tions should not reference any fields in this structure directly, as it
14       can be changed in future releases to provide faster  and  more  compact
15       term storage. Instead, applications should use the macros and functions
16       provided.
17
18       Each of the following macros takes a single ETERM pointer as  an  argu‐
19       ment. The macros return a non-zero value if the test is true, otherwise
20       0.
21
22         ERL_IS_INTEGER(t):
23           True if t is an integer.
24
25         ERL_IS_UNSIGNED_INTEGER(t):
26           True if t is an integer.
27
28         ERL_IS_FLOAT(t):
29           True if t is a floating point number.
30
31         ERL_IS_ATOM(t):
32           True if t is an atom.
33
34         ERL_IS_PID(t):
35           True if t is a pid (process identifier).
36
37         ERL_IS_PORT(t):
38           True if t is a port.
39
40         ERL_IS_REF(t):
41           True if t is a reference.
42
43         ERL_IS_TUPLE(t):
44           True if t is a tuple.
45
46         ERL_IS_BINARY(t):
47           True if t is a binary.
48
49         ERL_IS_LIST(t):
50           True if t is a list with zero or more elements.
51
52         ERL_IS_EMPTY_LIST(t):
53           True if t is an empty list.
54
55         ERL_IS_CONS(t):
56           True if t is a list with at least one element.
57
58       The following macros can be used for retrieving parts of Erlang  terms.
59       None  of  these do any type checking. Results are undefined if you pass
60       an ETERM* containing the wrong type. For example, passing  a  tuple  to
61       ERL_ATOM_PTR() likely results in garbage.
62
63         char *ERL_ATOM_PTR(t):
64
65
66         char *ERL_ATOM_PTR_UTF8(t):
67           A string representing atom t.
68
69         int ERL_ATOM_SIZE(t):
70
71
72         int ERL_ATOM_SIZE_UTF8(t):
73           The length (in bytes) of atom t.
74
75         void *ERL_BIN_PTR(t):
76           A pointer to the contents of t.
77
78         int ERL_BIN_SIZE(t):
79           The length (in bytes) of binary object t.
80
81         int ERL_INT_VALUE(t):
82           The integer of t.
83
84         unsigned int ERL_INT_UVALUE(t):
85           The unsigned integer value of t.
86
87         double ERL_FLOAT_VALUE(t):
88           The floating point value of t.
89
90         ETERM *ERL_PID_NODE(t):
91
92
93         ETERM *ERL_PID_NODE_UTF8(t):
94           The node in pid t.
95
96         int ERL_PID_NUMBER(t):
97           The sequence number in pid t.
98
99         int ERL_PID_SERIAL(t):
100           The serial number in pid t.
101
102         int ERL_PID_CREATION(t):
103           The creation number in pid t.
104
105         int ERL_PORT_NUMBER(t):
106           The sequence number in port t.
107
108         int ERL_PORT_CREATION(t):
109           The creation number in port t.
110
111         ETERM *ERL_PORT_NODE(t):
112
113
114         ETERM *ERL_PORT_NODE_UTF8(t):
115           The node in port t.
116
117         int ERL_REF_NUMBER(t):
118           The  first part of the reference number in ref t. Use only for com‐
119           patibility.
120
121         int ERL_REF_NUMBERS(t):
122           Pointer to the array of reference numbers in ref t.
123
124         int ERL_REF_LEN(t):
125           The number of used reference numbers in ref t.
126
127         int ERL_REF_CREATION(t):
128           The creation number in ref t.
129
130         int ERL_TUPLE_SIZE(t):
131           The number of elements in tuple t.
132
133         ETERM *ERL_CONS_HEAD(t):
134           The head element of list t.
135
136         ETERM *ERL_CONS_TAIL(t):
137           A list representing the tail elements of list t.
138

EXPORTS

140       ETERM *erl_cons(head, tail)
141
142              Types:
143
144                 ETERM *head;
145                 ETERM *tail;
146
147              Concatenates two Erlang terms, prepending  head  onto  tail  and
148              thereby  creating  a  cons  cell. To make a proper list, tail is
149              always to be a list or an empty list. Notice that NULL is not  a
150              valid list.
151
152                * head is the new term to be added.
153
154                * tail is the existing list to which head is concatenated.
155
156              The function returns a new list.
157
158              ERL_CONS_HEAD(list)  and  ERL_CONS_TAIL(list)  can  be  used  to
159              retrieve  the  head  and  tail   components   from   the   list.
160              erl_hd(list)  and erl_tl(list) do the same thing, but check that
161              the argument really is a list.
162
163              Example:
164
165              ETERM *list,*anAtom,*anInt;
166              anAtom = erl_mk_atom("madonna");
167              anInt  = erl_mk_int(21);
168              list   = erl_mk_empty_list();
169              list   = erl_cons(anAtom, list);
170              list   = erl_cons(anInt, list);
171               ... /* do some work */
172              erl_free_compound(list);
173
174
175       ETERM *erl_copy_term(term)
176
177              Types:
178
179                 ETERM *term;
180
181              Creates and returns a copy of the Erlang term term.
182
183       ETERM *erl_element(position, tuple)
184
185              Types:
186
187                 int position;
188                 ETERM *tuple;
189
190              Extracts a specified element from an Erlang tuple.
191
192                * position specifies which element to retrieve from tuple. The
193                  elements are numbered starting from 1.
194
195                * tuple  is  an  Erlang term containing at least position ele‐
196                  ments.
197
198              Returns a new Erlang term corresponding to  the  requested  ele‐
199              ment, or NULL if position was greater than the arity of tuple.
200
201       ETERM *erl_hd(list)
202
203              Types:
204
205                 ETERM *list;
206
207              Extracts the first element from a list.
208
209              list is an Erlang term containing a list.
210
211              Returns an Erlang term corresponding to the head head element in
212              the list, or a NULL pointer if list was not a list.
213
214       void erl_init(NULL, 0)
215
216              Types:
217
218                 void *NULL;
219                 int 0;
220
221              This function must be called before any of  the  others  in  the
222              Erl_Interface  library  to initialize the library functions. The
223              arguments must be specified as erl_init(NULL,0).
224
225       int erl_iolist_length(list)
226
227              Types:
228
229                 ETERM *list;
230
231              Returns the length of an I/O list.
232
233              list is an Erlang term containing an I/O list.
234
235              Returns the length of list, or -1 if list is not an I/O list.
236
237              For the definition of an I/O list, see erl_iolist_to_binary.
238
239       ETERM *erl_iolist_to_binary(term)
240
241              Types:
242
243                 ETERM *list;
244
245              Converts an I/O list to a binary term.
246
247              list is an Erlang term containing a list.
248
249              Returns an Erlang binary term, or NULL if list was  not  an  I/O
250              list.
251
252              Informally,  an  I/O list is a deep list of characters and bina‐
253              ries that can be sent to an Erlang port. In BNF, an I/O list  is
254              formally defined as follows:
255
256              iolist ::= []
257                      |   Binary
258                      |   [iohead | iolist]
259                      ;
260              iohead ::= Binary
261                      |   Byte (integer in the range [0..255])
262                      |   iolist
263                      ;
264
265
266       char *erl_iolist_to_string(list)
267
268              Types:
269
270                 ETERM *list;
271
272              Converts an I/O list to a NULL-terminated C string.
273
274              list is an Erlang term containing an I/O list. The I/O list must
275              not contain the integer 0, as C strings  may  not  contain  this
276              value except as a terminating marker.
277
278              Returns a pointer to a dynamically allocated buffer containing a
279              string. If list is not an I/O list,  or  if  list  contains  the
280              integer  0,  NULL is returned. It is the caller's responsibility
281              to free the allocated buffer with erl_free().
282
283              For the definition of an I/O list, see erl_iolist_to_binary.
284
285       int erl_length(list)
286
287              Types:
288
289                 ETERM *list;
290
291              Determines the length of a proper list.
292
293              list is an Erlang term containing a proper  list.  In  a  proper
294              list,  all tails except the last point to another list cell, and
295              the last tail points to an empty list.
296
297              Returns -1 if list is not a proper list.
298
299       ETERM *erl_mk_atom(string)
300
301              Types:
302
303                 const char *string;
304
305              Creates an atom.
306
307              string is the sequence of characters that will be used to create
308              the atom.
309
310              Returns an Erlang term containing an atom. Notice that it is the
311              caller's responsibility to ensure that string contains  a  valid
312              name for an atom.
313
314              ERL_ATOM_PTR(atom)  and  ERL_ATOM_PTR_UTF8(atom)  can be used to
315              retrieve  the  atom  name   (as   a   NULL-terminated   string).
316              ERL_ATOM_SIZE(atom)   and  ERL_ATOM_SIZE_UTF8(atom)  return  the
317              length of the atom name.
318
319          Note:
320              The UTF-8 variants were introduced in  Erlang/OTP  R16  and  the
321              string returned by ERL_ATOM_PTR(atom) was not NULL-terminated on
322              older releases.
323
324
325       ETERM *erl_mk_binary(bptr, size)
326
327              Types:
328
329                 char *bptr;
330                 int size;
331
332              Produces an Erlang binary object  from  a  buffer  containing  a
333              sequence of bytes.
334
335                * bptr  is  a  pointer  to a buffer containing data to be con‐
336                  verted.
337
338                * size indicates the length of bptr.
339
340              Returns an Erlang binary object.
341
342              ERL_BIN_PTR(bin)  retrieves  a  pointer  to  the  binary   data.
343              ERL_BIN_SIZE(bin) retrieves the size.
344
345       ETERM *erl_mk_empty_list()
346
347              Creates  and  returns  an empty Erlang list. Notice that NULL is
348              not used to represent an empty list; Use this function instead.
349
350       ETERM *erl_mk_estring(string, len)
351
352              Types:
353
354                 char *string;
355                 int len;
356
357              Creates a list from a sequence of bytes.
358
359                * string is a buffer containing a sequence of bytes. The  buf‐
360                  fer does not need to be NULL-terminated.
361
362                * len is the length of string.
363
364              Returns  an  Erlang  list  object corresponding to the character
365              sequence in string.
366
367       ETERM *erl_mk_float(f)
368
369              Types:
370
371                 double f;
372
373              Creates an Erlang float.
374
375              f is a value to be converted to an Erlang float.
376
377              Returns an Erlang float object with the value specified in f  or
378              NULL if f is not finite.
379
380              ERL_FLOAT_VALUE(t)  can  be  used  to retrieve the value from an
381              Erlang float.
382
383       ETERM *erl_mk_int(n)
384
385              Types:
386
387                 int n;
388
389              Creates an Erlang integer.
390
391              n is a value to be converted to an Erlang integer.
392
393              Returns an Erlang integer object with the value specified in n.
394
395              ERL_INT_VALUE(t) can be used  to  retrieve  the  value  from  an
396              Erlang integer.
397
398       ETERM *erl_mk_list(array, arrsize)
399
400              Types:
401
402                 ETERM **array;
403                 int arrsize;
404
405              Creates  an Erlang list from an array of Erlang terms, such that
406              each element in the list  corresponds  to  one  element  in  the
407              array.
408
409                * array is an array of Erlang terms.
410
411                * arrsize is the number of elements in array.
412
413              The function creates an Erlang list object, whose length arrsize
414              and whose elements are taken from the terms in array.
415
416       ETERM *erl_mk_long_ref(node, n1, n2, n3, creation)
417
418              Types:
419
420                 const char *node;
421                 unsigned int n1, n2, n3;
422                 unsigned int creation;
423
424              Creates an Erlang reference, with 82 bits.
425
426                * node is the name of the C-node.
427
428                * n1,  n2,  and  n3  can   be   seen   as   one   big   number
429                  n1*2^64+n2*2^32+n3,  which is to be chosen uniquely for each
430                  reference created for a given C-node.
431
432                * creation is an arbitrary number.
433
434              Notice that n3 and creation are limited in  precision,  so  only
435              the low 18 and 2 bits of these numbers are used.
436
437              Returns an Erlang reference object.
438
439              ERL_REF_NODE(ref),  ERL_REF_NUMBERS(ref),  ERL_REF_LEN(ref), and
440              ERL_REF_CREATION(ref) can be used to retrieve the values used to
441              create the reference.
442
443       ETERM *erl_mk_pid(node, number, serial, creation)
444
445              Types:
446
447                 const char *node;
448                 unsigned int number;
449                 unsigned int serial;
450                 unsigned int creation;
451
452              Creates  an  Erlang  process identifier (pid). The resulting pid
453              can be used by Erlang processes wishing to communicate with  the
454              C-node.
455
456                * node is the name of the C-node.
457
458                * number,  serial,  and creation are arbitrary numbers. Notice
459                  that these are limited in precision, so only the low 15,  3,
460                  and 2 bits of these numbers are used.
461
462              Returns an Erlang pid object.
463
464              ERL_PID_NODE(pid), ERL_PID_NUMBER(pid), ERL_PID_SERIAL(pid), and
465              ERL_PID_CREATION(pid) can be used to retrieve  the  four  values
466              used to create the pid.
467
468       ETERM *erl_mk_port(node, number, creation)
469
470              Types:
471
472                 const char *node;
473                 unsigned int number;
474                 unsigned int creation;
475
476              Creates an Erlang port identifier.
477
478                * node is the name of the C-node.
479
480                * number and creation are arbitrary numbers. Notice that these
481                  are limited in precision, so only the low 18 and 2  bits  of
482                  these numbers are used.
483
484              Returns an Erlang port object.
485
486              ERL_PORT_NODE(port),  ERL_PORT_NUMBER(port),  and  ERL_PORT_CRE‐
487              ATION can be used to retrieve the three values  used  to  create
488              the port.
489
490       ETERM *erl_mk_ref(node, number, creation)
491
492              Types:
493
494                 const char *node;
495                 unsigned int number;
496                 unsigned int creation;
497
498              Creates  an  old  Erlang  reference,  with  only  18  bits - use
499              erl_mk_long_ref instead.
500
501                * node is the name of the C-node.
502
503                * number is to be chosen uniquely for each  reference  created
504                  for a given C-node.
505
506                * creation is an arbitrary number.
507
508              Notice  that  number  and  creation are limited in precision, so
509              only the low 18 and 2 bits of these numbers are used.
510
511              Returns an Erlang reference object.
512
513              ERL_REF_NODE(ref),   ERL_REF_NUMBER(ref),    and    ERL_REF_CRE‐
514              ATION(ref) can be used to retrieve the three values used to cre‐
515              ate the reference.
516
517       ETERM *erl_mk_string(string)
518
519              Types:
520
521                 char *string;
522
523              Creates a list from a NULL-terminated string.
524
525              string is a NULL-terminated sequence of characters (that is, a C
526              string) from which the list will be created.
527
528              Returns an Erlang list.
529
530       ETERM *erl_mk_tuple(array, arrsize)
531
532              Types:
533
534                 ETERM **array;
535                 int arrsize;
536
537              Creates an Erlang tuple from an array of Erlang terms.
538
539                * array is an array of Erlang terms.
540
541                * arrsize is the number of elements in array.
542
543              The  function  creates  an Erlang tuple, whose arity is size and
544              whose elements are taken from the terms in array.
545
546              To retrieve the size of a tuple, either  use  function  erl_size
547              (which  checks  the  type  of  the  checked term and works for a
548              binary as well as for a tuple) or ERL_TUPLE_SIZE(tuple)  returns
549              the  arity  of  a  tuple. erl_size() does the same thing, but it
550              checks that the argument is  a  tuple.  erl_element(index,tuple)
551              returns  the  element  corresponding  to a given position in the
552              tuple.
553
554       ETERM *erl_mk_uint(n)
555
556              Types:
557
558                 unsigned int n;
559
560              Creates an Erlang unsigned integer.
561
562              n is a value to be converted to an Erlang unsigned integer.
563
564              Returns an Erlang unsigned integer object with the value  speci‐
565              fied in n.
566
567              ERL_INT_UVALUE(t)  can  be  used  to  retrieve the value from an
568              Erlang unsigned integer.
569
570       ETERM *erl_mk_var(name)
571
572              Types:
573
574                 char *name;
575
576              Creates an unbound Erlang variable. The variable  can  later  be
577              bound through pattern matching or assignment.
578
579              name specifies a name for the variable.
580
581              Returns an Erlang variable object with the name name.
582
583       int erl_print_term(stream, term)
584
585              Types:
586
587                 FILE *stream;
588                 ETERM *term;
589
590              Prints the specified Erlang term to the specified output stream.
591
592                * stream indicates where the function is to send its output.
593
594                * term is the Erlang term to print.
595
596              Returns the number of characters written on success, otherwise a
597              negative value.
598
599       void erl_set_compat_rel(release_number)
600
601              Types:
602
603                 unsigned release_number;
604
605              By default, the Erl_Interface library is only guaranteed  to  be
606              compatible  with  other  Erlang/OTP  components  from  the  same
607              release  as  the  Erl_Interface  library  itself.  For  example,
608              Erl_Interface  from  Erlang/OTP  R10  is  not compatible with an
609              Erlang emulator from Erlang/OTP R9 by default.
610
611              A call to erl_set_compat_rel(release_number) sets the Erl_Inter‐
612              face  library  in  compatibility mode of release release_number.
613              Valid range of release_number  is  [7,  current  release].  This
614              makes it possible to communicate with Erlang/OTP components from
615              earlier releases.
616
617          Note:
618              If this function is called, it may only be called once  directly
619              after the call to function erl_init().
620
621
622          Warning:
623              You  may  run  into  trouble if this feature is used carelessly.
624              Always ensure that all communicating components are either  from
625              the  same  Erlang/OTP  release,  or from release X and release Y
626              where all components from release Y are in compatibility mode of
627              release X.
628
629
630       int erl_size(term)
631
632              Types:
633
634                 ETERM *term;
635
636              Returns  either  the  arity  of an Erlang tuple or the number of
637              bytes in an Erlang binary object.
638
639              term is an Erlang tuple or an Erlang binary object.
640
641              Returns the size of term as described above, or -1  if  term  is
642              not one of the two supported types.
643
644       ETERM *erl_tl(list)
645
646              Types:
647
648                 ETERM *list;
649
650              Extracts the tail from a list.
651
652              list is an Erlang term containing a list.
653
654              Returns  an Erlang list corresponding to the original list minus
655              the first element, or NULL pointer if list was not a list.
656
657       ETERM *erl_var_content(term, name)
658
659              Types:
660
661                 ETERM *term;
662                 char *name;
663
664              Returns the contents of the  specified  variable  in  an  Erlang
665              term.
666
667                * term  is  an Erlang term. In order for this function to suc‐
668                  ceed, term must either be an Erlang variable with the speci‐
669                  fied  name, or it must be an Erlang list or tuple containing
670                  a variable with the specified name. Other Erlang types  can‐
671                  not contain variables.
672
673                * name is the name of an Erlang variable.
674
675              Returns  the Erlang object corresponding to the value of name in
676              term. If no variable with the name name is found in term, or  if
677              term is not a valid Erlang term, NULL is returned.
678
679
680
681Ericsson AB                  erl_interface 3.11.3                 erl_eterm(3)
Impressum