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

FUNCTIONALITY

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

INITIALIZATION

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

DATA TYPES

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

EXPORTS

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

SEE ALSO

2619       erlang:load_nif/2
2620
2621
2622
2623Ericsson AB                       erts 10.7.1                       erl_nif(3)
Impressum