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

NAME

6       erl_nif - API functions for an Erlang NIF library.
7

DESCRIPTION

9       A  NIF  library  contains native implementation of some functions of an
10       Erlang module. The native implemented functions (NIFs) are called  like
11       any other functions without any difference to the caller. A NIF library
12       is built as a dynamically linked library file and loaded in runtime  by
13       calling erlang:load_nif/2.
14
15   Warning:
16
17       Use this functionality with extreme care.
18
19       A  native function is executed as a direct extension of the native code
20       of the VM. Execution is not made in a safe environment. The  VM  cannot
21       provide  the same services as provided when executing Erlang code, such
22       as pre-emptive scheduling or memory protection. If the native  function
23       does not behave well, the whole VM will misbehave.
24
25         * A native function that crashes will crash the whole VM.
26
27         * An  erroneously implemented native function can cause a VM internal
28           state inconsistency, which can cause a crash of the VM, or  miscel‐
29           laneous  misbehaviors  of the VM at any point after the call to the
30           native function.
31
32         * A native function doing  lengthy  work  before  returning  degrades
33           responsiveness  of  the  VM,  and  can  cause miscellaneous strange
34           behaviors. Such strange behaviors include, but are not limited  to,
35           extreme  memory  usage,  and bad load balancing between schedulers.
36           Strange behaviors that can occur because of lengthy work  can  also
37           vary between Erlang/OTP releases.
38

EXAMPLE

40       A minimal example of a NIF library can look as follows:
41
42       /* niftest.c */
43       #include <erl_nif.h>
44
45       static ERL_NIF_TERM hello(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[])
46       {
47           return enif_make_string(env, "Hello world!", ERL_NIF_LATIN1);
48       }
49
50       static ErlNifFunc nif_funcs[] =
51       {
52           {"hello", 0, hello}
53       };
54
55       ERL_NIF_INIT(niftest,nif_funcs,NULL,NULL,NULL,NULL)
56
57       The Erlang module can look as follows:
58
59       -module(niftest).
60
61       -export([init/0, hello/0]).
62
63       -on_load(init/0).
64
65       init() ->
66             erlang:load_nif("./niftest", 0).
67
68       hello() ->
69             erlang:nif_error("NIF library not loaded").
70
71       Compile and test can look as follows (on Linux):
72
73       $> gcc -fPIC -shared -o niftest.so niftest.c -I $ERL_ROOT/usr/include/
74       $> erl
75
76       1> c(niftest).
77       {ok,niftest}
78       2> niftest:hello().
79       "Hello world!"
80
81       In  the  example  above the on_load directive is used get function init
82       called automatically when the module is loaded. Function init  in  turn
83       calls  erlang:load_nif/2  which  loads the NIF library and replaces the
84       hello function with its native implementation in C. Once loaded, a  NIF
85       library  is  persistent.  It will not be unloaded until the module code
86       version that it belongs to is purged.
87
88       Each NIF must have an implementation in Erlang to  be  invoked  if  the
89       function  is  called  before  the NIF library is successfully loaded. A
90       typical such stub implementation is to call erlang:nif_error which will
91       raise  an exception. The Erlang function can also be used as a fallback
92       implementation if the NIF library lacks implementation for some  OS  or
93       hardware architecture for example.
94
95   Note:
96       A NIF does not have to be exported, it can be local to the module. How‐
97       ever, unused local stub functions will be optimized away  by  the  com‐
98       piler, causing loading of the NIF library to fail.
99
100
101   Warning:
102       There  is  a  known  limitation  for Erlang fallback functions of NIFs.
103       Avoid functions involved in  traversal  of  binaries  by  matching  and
104       recursion.  If  a NIF is loaded over such function, binary arguments to
105       the NIF may get corrupted and cause VM crash or other misbehavior.
106
107       Example of such bad fallback function:
108
109       skip_until(Byte, <<Byte, Rest/binary>>) ->
110           Rest;
111       skip_until(Byte, <<_, Rest/binary>>) ->
112           skip_until(Byte, Rest).
113
114
115

FUNCTIONALITY

