1erl_nif(3) C Library Functions erl_nif(3)
2
6 erl_nif - API functions for an Erlang NIF library.
7
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 Warning:
16 Use this functionality with extreme care.
18 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 * A native function that crashes will crash the whole VM.
26 * 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 * 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
40 A minimal example of a NIF library can look as follows:
41 /* niftest.c */
43 #include <erl_nif.h>
44 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 static ErlNifFunc nif_funcs[] =
51 {
52 {"hello", 0, hello}
53 };
54 ERL_NIF_INIT(niftest,nif_funcs,NULL,NULL,NULL,NULL)
56 The Erlang module can look as follows:
58 -module(niftest).
60 -export([init/0, hello/0]).
62 -nifs([hello/0]).
64 -on_load(init/0).
66 init() ->
68 erlang:load_nif("./niftest", 0).
69 hello() ->
71 erlang:nif_error("NIF library not loaded").
72 Compile and test can look as follows (on Linux):
74 $> gcc -fPIC -shared -o niftest.so niftest.c -I $ERL_ROOT/usr/include/
76 $> erl
77 1> c(niftest).
79 {ok,niftest}
80 2> niftest:hello().
81 "Hello world!"
82 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 The -nifs() attribute specifies which functions in the module that are
91 to be replaced by NIFs.
92 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 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
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 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 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 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 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 enif_make_new_binary can be used as a shortcut to allocate and re‐
145 turn a binary in the same NIF call.
146 Binaries are sequences of whole bytes. Bitstrings with an arbitrary
148 bit length have no support yet.
149 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 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 The following is a template example of how to create and return a
177 resource object.
178 ERL_NIF_TERM term;
180 MyStruct* obj = enif_alloc_resource(my_resource_type, sizeof(MyStruct));
181 /* initialize struct ... */
183 term = enif_make_resource(env, obj);
185 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 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 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 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 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 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 The library initialization callbacks load and upgrade are thread-
241 safe even for shared state data.
242 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 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 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 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 Time Measurement:
269 Support for time measurement in NIF libraries:
270 * ErlNifTime
272 * ErlNifTimeUnit
274 * enif_monotonic_time()
276 * enif_time_offset()
278 * enif_convert_time_unit()
280 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 * SysIOVec
288 * ErlNifIOVec
290 * enif_ioq_create()
292 * enif_ioq_destroy()
294 * enif_ioq_enq_binary()
296 * enif_ioq_enqv()
298 * enif_ioq_deq()
300 * enif_ioq_peek()
302 * enif_ioq_peek_head()
304 * enif_inspect_iovec()
306 * enif_free_iovec()
308 Typical usage when writing to a file descriptor looks like this:
310 int writeiovec(ErlNifEnv *env, ERL_NIF_TERM term, ERL_NIF_TERM *tail,
312 ErlNifIOQueue *q, int fd) {
313 ErlNifIOVec vec, *iovec = &vec;
315 SysIOVec *sysiovec;
316 int saved_errno;
317 int iovcnt, n;
318 if (!enif_inspect_iovec(env, 64, term, tail, &iovec))
320 return -2;
321 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 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 /* Attempt to write the data */
336 n = writev(fd, sysiovec, iovcnt);
337 saved_errno = errno;
338 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 /* 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 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 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 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 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 * Make that series of NIF calls from the Erlang level.
383 * 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 Breaking up a long-running function in this manner enables the VM
390 to regain control between calls to the NIFs.
391 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 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 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 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 To schedule a dirty NIF for execution, the application has two
422 options:
423 * Set the appropriate flags value for the dirty NIF in its Erl‐
425 NifFunc entry.
426 * 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 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 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 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 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
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 MODULE is the name of the Erlang module as an identifier without
475 string quotations. It is stringified by the macro.
476 funcs is a static array of function descriptors for all the imple‐
478 mented NIFs in this library.
479 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 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 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 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 *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 load_info is the second argument to erlang:load_nif/2.
508 The library fails to load if load returns anything other than 0.
510 load can be NULL if initialization is not needed.
511 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 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 The library fails to load if upgrade returns anything other than 0
523 or if upgrade is NULL.
524 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
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 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 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 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 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 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 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 ErlNifFunc:
576 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 Describes a NIF by its name, arity, and implementation.
586 fptr:
588 A pointer to the function that implements the NIF.
589 argv:
591 Contains the function arguments passed to the NIF.
592 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 flags:
600 Is 0 for a regular NIF (and so its value can be omitted for stat‐
601 ically initialized ErlNifFunc instances).
602 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 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 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 ErlNifBinary:
617 typedef struct {
620 size_t size;
621 unsigned char* data;
622 } ErlNifBinary;
623 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 Notice that ErlNifBinary is a semi-opaque type and you are only al‐
629 lowed to read fields size and data.
630 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 When receiving data from untrusted sources, use option
636 ERL_NIF_BIN2TERM_SAFE.
637 ErlNifMonitor:
639 This is an opaque data type that identifies a monitor.
640 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 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 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 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 ErlNifResourceTypeInit:
666 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 Initialization structure read by enif_open_resource_type_x
677 enif_init_resource_type.
678 ErlNifResourceDtor:
680 typedef void ErlNifResourceDtor(ErlNifEnv* caller_env, void* obj);
683 The function prototype of a resource destructor function.
685 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 ErlNifResourceDown:
692 typedef void ErlNifResourceDown(ErlNifEnv* caller_env, void* obj, ErlNifPid* pid, ErlNifMonitor* mon);
695 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 ErlNifResourceStop:
702 typedef void ErlNifResourceStop(ErlNifEnv* caller_env, void* obj, ErlNifEvent event, int is_direct_call);
705 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 ErlNifResourceDynCall:
713 typedef void ErlNifResourceDynCall(ErlNifEnv* caller_env, void* obj, void* call_data);
716 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 ErlNifCharEncoding:
723 typedef enum {
726 ERL_NIF_LATIN1
727 }ErlNifCharEncoding;
728 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 ErlNifSysInfo:
733 Used by enif_system_info to return information about the runtime
734 system. Contains the same content as ErlDrvSysInfo.
735 ErlNifSInt64:
737 A native signed 64-bit integer type.
738 ErlNifUInt64:
740 A native unsigned 64-bit integer type.
741 ErlNifTime:
743 A signed 64-bit integer type for representation of time.
744 ErlNifTimeUnit:
746 An enumeration of time units supported by the NIF API:
747 ERL_NIF_SEC:
749 Seconds
750 ERL_NIF_MSEC:
752 Milliseconds
753 ERL_NIF_USEC:
755 Microseconds
756 ERL_NIF_NSEC:
758 Nanoseconds
759 ErlNifUniqueInteger:
761 An enumeration of the properties that can be requested from
762 enif_make_unique_integer. For default properties, use value 0.
763 ERL_NIF_UNIQUE_POSITIVE:
765 Return only positive integers.
766 ERL_NIF_UNIQUE_MONOTONIC:
768 Return only strictly monotonically increasing integer corre‐
769 sponding to creation time.
770 ErlNifHash:
772 An enumeration of the supported hash types that can be generated
773 using enif_hash.
774 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 It takes 32-bit salt values and generates hashes within
780 0..2^32-1.
781 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 It ignores salt values and generates hashes within 0..2^27-1.
787 Slower than ERL_NIF_INTERNAL_HASH. It corresponds to er‐
789 lang:phash2/1.
790 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 ErlNifIOVec:
796 typedef struct {
799 int iovcnt;
800 size_t size;
801 SysIOVec* iov;
802 } ErlNifIOVec;
803 An I/O vector containing iovcnt SysIOVecs pointing to the data. It
805 is used by enif_inspect_iovec and enif_ioq_enqv.
806 ErlNifIOQueueOpts:
808 Options to configure a ErlNifIOQueue.
809 ERL_NIF_IOQ_NORMAL:
811 Create a normal I/O Queue
812
814 void *enif_alloc(size_t size)
815 Allocates memory of size bytes.
817 Returns NULL if the allocation fails.
819 The returned pointer is suitably aligned for any built-in type
821 that fit in the allocated memory.
822 int enif_alloc_binary(size_t size, ErlNifBinary* bin)
824 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 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 Returns true on success, or false if allocation fails.
837 ErlNifEnv *enif_alloc_env()
839 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 Returns pointer to the new environment.
847 void *enif_alloc_resource(ErlNifResourceType*
849 type, unsigned size)
850 Allocates a memory-managed resource object of type type and size
852 size bytes.
853 size_t enif_binary_to_term(ErlNifEnv *env,
855 const unsigned char* data, size_t size, ERL_NIF_TERM *term,
856 ErlNifBinaryToTerm opts)
857 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 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 See also ErlNifBinaryToTerm, erlang:binary_to_term/2, and
869 enif_term_to_binary.
870 void enif_clear_env(ErlNifEnv* env)
872 Frees all terms in an environment and clears it for reuse. The
874 environment must have been allocated with enif_alloc_env.
875 int enif_compare(ERL_NIF_TERM lhs, ERL_NIF_TERM rhs)
877 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 int enif_compare_monitors(const ErlNifMonitor
883 *monitor1, const ErlNifMonitor *monitor2)
884 Compares two ErlNifMonitors. Can also be used to imply some ar‐
886 tificial order on monitors, for whatever reason.
887 Returns 0 if monitor1 and monitor2 are equal, < 0 if monitor1 <
889 monitor2, and > 0 if monitor1 > monitor2.
890 int enif_compare_pids(const ErlNifPid *pid1, const ErlNifPid *pid2)
892 Compares two ErlNifPids according to term order.
895 Returns 0 if pid1 and pid2 are equal, < 0 if pid1 < pid2, and >
897 0 if pid1 > pid2.
898 void enif_cond_broadcast(ErlNifCond *cnd)
900 Same as erl_drv_cond_broadcast.
902 ErlNifCond *enif_cond_create(char *name)
904 Same as erl_drv_cond_create.
906 void enif_cond_destroy(ErlNifCond *cnd)
908 Same as erl_drv_cond_destroy.
910 char*enif_cond_name(ErlNifCond* cnd)
912 Same as erl_drv_cond_name.
914 void enif_cond_signal(ErlNifCond *cnd)
916 Same as erl_drv_cond_signal.
918 void enif_cond_wait(ErlNifCond *cnd, ErlNifMutex *mtx)
920 Same as erl_drv_cond_wait.
922 int enif_consume_timeslice(ErlNifEnv *env, int percent)
924 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 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 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 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 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 See also the warning text at the beginning of this manual page.
955 ErlNifTime enif_convert_time_unit(ErlNifTime
957 val, ErlNifTimeUnit from, ErlNifTimeUnit to)
958 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 val:
964 Value to convert time unit for.
965 from:
967 Time unit of val.
968 to:
970 Time unit of returned value.
971 Returns ERL_NIF_TIME_ERROR if called with an invalid time unit
973 argument.
974 See also ErlNifTime and ErlNifTimeUnit.
976 ERL_NIF_TERM enif_cpu_time(ErlNifEnv *)
978 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 int enif_demonitor_process(ErlNifEnv* caller_env,
986 void* obj, const ErlNifMonitor* mon)
987 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 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 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 * never created for this resource
1001 * already cancelled
1003 * already triggered
1005 * just about to be triggered by a concurrent thread
1007 This function is thread-safe.
1009 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 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 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 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 int enif_equal_tids(ErlNifTid tid1, ErlNifTid tid2)
1031 Same as erl_drv_equal_tids.
1033 int enif_fprintf(FILE *stream, const char *format, ...)
1035 Similar to fprintf but this format string also accepts "%T",
1037 which formats Erlang terms of type ERL_NIF_TERM.
1038 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 void enif_free(void* ptr)
1044 Frees memory allocated by enif_alloc.
1046 void enif_free_env(ErlNifEnv* env)
1048 Frees an environment allocated with enif_alloc_env. All terms
1050 created in the environment are freed as well.
1051 void enif_free_iovec(ErlNifIOVec* iov)
1053 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 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 // Do things with the iovec
1065 /* Free the iovector, possibly in another thread or nif function call */
1067 enif_free_iovec(iovec);
1068 int enif_get_atom(ErlNifEnv* env, ERL_NIF_TERM
1070 term, char* buf, unsigned size, ErlNifCharEncoding encode)
1071 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 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 int enif_get_atom_length(ErlNifEnv* env,
1081 ERL_NIF_TERM term, unsigned* len, ErlNifCharEncoding encode)
1082 Sets *len to the length (number of bytes excluding terminating
1084 NULL character) of the atom term with encoding encode.
1085 Returns true on success, or false if term is not an atom.
1087 int enif_get_double(ErlNifEnv* env,
1089 ERL_NIF_TERM term, double* dp)
1090 Sets *dp to the floating-point value of term.
1092 Returns true on success, or false if term is not a float.
1094 int enif_get_int(ErlNifEnv* env, ERL_NIF_TERM
1096 term, int* ip)
1097 Sets *ip to the integer value of term.
1099 Returns true on success, or false if term is not an integer or
1101 is outside the bounds of type int.
1102 int enif_get_int64(ErlNifEnv* env, ERL_NIF_TERM
1104 term, ErlNifSInt64* ip)
1105 Sets *ip to the integer value of term.
1107 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 int enif_get_local_pid(ErlNifEnv* env,
1112 ERL_NIF_TERM term, ErlNifPid* pid)
1113 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 Note:
1120 enif_get_local_pid will return false if argument term is the
1121 atom undefined.
1122 int enif_get_local_port(ErlNifEnv* env,
1125 ERL_NIF_TERM term, ErlNifPort* port_id)
1126 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 int enif_get_list_cell(ErlNifEnv* env,
1132 ERL_NIF_TERM list, ERL_NIF_TERM* head, ERL_NIF_TERM* tail)
1133 Sets *head and *tail from list list.
1135 Returns true on success, or false if it is not a list or the
1137 list is empty.
1138 int enif_get_list_length(ErlNifEnv* env,
1140 ERL_NIF_TERM term, unsigned* len)
1141 Sets *len to the length of list term.
1143 Returns true on success, or false if term is not a proper list.
1145 int enif_get_long(ErlNifEnv* env, ERL_NIF_TERM
1147 term, long int* ip)
1148 Sets *ip to the long integer value of term.
1150 Returns true on success, or false if term is not an integer or
1152 is outside the bounds of type long int.
1153 int enif_get_map_size(ErlNifEnv* env,
1155 ERL_NIF_TERM term, size_t *size)
1156 Sets *size to the number of key-value pairs in the map term.
1158 Returns true on success, or false if term is not a map.
1160 int enif_get_map_value(ErlNifEnv* env,
1162 ERL_NIF_TERM map, ERL_NIF_TERM key, ERL_NIF_TERM* value)
1163 Sets *value to the value associated with key in the map map.
1165 Returns true on success, or false if map is not a map or if map
1167 does not contain key.
1168 int enif_get_resource(ErlNifEnv* env,
1170 ERL_NIF_TERM term, ErlNifResourceType* type, void** objp)
1171 Sets *objp to point to the resource object referred to by term.
1173 Returns true on success, or false if term is not a handle to a
1175 resource object of type type.
1176 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 int enif_get_string(ErlNifEnv* env,
1182 ERL_NIF_TERM list, char* buf, unsigned size,
1183 ErlNifCharEncoding encode)
1184 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 Returns one of the following:
1190 * The number of bytes written (including terminating NULL
1192 character)
1193 * -size if the string was truncated because of buffer space
1195 * 0 if list is not a string that can be encoded with encode or
1197 if size was < 1.
1198 The written string is always NULL-terminated, unless buffer size
1200 is < 1.
1201 int enif_get_tuple(ErlNifEnv* env, ERL_NIF_TERM
1203 term, int* arity, const ERL_NIF_TERM** array)
1204 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 Returns true on success, or false if term is not a tuple.
1212 int enif_get_uint(ErlNifEnv* env, ERL_NIF_TERM
1214 term, unsigned int* ip)
1215 Sets *ip to the unsigned integer value of term.
1217 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 int enif_get_uint64(ErlNifEnv* env,
1222 ERL_NIF_TERM term, ErlNifUInt64* ip)
1223 Sets *ip to the unsigned integer value of term.
1225 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 int enif_get_ulong(ErlNifEnv* env, ERL_NIF_TERM
1230 term, unsigned long* ip)
1231 Sets *ip to the unsigned long integer value of term.
1233 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 int enif_getenv(const char* key, char* value,
1238 size_t *value_size)
1239 Same as erl_drv_getenv.
1241 int enif_has_pending_exception(ErlNifEnv* env,
1243 ERL_NIF_TERM* reason)
1244 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 See also enif_make_badarg and enif_raise_exception.
1254 ErlNifUInt64 enif_hash(ErlNifHash type, ERL_NIF_TERM term, ErlNifUInt64
1256 salt)
1257 Hashes term according to the specified ErlNifHash type.
1259 Ranges of taken salt (if any) and returned value depend on the
1261 hash type.
1262 int enif_inspect_binary(ErlNifEnv* env,
1264 ERL_NIF_TERM bin_term, ErlNifBinary* bin)
1265 Initializes the structure pointed to by bin with information
1267 about binary term bin_term.
1268 Returns true on success, or false if bin_term is not a binary.
1270 int enif_inspect_iolist_as_binary(ErlNifEnv*
1272 env, ERL_NIF_TERM term, ErlNifBinary* bin)
1273 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 Returns true on success, or false if iolist is not an iolist.
1280 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 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 To create a list of binaries from an arbitrary iolist, use er‐
1292 lang:iolist_to_iovec/1.
1293 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 /* Don't use a pre-allocated structure */
1299 ErlNifIOVec *iovec = NULL;
1300 enif_inspect_iovec(env, max_elements, term, &tail, &iovec);
1301 /* 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 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 Returns true on success, or false if iovec_term not an iovec.
1314 ErlNifIOQueue *enif_ioq_create(ErlNifIOQueueOpts opts)
1316 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 void enif_ioq_destroy(ErlNifIOQueue *q)
1321 Destroy the I/O queue and free all of it's contents
1323 int enif_ioq_deq(ErlNifIOQueue *q, size_t count, size_t *size)
1325 Dequeue count bytes from the I/O queue. If size is not NULL, the
1327 new size of the queue is placed there.
1328 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 int enif_ioq_enq_binary(ErlNifIOQueue *q, ErlNifBinary *bin, size_t
1333 skip)
1334 Enqueue the bin into q skipping the first skip bytes.
1336 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 int enif_ioq_enqv(ErlNifIOQueue *q, ErlNifIOVec *iovec, size_t skip)
1343 Enqueue the iovec into q skipping the first skip bytes.
1345 Returns true on success, or false if skip is greater than the
1347 size of iovec.
1348 SysIOVec *enif_ioq_peek(ErlNifIOQueue *q, int *iovlen)
1350 Get the I/O queue as a pointer to an array of SysIOVecs. It also
1352 returns the number of elements in iovlen.
1353 Nothing is removed from the queue by this function, that must be
1355 done with enif_ioq_deq.
1356 The returned array is suitable to use with the Unix system call
1358 writev.
1359 int enif_ioq_peek_head(ErlNifEnv *env, ErlNifIOQueue *q, size_t *size,
1361 ERL_NIF_TERM *bin_term)
1362 Get the head of the IO Queue as a binary term.
1364 If size is not NULL, the size of the head is placed there.
1366 Nothing is removed from the queue by this function, that must be
1368 done with enif_ioq_deq.
1369 Returns true on success, or false if the queue is empty.
1371 size_t enif_ioq_size(ErlNifIOQueue *q)
1373 Get the size of q.
1375 int enif_is_atom(ErlNifEnv* env, ERL_NIF_TERM term)
1377 Returns true if term is an atom.
1379 int enif_is_binary(ErlNifEnv* env, ERL_NIF_TERM term)
1381 Returns true if term is a binary.
1383 int enif_is_current_process_alive(ErlNifEnv* env)
1385 Returns true if the currently executing process is currently
1387 alive, otherwise false.
1388 This function can only be used from a NIF-calling thread, and
1390 with an environment corresponding to currently executing pro‐
1391 cesses.
1392 int enif_is_empty_list(ErlNifEnv* env,
1394 ERL_NIF_TERM term)
1395 Returns true if term is an empty list.
1397 int enif_is_exception(ErlNifEnv* env,
1399 ERL_NIF_TERM term)
1400 Return true if term is an exception.
1402 int enif_is_fun(ErlNifEnv* env, ERL_NIF_TERM
1404 term)
1405 Returns true if term is a fun.
1407 int enif_is_identical(ERL_NIF_TERM lhs,
1409 ERL_NIF_TERM rhs)
1410 Returns true if the two terms are identical. Corresponds to the
1412 Erlang operators =:= and =/=.
1413 int enif_is_list(ErlNifEnv* env, ERL_NIF_TERM term)
1415 Returns true if term is a list.
1417 int enif_is_map(ErlNifEnv* env, ERL_NIF_TERM
1419 term)
1420 Returns true if term is a map, otherwise false.
1422 int enif_is_number(ErlNifEnv* env, ERL_NIF_TERM
1424 term)
1425 Returns true if term is a number.
1427 int enif_is_pid(ErlNifEnv* env, ERL_NIF_TERM term)
1429 Returns true if term is a pid.
1431 int enif_is_pid_undefined(const ErlNifPid* pid)
1433 Returns true if pid has been set as undefined by
1435 enif_set_pid_undefined.
1436 int enif_is_port(ErlNifEnv* env, ERL_NIF_TERM term)
1438 Returns true if term is a port.
1440 int enif_is_port_alive(ErlNifEnv* env,
1442 ErlNifPort *port_id)
1443 Returns true if port_id is alive.
1445 This function is thread-safe.
1447 int enif_is_process_alive(ErlNifEnv* env,
1449 ErlNifPid *pid)
1450 Returns true if pid is alive.
1452 This function is thread-safe.
1454 int enif_is_ref(ErlNifEnv* env, ERL_NIF_TERM term)
1456 Returns true if term is a reference.
1458 int enif_is_tuple(ErlNifEnv* env, ERL_NIF_TERM term)
1460 Returns true if term is a tuple.
1462 int enif_keep_resource(void* obj)
1464 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 ERL_NIF_TERM enif_make_atom(ErlNifEnv* env, const char* name)
1471 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 ERL_NIF_TERM enif_make_atom_len(ErlNifEnv* env,
1478 const char* name, size_t len)
1479 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 ERL_NIF_TERM enif_make_badarg(ErlNifEnv* env)
1486 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 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 See also enif_has_pending_exception and enif_raise_exception.
1499 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 ERL_NIF_TERM enif_make_binary(ErlNifEnv* env, ErlNifBinary* bin)
1508 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 ERL_NIF_TERM enif_make_copy(ErlNifEnv* dst_env,
1514 ERL_NIF_TERM src_term)
1515 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 ERL_NIF_TERM enif_make_double(ErlNifEnv* env, double d)
1520 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 int enif_make_existing_atom(ErlNifEnv* env,
1526 const char* name, ERL_NIF_TERM* atom, ErlNifCharEncoding
1527 encode)
1528 Tries to create the term of an already existing atom from the
1530 NULL-terminated C-string name with encoding encode.
1531 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 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 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 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 ERL_NIF_TERM enif_make_int(ErlNifEnv* env, int i)
1552 Creates an integer term.
1554 ERL_NIF_TERM enif_make_int64(ErlNifEnv* env, ErlNifSInt64 i)
1556 Creates an integer term from a signed 64-bit integer.
1558 ERL_NIF_TERM enif_make_list(ErlNifEnv* env, unsigned cnt, ...)
1560 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 Returns an empty list if cnt is 0.
1566 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 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 ERL_NIF_TERM enif_make_list_cell(ErlNifEnv*
1591 env, ERL_NIF_TERM head, ERL_NIF_TERM tail)
1592 Creates a list cell [head | tail].
1594 ERL_NIF_TERM enif_make_list_from_array(ErlNifEnv* env, const
1596 ERL_NIF_TERM
1597 arr[], unsigned cnt)
1598 Creates an ordinary list containing the elements of array arr of
1600 length cnt.
1601 Returns an empty list if cnt is 0.
1603 ERL_NIF_TERM enif_make_long(ErlNifEnv* env, long int i)
1605 Creates an integer term from a long int.
1607 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 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 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 The map_in term must belong to environment env.
1620 int enif_make_map_remove(ErlNifEnv* env,
1622 ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM* map_out)
1623 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 Returns true on success, or false if map_in is not a map.
1629 The map_in term must belong to environment env.
1631 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 Makes a copy of map map_in and replace the old associated value
1637 for key with new_value.
1638 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 The map_in term must belong to environment env.
1644 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 Makes a map term from the given keys and values.
1649 If successful, this function sets *map_out to the new map and
1651 returns true. Returns false there are any duplicate keys.
1652 All keys and values must belong to env.
1654 ERL_NIF_TERM enif_make_monitor_term(ErlNifEnv* env, const ErlNifMoni‐
1656 tor* mon)
1657 Creates a term identifying the given monitor received from
1659 enif_monitor_process.
1660 This function is primarily intended for debugging purpose.
1662 unsigned char *enif_make_new_binary(ErlNifEnv*
1664 env, size_t size, ERL_NIF_TERM* termp)
1665 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 Returns a pointer to the raw binary data and sets *termp to the
1673 binary term.
1674 ERL_NIF_TERM enif_make_new_map(ErlNifEnv* env)
1676 Makes an empty map term.
1678 ERL_NIF_TERM enif_make_pid(ErlNifEnv* env, const ErlNifPid* pid)
1680 Makes a pid term or the atom undefined from *pid.
1682 ERL_NIF_TERM enif_make_ref(ErlNifEnv* env)
1684 Creates a reference like erlang:make_ref/0.
1686 ERL_NIF_TERM enif_make_resource(ErlNifEnv* env, void* obj)
1688 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 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 * 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 * 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 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 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 ERL_NIF_TERM enif_make_resource_binary(ErlNifEnv* env, void* obj, const
1726 void* data, size_t size)
1727 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 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 As with enif_make_resource, no ownership transfer is done. The
1742 resource still needs to be released with enif_release_resource.
1743 int enif_make_reverse_list(ErlNifEnv* env, ERL_NIF_TERM list_in,
1745 ERL_NIF_TERM *list_out)
1746 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 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 The list_in term must belong to environment env.
1755 ERL_NIF_TERM enif_make_string(ErlNifEnv* env,
1757 const char* string, ErlNifCharEncoding encoding)
1758 Creates a list containing the characters of the NULL-terminated
1760 string string with encoding encoding.
1761 ERL_NIF_TERM enif_make_string_len(ErlNifEnv*
1763 env, const char* string, size_t len, ErlNifCharEncoding
1764 encoding)
1765 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 ERL_NIF_TERM enif_make_sub_binary(ErlNifEnv*
1771 env, ERL_NIF_TERM bin_term, size_t pos, size_t size)
1772 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 ERL_NIF_TERM enif_make_tuple(ErlNifEnv* env,
1779 unsigned cnt, ...)
1780 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 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 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 ERL_NIF_TERM enif_make_tuple_from_array(ErlNifEnv* env, const
1810 ERL_NIF_TERM
1811 arr[], unsigned cnt)
1812 Creates a tuple containing the elements of array arr of length
1814 cnt.
1815 ERL_NIF_TERM enif_make_uint(ErlNifEnv* env, unsigned int i)
1817 Creates an integer term from an unsigned int.
1819 ERL_NIF_TERM enif_make_uint64(ErlNifEnv* env, ErlNifUInt64 i)
1821 Creates an integer term from an unsigned 64-bit integer.
1823 ERL_NIF_TERM enif_make_ulong(ErlNifEnv* env, unsigned long i)
1825 Creates an integer term from an unsigned long int.
1827 ERL_NIF_TERM enif_make_unique_integer(ErlNifEnv
1829 *env, ErlNifUniqueInteger properties)
1830 Returns a unique integer with the same properties as specified
1832 by erlang:unique_integer/1.
1833 env is the environment to create the integer in.
1835 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 See also ErlNifUniqueInteger.
1842 int enif_map_iterator_create(ErlNifEnv *env,
1844 ERL_NIF_TERM map, ErlNifMapIterator *iter, ErlNifMapIteratorEn‐
1845 try
1846 entry)
1847 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 Returns true on success, or false if map is not a map.
1854 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 ERL_NIF_TERM key, value;
1860 ErlNifMapIterator iter;
1861 enif_map_iterator_create(env, my_map, &iter, ERL_NIF_MAP_ITERATOR_FIRST);
1862 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 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 void enif_map_iterator_destroy(ErlNifEnv *env,
1877 ErlNifMapIterator *iter)
1878 Destroys a map iterator created by enif_map_iterator_create.
1880 int enif_map_iterator_get_pair(ErlNifEnv *env,
1882 ErlNifMapIterator *iter, ERL_NIF_TERM *key, ERL_NIF_TERM
1883 *value)
1884 Gets key and value terms at the current map iterator position.
1886 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 int enif_map_iterator_is_head(ErlNifEnv *env,
1892 ErlNifMapIterator *iter)
1893 Returns true if map iterator iter is positioned before the first
1895 entry.
1896 int enif_map_iterator_is_tail(ErlNifEnv *env,
1898 ErlNifMapIterator *iter)
1899 Returns true if map iterator iter is positioned after the last
1901 entry.
1902 int enif_map_iterator_next(ErlNifEnv *env,
1904 ErlNifMapIterator *iter)
1905 Increments map iterator to point to the next key-value entry.
1907 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 int enif_map_iterator_prev(ErlNifEnv *env,
1913 ErlNifMapIterator *iter)
1914 Decrements map iterator to point to the previous key-value en‐
1916 try.
1917 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 int enif_monitor_process(ErlNifEnv* caller_env,
1923 void* obj, const ErlNifPid* target_pid, ErlNifMonitor* mon)
1924 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 Argument obj is pointer to the resource to hold the monitor and
1930 *target_pid identifies the local process to be monitored.
1931 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 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 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 This function is thread-safe.
1948 ErlNifTime enif_monotonic_time(ErlNifTimeUnit time_unit)
1950 Returns the current Erlang monotonic time. Notice that it is
1952 not uncommon with negative values.
1953 time_unit is the time unit of the returned value.
1955 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 See also ErlNifTime and ErlNifTimeUnit.
1961 ErlNifMutex *enif_mutex_create(char *name)
1963 Same as erl_drv_mutex_create.
1965 void enif_mutex_destroy(ErlNifMutex *mtx)
1967 Same as erl_drv_mutex_destroy.
1969 void enif_mutex_lock(ErlNifMutex *mtx)
1971 Same as erl_drv_mutex_lock.
1973 char*enif_mutex_name(ErlNifMutex* mtx)
1975 Same as erl_drv_mutex_name.
1977 int enif_mutex_trylock(ErlNifMutex *mtx)
1979 Same as erl_drv_mutex_trylock.
1981 void enif_mutex_unlock(ErlNifMutex *mtx)
1983 Same as erl_drv_mutex_unlock.
1985 ERL_NIF_TERM enif_now_time(ErlNifEnv *env)
1987 Returns an erlang:now() time stamp.
1989 This function is deprecated.
1991 ErlNifResourceType *enif_open_resource_type(ErlNifEnv* env, const char*
1993 module_str, const char* name, ErlNifResourceDtor* dtor,
1994 ErlNifResourceFlags flags, ErlNifResourceFlags* tried)
1995 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 ERL_NIF_RT_CREATE:
2001 Creates a new resource type that does not already exist.
2002 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 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 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 Notice that enif_open_resource_type is only allowed to be called
2021 in the two callbacks load and upgrade.
2022 See also enif_open_resource_type_x.
2024 ErlNifResourceType *enif_open_resource_type_x(ErlNifEnv* env, const
2026 char* name, const ErlNifResourceTypeInit* init,
2027 ErlNifResourceFlags flags, ErlNifResourceFlags* tried)
2028 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 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 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 ErlNifResourceType *enif_init_resource_type(ErlNifEnv* env, const char*
2044 name, const ErlNifResourceTypeInit* init,
2045 ErlNifResourceFlags flags, ErlNifResourceFlags* tried)
2046 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 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 int enif_port_command(ErlNifEnv* env, const
2060 ErlNifPort* to_port, ErlNifEnv *msg_env, ERL_NIF_TERM msg)
2061 Works as erlang:port_command/2, except that it is always com‐
2063 pletely asynchronous.
2064 env:
2066 The environment of the calling process. Must not be NULL.
2067 *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 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 msg:
2077 The message term to send. The same limitations apply as on
2078 the payload to erlang:port_command/2.
2079 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 Returns true if the command is successfully sent. Returns false
2087 if the command fails, for example:
2088 * *to_port does not refer to a local port.
2090 * The currently executing process (that is, the sender) is not
2092 alive.
2093 * msg is invalid.
2095 See also enif_get_local_port.
2097 void *enif_priv_data(ErlNifEnv* env)
2099 Returns the pointer to the private data that was set by load or
2101 upgrade.
2102 ERL_NIF_TERM enif_raise_exception(ErlNifEnv*
2104 env, ERL_NIF_TERM reason)
2105 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 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 See also enif_has_pending_exception and enif_make_badarg.
2119 void *enif_realloc(void* ptr, size_t size)
2121 Reallocates memory allocated by enif_alloc to size bytes.
2123 Returns NULL if the reallocation fails.
2125 The returned pointer is suitably aligned for any built-in type
2127 that fit in the allocated memory.
2128 int enif_realloc_binary(ErlNifBinary* bin, size_t size)
2130 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 Returns true on success, or false if memory allocation failed.
2136 void enif_release_binary(ErlNifBinary* bin)
2138 Releases a binary obtained from enif_alloc_binary.
2140 void enif_release_resource(void* obj)
2142 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 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 ErlNifRWLock *enif_rwlock_create(char *name)
2156 Same as erl_drv_rwlock_create.
2158 void enif_rwlock_destroy(ErlNifRWLock *rwlck)
2160 Same as erl_drv_rwlock_destroy.
2162 char*enif_rwlock_name(ErlNifRWLock* rwlck)
2164 Same as erl_drv_rwlock_name.
2166 void enif_rwlock_rlock(ErlNifRWLock *rwlck)
2168 Same as erl_drv_rwlock_rlock.
2170 void enif_rwlock_runlock(ErlNifRWLock *rwlck)
2172 Same as erl_drv_rwlock_runlock.
2174 void enif_rwlock_rwlock(ErlNifRWLock *rwlck)
2176 Same as erl_drv_rwlock_rwlock.
2178 void enif_rwlock_rwunlock(ErlNifRWLock *rwlck)
2180 Same as erl_drv_rwlock_rwunlock.
2182 int enif_rwlock_tryrlock(ErlNifRWLock *rwlck)
2184 Same as erl_drv_rwlock_tryrlock.
2186 int enif_rwlock_tryrwlock(ErlNifRWLock *rwlck)
2188 Same as erl_drv_rwlock_tryrwlock.
2190 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 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 caller_env:
2201 Must be process bound environment of the calling NIF.
2202 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 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 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 The calling NIF must use the return value of enif_schedule_nif
2222 as its own return value.
2223 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 int enif_select(ErlNifEnv* env, ErlNifEvent event, enum ErlNifSelect‐
2231 Flags mode, void* obj, const ErlNifPid* pid, ERL_NIF_TERM ref)
2232 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 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 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 {select, Obj, Ref, ready_input | ready_output}
2250 ready_input or ready_output indicates if the event object is
2252 ready for reading or writing.
2253 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 Argument pid may be NULL to indicate the calling process. It
2261 must not be set as undefined.
2262 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 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 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 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 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 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 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 Returns a non-negative value on success where the following bits
2314 can be set:
2315 ERL_NIF_SELECT_STOP_CALLED:
2317 The stop callback was called directly by enif_select.
2318 ERL_NIF_SELECT_STOP_SCHEDULED:
2320 The stop callback was scheduled to run on some other thread
2321 or later by this thread.
2322 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 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 Returns a negative value if the call failed where the following
2334 bits can be set:
2335 ERL_NIF_SELECT_INVALID_EVENT:
2337 Argument event is not a valid OS event object.
2338 ERL_NIF_SELECT_FAILED:
2340 The system call failed to add the event object to the poll
2341 set.
2342 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 Example:
2351 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 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 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 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 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 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 ErlNifPid *enif_self(ErlNifEnv* caller_env, ErlNifPid* pid)
2392 Initializes the ErlNifPid variable at *pid to represent the
2394 calling process.
2395 Returns pid if successful, or NULL if caller_env is not a
2397 process bound environment.
2398 int enif_send(ErlNifEnv* caller_env,
2400 ErlNifPid* to_pid, ErlNifEnv* msg_env, ERL_NIF_TERM msg)
2401 Sends a message to a process.
2403 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 *to_pid:
2410 The pid of the receiving process. The pid is to refer to a
2411 process on the local node.
2412 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 msg:
2418 The message term to send.
2419 Returns true if the message is successfully sent. Returns false
2421 if the send operation fails, that is:
2422 * *to_pid does not refer to an alive local process.
2424 * The currently executing process (that is, the sender) is not
2426 alive.
2427 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 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 This function is thread-safe.
2438 Note:
2440 Passing msg_env as NULL is only supported as from ERTS 8.0 (Er‐
2441 lang/OTP 19).
2442 void enif_set_pid_undefined(ErlNifPid* pid)
2445 Sets an ErlNifPid variable as undefined. See enif_is_pid_unde‐
2447 fined.
2448 unsigned enif_sizeof_resource(void* obj)
2450 Gets the byte size of resource object obj obtained by enif_al‐
2452 loc_resource.
2453 int enif_snprintf(char *str, size_t size, const
2455 char *format, ...)
2456 Similar to snprintf but this format string also accepts "%T",
2458 which formats Erlang terms of type ERL_NIF_TERM.
2459 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 void enif_system_info(ErlNifSysInfo
2465 *sys_info_ptr, size_t size)
2466 Same as driver_system_info.
2468 int enif_term_to_binary(ErlNifEnv *env,
2470 ERL_NIF_TERM term, ErlNifBinary *bin)
2471 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 Returns true on success, or false if the allocation fails.
2477 See also erlang:term_to_binary/1 and enif_binary_to_term.
2479 ErlNifTermType enif_term_type(ErlNifEnv *env, ERL_NIF_TERM term)
2481 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 The following types are defined at the moment:
2487 ERL_NIF_TERM_TYPE_ATOM:
2489 ERL_NIF_TERM_TYPE_BITSTRING:
2492 A bitstring or binary
2493 ERL_NIF_TERM_TYPE_FLOAT:
2495 ERL_NIF_TERM_TYPE_FUN:
2498 ERL_NIF_TERM_TYPE_INTEGER:
2501 ERL_NIF_TERM_TYPE_LIST:
2504 A list, empty or not
2505 ERL_NIF_TERM_TYPE_MAP:
2507 ERL_NIF_TERM_TYPE_PID:
2510 ERL_NIF_TERM_TYPE_PORT:
2513 ERL_NIF_TERM_TYPE_REFERENCE:
2516 ERL_NIF_TERM_TYPE_TUPLE:
2519 Note that new types may be added in the future, so the caller
2522 must be prepared to handle unknown types.
2523 int enif_thread_create(char *name,ErlNifTid
2525 *tid,void * (*func)(void *),void *args,ErlNifThreadOpts
2526 *opts)
2527 Same as erl_drv_thread_create.
2529 void enif_thread_exit(void *resp)
2531 Same as erl_drv_thread_exit.
2533 int enif_thread_join(ErlNifTid, void **respp)
2535 Same as erl_drv_thread_join.
2537 char*enif_thread_name(ErlNifTid tid)
2539 Same as erl_drv_thread_name.
2541 ErlNifThreadOpts *enif_thread_opts_create(char *name)
2543 Same as erl_drv_thread_opts_create.
2545 void enif_thread_opts_destroy(ErlNifThreadOpts *opts)
2547 Same as erl_drv_thread_opts_destroy.
2549 ErlNifTid enif_thread_self(void)
2551 Same as erl_drv_thread_self.
2553 int enif_thread_type(void)
2555 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 ERL_NIF_THR_UNDEFINED:
2562 Undefined thread that is not a scheduler thread.
2563 ERL_NIF_THR_NORMAL_SCHEDULER:
2565 A normal scheduler thread.
2566 ERL_NIF_THR_DIRTY_CPU_SCHEDULER:
2568 A dirty CPU scheduler thread.
2569 ERL_NIF_THR_DIRTY_IO_SCHEDULER:
2571 A dirty I/O scheduler thread.
2572 ErlNifTime enif_time_offset(ErlNifTimeUnit time_unit)
2574 Returns the current time offset between Erlang monotonic time
2576 and Erlang system time converted into the time_unit passed as
2577 argument.
2578 time_unit is the time unit of the returned value.
2580 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 See also ErlNifTime and ErlNifTimeUnit.
2586 void *enif_tsd_get(ErlNifTSDKey key)
2588 Same as erl_drv_tsd_get.
2590 int enif_tsd_key_create(char *name, ErlNifTSDKey *key)
2592 Same as erl_drv_tsd_key_create.
2594 void enif_tsd_key_destroy(ErlNifTSDKey key)
2596 Same as erl_drv_tsd_key_destroy.
2598 void enif_tsd_set(ErlNifTSDKey key, void *data)
2600 Same as erl_drv_tsd_set.
2602 int enif_vfprintf(FILE *stream, const char *format, va_list ap)
2604 Equivalent to enif_fprintf except that its called with a va_list
2607 instead of a variable number of arguments.
2608 int enif_vsnprintf(char *str, size_t size, const char *format, va_list
2610 ap)
2611 Equivalent to enif_snprintf except that its called with a
2614 va_list instead of a variable number of arguments.
2615 int enif_whereis_pid(ErlNifEnv *caller_env,
2617 ERL_NIF_TERM name, ErlNifPid *pid)
2618 Looks up a process by its registered name.
2620 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 name:
2627 The name of a registered process, as an atom.
2628 *pid:
2630 The ErlNifPid in which the resolved process id is stored.
2631 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 Works as erlang:whereis/1, but restricted to processes. See
2637 enif_whereis_port to resolve registered ports.
2638 int enif_whereis_port(ErlNifEnv *caller_env,
2640 ERL_NIF_TERM name, ErlNifPort *port)
2641 Looks up a port by its registered name.
2643 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 name:
2650 The name of a registered port, as an atom.
2651 *port:
2653 The ErlNifPort in which the resolved port id is stored.
2654 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 Works as erlang:whereis/1, but restricted to ports. See
2660 enif_whereis_pid to resolve registered processes.
2661
2663 erlang:load_nif/2
2664 NIFs (tutorial)
2665 Debugging NIFs and Port Drivers
2666Ericsson AB erts 13.1.4 erl_nif(3)