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       -nifs([hello/0]).
64
65       -on_load(init/0).
66
67       init() ->
68             erlang:load_nif("./niftest", 0).
69
70       hello() ->
71             erlang:nif_error("NIF library not loaded").
72
73       Compile and test can look as follows (on Linux):
74
75       $> gcc -fPIC -shared -o niftest.so niftest.c -I $ERL_ROOT/usr/include/
76       $> erl
77
78       1> c(niftest).
79       {ok,niftest}
80       2> niftest:hello().
81       "Hello world!"
82
83       In  the  example  above the on_load directive is used get function init
84       called automatically when the module is loaded. Function init  in  turn
85       calls  erlang:load_nif/2  which  loads the NIF library and replaces the
86       hello function with its native implementation in C. Once loaded, a  NIF
87       library  is  persistent.  It will not be unloaded until the module code
88       version that it belongs to is purged.
89
90       The -nifs() attribute specifies which functions in the module that  are
91       to be replaced by NIFs.
92
93       Each  NIF  must  have  an implementation in Erlang to be invoked if the
94       function is called before the NIF library  is  successfully  loaded.  A
95       typical such stub implementation is to call erlang:nif_error which will
96       raise an exception. The Erlang function can also be used as a  fallback
97       implementation  if  the NIF library lacks implementation for some OS or
98       hardware architecture for example.
99
100   Note:
101       A NIF does not have to be exported, it can be local to the module. How‐
102       ever,  unused  local  stub functions will be optimized away by the com‐
103       piler, causing loading of the NIF library to fail.
104
105

FUNCTIONALITY

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

INITIALIZATION

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

DATA TYPES

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

EXPORTS

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

SEE ALSO

2663       erlang:load_nif/2
2664       NIFs (tutorial)
2665       Debugging NIFs and Port Drivers
2666
2667
2668
2669Ericsson AB                       erts 13.1.4                       erl_nif(3)
Impressum