117       All interaction between NIF code and the Erlang runtime system is  per‐
118       formed  by calling NIF API functions. Functions exist for the following
119       functionality:
120
121         Read and write Erlang terms:
122           Any Erlang terms can be passed to a NIF as function  arguments  and
123           be  returned  as  function  return  values. The terms are of C-type
124           ERL_NIF_TERM and can only be read or written using  API  functions.
125           Most functions to read the content of a term are prefixed enif_get_
126           and usually return true (or false) if the term is of  the  expected
127           type  (or  not).  The  functions  to  write  terms are all prefixed
128           enif_make_ and usually return the created ERL_NIF_TERM.  There  are
129           also   some   functions   to   query   terms,   like  enif_is_atom,
130           enif_is_identical, and enif_compare.
131
132           All terms of type ERL_NIF_TERM belong to  an  environment  of  type
133           ErlNifEnv.  The lifetime of a term is controlled by the lifetime of
134           its environment object. All API functions that read or write  terms
135           has  the environment that the term belongs to as the first function
136           argument.
137
138         Binaries:
139           Terms of type binary are accessed with the help of struct type Erl‐
140           NifBinary,  which  contains a pointer (data) to the raw binary data
141           and the length (size) of the data in bytes. Both data and size  are
142           read-only  and are only to be written using calls to API functions.
143           Instances of ErlNifBinary are, however,  always  allocated  by  the
144           user (usually as local variables).
145
146           The  raw  data  pointed  to by data is only mutable after a call to
147           enif_alloc_binary or enif_realloc_binary. All other functions  that
148           operate  on  a binary leave the data as read-only. A mutable binary
149           must in the end either be freed with  enif_release_binary  or  made
150           read-only   by   transferring   it   to   an   Erlang   term   with
151           enif_make_binary. However, it does not have to occur  in  the  same
152           NIF call. Read-only binaries do not have to be released.
153
154           enif_make_new_binary  can  be  used  as  a shortcut to allocate and
155           return a binary in the same NIF call.
156
157           Binaries are sequences of whole bytes. Bitstrings with an arbitrary
158           bit length have no support yet.
159
160         Resource objects:
161           The  use  of  resource  objects is a safe way to return pointers to
162           native data structures from a NIF. A  resource  object  is  only  a
163           block of memory allocated with enif_alloc_resource. A handle ("safe
164           pointer") to this memory block can then be returned  to  Erlang  by
165           the    use    of   enif_make_resource.   The   term   returned   by
166           enif_make_resource is opaque in nature. It can be stored and passed
167           between  processes,  but the only real end usage is to pass it back
168           as an argument to a NIF. The NIF can  then  call  enif_get_resource
169           and  get back a pointer to the memory block, which is guaranteed to
170           still be valid. A resource object is not deallocated until the last
171           handle  term  is  garbage  collected  by the VM and the resource is
172           released  with  enif_release_resource  (not  necessarily  in   that
173           order).
174
175           All  resource  objects  are  created  as instances of some resource
176           type. This makes resources from different  modules  to  be  distin‐
177           guishable.    A    resource    type    is    created   by   calling
178           enif_open_resource_type when a library is loaded. Objects  of  that
179           resource  type  can  then  later be allocated and enif_get_resource
180           verifies that the resource is of the expected type. A resource type
181           can  have  a  user-supplied destructor function, which is automati‐
182           cally called when resources of that type are  released  (by  either
183           the garbage collector or enif_release_resource). Resource types are
184           uniquely identified by a supplied name string and the name  of  the
185           implementing module.
186
187           The  following  is a template example of how to create and return a
188           resource object.
189
190         ERL_NIF_TERM term;
191         MyStruct* obj = enif_alloc_resource(my_resource_type, sizeof(MyStruct));
192
193         /* initialize struct ... */
194
195         term = enif_make_resource(env, obj);
196
197         if (keep_a_reference_of_our_own) {
198             /* store 'obj' in static variable, private data or other resource object */
199         }
200         else {
201             enif_release_resource(obj);
202             /* resource now only owned by "Erlang" */
203         }
204         return term;
205
206           Notice that once enif_make_resource creates the term to  return  to
207           Erlang,  the  code can choose to either keep its own native pointer
208           to the allocated struct and release it later, or release it immedi‐
209           ately  and  rely  only  on  the garbage collector to deallocate the
210           resource object eventually when it collects the term.
211
212           Another use of resource objects is  to  create  binary  terms  with
213           user-defined memory management. enif_make_resource_binary creates a
214           binary term that is connected to a resource object. The  destructor
215           of  the resource is called when the binary is garbage collected, at
216           which time the binary data can be released. An example of this  can
217           be  a  binary  term  consisting  of  data  from a mmap'ed file. The
218           destructor can then do munmap to release the memory region.
219
220           Resource types support upgrade in runtime by allowing a loaded  NIF
221           library  to take over an already existing resource type and by that
222           "inherit" all existing objects of that type. The destructor of  the
223           new  library is thereafter called for the inherited objects and the
224           library with the old destructor function can  be  safely  unloaded.
225           Existing  resource  objects,  of  a  module  that is upgraded, must
226           either be deleted or taken over by the new NIF library. The unload‐
227           ing  of  a  library  is  postponed  as long as there exist resource
228           objects with a destructor function in the library.
229
230         Module upgrade and static data:
231           A loaded NIF library is tied to the  Erlang  module  instance  that
232           loaded it. If the module is upgraded, the new module instance needs
233           to load its own NIF library (or maybe choose not to). The new  mod‐
234           ule  instance  can,  however,  choose  to  load  the exact same NIF
235           library as the old code if it wants to. Sharing the dynamic library
236           means that static data defined by the library is shared as well. To
237           avoid unintentionally shared static data between module  instances,
238           each Erlang module version can keep its own private data. This pri‐
239           vate data can be set when the  NIF  library  is  loaded  and  later
240           retrieved by calling enif_priv_data.
241
242         Threads and concurrency:
243           A  NIF  is thread-safe without any explicit synchronization as long
244           as it acts as a pure function and only  reads  the  supplied  argu‐
245           ments. When you write to a shared state either through static vari‐
246           ables or enif_priv_data, you need to supply your own explicit  syn‐
247           chronization.  This  includes terms in process independent environ‐
248           ments that  are  shared  between  threads.  Resource  objects  also
249           require synchronization if you treat them as mutable.
250
251           The  library  initialization callbacks load and upgrade are thread-
252           safe even for shared state data.
253
254         Version Management:
255           When a NIF library is built, information about the NIF API  version
256           is  compiled  into  the  library. When a NIF library is loaded, the
257           runtime system verifies that the library is of  a  compatible  ver‐
258           sion. erl_nif.h defines the following:
259
260           ERL_NIF_MAJOR_VERSION:
261             Incremented when NIF library incompatible changes are made to the
262             Erlang runtime system. Normally it suffices to recompile the  NIF
263             library  when  the ERL_NIF_MAJOR_VERSION has changed, but it can,
264             under  rare  circumstances,  mean  that  NIF  libraries  must  be
265             slightly modified. If so, this will of course be documented.
266
267           ERL_NIF_MINOR_VERSION:
268             Incremented  when new features are added. The runtime system uses
269             the minor version to determine what features to use.
270
271           The runtime system normally refuses to load a NIF  library  if  the
272           major  versions  differ, or if the major versions are equal and the
273           minor version used by the NIF library is greater than the one  used
274           by  the runtime system. Old NIF libraries with lower major versions
275           are, however, allowed after a bump of the major  version  during  a
276           transition period of two major releases. Such old NIF libraries can
277           however fail if deprecated features are used.
278
279         Time Measurement:
280           Support for time measurement in NIF libraries:
281
282           * ErlNifTime
283
284           * ErlNifTimeUnit
285
286           * enif_monotonic_time()
287
288           * enif_time_offset()
289
290           * enif_convert_time_unit()
291
292         I/O Queues:
293           The Erlang nif library contains function for  easily  working  with
294           I/O  vectors  as used by the unix system call writev. The I/O Queue
295           is not thread safe, so some other synchronization mechanism has  to
296           be used.
297
298           * SysIOVec
299
300           * ErlNifIOVec
301
302           * enif_ioq_create()
303
304           * enif_ioq_destroy()
305
306           * enif_ioq_enq_binary()
307
308           * enif_ioq_enqv()
309
310           * enif_ioq_deq()
311
312           * enif_ioq_peek()
313
314           * enif_ioq_peek_head()
315
316           * enif_inspect_iovec()
317
318           * enif_free_iovec()
319
320           Typical usage when writing to a file descriptor looks like this:
321
322         int writeiovec(ErlNifEnv *env, ERL_NIF_TERM term, ERL_NIF_TERM *tail,
323                        ErlNifIOQueue *q, int fd) {
324
325             ErlNifIOVec vec, *iovec = &vec;
326             SysIOVec *sysiovec;
327             int saved_errno;
328             int iovcnt, n;
329
330             if (!enif_inspect_iovec(env, 64, term, tail, &iovec))
331                 return -2;
332
333             if (enif_ioq_size(q) > 0) {
334                 /* If the I/O queue contains data we enqueue the iovec and
335                    then peek the data to write out of the queue. */
336                 if (!enif_ioq_enqv(q, iovec, 0))
337                     return -3;
338
339                 sysiovec = enif_ioq_peek(q, &iovcnt);
340             } else {
341                 /* If the I/O queue is empty we skip the trip through it. */
342                 iovcnt = iovec->iovcnt;
343                 sysiovec = iovec->iov;
344             }
345
346             /* Attempt to write the data */
347             n = writev(fd, sysiovec, iovcnt);
348             saved_errno = errno;
349
350             if (enif_ioq_size(q) == 0) {
351                 /* If the I/O queue was initially empty we enqueue any
352                    remaining data into the queue for writing later. */
353                 if (n >= 0 && !enif_ioq_enqv(q, iovec, n))
354                     return -3;
355             } else {
356                 /* Dequeue any data that was written from the queue. */
357                 if (n > 0 && !enif_ioq_deq(q, n, NULL))
358                     return -4;
359             }
360
361             /* return n, which is either number of bytes written or -1 if
362                some error happened */
363             errno = saved_errno;
364             return n;
365         }
366
367         Long-running NIFs:
368           As  mentioned  in  the warning text at the beginning of this manual
369           page, it is of vital importance that a native function returns rel‐
370           atively  fast.  It  is difficult to give an exact maximum amount of
371           time that a native function is allowed to work, but usually a well-
372           behaving  native  function is to return to its caller within 1 mil‐
373           lisecond. This can be achieved using different approaches.  If  you
374           have  full control over the code to execute in the native function,
375           the best approach is to divide the work  into  multiple  chunks  of
376           work and call the native function multiple times. This is, however,
377           not  always  possible,  for  example   when   calling   third-party
378           libraries.
379
380           The  enif_consume_timeslice()  function  can  be used to inform the
381           runtime system about the length of the NIF call.  It  is  typically
382           always to be used unless the NIF executes very fast.
383
384           If  the NIF call is too lengthy, this must be handled in one of the
385           following ways to avoid  degraded  responsiveness,  scheduler  load
386           balancing problems, and other strange behaviors:
387
388           Yielding NIF:
389             If  the  functionality of a long-running NIF can be split so that
390             its work can be achieved through a series of shorter  NIF  calls,
391             the application has two options:
392
393             * Make that series of NIF calls from the Erlang level.
394
395             * Call  a  NIF  that  first  performs  a  chunk of the work, then
396               invokes the enif_schedule_nif function to schedule another  NIF
397               call  to  perform  the  next chunk. The final call scheduled in
398               this manner can then return the overall result.
399
400             Breaking up a long-running function in this manner enables the VM
401             to regain control between calls to the NIFs.
402
403             This  approach  is  always  preferred over the other alternatives
404             described below. This both from a performance perspective  and  a
405             system characteristics perspective.
406
407           Threaded NIF:
408             This  is  accomplished  by dispatching the work to another thread
409             managed by the NIF library, return from the NIF, and wait for the
410             result. The thread can send the result back to the Erlang process
411             using enif_send. Information about thread primitives is  provided
412             below.
413
414           Dirty NIF:
415
416
417       Note:
418           Dirty NIF support is available only when the emulator is configured
419           with dirty scheduler support. As of ERTS version 9.0, dirty  sched‐
420           uler  support  is enabled by default on the runtime system with SMP
421           support. The Erlang runtime without SMP support  does  not  support
422           dirty  schedulers  even when the dirty scheduler support is explic‐
423           itly enabled. To check at runtime for the presence of dirty  sched‐
424           uler threads, code can use the enif_system_info() API function.
425
426
427             A NIF that cannot be split and cannot execute in a millisecond or
428             less is called a "dirty NIF", as it performs work that the  ordi‐
429             nary  schedulers  of  the  Erlang  runtime  system  cannot handle
430             cleanly. Applications that make use of such functions must  indi‐
431             cate  to  the runtime that the functions are dirty so they can be
432             handled specially. This is handled by executing dirty jobs  on  a
433             separate  set  of schedulers called dirty schedulers. A dirty NIF
434             executing on a dirty scheduler does not have  the  same  duration
435             restriction as a normal NIF.
436
437             It  is  important to classify the dirty job correct. An I/O bound
438             job should be classified as such, and a CPU bound job  should  be
439             classified  as such. If you should classify CPU bound jobs as I/O
440             bound jobs, dirty I/O schedulers  might  starve  ordinary  sched‐
441             ulers.  I/O  bound  jobs are expected to either block waiting for
442             I/O, and/or spend a limited amount of time moving data.
443
444             To schedule a dirty NIF for execution, the  application  has  two
445             options:
446
447             * Set  the  appropriate flags value for the dirty NIF in its Erl‐
448               NifFunc entry.
449
450             * Call enif_schedule_nif, pass to it a pointer to the  dirty  NIF
451               to  be  executed,  and  indicate with argument flags whether it
452               expects the operation to be CPU-bound or I/O-bound.
453
454             A job that alternates between I/O bound  and  CPU  bound  can  be
455             reclassified  and  rescheduled using enif_schedule_nif so that it
456             executes on the correct type of dirty scheduler at all times. For
457             more information see the documentation of the erl(1) command line
458             arguments +SDcpu, and +SDio.
459
460             While a process executes a dirty NIF, some operations that commu‐
461             nicate  with it can take a very long time to complete. Suspend or
462             garbage collection of a process executing a dirty NIF  cannot  be
463             done  until  the  dirty  NIF  has returned. Thus, other processes
464             waiting for such operations to complete might have to wait for  a
465             very  long  time.  Blocking  multi-scheduling,  that  is, calling
466             erlang:system_flag(multi_scheduling, block), can also take a very
467             long  time  to complete. This is because all ongoing dirty opera‐
468             tions on all dirty schedulers  must  complete  before  the  block
469             operation can complete.
470
471             Many  operations  communicating  with a process executing a dirty
472             NIF can, however, complete while it executes the dirty  NIF.  For
473             example,  retrieving  information  about it through process_info,
474             setting its group leader, register/unregister its  name,  and  so
475             on.
476
477             Termination  of  a process executing a dirty NIF can only be com‐
478             pleted up to a certain point while it executes the dirty NIF. All
479             Erlang resources, such as its registered name and its ETS tables,
480             are released. All links and monitors are triggered. The execution
481             of  the NIF is, however, not stopped. The NIF can safely continue
482             execution, allocate heap memory, and so on, but it is  of  course
483             better  to  stop executing as soon as possible. The NIF can check
484             whether  a  current   process   is   alive   using   enif_is_cur‐
485             rent_process_alive.    Communication    using    enif_send    and
486             enif_port_command is also dropped when the sending process is not
487             alive.  Deallocation  of  certain  internal  resources,  such  as
488             process heap and process control  block,  is  delayed  until  the
489             dirty NIF has completed.
490

INITIALIZATION

492         ERL_NIF_INIT(MODULE,   ErlNifFunc   funcs[],   load,  NULL,  upgrade,
493         unload):
494           This is the magic macro to initialize a NIF library. It  is  to  be
495           evaluated in global file scope.
496
497           MODULE  is  the  name of the Erlang module as an identifier without
498           string quotations. It is stringified by the macro.
499
500           funcs is a static array of function descriptors for all the  imple‐
501           mented NIFs in this library.
502
503           load,  upgrade and unload are pointers to functions. One of load or
504           upgrade is called to initialize the library. unload  is  called  to
505           release the library. All are described individually below.
506
507           The  fourth  argument  NULL is ignored. It was earlier used for the
508           deprecated reload callback which is no longer supported  since  OTP
509           20.
510
511           If  compiling  a  NIF for static inclusion through --enable-static-
512           nifs, you must define  STATIC_ERLANG_NIF  before  the  ERL_NIF_INIT
513           declaration.
514
515         int  (*load)(ErlNifEnv*  caller_env,  void**  priv_data, ERL_NIF_TERM
516         load_info):
517           load is called when the NIF library is  loaded  and  no  previously
518           loaded library exists for this module.
519
520           *priv_data  can be set to point to some private data if the library
521           needs to keep a state between  NIF  calls.  enif_priv_data  returns
522           this  pointer.  *priv_data  is  initialized  to  NULL  when load is
523           called.
524
525           load_info is the second argument to erlang:load_nif/2.
526
527           The library fails to load if load returns anything  other  than  0.
528           load can be NULL if initialization is not needed.
529
530         int   (*upgrade)(ErlNifEnv*   caller_env,  void**  priv_data,  void**
531         old_priv_data, ERL_NIF_TERM load_info):
532           upgrade is called when the NIF library is loaded and there  is  old
533           code of this module with a loaded NIF library.
534
535           Works  as  load,  except  that  *old_priv_data already contains the
536           value set by the last call to load or upgrade for  the  old  module
537           code.  *priv_data is initialized to NULL when upgrade is called. It
538           is allowed to write to both *priv_data and *old_priv_data.
539
540           The library fails to load if upgrade returns anything other than  0
541           or if upgrade is NULL.
542
543         void (*unload)(ErlNifEnv* caller_env, void* priv_data):
544           unload  is called when the module code that the NIF library belongs
545           to is purged as old. New code of the same module  may  or  may  not
546           exist.
547

DATA TYPES

549         ERL_NIF_TERM:
550           Variables  of  type ERL_NIF_TERM can refer to any Erlang term. This
551           is an opaque type and values of it can only by used either as argu‐
552           ments  to  API  functions  or  as  return  values  from  NIFs.  All
553           ERL_NIF_TERMs belong to an environment (ErlNifEnv). A  term  cannot
554           be  destructed  individually,  it is valid until its environment is
555           destructed.
556
557         ErlNifEnv:
558           ErlNifEnv represents an environment that can host Erlang terms. All
559           terms  in  an  environment  are valid as long as the environment is
560           valid. ErlNifEnv is an opaque type; pointers  to  it  can  only  be
561           passed on to API functions. Three types of environments exist:
562
563           Process bound environment:
564             Passed  as the first argument to all NIFs. All function arguments
565             passed to a NIF belong to that environment. The return value from
566             a NIF must also be a term belonging to the same environment.
567
568             A  process bound environment contains transient information about
569             the calling Erlang process. The environment is only valid in  the
570             thread  where  it was supplied as argument until the NIF returns.
571             It is thus useless and dangerous to  store  pointers  to  process
572             bound environments between NIF calls.
573
574           Callback environment:
575             Passed  as  the  first argument to all the non-NIF callback func‐
576             tions (load, upgrade, unload, dtor, down and stop). Works like  a
577             process  bound  environment  but  with a temporary pseudo process
578             that "terminates" when the callback has returned.  Terms  may  be
579             created in this environment but they will only be accessible dur‐
580             ing the callback.
581
582           Process independent environment:
583             Created by calling enif_alloc_env. This environment can  be  used
584             to  store  terms  between  NIF  calls  and  to  send  terms  with
585             enif_send. A process independent environment with all  its  terms
586             is valid until you explicitly invalidate it with enif_free_env or
587             enif_send.
588
589           All contained terms of a list/tuple/map must  belong  to  the  same
590           environment  as  the  list/tuple/map  itself.  Terms  can be copied
591           between environments with enif_make_copy.
592
593         ErlNifFunc:
594
595
596         typedef struct {
597             const char* name;
598             unsigned arity;
599             ERL_NIF_TERM (*fptr)(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]);
600             unsigned flags;
601         } ErlNifFunc;
602
603           Describes a NIF by its name, arity, and implementation.
604
605           fptr:
606             A pointer to the function that implements the NIF.
607
608           argv:
609             Contains the function arguments passed to the NIF.
610
611           argc:
612             The array length, that is, the  function  arity.  argv[N-1]  thus
613             denotes  the  Nth  argument  to the NIF. Notice that the argument
614             argc allows for the same C function to implement  several  Erlang
615             functions with different arity (but probably with the same name).
616
617           flags:
618             Is 0 for a regular NIF (and so its value can be omitted for stat‐
619             ically initialized ErlNifFunc instances).
620
621             flags can be used to indicate that the NIF is a dirty NIF that is
622             to be executed on a dirty scheduler thread.
623
624             If  the dirty NIF is expected to be CPU-bound, its flags field is
625             to     be     set     to      ERL_NIF_DIRTY_JOB_CPU_BOUND      or
626             ERL_NIF_DIRTY_JOB_IO_BOUND.
627
628       Note:
629           If  one of the ERL_NIF_DIRTY_JOB_*_BOUND flags is set, and the run‐
630           time system has no support for dirty schedulers, the runtime system
631           refuses to load the NIF library.
632
633
634         ErlNifBinary:
635
636
637         typedef struct {
638             size_t size;
639             unsigned char* data;
640         } ErlNifBinary;
641
642           ErlNifBinary  contains  transient  information  about  an inspected
643           binary term. data is a pointer to a buffer of size bytes  with  the
644           raw content of the binary.
645
646           Notice  that  ErlNifBinary  is  a semi-opaque type and you are only
647           allowed to read fields size and data.
648
649         ErlNifBinaryToTerm:
650           An  enumeration  of  the  options  that   can   be   specified   to
651           enif_binary_to_term. For default behavior, use value 0.
652
653           When   receiving   data   from   untrusted   sources,   use  option
654           ERL_NIF_BIN2TERM_SAFE.
655
656         ErlNifMonitor:
657           This is an opaque data type that identifies a monitor.
658
659           The nif writer is to provide the memory  for  storing  the  monitor
660           when  calling  enif_monitor_process. The address of the data is not
661           stored by the runtime system, so ErlNifMonitor can be used  as  any
662           other  data,  it  can be copied, moved in memory, forgotten, and so
663           on. To compare two monitors, enif_compare_monitors must be used.
664
665         ErlNifPid:
666           A process identifier (pid). In contrast to pid terms (instances  of
667           ERL_NIF_TERM),  ErlNifPids  are self-contained and not bound to any
668           environment. ErlNifPid is an opaque type. It can be  copied,  moved
669           in memory, forgotten, and so on.
670
671         ErlNifPort:
672           A  port  identifier.  In  contrast  to  port ID terms (instances of
673           ERL_NIF_TERM), ErlNifPorts are self-contained and not bound to  any
674           environment.  ErlNifPort is an opaque type. It can be copied, moved
675           in memory, forgotten, and so on.
676
677         ErlNifResourceType:
678           Each instance of ErlNifResourceType represents a class  of  memory-
679           managed  resource  objects  that  can  be  garbage  collected. Each
680           resource type has a unique name and a destructor function  that  is
681           called when objects of its type are released.
682
683         ErlNifResourceTypeInit:
684
685
686         typedef struct {
687             ErlNifResourceDtor* dtor;
688             ErlNifResourceStop* stop;
689             ErlNifResourceDown* down;
690         } ErlNifResourceTypeInit;
691
692           Initialization structure read by  enif_open_resource_type_x.
693
694         ErlNifResourceDtor:
695
696
697         typedef void ErlNifResourceDtor(ErlNifEnv* caller_env, void* obj);
698
699           The function prototype of a resource destructor function.
700
701           The obj argument is a pointer to the resource. The only allowed use
702           for the resource in the destructor is to access its user  data  one
703           final  time.  The  destructor is guaranteed to be the last callback
704           before the resource is deallocated.
705
706         ErlNifResourceDown:
707
708
709         typedef void ErlNifResourceDown(ErlNifEnv* caller_env, void* obj, ErlNifPid* pid, ErlNifMonitor* mon);
710
711           The function prototype of a resource down function, called  on  the
712           behalf  of   enif_monitor_process.  obj is the resource, pid is the
713           identity of the monitored process that is exiting, and mon  is  the
714           identity of the monitor.
715
716         ErlNifResourceStop:
717
718
719         typedef void ErlNifResourceStop(ErlNifEnv* caller_env, void* obj, ErlNifEvent event, int is_direct_call);
720
721           The  function  prototype of a resource stop function, called on the
722           behalf of  enif_select. obj is the resource,  event  is  OS  event,
723           is_direct_call   is   true  if  the  call  is  made  directly  from
724           enif_select or false if it is a scheduled  call  (potentially  from
725           another thread).
726
727         ErlNifCharEncoding:
728
729
730         typedef enum {
731             ERL_NIF_LATIN1
732         }ErlNifCharEncoding;
733
734           The  character  encoding  used  in strings and atoms. The only sup‐
735           ported encoding is ERL_NIF_LATIN1 for ISO Latin-1 (8-bit ASCII).
736
737         ErlNifSysInfo:
738           Used by enif_system_info to return information  about  the  runtime
739           system. Contains the same content as ErlDrvSysInfo.
740
741         ErlNifSInt64:
742           A native signed 64-bit integer type.
743
744         ErlNifUInt64:
745           A native unsigned 64-bit integer type.
746
747         ErlNifTime:
748           A signed 64-bit integer type for representation of time.
749
750         ErlNifTimeUnit:
751           An enumeration of time units supported by the NIF API:
752
753           ERL_NIF_SEC:
754             Seconds
755
756           ERL_NIF_MSEC:
757             Milliseconds
758
759           ERL_NIF_USEC:
760             Microseconds
761
762           ERL_NIF_NSEC:
763             Nanoseconds
764
765         ErlNifUniqueInteger:
766           An  enumeration  of  the  properties  that  can  be  requested from
767           enif_make_unique_integer. For default properties, use value 0.
768
769           ERL_NIF_UNIQUE_POSITIVE:
770             Return only positive integers.
771
772           ERL_NIF_UNIQUE_MONOTONIC:
773             Return only  strictly  monotonically  increasing  integer  corre‐
774             sponding to creation time.
775
776         ErlNifHash:
777           An  enumeration  of  the supported hash types that can be generated
778           using enif_hash.
779
780           ERL_NIF_INTERNAL_HASH:
781             Non-portable hash function that only guarantees the same hash for
782             the same term within one Erlang VM instance.
783
784             It   takes   32-bit  salt  values  and  generates  hashes  within
785             0..2^32-1.
786
787           ERL_NIF_PHASH2:
788             Portable hash function that gives the  same  hash  for  the  same
789             Erlang term regardless of machine architecture and ERTS version.
790
791             It ignores salt values and generates hashes within 0..2^27-1.
792
793             Slower    than    ERL_NIF_INTERNAL_HASH.    It   corresponds   to
794             erlang:phash2/1.
795
796         SysIOVec:
797           A system I/O vector, as used by  writev  on  Unix  and  WSASend  on
798           Win32. It is used in ErlNifIOVec and by enif_ioq_peek.
799
800         ErlNifIOVec:
801
802
803         typedef struct {
804           int iovcnt;
805           size_t size;
806           SysIOVec* iov;
807         } ErlNifIOVec;
808
809           An  I/O vector containing iovcnt SysIOVecs pointing to the data. It
810           is used by enif_inspect_iovec and enif_ioq_enqv.
811
812         ErlNifIOQueueOpts:
813            Options to configure a ErlNifIOQueue.
814
815           ERL_NIF_IOQ_NORMAL:
816             Create a normal I/O Queue
817

