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  re‐
33           sponsiveness  of the VM, and can cause miscellaneous strange behav‐
34           iors. Such strange behaviors include, but are not limited  to,  ex‐
35           treme  memory  usage,  and  bad  load balancing between schedulers.
36           Strange behaviors that can occur because of lengthy work  can  also
37           vary between Erlang/OTP releases.
38

EXAMPLE

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

FUNCTIONALITY

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

INITIALIZATION

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

DATA TYPES

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

EXPORTS

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

SEE ALSO

2668       erlang:load_nif/2
2669
2670
2671
2672Ericsson AB                      erts 12.3.2.1                      erl_nif(3)
Impressum