EXPORTS

819       void *enif_alloc(size_t size)
820
821              Allocates memory of size bytes.
822
823              Returns NULL if the allocation fails.
824
825              The returned pointer is suitably aligned for any  built-in  type
826              that fit in the allocated memory.
827
828       int enif_alloc_binary(size_t size, ErlNifBinary* bin)
829
830              Allocates  a  new  binary  of  size  size bytes. Initializes the
831              structure pointed to by bin to refer to  the  allocated  binary.
832              The  binary  must  either  be released by enif_release_binary or
833              ownership transferred to an Erlang term  with  enif_make_binary.
834              An  allocated  (and  owned) ErlNifBinary can be kept between NIF
835              calls.
836
837              If you do not need to reallocate or keep the data  alive  across
838              NIF  calls,  consider  using  enif_make_new_binary instead as it
839              will allocate small binaries on the process heap when possible.
840
841              Returns true on success, or false if allocation fails.
842
843       ErlNifEnv *enif_alloc_env()
844
845              Allocates a new process independent environment. The environment
846              can  be  used  to  hold terms that are not bound to any process.
847              Such terms can later be copied to  a  process  environment  with
848              enif_make_copy  or  be  sent  to  a  process  as  a message with
849              enif_send.
850
851              Returns pointer to the new environment.
852
853       void *enif_alloc_resource(ErlNifResourceType*
854               type, unsigned size)
855
856              Allocates a memory-managed resource object of type type and size
857              size bytes.
858
859       size_t enif_binary_to_term(ErlNifEnv *env,
860               const unsigned char* data, size_t size, ERL_NIF_TERM *term,
861               ErlNifBinaryToTerm opts)
862
863              Creates a term that is the result of decoding the binary data at
864              data, which must be encoded according  to  the  Erlang  external
865              term  format.  No more than size bytes are read from data. Argu‐
866              ment   opts   corresponds   to   the    second    argument    to
867              erlang:binary_to_term/2    and    must    be    either    0   or
868              ERL_NIF_BIN2TERM_SAFE.
869
870              On success, stores the resulting term at *term and  returns  the
871              number  of bytes read. Returns 0 if decoding fails or if opts is
872              invalid.
873
874              See  also   ErlNifBinaryToTerm,   erlang:binary_to_term/2,   and
875              enif_term_to_binary.
876
877       void enif_clear_env(ErlNifEnv* env)
878
879              Frees  all  terms in an environment and clears it for reuse. The
880              environment must have been allocated with enif_alloc_env.
881
882       int enif_compare(ERL_NIF_TERM lhs, ERL_NIF_TERM rhs)
883
884              Returns an integer < 0 if lhs < rhs, 0 if lhs = rhs, and > 0  if
885              lhs  >  rhs.  Corresponds to the Erlang operators ==, /=, =<, <,
886              >=, and > (but not =:= or =/=).
887
888       int enif_compare_monitors(const ErlNifMonitor
889               *monitor1, const ErlNifMonitor *monitor2)
890
891              Compares two ErlNifMonitors. Can also  be  used  to  imply  some
892              artificial order on monitors, for whatever reason.
893
894              Returns  0 if monitor1 and monitor2 are equal, < 0 if monitor1 <
895              monitor2, and > 0 if monitor1 > monitor2.
896
897       int enif_compare_pids(const ErlNifPid *pid1, const ErlNifPid *pid2)
898
899
900              Compares two ErlNifPids according to term order.
901
902              Returns 0 if pid1 and pid2 are equal, < 0 if pid1 < pid2, and  >
903              0 if pid1 > pid2.
904
905       void enif_cond_broadcast(ErlNifCond *cnd)
906
907              Same as erl_drv_cond_broadcast.
908
909       ErlNifCond *enif_cond_create(char *name)
910
911              Same as erl_drv_cond_create.
912
913       void enif_cond_destroy(ErlNifCond *cnd)
914
915              Same as erl_drv_cond_destroy.
916
917       char*enif_cond_name(ErlNifCond* cnd)
918
919              Same as erl_drv_cond_name.
920
921       void enif_cond_signal(ErlNifCond *cnd)
922
923              Same as erl_drv_cond_signal.
924
925       void enif_cond_wait(ErlNifCond *cnd, ErlNifMutex *mtx)
926
927              Same as erl_drv_cond_wait.
928
929       int enif_consume_timeslice(ErlNifEnv *env, int percent)
930
931              Gives the runtime system a hint about how much CPU time the cur‐
932              rent NIF call has consumed since the last  hint,  or  since  the
933              start  of  the  NIF  if no previous hint has been specified. The
934              time is specified as a percent of the timeslice that  a  process
935              is  allowed  to execute Erlang code until it can be suspended to
936              give time for other runnable processes. The scheduling timeslice
937              is not an exact entity, but can usually be approximated to about
938              1 millisecond.
939
940              Notice that it is up to the runtime system to determine  if  and
941              how  to  use this information. Implementations on some platforms
942              can use other means to determine consumed CPU time. Lengthy NIFs
943              should regardless of this frequently call enif_consume_timeslice
944              to determine if it is allowed to continue execution.
945
946              Argument percent must be an integer  between  1  and  100.  This
947              function  must  only  be  called  from a NIF-calling thread, and
948              argument env must be the environment of the calling process.
949
950              Returns 1 if the timeslice is exhausted, otherwise 0.  If  1  is
951              returned,  the NIF is to return as soon as possible in order for
952              the process to yield.
953
954              This function is provided to better support co-operative  sched‐
955              uling, improve system responsiveness, and make it easier to pre‐
956              vent misbehaviors of the VM because  of  a  NIF  monopolizing  a
957              scheduler  thread.  It can be used to divide  length work into a
958              number of repeated NIF calls without the need to create threads.
959
960              See also the warning text at the beginning of this manual page.
961
962       ErlNifTime enif_convert_time_unit(ErlNifTime
963               val, ErlNifTimeUnit from, ErlNifTimeUnit to)
964
965              Converts the val value of time unit from  to  the  corresponding
966              value  of  time  unit  to. The result is rounded using the floor
967              function.
968
969                val:
970                  Value to convert time unit for.
971
972                from:
973                  Time unit of val.
974
975                to:
976                  Time unit of returned value.
977
978              Returns ERL_NIF_TIME_ERROR if called with an invalid  time  unit
979              argument.
980
981              See also ErlNifTime and ErlNifTimeUnit.
982
983       ERL_NIF_TERM enif_cpu_time(ErlNifEnv *)
984
985              Returns  the  CPU time in the same format as erlang:timestamp().
986              The CPU time is the time the current logical CPU has spent  exe‐
987              cuting  since  some  arbitrary point in the past. If the OS does
988              not  support  fetching   this   value,   enif_cpu_time   invokes
989              enif_make_badarg.
990
991       int enif_demonitor_process(ErlNifEnv* caller_env,
992             void* obj, const ErlNifMonitor* mon)
993
994              Cancels  a  monitor  created  earlier with enif_monitor_process.
995              Argument obj is a pointer to the resource  holding  the  monitor
996              and *mon identifies the monitor.
997
998              Argument  caller_env  is  the  environment of the calling thread
999              (process bound or callback environment) or NULL if calling  from
1000              a custom thread not spawned by ERTS.
1001
1002              Returns  0  if  the  monitor  was  successfully  identified  and
1003              removed. Returns a non-zero value if the monitor  could  not  be
1004              identified, which means it was either
1005
1006                * never created for this resource
1007
1008                * already cancelled
1009
1010                * already triggered
1011
1012                * just about to be triggered by a concurrent thread
1013
1014              This  function  is  only  thread-safe when the emulator with SMP
1015              support is used. It can only be used in a non-SMP emulator  from
1016              a NIF-calling thread.
1017
1018       int enif_equal_tids(ErlNifTid tid1, ErlNifTid tid2)
1019
1020              Same as erl_drv_equal_tids.
1021
1022       int enif_fprintf(FILE *stream, const char *format, ...)
1023
1024              Similar  to  fprintf  but  this format string also accepts "%T",
1025              which formats Erlang terms of type ERL_NIF_TERM.
1026
1027              This function is primarily intended for debugging purpose. It is
1028              not  recommended to print very large terms with %T. The function
1029              may change errno, even if successful.
1030
1031       void enif_free(void* ptr)
1032
1033              Frees memory allocated by enif_alloc.
1034
1035       void enif_free_env(ErlNifEnv* env)
1036
1037              Frees an environment allocated with  enif_alloc_env.  All  terms
1038              created in the environment are freed as well.
1039
1040       void enif_free_iovec(ErlNifIOVec* iov)
1041
1042              Frees  an  io  vector  returned from enif_inspect_iovec. This is
1043              needed   only   if   a   NULL   environment   is    passed    to
1044              enif_inspect_iovec.
1045
1046              ErlNifIOVec *iovec = NULL;
1047              size_t max_elements = 128;
1048              ERL_NIF_TERM tail;
1049              if (!enif_inspect_iovec(NULL, max_elements, term, &tail, &iovec))
1050                return 0;
1051
1052              // Do things with the iovec
1053
1054              /* Free the iovector, possibly in another thread or nif function call */
1055              enif_free_iovec(iovec);
1056
1057       int enif_get_atom(ErlNifEnv* env, ERL_NIF_TERM
1058               term, char* buf, unsigned size, ErlNifCharEncoding encode)
1059
1060              Writes  a NULL-terminated string in the buffer pointed to by buf
1061              of size size, consisting of the  string  representation  of  the
1062              atom term with encoding encode.
1063
1064              Returns  the number of bytes written (including terminating NULL
1065              character) or 0 if term is not an atom with  maximum  length  of
1066              size-1.
1067
1068       int enif_get_atom_length(ErlNifEnv* env,
1069               ERL_NIF_TERM term, unsigned* len, ErlNifCharEncoding encode)
1070
1071              Sets  *len  to the length (number of bytes excluding terminating
1072              NULL character) of the atom term with encoding encode.
1073
1074              Returns true on success, or false if term is not an atom.
1075
1076       int enif_get_double(ErlNifEnv* env,
1077               ERL_NIF_TERM term, double* dp)
1078
1079              Sets *dp to the floating-point value of term.
1080
1081              Returns true on success, or false if term is not a float.
1082
1083       int enif_get_int(ErlNifEnv* env, ERL_NIF_TERM
1084               term, int* ip)
1085
1086              Sets *ip to the integer value of term.
1087
1088              Returns true on success, or false if term is not an  integer  or
1089              is outside the bounds of type int.
1090
1091       int enif_get_int64(ErlNifEnv* env, ERL_NIF_TERM
1092               term, ErlNifSInt64* ip)
1093
1094              Sets *ip to the integer value of term.
1095
1096              Returns  true  on success, or false if term is not an integer or
1097              is outside the bounds of a signed 64-bit integer.
1098
1099       int enif_get_local_pid(ErlNifEnv* env,
1100               ERL_NIF_TERM term, ErlNifPid* pid)
1101
1102              If term is the pid of a node local process, this  function  ini‐
1103              tializes  the pid variable *pid from it and returns true. Other‐
1104              wise returns false. No check is done to see if  the  process  is
1105              alive.
1106
1107          Note:
1108              enif_get_local_pid  will  return  false  if argument term is the
1109              atom undefined.
1110
1111
1112       int enif_get_local_port(ErlNifEnv* env,
1113               ERL_NIF_TERM term, ErlNifPort* port_id)
1114
1115              If term identifies a node local port, this function  initializes
1116              the  port  variable *port_id from it and returns true. Otherwise
1117              returns false. No check is done to see if the port is alive.
1118
1119       int enif_get_list_cell(ErlNifEnv* env,
1120               ERL_NIF_TERM list, ERL_NIF_TERM* head, ERL_NIF_TERM* tail)
1121
1122              Sets *head and *tail from list list.
1123
1124              Returns true on success, or false if it is not  a  list  or  the
1125              list is empty.
1126
1127       int enif_get_list_length(ErlNifEnv* env,
1128               ERL_NIF_TERM term, unsigned* len)
1129
1130              Sets *len to the length of list term.
1131
1132              Returns true on success, or false if term is not a proper list.
1133
1134       int enif_get_long(ErlNifEnv* env, ERL_NIF_TERM
1135               term, long int* ip)
1136
1137              Sets *ip to the long integer value of term.
1138
1139              Returns  true  on success, or false if term is not an integer or
1140              is outside the bounds of type long int.
1141
1142       int enif_get_map_size(ErlNifEnv* env,
1143               ERL_NIF_TERM term, size_t *size)
1144
1145              Sets *size to the number of key-value pairs in the map term.
1146
1147              Returns true on success, or false if term is not a map.
1148
1149       int enif_get_map_value(ErlNifEnv* env,
1150               ERL_NIF_TERM map, ERL_NIF_TERM key, ERL_NIF_TERM* value)
1151
1152              Sets *value to the value associated with key in the map map.
1153
1154              Returns true on success, or false if map is not a map or if  map
1155              does not contain key.
1156
1157       int enif_get_resource(ErlNifEnv* env,
1158               ERL_NIF_TERM term, ErlNifResourceType* type, void** objp)
1159
1160              Sets *objp to point to the resource object referred to by term.
1161
1162              Returns  true  on success, or false if term is not a handle to a
1163              resource object of type type.
1164
1165              enif_get_resource does not  add  a  reference  to  the  resource
1166              object.  However, the pointer received in *objp is guaranteed to
1167              be valid at least as long as the resource handle term is valid.
1168
1169       int enif_get_string(ErlNifEnv* env,
1170               ERL_NIF_TERM list, char* buf, unsigned size,
1171               ErlNifCharEncoding encode)
1172
1173              Writes a NULL-terminated string in the buffer pointed to by  buf
1174              with size size, consisting of the characters in the string list.
1175              The characters are written using encoding encode.
1176
1177              Returns one of the following:
1178
1179                * The number of  bytes  written  (including  terminating  NULL
1180                  character)
1181
1182                * -size if the string was truncated because of buffer space
1183
1184                * 0 if list is not a string that can be encoded with encode or
1185                  if size was < 1.
1186
1187              The written string is always NULL-terminated, unless buffer size
1188              is < 1.
1189
1190       int enif_get_tuple(ErlNifEnv* env, ERL_NIF_TERM
1191               term, int* arity, const ERL_NIF_TERM** array)
1192
1193              If  term  is  a  tuple, this function sets *array to point to an
1194              array containing the elements of the tuple, and sets  *arity  to
1195              the  number  of elements. Notice that the array is read-only and
1196              (*array)[N-1] is the Nth element of the tuple. *array  is  unde‐
1197              fined if the arity of the tuple is zero.
1198
1199              Returns true on success, or false if term is not a tuple.
1200
1201       int enif_get_uint(ErlNifEnv* env, ERL_NIF_TERM
1202               term, unsigned int* ip)
1203
1204              Sets *ip to the unsigned integer value of term.
1205
1206              Returns  true  on  success,  or false if term is not an unsigned
1207              integer or is outside the bounds of type unsigned int.
1208
1209       int enif_get_uint64(ErlNifEnv* env,
1210               ERL_NIF_TERM term, ErlNifUInt64* ip)
1211
1212              Sets *ip to the unsigned integer value of term.
1213
1214              Returns true on success, or false if term  is  not  an  unsigned
1215              integer or is outside the bounds of an unsigned 64-bit integer.
1216
1217       int enif_get_ulong(ErlNifEnv* env, ERL_NIF_TERM
1218               term, unsigned long* ip)
1219
1220              Sets *ip to the unsigned long integer value of term.
1221
1222              Returns  true  on  success,  or false if term is not an unsigned
1223              integer or is outside the bounds of type unsigned long.
1224
1225       int enif_getenv(const char* key, char* value,
1226               size_t *value_size)
1227
1228              Same as erl_drv_getenv.
1229
1230       int enif_has_pending_exception(ErlNifEnv* env,
1231               ERL_NIF_TERM* reason)
1232
1233              Returns true if a pending exception is associated with the envi‐
1234              ronment  env. If reason is a NULL pointer, ignore it. Otherwise,
1235              if a pending exception associated with env exists,  set  *reason
1236              to   the   value   of   the  exception  term.  For  example,  if
1237              enif_make_badarg is called to set a pending badarg exception,  a
1238              later  call  to  enif_has_pending_exception(env,  &reason)  sets
1239              *reason to the atom badarg, then return true.
1240
1241              See also enif_make_badarg and enif_raise_exception.
1242
1243       ErlNifUInt64 enif_hash(ErlNifHash type, ERL_NIF_TERM term, ErlNifUInt64
1244       salt)
1245
1246              Hashes term according to the specified ErlNifHash type.
1247
1248              Ranges  of  taken salt (if any) and returned value depend on the
1249              hash type.
1250
1251       int enif_inspect_binary(ErlNifEnv* env,
1252               ERL_NIF_TERM bin_term, ErlNifBinary* bin)
1253
1254              Initializes the structure pointed to  by  bin  with  information
1255              about binary term bin_term.
1256
1257              Returns true on success, or false if bin_term is not a binary.
1258
1259       int enif_inspect_iolist_as_binary(ErlNifEnv*
1260               env, ERL_NIF_TERM term, ErlNifBinary* bin)
1261
1262              Initializes  the  structure  pointed to by bin with a continuous
1263              buffer  with  the  same  byte  content  as   iolist.   As   with
1264              inspect_binary, the data pointed to by bin is transient and does
1265              not need to be released.
1266
1267              Returns true on success, or false if iolist is not an iolist.
1268
1269       int enif_inspect_iovec(ErlNifEnv*
1270               env,    size_t    max_elements,    ERL_NIF_TERM     iovec_term,
1271       ERL_NIF_TERM* tail,
1272               ErlNifIOVec** iovec)
1273
1274              Fills  iovec  with  the list of binaries provided in iovec_term.
1275              The number of  elements  handled  in  the  call  is  limited  to
1276              max_elements, and tail is set to the remainder of the list. Note
1277              that the output may be longer than max_elements  on  some  plat‐
1278              forms.
1279
1280              To  create  a  list  of  binaries  from an arbitrary iolist, use
1281              erlang:iolist_to_iovec/1.
1282
1283              When calling this function, iovec should contain  a  pointer  to
1284              NULL or a ErlNifIOVec structure that should be used if possible.
1285              e.g.
1286
1287              /* Don't use a pre-allocated structure */
1288              ErlNifIOVec *iovec = NULL;
1289              enif_inspect_iovec(env, max_elements, term, &tail, &iovec);
1290
1291              /* Use a stack-allocated vector as an optimization for vectors with few elements */
1292              ErlNifIOVec vec, *iovec = &vec;
1293              enif_inspect_iovec(env, max_elements, term, &tail, &iovec);
1294
1295
1296              The contents of the iovec is valid until the called nif function
1297              returns.  If  the  iovec  should  be  valid  after  the nif call
1298              returns, it is possible to call this function with a NULL  envi‐
1299              ronment.  If  no environment is given the iovec owns the data in
1300              the  vector  and  it  has   to   be   explicitly   freed   using
1301              enif_free_iovec.
1302
1303              Returns true on success, or false if iovec_term not an iovec.
1304
1305       ErlNifIOQueue *enif_ioq_create(ErlNifIOQueueOpts opts)
1306
1307              Create  a new I/O Queue that can be used to store data. opts has
1308              to be set to ERL_NIF_IOQ_NORMAL.
1309
1310       void enif_ioq_destroy(ErlNifIOQueue *q)
1311
1312              Destroy the I/O queue and free all of it's contents
1313
1314       int enif_ioq_deq(ErlNifIOQueue *q, size_t count, size_t *size)
1315
1316              Dequeue count bytes from the I/O queue. If size is not NULL, the
1317              new size of the queue is placed there.
1318
1319              Returns  true  on  success, or false if the I/O does not contain
1320              count bytes. On failure the queue is left un-altered.
1321
1322       int enif_ioq_enq_binary(ErlNifIOQueue  *q,  ErlNifBinary  *bin,  size_t
1323       skip)
1324
1325              Enqueue the bin into q skipping the first skip bytes.
1326
1327              Returns  true  on  success, or false if skip is greater than the
1328              size of bin. Any ownership of the binary data is transferred  to
1329              the  queue and bin is to be considered read-only for the rest of
1330              the NIF call and then as released.
1331
1332       int enif_ioq_enqv(ErlNifIOQueue *q, ErlNifIOVec *iovec, size_t skip)
1333
1334              Enqueue the iovec into q skipping the first skip bytes.
1335
1336              Returns true on success, or false if skip is  greater  than  the
1337              size of iovec.
1338
1339       SysIOVec *enif_ioq_peek(ErlNifIOQueue *q, int *iovlen)
1340
1341              Get the I/O queue as a pointer to an array of SysIOVecs. It also
1342              returns the number of elements in iovlen.
1343
1344              Nothing is removed from the queue by this function, that must be
1345              done with enif_ioq_deq.
1346
1347              The  returned array is suitable to use with the Unix system call
1348              writev.
1349
1350       int enif_ioq_peek_head(ErlNifEnv *env, ErlNifIOQueue *q, size_t  *size,
1351       ERL_NIF_TERM *bin_term)
1352
1353              Get the head of the IO Queue as a binary term.
1354
1355              If size is not NULL, the size of the head is placed there.
1356
1357              Nothing is removed from the queue by this function, that must be
1358              done with enif_ioq_deq.
1359
1360              Returns true on success, or false if the queue is empty.
1361
1362       size_t enif_ioq_size(ErlNifIOQueue *q)
1363
1364              Get the size of q.
1365
1366       int enif_is_atom(ErlNifEnv* env, ERL_NIF_TERM term)
1367
1368              Returns true if term is an atom.
1369
1370       int enif_is_binary(ErlNifEnv* env, ERL_NIF_TERM term)
1371
1372              Returns true if term is a binary.
1373
1374       int enif_is_current_process_alive(ErlNifEnv* env)
1375
1376              Returns true if the currently  executing  process  is  currently
1377              alive, otherwise false.
1378
1379              This  function  can  only be used from a NIF-calling thread, and
1380              with an environment corresponding to  currently  executing  pro‐
1381              cesses.
1382
1383       int enif_is_empty_list(ErlNifEnv* env,
1384               ERL_NIF_TERM term)
1385
1386              Returns true if term is an empty list.
1387
1388       int enif_is_exception(ErlNifEnv* env,
1389               ERL_NIF_TERM term)
1390
1391              Return true if term is an exception.
1392
1393       int enif_is_fun(ErlNifEnv* env, ERL_NIF_TERM
1394               term)
1395
1396              Returns true if term is a fun.
1397
1398       int enif_is_identical(ERL_NIF_TERM lhs,
1399               ERL_NIF_TERM rhs)
1400
1401              Returns  true if the two terms are identical. Corresponds to the
1402              Erlang operators =:= and =/=.
1403
1404       int enif_is_list(ErlNifEnv* env, ERL_NIF_TERM term)
1405
1406              Returns true if term is a list.
1407
1408       int enif_is_map(ErlNifEnv* env, ERL_NIF_TERM
1409               term)
1410
1411              Returns true if term is a map, otherwise false.
1412
1413       int enif_is_number(ErlNifEnv* env, ERL_NIF_TERM
1414               term)
1415
1416              Returns true if term is a number.
1417
1418       int enif_is_pid(ErlNifEnv* env, ERL_NIF_TERM term)
1419
1420              Returns true if term is a pid.
1421
1422       int enif_is_pid_undefined(const ErlNifPid* pid)
1423
1424              Returns  true  if   pid   has   been   set   as   undefined   by
1425              enif_set_pid_undefined.
1426
1427       int enif_is_port(ErlNifEnv* env, ERL_NIF_TERM term)
1428
1429              Returns true if term is a port.
1430
1431       int enif_is_port_alive(ErlNifEnv* env,
1432               ErlNifPort *port_id)
1433
1434              Returns true if port_id is alive.
1435
1436              This  function  is  only  thread-safe when the emulator with SMP
1437              support is used. It can only be used in a non-SMP emulator  from
1438              a NIF-calling thread.
1439
1440       int enif_is_process_alive(ErlNifEnv* env,
1441               ErlNifPid *pid)
1442
1443              Returns true if pid is alive.
1444
1445              This  function  is  only  thread-safe when the emulator with SMP
1446              support is used. It can only be used in a non-SMP emulator  from
1447              a NIF-calling thread.
1448
1449       int enif_is_ref(ErlNifEnv* env, ERL_NIF_TERM term)
1450
1451              Returns true if term is a reference.
1452
1453       int enif_is_tuple(ErlNifEnv* env, ERL_NIF_TERM term)
1454
1455              Returns true if term is a tuple.
1456
1457       int enif_keep_resource(void* obj)
1458
1459              Adds   a   reference   to  resource  object  obj  obtained  from
1460              enif_alloc_resource. Each  call  to  enif_keep_resource  for  an
1461              object  must  be  balanced  by  a  call to enif_release_resource
1462              before the object is destructed.
1463
1464       ERL_NIF_TERM enif_make_atom(ErlNifEnv* env, const char* name)
1465
1466              Creates an atom term from the NULL-terminated C-string name with
1467              ISO  Latin-1 encoding. If the length of name exceeds the maximum
1468              length allowed for  an  atom  (255  characters),  enif_make_atom
1469              invokes enif_make_badarg.
1470
1471       ERL_NIF_TERM enif_make_atom_len(ErlNifEnv* env,
1472               const char* name, size_t len)
1473
1474              Create  an  atom term from the string name with length len. NULL
1475              characters are treated as any other characters. If  len  exceeds
1476              the  maximum  length  allowed  for  an  atom  (255  characters),
1477              enif_make_atom invokes enif_make_badarg.
1478
1479       ERL_NIF_TERM enif_make_badarg(ErlNifEnv* env)
1480
1481              Makes a badarg exception to be returned from a  NIF,  and  asso‐
1482              ciates  it  with  environment env. Once a NIF or any function it
1483              calls invokes  enif_make_badarg,  the  runtime  ensures  that  a
1484              badarg exception is raised when the NIF returns, even if the NIF
1485              attempts to return a non-exception term instead.
1486
1487              The return value from enif_make_badarg can be used only  as  the
1488              return  value  from  the  NIF that invoked it (directly or indi‐
1489              rectly) or be passed to enif_is_exception, but not to any  other
1490              NIF API function.
1491
1492              See also enif_has_pending_exception and enif_raise_exception.
1493
1494          Note:
1495              Before   ERTS   7.0  (Erlang/OTP  18),  the  return  value  from
1496              enif_make_badarg had to be returned from the NIF. This  require‐
1497              ment  is  now lifted as the return value from the NIF is ignored
1498              if enif_make_badarg has been invoked.
1499
1500
1501       ERL_NIF_TERM enif_make_binary(ErlNifEnv* env, ErlNifBinary* bin)
1502
1503              Makes a binary term from bin. Any ownership of the  binary  data
1504              is  transferred  to the created term and bin is to be considered
1505              read-only for the rest of the NIF call and then as released.
1506
1507       ERL_NIF_TERM enif_make_copy(ErlNifEnv* dst_env,
1508               ERL_NIF_TERM src_term)
1509
1510              Makes a copy of term src_term. The copy is created  in  environ‐
1511              ment dst_env. The source term can be located in any environment.
1512
1513       ERL_NIF_TERM enif_make_double(ErlNifEnv* env, double d)
1514
1515              Creates  a floating-point term from a double. If argument double
1516              is   not   finite   or   is   NaN,   enif_make_double    invokes
1517              enif_make_badarg.
1518
1519       int enif_make_existing_atom(ErlNifEnv* env,
1520               const char* name, ERL_NIF_TERM* atom, ErlNifCharEncoding
1521               encode)
1522
1523              Tries  to  create  the term of an already existing atom from the
1524              NULL-terminated C-string name with encoding encode.
1525
1526              If the atom already exists, this function  stores  the  term  in
1527              *atom  and  returns true, otherwise false. Also returns false if
1528              the length of name exceeds the maximum  length  allowed  for  an
1529              atom (255 characters).
1530
1531       int enif_make_existing_atom_len(ErlNifEnv* env,
1532               const char* name, size_t len, ERL_NIF_TERM* atom, ErlNifCharEn‐
1533       coding
1534               encoding)
1535
1536              Tries to create the term of an already existing  atom  from  the
1537              string name with length len and encoding encode. NULL characters
1538              are treated as any other characters.
1539
1540              If the atom already exists, this function  stores  the  term  in
1541              *atom  and  returns true, otherwise false. Also returns false if
1542              len exceeds the maximum length allowed for an atom (255  charac‐
1543              ters).
1544
1545       ERL_NIF_TERM enif_make_int(ErlNifEnv* env, int i)
1546
1547              Creates an integer term.
1548
1549       ERL_NIF_TERM enif_make_int64(ErlNifEnv* env, ErlNifSInt64 i)
1550
1551              Creates an integer term from a signed 64-bit integer.
1552
1553       ERL_NIF_TERM enif_make_list(ErlNifEnv* env, unsigned cnt, ...)
1554
1555              Creates  an ordinary list term of length cnt. Expects cnt number
1556              of arguments (after cnt) of type ERL_NIF_TERM as the elements of
1557              the list.
1558
1559              Returns an empty list if cnt is 0.
1560
1561       ERL_NIF_TERM enif_make_list1(ErlNifEnv* env, ERL_NIF_TERM e1)
1562       ERL_NIF_TERM enif_make_list2(ErlNifEnv* env,
1563               ERL_NIF_TERM e1, ERL_NIF_TERM e2)
1564       ERL_NIF_TERM enif_make_list3(ErlNifEnv* env,
1565               ERL_NIF_TERM e1, ERL_NIF_TERM e2, ERL_NIF_TERM e3)
1566       ERL_NIF_TERM enif_make_list4(ErlNifEnv* env,
1567               ERL_NIF_TERM e1, ..., ERL_NIF_TERM e4)
1568       ERL_NIF_TERM enif_make_list5(ErlNifEnv* env,
1569               ERL_NIF_TERM e1, ..., ERL_NIF_TERM e5)
1570       ERL_NIF_TERM enif_make_list6(ErlNifEnv* env,
1571               ERL_NIF_TERM e1, ..., ERL_NIF_TERM e6)
1572       ERL_NIF_TERM enif_make_list7(ErlNifEnv* env,
1573               ERL_NIF_TERM e1, ..., ERL_NIF_TERM e7)
1574       ERL_NIF_TERM enif_make_list8(ErlNifEnv* env,
1575               ERL_NIF_TERM e1, ..., ERL_NIF_TERM e8)
1576       ERL_NIF_TERM enif_make_list9(ErlNifEnv* env,
1577               ERL_NIF_TERM e1, ..., ERL_NIF_TERM e9)
1578
1579              Creates an ordinary list term with length indicated by the func‐
1580              tion name. Prefer these functions  (macros)  over  the  variadic
1581              enif_make_list  to  get  a  compile-time  error if the number of
1582              arguments does not match.
1583
1584       ERL_NIF_TERM enif_make_list_cell(ErlNifEnv*
1585               env, ERL_NIF_TERM head, ERL_NIF_TERM tail)
1586
1587              Creates a list cell [head | tail].
1588
1589       ERL_NIF_TERM    enif_make_list_from_array(ErlNifEnv*     env,     const
1590       ERL_NIF_TERM
1591                 arr[], unsigned cnt)
1592
1593              Creates an ordinary list containing the elements of array arr of
1594              length cnt.
1595
1596              Returns an empty list if cnt is 0.
1597
1598       ERL_NIF_TERM enif_make_long(ErlNifEnv* env, long int i)
1599
1600              Creates an integer term from a long int.
1601
1602       int enif_make_map_put(ErlNifEnv* env,
1603               ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM value,
1604               ERL_NIF_TERM* map_out)
1605
1606              Makes a copy of map map_in and inserts key with  value.  If  key
1607              already  exists  in map_in, the old associated value is replaced
1608              by value.
1609
1610              If successful, this function sets *map_out to the  new  map  and
1611              returns true. Returns false if map_in is not a map.
1612
1613              The map_in term must belong to environment env.
1614
1615       int enif_make_map_remove(ErlNifEnv* env,
1616               ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM* map_out)
1617
1618              If map map_in contains key, this function makes a copy of map_in
1619              in *map_out, and removes key and the associated  value.  If  map
1620              map_in does not contain key, *map_out is set to map_in.
1621
1622              Returns true on success, or false if map_in is not a map.
1623
1624              The map_in term must belong to environment env.
1625
1626       int enif_make_map_update(ErlNifEnv* env,
1627               ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM new_value,
1628               ERL_NIF_TERM* map_out)
1629
1630              Makes  a copy of map map_in and replace the old associated value
1631              for key with new_value.
1632
1633              If successful, this function sets *map_out to the  new  map  and
1634              returns true. Returns false if map_in is not a map or if it does
1635              not contain key.
1636
1637              The map_in term must belong to environment env.
1638
1639       int enif_make_map_from_arrays(ErlNifEnv* env, ERL_NIF_TERM keys[],
1640               ERL_NIF_TERM values[], size_t cnt, ERL_NIF_TERM *map_out)
1641
1642              Makes a map term from the given keys and values.
1643
1644              If successful, this function sets *map_out to the  new  map  and
1645              returns true. Returns false there are any duplicate keys.
1646
1647              All keys and values must belong to env.
1648
1649       ERL_NIF_TERM  enif_make_monitor_term(ErlNifEnv*  env, const ErlNifMoni‐
1650       tor* mon)
1651
1652              Creates a term  identifying  the  given  monitor  received  from
1653              enif_monitor_process.
1654
1655              This function is primarily intended for debugging purpose.
1656
1657       unsigned char *enif_make_new_binary(ErlNifEnv*
1658               env, size_t size, ERL_NIF_TERM* termp)
1659
1660              Allocates  a  binary  of  size  size bytes and creates an owning
1661              term. The binary data is mutable until the calling NIF  returns.
1662              This is a quick way to create a new binary without having to use
1663              ErlNifBinary. The drawbacks are that the binary cannot  be  kept
1664              between NIF calls and it cannot be reallocated.
1665
1666              Returns  a pointer to the raw binary data and sets *termp to the
1667              binary term.
1668
1669       ERL_NIF_TERM enif_make_new_map(ErlNifEnv* env)
1670
1671              Makes an empty map term.
1672
1673       ERL_NIF_TERM enif_make_pid(ErlNifEnv* env, const ErlNifPid* pid)
1674
1675              Makes a pid term or the atom undefined from *pid.
1676
1677       ERL_NIF_TERM enif_make_ref(ErlNifEnv* env)
1678
1679              Creates a reference like erlang:make_ref/0.
1680
1681       ERL_NIF_TERM enif_make_resource(ErlNifEnv* env, void* obj)
1682
1683              Creates an opaque handle to  a  memory-managed  resource  object
1684              obtained  by enif_alloc_resource. No ownership transfer is done,
1685              as  the  resource  object  still  needs  to   be   released   by
1686              enif_release_resource.   However,   notice   that  the  call  to
1687              enif_release_resource can occur immediately after obtaining  the
1688              term  from enif_make_resource, in which case the resource object
1689              is deallocated when the term  is  garbage  collected.  For  more
1690              details,  see  the  example of creating and returning a resource
1691              object in the User's Guide.
1692
1693          Note:
1694              Since ERTS 9.0 (OTP-20.0), resource terms have a defined  behav‐
1695              ior  when  compared  and  serialized  through  term_to_binary or
1696              passed between nodes.
1697
1698                * Two resource terms will compare equal if and  only  if  they
1699                  would  yield the same resource object pointer when passed to
1700                  enif_get_resource.
1701
1702                * A resource term can be serialized  with  term_to_binary  and
1703                  later  be  fully  recreated  if the resource object is still
1704                  alive when binary_to_term is called. A stale  resource  term
1705                  will  be returned from binary_to_term if the resource object
1706                  has been deallocated. enif_get_resource  will  return  false
1707                  for stale resource terms.
1708
1709                  The  same  principles  of  serialization  apply when passing
1710                  resource terms in messages to remote nodes and back again. A
1711                  resource  term  will  act stale on all nodes except the node
1712                  where its resource object is still alive in memory.
1713
1714              Before ERTS 9.0 (OTP-20.0), all resource terms did compare equal
1715              to  each other and to empty binaries (<<>>). If serialized, they
1716              would be recreated as plain empty binaries.
1717
1718
1719       ERL_NIF_TERM enif_make_resource_binary(ErlNifEnv* env, void* obj, const
1720               void* data, size_t size)
1721
1722              Creates a binary term  that  is  memory-managed  by  a  resource
1723              object  obj obtained by enif_alloc_resource. The returned binary
1724              term consists of size bytes pointed to by data. This raw  binary
1725              data must be kept readable and unchanged until the destructor of
1726              the resource is called. The binary data can be  stored  external
1727              to  the resource object, in which case the destructor is respon‐
1728              sible for releasing the data.
1729
1730              Several binary terms can be managed by the same resource object.
1731              The  destructor  is  not called until the last binary is garbage
1732              collected. This can be useful to return  different  parts  of  a
1733              larger binary buffer.
1734
1735              As  with  enif_make_resource, no ownership transfer is done. The
1736              resource still needs to be released with enif_release_resource.
1737
1738       int enif_make_reverse_list(ErlNifEnv* env, ERL_NIF_TERM list_in,
1739               ERL_NIF_TERM *list_out)
1740
1741              Sets *list_out to the reverse  list  of  the  list  list_in  and
1742              returns true, or returns false if list_in is not a list.
1743
1744              This  function  is  only to be used on short lists, as a copy is
1745              created of the list, which is not released until after  the  NIF
1746              returns.
1747
1748              The list_in term must belong to environment env.
1749
1750       ERL_NIF_TERM enif_make_string(ErlNifEnv* env,
1751               const char* string, ErlNifCharEncoding encoding)
1752
1753              Creates  a list containing the characters of the NULL-terminated
1754              string string with encoding encoding.
1755
1756       ERL_NIF_TERM enif_make_string_len(ErlNifEnv*
1757               env, const char* string, size_t len, ErlNifCharEncoding
1758               encoding)
1759
1760              Creates a list containing the characters of  the  string  string
1761              with  length  len  and  encoding  encoding.  NULL characters are
1762              treated as any other characters.
1763
1764       ERL_NIF_TERM enif_make_sub_binary(ErlNifEnv*
1765               env, ERL_NIF_TERM bin_term, size_t pos, size_t size)
1766
1767              Makes a subbinary of binary  bin_term,  starting  at  zero-based
1768              position  pos  with  a  length of size bytes. bin_term must be a
1769              binary or bitstring. pos+size must be less or equal to the  num‐
1770              ber of whole bytes in bin_term.
1771
1772       ERL_NIF_TERM enif_make_tuple(ErlNifEnv* env,
1773               unsigned cnt, ...)
1774
1775              Creates  a  tuple term of arity cnt. Expects cnt number of argu‐
1776              ments (after cnt) of type ERL_NIF_TERM as the  elements  of  the
1777              tuple.
1778
1779       ERL_NIF_TERM enif_make_tuple1(ErlNifEnv* env,
1780               ERL_NIF_TERM e1)
1781       ERL_NIF_TERM enif_make_tuple2(ErlNifEnv* env,
1782               ERL_NIF_TERM e1, ERL_NIF_TERM e2)
1783       ERL_NIF_TERM enif_make_tuple3(ErlNifEnv* env,
1784               ERL_NIF_TERM e1, ERL_NIF_TERM e2, ERL_NIF_TERM e3)
1785       ERL_NIF_TERM enif_make_tuple4(ErlNifEnv* env,
1786               ERL_NIF_TERM e1, ..., ERL_NIF_TERM e4)
1787       ERL_NIF_TERM enif_make_tuple5(ErlNifEnv* env,
1788               ERL_NIF_TERM e1, ..., ERL_NIF_TERM e5)
1789       ERL_NIF_TERM enif_make_tuple6(ErlNifEnv* env,
1790               ERL_NIF_TERM e1, ..., ERL_NIF_TERM e6)
1791       ERL_NIF_TERM enif_make_tuple7(ErlNifEnv* env,
1792               ERL_NIF_TERM e1, ..., ERL_NIF_TERM e7)
1793       ERL_NIF_TERM enif_make_tuple8(ErlNifEnv* env,
1794               ERL_NIF_TERM e1, ..., ERL_NIF_TERM e8)
1795       ERL_NIF_TERM enif_make_tuple9(ErlNifEnv* env,
1796               ERL_NIF_TERM e1, ..., ERL_NIF_TERM e9)
1797
1798              Creates a tuple term with length indicated by the function name.
1799              Prefer   these   functions   (macros)    over    the    variadic
1800              enif_make_tuple  to  get  a  compile-time error if the number of
1801              arguments does not match.
1802
1803       ERL_NIF_TERM    enif_make_tuple_from_array(ErlNifEnv*    env,     const
1804       ERL_NIF_TERM
1805               arr[], unsigned cnt)
1806
1807              Creates  a  tuple containing the elements of array arr of length
1808              cnt.
1809
1810       ERL_NIF_TERM enif_make_uint(ErlNifEnv* env, unsigned int i)
1811
1812              Creates an integer term from an unsigned int.
1813
1814       ERL_NIF_TERM enif_make_uint64(ErlNifEnv* env, ErlNifUInt64 i)
1815
1816              Creates an integer term from an unsigned 64-bit integer.
1817
1818       ERL_NIF_TERM enif_make_ulong(ErlNifEnv* env, unsigned long i)
1819
1820              Creates an integer term from an unsigned long int.
1821
1822       ERL_NIF_TERM enif_make_unique_integer(ErlNifEnv
1823               *env, ErlNifUniqueInteger properties)
1824
1825              Returns a unique integer with the same properties  as  specified
1826              by erlang:unique_integer/1.
1827
1828              env is the environment to create the integer in.
1829
1830              ERL_NIF_UNIQUE_POSITIVE   and  ERL_NIF_UNIQUE_MONOTONIC  can  be
1831              passed as the second argument to change the  properties  of  the
1832              integer  returned. They can be combined by OR:ing the two values
1833              together.
1834
1835              See also ErlNifUniqueInteger.
1836
1837       int enif_map_iterator_create(ErlNifEnv *env,
1838               ERL_NIF_TERM map, ErlNifMapIterator *iter, ErlNifMapIteratorEn‐
1839       try
1840               entry)
1841
1842              Creates  an  iterator for the map map by initializing the struc‐
1843              ture pointed to by iter. Argument  entry  determines  the  start
1844              position   of   the   iterator:   ERL_NIF_MAP_ITERATOR_FIRST  or
1845              ERL_NIF_MAP_ITERATOR_LAST.
1846
1847              Returns true on success, or false if map is not a map.
1848
1849              A map iterator is only useful during the lifetime of environment
1850              env  that  the map belongs to. The iterator must be destroyed by
1851              calling enif_map_iterator_destroy:
1852
1853              ERL_NIF_TERM key, value;
1854              ErlNifMapIterator iter;
1855              enif_map_iterator_create(env, my_map, &iter, ERL_NIF_MAP_ITERATOR_FIRST);
1856
1857              while (enif_map_iterator_get_pair(env, &iter, &key, &value)) {
1858                  do_something(key,value);
1859                  enif_map_iterator_next(env, &iter);
1860              }
1861              enif_map_iterator_destroy(env, &iter);
1862
1863          Note:
1864              The key-value pairs of a map have no  defined  iteration  order.
1865              The  only  guarantee is that the iteration order of a single map
1866              instance is preserved during the  lifetime  of  the  environment
1867              that the map belongs to.
1868
1869
1870       void enif_map_iterator_destroy(ErlNifEnv *env,
1871               ErlNifMapIterator *iter)
1872
1873              Destroys a map iterator created by enif_map_iterator_create.
1874
1875       int enif_map_iterator_get_pair(ErlNifEnv *env,
1876               ErlNifMapIterator *iter, ERL_NIF_TERM *key, ERL_NIF_TERM
1877               *value)
1878
1879              Gets key and value terms at the current map iterator position.
1880
1881              On success, sets *key and *value and returns true. Returns false
1882              if the iterator is positioned at head (before  first  entry)  or
1883              tail (beyond last entry).
1884
1885       int enif_map_iterator_is_head(ErlNifEnv *env,
1886               ErlNifMapIterator *iter)
1887
1888              Returns true if map iterator iter is positioned before the first
1889              entry.
1890
1891       int enif_map_iterator_is_tail(ErlNifEnv *env,
1892               ErlNifMapIterator *iter)
1893
1894              Returns true if map iterator iter is positioned after  the  last
1895              entry.
1896
1897       int enif_map_iterator_next(ErlNifEnv *env,
1898               ErlNifMapIterator *iter)
1899
1900              Increments map iterator to point to the next key-value entry.
1901
1902              Returns  true  if the iterator is now positioned at a valid key-
1903              value entry, or false if the iterator is positioned at the  tail
1904              (beyond the last entry).
1905
1906       int enif_map_iterator_prev(ErlNifEnv *env,
1907               ErlNifMapIterator *iter)
1908
1909              Decrements  map  iterator  to  point  to  the previous key-value
1910              entry.
1911
1912              Returns true if the iterator is now positioned at a  valid  key-
1913              value  entry, or false if the iterator is positioned at the head
1914              (before the first entry).
1915
1916       int enif_monitor_process(ErlNifEnv* caller_env,
1917             void* obj, const ErlNifPid* target_pid, ErlNifMonitor* mon)
1918
1919              Starts monitoring a process from a resource. When a  process  is
1920              monitored, a process exit results in a call to the provided down
1921              callback associated with the resource type.
1922
1923              Argument obj is pointer to the resource to hold the monitor  and
1924              *target_pid identifies the local process to be monitored.
1925
1926              If mon is not NULL, a successful call stores the identity of the
1927              monitor in the ErlNifMonitor struct  pointed  to  by  mon.  This
1928              identifier  is  used  to  refer to the monitor for later removal
1929              with enif_demonitor_process or compare  with  enif_compare_moni‐
1930              tors.  A  monitor  is  automatically removed when it triggers or
1931              when the resource is deallocated.
1932
1933              Argument caller_env is the environment  of  the  calling  thread
1934              (process  bound or callback environment) or NULL if calling from
1935              a custom thread not spawned by ERTS.
1936
1937              Returns 0 on success, < 0 if no down callback is provided, and >
1938              0  if  the process is no longer alive or if target_pid is  unde‐
1939              fined.
1940
1941              This function is only thread-safe when  the  emulator  with  SMP
1942              support  is used. It can only be used in a non-SMP emulator from
1943              a NIF-calling thread.
1944
1945       ErlNifTime enif_monotonic_time(ErlNifTimeUnit time_unit)
1946
1947              Returns the current  Erlang monotonic time. Notice  that  it  is
1948              not uncommon with negative values.
1949
1950              time_unit is the time unit of the returned value.
1951
1952              Returns  ERL_NIF_TIME_ERROR  if called with an invalid time unit
1953              argument, or if called from a thread that  is  not  a  scheduler
1954              thread.
1955
1956              See also ErlNifTime and ErlNifTimeUnit.
1957
1958       ErlNifMutex *enif_mutex_create(char *name)
1959
1960              Same as erl_drv_mutex_create.
1961
1962       void enif_mutex_destroy(ErlNifMutex *mtx)
1963
1964              Same as erl_drv_mutex_destroy.
1965
1966       void enif_mutex_lock(ErlNifMutex *mtx)
1967
1968              Same as erl_drv_mutex_lock.
1969
1970       char*enif_mutex_name(ErlNifMutex* mtx)
1971
1972              Same as erl_drv_mutex_name.
1973
1974       int enif_mutex_trylock(ErlNifMutex *mtx)
1975
1976              Same as erl_drv_mutex_trylock.
1977
1978       void enif_mutex_unlock(ErlNifMutex *mtx)
1979
1980              Same as erl_drv_mutex_unlock.
1981
1982       ERL_NIF_TERM enif_now_time(ErlNifEnv *env)
1983
1984              Returns an erlang:now() time stamp.
1985
1986              This function is deprecated.
1987
1988       ErlNifResourceType *enif_open_resource_type(ErlNifEnv* env, const char*
1989               module_str, const char* name, ErlNifResourceDtor* dtor,
1990               ErlNifResourceFlags flags, ErlNifResourceFlags* tried)
1991
1992              Creates  or  takes over a resource type identified by the string
1993              name and gives it the destructor function pointed  to  by  dtor.
1994              Argument flags can have the following values:
1995
1996                ERL_NIF_RT_CREATE:
1997                  Creates a new resource type that does not already exist.
1998
1999                ERL_NIF_RT_TAKEOVER:
2000                  Opens  an existing resource type and takes over ownership of
2001                  all its instances. The supplied destructor  dtor  is  called
2002                  both  for  existing instances and new instances not yet cre‐
2003                  ated by the calling NIF library.
2004
2005              The two flag  values  can  be  combined  with  bitwise  OR.  The
2006              resource type name is local to the calling module. Argument mod‐
2007              ule_str is not (yet) used and must be NULL. dtor can be NULL  if
2008              no destructor is needed.
2009
2010              On  success, the function returns a pointer to the resource type
2011              and   *tried   is   set   to   either    ERL_NIF_RT_CREATE    or
2012              ERL_NIF_RT_TAKEOVER  to  indicate  what  was  done.  On failure,
2013              returns NULL and sets *tried to flags.  It  is  allowed  to  set
2014              tried to NULL.
2015
2016              Notice that enif_open_resource_type is only allowed to be called
2017              in the two callbacks load and upgrade.
2018
2019              See also enif_open_resource_type_x.
2020
2021       ErlNifResourceType  *enif_open_resource_type_x(ErlNifEnv*  env,   const
2022       char* name,      const ErlNifResourceTypeInit* init,
2023               ErlNifResourceFlags flags, ErlNifResourceFlags* tried)
2024
2025              Same  as  enif_open_resource_type  except  it accepts additional
2026              callback functions for resource types  that  are  used  together
2027              with enif_select and enif_monitor_process.
2028
2029              Argument  init  is a pointer to an ErlNifResourceTypeInit struc‐
2030              ture that contains the function pointers  for  destructor,  down
2031              and stop callbacks for the resource type.
2032
2033       int enif_port_command(ErlNifEnv* env, const
2034              ErlNifPort* to_port, ErlNifEnv *msg_env, ERL_NIF_TERM msg)
2035
2036              Works  as  erlang:port_command/2,  except that it is always com‐
2037              pletely asynchronous.
2038
2039                env:
2040                  The environment of the calling process. Must not be NULL.
2041
2042                *to_port:
2043                  The port ID of the receiving port. The port ID is  to  refer
2044                  to a port on the local node.
2045
2046                msg_env:
2047                  The  environment of the message term. Can be a process inde‐
2048                  pendent environment allocated with enif_alloc_env or NULL.
2049
2050                msg:
2051                  The message term to send. The same limitations apply  as  on
2052                  the payload to erlang:port_command/2.
2053
2054              Using  a  msg_env  of  NULL  is  an  optimization,  which groups
2055              together calls to enif_alloc_env, enif_make_copy, enif_port_com‐
2056              mand, and enif_free_env into one call. This optimization is only
2057              useful when a majority of the terms are to be copied from env to
2058              msg_env.
2059
2060              Returns  true if the command is successfully sent. Returns false
2061              if the command fails, for example:
2062
2063                * *to_port does not refer to a local port.
2064
2065                * The currently executing process (that is, the sender) is not
2066                  alive.
2067
2068                * msg is invalid.
2069
2070              See also enif_get_local_port.
2071
2072       void *enif_priv_data(ErlNifEnv* env)
2073
2074              Returns  the pointer to the private data that was set by load or
2075              upgrade.
2076
2077       ERL_NIF_TERM enif_raise_exception(ErlNifEnv*
2078               env, ERL_NIF_TERM reason)
2079
2080              Creates an error exception with the term reason to  be  returned
2081              from  a  NIF, and associates it with environment env. Once a NIF
2082              or any function it calls invokes enif_raise_exception, the  run‐
2083              time  ensures  that  the exception it creates is raised when the
2084              NIF returns, even if the NIF attempts to return a  non-exception
2085              term instead.
2086
2087              The  return  value from enif_raise_exception can only be used as
2088              the return value from the NIF that invoked it (directly or indi‐
2089              rectly)  or be passed to enif_is_exception, but not to any other
2090              NIF API function.
2091
2092              See also enif_has_pending_exception and enif_make_badarg.
2093
2094       void *enif_realloc(void* ptr, size_t size)
2095
2096              Reallocates memory allocated by enif_alloc to size bytes.
2097
2098              Returns NULL if the reallocation fails.
2099
2100              The returned pointer is suitably aligned for any  built-in  type
2101              that fit in the allocated memory.
2102
2103       int enif_realloc_binary(ErlNifBinary* bin, size_t size)
2104
2105              Changes the size of a binary bin. The source binary can be read-
2106              only, in which case it is left untouched and a mutable  copy  is
2107              allocated and assigned to *bin.
2108
2109              Returns true on success, or false if memory allocation failed.
2110
2111       void enif_release_binary(ErlNifBinary* bin)
2112
2113              Releases a binary obtained from enif_alloc_binary.
2114
2115       void enif_release_resource(void* obj)
2116
2117              Removes  a  reference  to  resource  object  obj  obtained  from
2118              enif_alloc_resource. The resource object is destructed when  the
2119              last  reference  is  removed. Each call to enif_release_resource
2120              must correspond to a previous  call  to  enif_alloc_resource  or
2121              enif_keep_resource.  References  made  by enif_make_resource can
2122              only be removed by the garbage collector.
2123
2124              There are no guarantees exactly when the destructor of an unref‐
2125              erenced  resource  is  called.  It  could  be called directly by
2126              enif_release_resource but it  could  also  be  scheduled  to  be
2127              called at a later time possibly by another thread.
2128
2129       ErlNifRWLock *enif_rwlock_create(char *name)
2130
2131              Same as erl_drv_rwlock_create.
2132
2133       void enif_rwlock_destroy(ErlNifRWLock *rwlck)
2134
2135              Same as erl_drv_rwlock_destroy.
2136
2137       char*enif_rwlock_name(ErlNifRWLock* rwlck)
2138
2139              Same as erl_drv_rwlock_name.
2140
2141       void enif_rwlock_rlock(ErlNifRWLock *rwlck)
2142
2143              Same as erl_drv_rwlock_rlock.
2144
2145       void enif_rwlock_runlock(ErlNifRWLock *rwlck)
2146
2147              Same as erl_drv_rwlock_runlock.
2148
2149       void enif_rwlock_rwlock(ErlNifRWLock *rwlck)
2150
2151              Same as erl_drv_rwlock_rwlock.
2152
2153       void enif_rwlock_rwunlock(ErlNifRWLock *rwlck)
2154
2155              Same as erl_drv_rwlock_rwunlock.
2156
2157       int enif_rwlock_tryrlock(ErlNifRWLock *rwlck)
2158
2159              Same as erl_drv_rwlock_tryrlock.
2160
2161       int enif_rwlock_tryrwlock(ErlNifRWLock *rwlck)
2162
2163              Same as erl_drv_rwlock_tryrwlock.
2164
2165       ERL_NIF_TERM enif_schedule_nif(ErlNifEnv* env,
2166               const  char* fun_name, int flags, ERL_NIF_TERM (*fp)(ErlNifEnv*
2167       env, int
2168               argc, const ERL_NIF_TERM argv[]), int argc, const ERL_NIF_TERM
2169               argv[])
2170
2171              Schedules NIF fp to execute. This function allows an application
2172              to break up long-running work into multiple regular NIF calls or
2173              to schedule a  dirty NIF to execute on a dirty scheduler thread.
2174
2175                fun_name:
2176                  Provides a name for the NIF that is scheduled for execution.
2177                  If  it  cannot  be  converted  to an atom, enif_schedule_nif
2178                  returns a badarg exception.
2179
2180                flags:
2181                  Must be set to 0 for a regular  NIF.  If  the  emulator  was
2182                  built with dirty scheduler support enabled, flags can be set
2183                  to either ERL_NIF_DIRTY_JOB_CPU_BOUND if the job is expected
2184                  to be CPU-bound, or ERL_NIF_DIRTY_JOB_IO_BOUND for jobs that
2185                  will be I/O-bound. If dirty scheduler threads are not avail‐
2186                  able  in  the  emulator,  an  attempt to schedule such a job
2187                  results in a notsup exception.
2188
2189                argc and argv:
2190                  Can either be the originals passed into the calling NIF,  or
2191                  can be values created by the calling NIF.
2192
2193              The  calling  NIF must use the return value of enif_schedule_nif
2194              as its own return value.
2195
2196              Be aware that  enif_schedule_nif,  as  its  name  implies,  only
2197              schedules the NIF for future execution. The calling NIF does not
2198              block waiting for the scheduled NIF to execute and return.  This
2199              means  that  the calling NIF cannot expect to receive the sched‐
2200              uled NIF return value and use it for further operations.
2201
2202       int enif_select(ErlNifEnv* env, ErlNifEvent event,  enum  ErlNifSelect‐
2203       Flags mode,      void* obj, const ErlNifPid* pid, ERL_NIF_TERM ref)
2204
2205              This  function can be used to receive asynchronous notifications
2206              when OS-specific event objects become ready for either  read  or
2207              write operations.
2208
2209              Argument event identifies the event object. On Unix systems, the
2210              functions select/poll are used.  The  event  object  must  be  a
2211              socket,  pipe  or  other file descriptor object that select/poll
2212              can use.
2213
2214              Argument mode describes the type of events to wait for.  It  can
2215              be  ERL_NIF_SELECT_READ,  ERL_NIF_SELECT_WRITE  or  a bitwise OR
2216              combination to wait for both. It can also be ERL_NIF_SELECT_STOP
2217              or ERL_NIF_SELECT_CANCEL which are described further below. When
2218              a read or write event is triggered, a notification message  like
2219              this is sent to the process identified by pid:
2220
2221              {select, Obj, Ref, ready_input | ready_output}
2222
2223              ready_input  or  ready_output  indicates  if the event object is
2224              ready for reading or writing.
2225
2226          Note:
2227              For complete control over the message format use the newer func‐
2228              tions   enif_select_read   or  enif_select_write  introduced  in
2229              erts-11.0 (OTP-22.0).
2230
2231
2232              Argument pid may be NULL to indicate  the  calling  process.  It
2233              must not be set as  undefined.
2234
2235              Argument    obj    is    a   resource   object   obtained   from
2236              enif_alloc_resource. The purpose of the resource objects is as a
2237              container  of the event object to manage its state and lifetime.
2238              A handle to the resource is received in the notification message
2239              as Obj.
2240
2241              Argument   ref   must   be  either  a  reference  obtained  from
2242              erlang:make_ref/0 or the atom undefined. It will  be  passed  as
2243              Ref  in  the  notifications. If a selective receive statement is
2244              used to wait for the notification then a reference created  just
2245              before  the  receive  will  exploit  a runtime optimization that
2246              bypasses all earlier received messages in the queue.
2247
2248              The notifications are one-shot only. To receive further  notifi‐
2249              cations  of  the  same  type  (read or write), repeated calls to
2250              enif_select must be made after receiving each notification.
2251
2252              ERL_NIF_SELECT_CANCEL can be used to cancel previously  selected
2253              events.  It  must  be  used  in  a  bitwise  OR combination with
2254              ERL_NIF_SELECT_READ  and/or  ERL_NIF_SELECT_WRITE  to   indicate
2255              which type of event to cancel. Arguments pid and ref are ignored
2256              when ERL_NIF_SELECT_CANCEL is specified. The return  value  will
2257              tell if the event was actualy cancelled or if a notification may
2258              already have been sent.
2259
2260              Use ERL_NIF_SELECT_STOP as mode in  order  to  safely  close  an
2261              event object that has been passed to enif_select. The stop call‐
2262              back of the resource obj will be called when it is safe to close
2263              the event object. This safe way of closing event objects must be
2264              used even if all notifications have been received (or cancelled)
2265              and   no   further   calls   to   enif_select  have  been  made.
2266              ERL_NIF_SELECT_STOP will first cancel any selected events before
2267              it  calls  or schedules the stop callback. Arguments pid and ref
2268              are ignored when ERL_NIF_SELECT_STOP is specified.
2269
2270              The first call to enif_select  for  a  specific  OS  event  will
2271              establish a relation between the event object and the containing
2272              resource. All subsequent calls for an event must pass  its  con‐
2273              taining resource as argument obj. The relation is dissolved when
2274              enif_select has been called with mode as ERL_NIF_SELECT_STOP and
2275              the  corresponding  stop  callback  has returned. A resource can
2276              contain several event objects but one event object can  only  be
2277              contained within one resource. A resource will not be destructed
2278              until all its contained relations have been dissolved.
2279
2280          Note:
2281              Use enif_monitor_process together  with  enif_select  to  detect
2282              failing Erlang processes and prevent them from causing permanent
2283              leakage of resources and their contained OS event objects.
2284
2285
2286              Returns a non-negative value on success where the following bits
2287              can be set:
2288
2289                ERL_NIF_SELECT_STOP_CALLED:
2290                  The stop callback was called directly by enif_select.
2291
2292                ERL_NIF_SELECT_STOP_SCHEDULED:
2293                  The  stop callback was scheduled to run on some other thread
2294                  or later by this thread.
2295
2296                ERL_NIF_SELECT_READ_CANCELLED:
2297                  A read  event  was  cancelled  by  ERL_NIF_SELECT_CANCEL  or
2298                  ERL_NIF_SELECT_STOP  and  is  guaranteed  not  to generate a
2299                  ready_input notification message.
2300
2301                ERL_NIF_SELECT_WRITE_CANCELLED:
2302                  A write event  was  cancelled  by  ERL_NIF_SELECT_CANCEL  or
2303                  ERL_NIF_SELECT_STOP  and  is  guaranteed  not  to generate a
2304                  ready_output notification message.
2305
2306              Returns a negative value if the call failed where the  following
2307              bits can be set:
2308
2309                ERL_NIF_SELECT_INVALID_EVENT:
2310                  Argument event is not a valid OS event object.
2311
2312                ERL_NIF_SELECT_FAILED:
2313                  The  system  call failed to add the event object to the poll
2314                  set.
2315
2316          Note:
2317              Use bitwise AND to test for specific bits in the  return  value.
2318              New  significant  bits  may  be added in future releases to give
2319              more detailed information for both failed and successful  calls.
2320              Do NOT use equality tests like ==, as that may cause your appli‐
2321              cation to stop working.
2322
2323              Example:
2324
2325              retval = enif_select(env, fd, ERL_NIF_SELECT_STOP, resource, ref);
2326              if (retval < 0) {
2327                  /* handle error */
2328              }
2329              /* Success! */
2330              if (retval & ERL_NIF_SELECT_STOP_CALLED) {
2331                  /* ... */
2332              }
2333
2334
2335
2336          Note:
2337              The  mode  flag  ERL_NIF_SELECT_CANCEL  and  the  return   flags
2338              ERL_NIF_SELECT_READ_CANCELLED and ERL_NIF_SELECT_WRITE_CANCELLED
2339              were introduced in erts-11.0 (OTP-22.0).
2340
2341
2342       int enif_select_read(ErlNifEnv* env, ErlNifEvent event, void* obj,
2343             const ErlNifPid* pid, ERL_NIF_TERM msg, ErlNifEnv* msg_env)
2344       int enif_select_write(ErlNifEnv* env, ErlNifEvent event, void* obj,
2345             const ErlNifPid* pid, ERL_NIF_TERM msg, ErlNifEnv* msg_env)
2346
2347              These are variants of enif_select where you can supply your  own
2348              message term msg that will be sent to the process instead of the
2349              predefined tuple {select,_,_,_}.
2350
2351              Argument msg_env must either be NULL or the environment  of  msg
2352              allocated  with  enif_alloc_env. If argument msg_env is NULL the
2353              term msg will be copied, otherwise both msg and msg_env will  be
2354              invalidated   by   a  successful  call  to  enif_select_read  or
2355              enif_select_write. The environment is then to  either  be  freed
2356              with  enif_free_env or cleared for reuse with enif_clear_env. An
2357              unsuccessful call will leave msg and msg_env still valid.
2358
2359              Apart   from   the   message   format    enif_select_read    and
2360              enif_select_write  behaves  exactly the same as enif_select with
2361              argument    mode    as     either     ERL_NIF_SELECT_READ     or
2362              ERL_NIF_SELECT_WRITE. To cancel or close events use enif_select.
2363
2364       ErlNifPid *enif_self(ErlNifEnv* caller_env, ErlNifPid* pid)
2365
2366              Initializes  the  ErlNifPid  variable  at  *pid to represent the
2367              calling process.
2368
2369              Returns pid if successful,  or  NULL  if  caller_env  is  not  a
2370              process bound environment.
2371
2372       int enif_send(ErlNifEnv* caller_env,
2373             ErlNifPid* to_pid, ErlNifEnv* msg_env, ERL_NIF_TERM msg)
2374
2375              Sends a message to a process.
2376
2377                caller_env:
2378                   The  environment  of  the  calling thread (process bound or
2379                  callback environment) or  NULL  if  calling  from  a  custom
2380                  thread not spawned by ERTS.
2381
2382                *to_pid:
2383                  The  pid  of the receiving process. The pid is to refer to a
2384                  process on the local node.
2385
2386                msg_env:
2387                  The environment of the message term. Must be a process inde‐
2388                  pendent environment allocated with enif_alloc_env or NULL.
2389
2390                msg:
2391                  The message term to send.
2392
2393              Returns  true if the message is successfully sent. Returns false
2394              if the send operation fails, that is:
2395
2396                * *to_pid does not refer to an alive local process.
2397
2398                * The currently executing process (that is, the sender) is not
2399                  alive.
2400
2401              The  message  environment  msg_env with all its terms (including
2402              msg) is invalidated by a successful call to enif_send. The envi‐
2403              ronment  is to either be freed with enif_free_env or cleared for
2404              reuse with enif_clear_env. An unsuccessful call will  leave  msg
2405              and msg_env still valid.
2406
2407              If msg_env is set to NULL, the msg term is copied and the origi‐
2408              nal term and its environment is still valid after the call.
2409
2410              This function is only thread-safe when  the  emulator  with  SMP
2411              support  is used. It can only be used in a non-SMP emulator from
2412              a NIF-calling thread.
2413
2414          Note:
2415              Passing msg_env as NULL is  only  supported  as  from  ERTS  8.0
2416              (Erlang/OTP 19).
2417
2418
2419       void enif_set_pid_undefined(ErlNifPid* pid)
2420
2421              Sets  an  ErlNifPid variable as undefined. See enif_is_pid_unde‐
2422              fined.
2423
2424       unsigned enif_sizeof_resource(void* obj)
2425
2426              Gets  the  byte  size  of  resource  object  obj   obtained   by
2427              enif_alloc_resource.
2428
2429       int enif_snprintf(char *str, size_t size, const
2430               char *format, ...)
2431
2432              Similar  to  snprintf  but this format string also accepts "%T",
2433              which formats Erlang terms of type ERL_NIF_TERM.
2434
2435              This function is primarily intended for debugging purpose. It is
2436              not  recommended to print very large terms with %T. The function
2437              may change errno, even if successful.
2438
2439       void enif_system_info(ErlNifSysInfo
2440               *sys_info_ptr, size_t size)
2441
2442              Same as driver_system_info.
2443
2444       int enif_term_to_binary(ErlNifEnv *env,
2445               ERL_NIF_TERM term, ErlNifBinary *bin)
2446
2447              Allocates a new binary with  enif_alloc_binary  and  stores  the
2448              result  of  encoding  term according to the Erlang external term
2449              format.
2450
2451              Returns true on success, or false if the allocation fails.
2452
2453              See also erlang:term_to_binary/1 and enif_binary_to_term.
2454
2455       ErlNifTermType enif_term_type(ErlNifEnv *env, ERL_NIF_TERM term)
2456
2457              Determines the type of the given term. The term must be an ordi‐
2458              nary  Erlang  term  and not one of the special terms returned by
2459              enif_raise_exception, enif_schedule_nif, or similar.
2460
2461              The following types are defined at the moment:
2462
2463                ERL_NIF_TERM_TYPE_ATOM:
2464
2465
2466                ERL_NIF_TERM_TYPE_BITSTRING:
2467                  A bitstring or binary
2468
2469                ERL_NIF_TERM_TYPE_FLOAT:
2470
2471
2472                ERL_NIF_TERM_TYPE_FUN:
2473
2474
2475                ERL_NIF_TERM_TYPE_INTEGER:
2476
2477
2478                ERL_NIF_TERM_TYPE_LIST:
2479                  A list, empty or not
2480
2481                ERL_NIF_TERM_TYPE_MAP:
2482
2483
2484                ERL_NIF_TERM_TYPE_PID:
2485
2486
2487                ERL_NIF_TERM_TYPE_PORT:
2488
2489
2490                ERL_NIF_TERM_TYPE_REFERENCE:
2491
2492
2493                ERL_NIF_TERM_TYPE_TUPLE:
2494
2495
2496              Note that new types may be added in the future,  so  the  caller
2497              must be prepared to handle unknown types.
2498
2499       int enif_thread_create(char *name,ErlNifTid
2500               *tid,void * (*func)(void *),void *args,ErlNifThreadOpts
2501               *opts)
2502
2503              Same as erl_drv_thread_create.
2504
2505       void enif_thread_exit(void *resp)
2506
2507              Same as erl_drv_thread_exit.
2508
2509       int enif_thread_join(ErlNifTid, void **respp)
2510
2511              Same as erl_drv_thread_join.
2512
2513       char*enif_thread_name(ErlNifTid tid)
2514
2515              Same as erl_drv_thread_name.
2516
2517       ErlNifThreadOpts *enif_thread_opts_create(char *name)
2518
2519              Same as erl_drv_thread_opts_create.
2520
2521       void enif_thread_opts_destroy(ErlNifThreadOpts *opts)
2522
2523              Same as erl_drv_thread_opts_destroy.
2524
2525       ErlNifTid enif_thread_self(void)
2526
2527              Same as erl_drv_thread_self.
2528
2529       int enif_thread_type(void)
2530
2531              Determine  the  type  of  currently executing thread. A positive
2532              value indicates a scheduler thread while  a  negative  value  or
2533              zero  indicates  another type of thread. Currently the following
2534              specific types exist (which may be extended in the future):
2535
2536                ERL_NIF_THR_UNDEFINED:
2537                  Undefined thread that is not a scheduler thread.
2538
2539                ERL_NIF_THR_NORMAL_SCHEDULER:
2540                  A normal scheduler thread.
2541
2542                ERL_NIF_THR_DIRTY_CPU_SCHEDULER:
2543                  A dirty CPU scheduler thread.
2544
2545                ERL_NIF_THR_DIRTY_IO_SCHEDULER:
2546                  A dirty I/O scheduler thread.
2547
2548       ErlNifTime enif_time_offset(ErlNifTimeUnit time_unit)
2549
2550              Returns the current time offset between  Erlang  monotonic  time
2551              and   Erlang  system time converted into the time_unit passed as
2552              argument.
2553
2554              time_unit is the time unit of the returned value.
2555
2556              Returns ERL_NIF_TIME_ERROR if called with an invalid  time  unit
2557              argument  or  if  called  from  a thread that is not a scheduler
2558              thread.
2559
2560              See also ErlNifTime and ErlNifTimeUnit.
2561
2562       void *enif_tsd_get(ErlNifTSDKey key)
2563
2564              Same as erl_drv_tsd_get.
2565
2566       int enif_tsd_key_create(char *name, ErlNifTSDKey *key)
2567
2568              Same as erl_drv_tsd_key_create.
2569
2570       void enif_tsd_key_destroy(ErlNifTSDKey key)
2571
2572              Same as erl_drv_tsd_key_destroy.
2573
2574       void enif_tsd_set(ErlNifTSDKey key, void *data)
2575
2576              Same as erl_drv_tsd_set.
2577
2578       int enif_vfprintf(FILE *stream, const char *format, va_list ap)
2579
2580
2581              Equivalent to enif_fprintf except that its called with a va_list
2582              instead of a variable number of arguments.
2583
2584       int  enif_vsnprintf(char *str, size_t size, const char *format, va_list
2585       ap)
2586
2587
2588              Equivalent to  enif_snprintf  except  that  its  called  with  a
2589              va_list instead of a variable number of arguments.
2590
2591       int enif_whereis_pid(ErlNifEnv *caller_env,
2592                 ERL_NIF_TERM name, ErlNifPid *pid)
2593
2594              Looks up a process by its registered name.
2595
2596                caller_env:
2597                  The  environment  of  the  calling  thread (process bound or
2598                  callback environment) or  NULL  if  calling  from  a  custom
2599                  thread not spawned by ERTS.
2600
2601                name:
2602                  The name of a registered process, as an atom.
2603
2604                *pid:
2605                  The ErlNifPid in which the resolved process id is stored.
2606
2607              On  success, sets *pid to the local process registered with name
2608              and returns true. If name is not a registered process, or is not
2609              an atom, false is returned and *pid is unchanged.
2610
2611              Works  as  erlang:whereis/1,  but  restricted  to processes. See
2612              enif_whereis_port to resolve registered ports.
2613
2614       int enif_whereis_port(ErlNifEnv *caller_env,
2615                 ERL_NIF_TERM name, ErlNifPort *port)
2616
2617              Looks up a port by its registered name.
2618
2619                caller_env:
2620                  The environment of the  calling  thread  (process  bound  or
2621                  callback  environment)  or  NULL  if  calling  from a custom
2622                  thread not spawned by ERTS.
2623
2624                name:
2625                  The name of a registered port, as an atom.
2626
2627                *port:
2628                  The ErlNifPort in which the resolved port id is stored.
2629
2630              On success, sets *port to the  port  registered  with  name  and
2631              returns  true.  If  name  is not a registered port, or is not an
2632              atom, false is returned and *port is unchanged.
2633
2634              Works  as  erlang:whereis/1,  but  restricted  to   ports.   See
2635              enif_whereis_pid to resolve registered processes.
2636

SEE ALSO

2638       erlang:load_nif/2
2639
2640
2641
2642Ericsson AB                        erts 11.2                        erl_nif(3)
Impressum