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 -on_load(init/0).
64 init() ->
66 erlang:load_nif("./niftest", 0).
67 hello() ->
69 erlang:nif_error("NIF library not loaded").
70 Compile and test can look as follows (on Linux):
72 $> gcc -fPIC -shared -o niftest.so niftest.c -I $ERL_ROOT/usr/include/
74 $> erl
75 1> c(niftest).
77 {ok,niftest}
78 2> niftest:hello().
79 "Hello world!"
80 In the example above the on_load directive is used get function init
82 called automatically when the module is loaded. Function init in turn
83 calls erlang:load_nif/2 which loads the NIF library and replaces the
84 hello function with its native implementation in C. Once loaded, a NIF
85 library is persistent. It will not be unloaded until the module code
86 version that it belongs to is purged.
87 Each NIF must have an implementation in Erlang to be invoked if the
89 function is called before the NIF library is successfully loaded. A
90 typical such stub implementation is to call erlang:nif_error which will
91 raise an exception. The Erlang function can also be used as a fallback
92 implementation if the NIF library lacks implementation for some OS or
93 hardware architecture for example.
94 Note:
96 A NIF does not have to be exported, it can be local to the module. How‐
97 ever, unused local stub functions will be optimized away by the com‐
98 piler, causing loading of the NIF library to fail.
99 Warning:
102 There is a known limitation for Erlang fallback functions of NIFs.
103 Avoid functions involved in traversal of binaries by matching and re‐
104 cursion. If a NIF is loaded over such function, binary arguments to the
105 NIF may get corrupted and cause VM crash or other misbehavior.
106 Example of such bad fallback function:
108 skip_until(Byte, <<Byte, Rest/binary>>) ->
110 Rest;
111 skip_until(Byte, <<_, Rest/binary>>) ->
112 skip_until(Byte, Rest).
113
117 All interaction between NIF code and the Erlang runtime system is per‐
118 formed by calling NIF API functions. Functions exist for the following
119 functionality:
120 Read and write Erlang terms:
122 Any Erlang terms can be passed to a NIF as function arguments and
123 be returned as function return values. The terms are of C-type
124 ERL_NIF_TERM and can only be read or written using API functions.
125 Most functions to read the content of a term are prefixed enif_get_
126 and usually return true (or false) if the term is of the expected
127 type (or not). The functions to write terms are all prefixed
128 enif_make_ and usually return the created ERL_NIF_TERM. There are
129 also some functions to query terms, like enif_is_atom,
130 enif_is_identical, and enif_compare.
131 All terms of type ERL_NIF_TERM belong to an environment of type
133 ErlNifEnv. The lifetime of a term is controlled by the lifetime of
134 its environment object. All API functions that read or write terms
135 has the environment that the term belongs to as the first function
136 argument.
137 Binaries:
139 Terms of type binary are accessed with the help of struct type Erl‐
140 NifBinary, which contains a pointer (data) to the raw binary data
141 and the length (size) of the data in bytes. Both data and size are
142 read-only and are only to be written using calls to API functions.
143 Instances of ErlNifBinary are, however, always allocated by the
144 user (usually as local variables).
145 The raw data pointed to by data is only mutable after a call to
147 enif_alloc_binary or enif_realloc_binary. All other functions that
148 operate on a binary leave the data as read-only. A mutable binary
149 must in the end either be freed with enif_release_binary or made
150 read-only by transferring it to an Erlang term with enif_make_bi‐
151 nary. However, it does not have to occur in the same NIF call.
152 Read-only binaries do not have to be released.
153 enif_make_new_binary can be used as a shortcut to allocate and re‐
155 turn a binary in the same NIF call.
156 Binaries are sequences of whole bytes. Bitstrings with an arbitrary
158 bit length have no support yet.
159 Resource objects:
161 The use of resource objects is a safe way to return pointers to na‐
162 tive data structures from a NIF. A resource object is only a block
163 of memory allocated with enif_alloc_resource. A handle ("safe
164 pointer") to this memory block can then be returned to Erlang by
165 the use of enif_make_resource. The term returned by enif_make_re‐
166 source is opaque in nature. It can be stored and passed between
167 processes, but the only real end usage is to pass it back as an ar‐
168 gument to a NIF. The NIF can then call enif_get_resource and get
169 back a pointer to the memory block, which is guaranteed to still be
170 valid. A resource object is not deallocated until the last handle
171 term is garbage collected by the VM and the resource is released
172 with enif_release_resource (not necessarily in that order).
173 All resource objects are created as instances of some resource
175 type. This makes resources from different modules to be distin‐
176 guishable. A resource type is created by calling enif_open_re‐
177 source_type when a library is loaded. Objects of that resource type
178 can then later be allocated and enif_get_resource verifies that the
179 resource is of the expected type. A resource type can have a user-
180 supplied destructor function, which is automatically called when
181 resources of that type are released (by either the garbage collec‐
182 tor or enif_release_resource). Resource types are uniquely identi‐
183 fied by a supplied name string and the name of the implementing
184 module.
185 The following is a template example of how to create and return a
187 resource object.
188 ERL_NIF_TERM term;
190 MyStruct* obj = enif_alloc_resource(my_resource_type, sizeof(MyStruct));
191 /* initialize struct ... */
193 term = enif_make_resource(env, obj);
195 if (keep_a_reference_of_our_own) {
197 /* store 'obj' in static variable, private data or other resource object */
198 }
199 else {
200 enif_release_resource(obj);
201 /* resource now only owned by "Erlang" */
202 }
203 return term;
204 Notice that once enif_make_resource creates the term to return to
206 Erlang, the code can choose to either keep its own native pointer
207 to the allocated struct and release it later, or release it immedi‐
208 ately and rely only on the garbage collector to deallocate the re‐
209 source object eventually when it collects the term.
210 Another use of resource objects is to create binary terms with
212 user-defined memory management. enif_make_resource_binary creates a
213 binary term that is connected to a resource object. The destructor
214 of the resource is called when the binary is garbage collected, at
215 which time the binary data can be released. An example of this can
216 be a binary term consisting of data from a mmap'ed file. The de‐
217 structor can then do munmap to release the memory region.
218 Resource types support upgrade in runtime by allowing a loaded NIF
220 library to take over an already existing resource type and by that
221 "inherit" all existing objects of that type. The destructor of the
222 new library is thereafter called for the inherited objects and the
223 library with the old destructor function can be safely unloaded.
224 Existing resource objects, of a module that is upgraded, must ei‐
225 ther be deleted or taken over by the new NIF library. The unloading
226 of a library is postponed as long as there exist resource objects
227 with a destructor function in the library.
228 Module upgrade and static data:
230 A loaded NIF library is tied to the Erlang module instance that
231 loaded it. If the module is upgraded, the new module instance needs
232 to load its own NIF library (or maybe choose not to). The new mod‐
233 ule instance can, however, choose to load the exact same NIF li‐
234 brary as the old code if it wants to. Sharing the dynamic library
235 means that static data defined by the library is shared as well. To
236 avoid unintentionally shared static data between module instances,
237 each Erlang module version can keep its own private data. This pri‐
238 vate data can be set when the NIF library is loaded and later re‐
239 trieved by calling enif_priv_data.
240 Threads and concurrency:
242 A NIF is thread-safe without any explicit synchronization as long
243 as it acts as a pure function and only reads the supplied argu‐
244 ments. When you write to a shared state either through static vari‐
245 ables or enif_priv_data, you need to supply your own explicit syn‐
246 chronization. This includes terms in process independent environ‐
247 ments that are shared between threads. Resource objects also re‐
248 quire synchronization if you treat them as mutable.
249 The library initialization callbacks load and upgrade are thread-
251 safe even for shared state data.
252 Version Management:
254 When a NIF library is built, information about the NIF API version
255 is compiled into the library. When a NIF library is loaded, the
256 runtime system verifies that the library is of a compatible ver‐
257 sion. erl_nif.h defines the following:
258 ERL_NIF_MAJOR_VERSION:
260 Incremented when NIF library incompatible changes are made to the
261 Erlang runtime system. Normally it suffices to recompile the NIF
262 library when the ERL_NIF_MAJOR_VERSION has changed, but it can,
263 under rare circumstances, mean that NIF libraries must be
264 slightly modified. If so, this will of course be documented.
265 ERL_NIF_MINOR_VERSION:
267 Incremented when new features are added. The runtime system uses
268 the minor version to determine what features to use.
269 The runtime system normally refuses to load a NIF library if the
271 major versions differ, or if the major versions are equal and the
272 minor version used by the NIF library is greater than the one used
273 by the runtime system. Old NIF libraries with lower major versions
274 are, however, allowed after a bump of the major version during a
275 transition period of two major releases. Such old NIF libraries can
276 however fail if deprecated features are used.
277 Time Measurement:
279 Support for time measurement in NIF libraries:
280 * ErlNifTime
282 * ErlNifTimeUnit
284 * enif_monotonic_time()
286 * enif_time_offset()
288 * enif_convert_time_unit()
290 I/O Queues:
292 The Erlang nif library contains function for easily working with
293 I/O vectors as used by the unix system call writev. The I/O Queue
294 is not thread safe, so some other synchronization mechanism has to
295 be used.
296 * SysIOVec
298 * ErlNifIOVec
300 * enif_ioq_create()
302 * enif_ioq_destroy()
304 * enif_ioq_enq_binary()
306 * enif_ioq_enqv()
308 * enif_ioq_deq()
310 * enif_ioq_peek()
312 * enif_ioq_peek_head()
314 * enif_inspect_iovec()
316 * enif_free_iovec()
318 Typical usage when writing to a file descriptor looks like this:
320 int writeiovec(ErlNifEnv *env, ERL_NIF_TERM term, ERL_NIF_TERM *tail,
322 ErlNifIOQueue *q, int fd) {
323 ErlNifIOVec vec, *iovec = &vec;
325 SysIOVec *sysiovec;
326 int saved_errno;
327 int iovcnt, n;
328 if (!enif_inspect_iovec(env, 64, term, tail, &iovec))
330 return -2;
331 if (enif_ioq_size(q) > 0) {
333 /* If the I/O queue contains data we enqueue the iovec and
334 then peek the data to write out of the queue. */
335 if (!enif_ioq_enqv(q, iovec, 0))
336 return -3;
337 sysiovec = enif_ioq_peek(q, &iovcnt);
339 } else {
340 /* If the I/O queue is empty we skip the trip through it. */
341 iovcnt = iovec->iovcnt;
342 sysiovec = iovec->iov;
343 }
344 /* Attempt to write the data */
346 n = writev(fd, sysiovec, iovcnt);
347 saved_errno = errno;
348 if (enif_ioq_size(q) == 0) {
350 /* If the I/O queue was initially empty we enqueue any
351 remaining data into the queue for writing later. */
352 if (n >= 0 && !enif_ioq_enqv(q, iovec, n))
353 return -3;
354 } else {
355 /* Dequeue any data that was written from the queue. */
356 if (n > 0 && !enif_ioq_deq(q, n, NULL))
357 return -4;
358 }
359 /* return n, which is either number of bytes written or -1 if
361 some error happened */
362 errno = saved_errno;
363 return n;
364 }
365 Long-running NIFs:
367 As mentioned in the warning text at the beginning of this manual
368 page, it is of vital importance that a native function returns rel‐
369 atively fast. It is difficult to give an exact maximum amount of
370 time that a native function is allowed to work, but usually a well-
371 behaving native function is to return to its caller within 1 mil‐
372 lisecond. This can be achieved using different approaches. If you
373 have full control over the code to execute in the native function,
374 the best approach is to divide the work into multiple chunks of
375 work and call the native function multiple times. This is, however,
376 not always possible, for example when calling third-party li‐
377 braries.
378 The enif_consume_timeslice() function can be used to inform the
380 runtime system about the length of the NIF call. It is typically
381 always to be used unless the NIF executes very fast.
382 If the NIF call is too lengthy, this must be handled in one of the
384 following ways to avoid degraded responsiveness, scheduler load
385 balancing problems, and other strange behaviors:
386 Yielding NIF:
388 If the functionality of a long-running NIF can be split so that
389 its work can be achieved through a series of shorter NIF calls,
390 the application has two options:
391 * Make that series of NIF calls from the Erlang level.
393 * Call a NIF that first performs a chunk of the work, then in‐
395 vokes the enif_schedule_nif function to schedule another NIF
396 call to perform the next chunk. The final call scheduled in
397 this manner can then return the overall result.
398 Breaking up a long-running function in this manner enables the VM
400 to regain control between calls to the NIFs.
401 This approach is always preferred over the other alternatives de‐
403 scribed below. This both from a performance perspective and a
404 system characteristics perspective.
405 Threaded NIF:
407 This is accomplished by dispatching the work to another thread
408 managed by the NIF library, return from the NIF, and wait for the
409 result. The thread can send the result back to the Erlang process
410 using enif_send. Information about thread primitives is provided
411 below.
412 Dirty NIF:
414 A NIF that cannot be split and cannot execute in a millisecond or
415 less is called a "dirty NIF", as it performs work that the ordi‐
416 nary schedulers of the Erlang runtime system cannot handle
417 cleanly. Applications that make use of such functions must indi‐
418 cate to the runtime that the functions are dirty so they can be
419 handled specially. This is handled by executing dirty jobs on a
420 separate set of schedulers called dirty schedulers. A dirty NIF
421 executing on a dirty scheduler does not have the same duration
422 restriction as a normal NIF.
423 It is important to classify the dirty job correct. An I/O bound
425 job should be classified as such, and a CPU bound job should be
426 classified as such. If you should classify CPU bound jobs as I/O
427 bound jobs, dirty I/O schedulers might starve ordinary sched‐
428 ulers. I/O bound jobs are expected to either block waiting for
429 I/O, and/or spend a limited amount of time moving data.
430 To schedule a dirty NIF for execution, the application has two
432 options:
433 * Set the appropriate flags value for the dirty NIF in its Erl‐
435 NifFunc entry.
436 * Call enif_schedule_nif, pass to it a pointer to the dirty NIF
438 to be executed, and indicate with argument flags whether it ex‐
439 pects the operation to be CPU-bound or I/O-bound.
440 A job that alternates between I/O bound and CPU bound can be re‐
442 classified and rescheduled using enif_schedule_nif so that it ex‐
443 ecutes on the correct type of dirty scheduler at all times. For
444 more information see the documentation of the erl(1) command line
445 arguments +SDcpu, and +SDio.
446 While a process executes a dirty NIF, some operations that commu‐
448 nicate with it can take a very long time to complete. Suspend or
449 garbage collection of a process executing a dirty NIF cannot be
450 done until the dirty NIF has returned. Thus, other processes
451 waiting for such operations to complete might have to wait for a
452 very long time. Blocking multi-scheduling, that is, calling er‐
453 lang:system_flag(multi_scheduling, block), can also take a very
454 long time to complete. This is because all ongoing dirty opera‐
455 tions on all dirty schedulers must complete before the block op‐
456 eration can complete.
457 Many operations communicating with a process executing a dirty
459 NIF can, however, complete while it executes the dirty NIF. For
460 example, retrieving information about it through process_info,
461 setting its group leader, register/unregister its name, and so
462 on.
463 Termination of a process executing a dirty NIF can only be com‐
465 pleted up to a certain point while it executes the dirty NIF. All
466 Erlang resources, such as its registered name and its ETS tables,
467 are released. All links and monitors are triggered. The execution
468 of the NIF is, however, not stopped. The NIF can safely continue
469 execution, allocate heap memory, and so on, but it is of course
470 better to stop executing as soon as possible. The NIF can check
471 whether a current process is alive using enif_is_cur‐
472 rent_process_alive. Communication using enif_send and
473 enif_port_command is also dropped when the sending process is not
474 alive. Deallocation of certain internal resources, such as
475 process heap and process control block, is delayed until the
476 dirty NIF has completed.
477
479 ERL_NIF_INIT(MODULE, ErlNifFunc funcs[], load, NULL, upgrade, un‐
480 load):
481 This is the magic macro to initialize a NIF library. It is to be
482 evaluated in global file scope.
483 MODULE is the name of the Erlang module as an identifier without
485 string quotations. It is stringified by the macro.
486 funcs is a static array of function descriptors for all the imple‐
488 mented NIFs in this library.
489 load, upgrade and unload are pointers to functions. One of load or
491 upgrade is called to initialize the library. unload is called to
492 release the library. All are described individually below.
493 The fourth argument NULL is ignored. It was earlier used for the
495 deprecated reload callback which is no longer supported since OTP
496 20.
497 If compiling a NIF for static inclusion through --enable-static-
499 nifs, you must define STATIC_ERLANG_NIF before the ERL_NIF_INIT
500 declaration.
501 int (*load)(ErlNifEnv* caller_env, void** priv_data, ERL_NIF_TERM
503 load_info):
504 load is called when the NIF library is loaded and no previously
505 loaded library exists for this module.
506 *priv_data can be set to point to some private data if the library
508 needs to keep a state between NIF calls. enif_priv_data returns
509 this pointer. *priv_data is initialized to NULL when load is
510 called.
511 load_info is the second argument to erlang:load_nif/2.
513 The library fails to load if load returns anything other than 0.
515 load can be NULL if initialization is not needed.
516 int (*upgrade)(ErlNifEnv* caller_env, void** priv_data, void**
518 old_priv_data, ERL_NIF_TERM load_info):
519 upgrade is called when the NIF library is loaded and there is old
520 code of this module with a loaded NIF library.
521 Works as load, except that *old_priv_data already contains the
523 value set by the last call to load or upgrade for the old module
524 code. *priv_data is initialized to NULL when upgrade is called. It
525 is allowed to write to both *priv_data and *old_priv_data.
526 The library fails to load if upgrade returns anything other than 0
528 or if upgrade is NULL.
529 void (*unload)(ErlNifEnv* caller_env, void* priv_data):
531 unload is called when the module code that the NIF library belongs
532 to is purged as old. New code of the same module may or may not ex‐
533 ist.
534
536 ERL_NIF_TERM:
537 Variables of type ERL_NIF_TERM can refer to any Erlang term. This
538 is an opaque type and values of it can only by used either as argu‐
539 ments to API functions or as return values from NIFs. All
540 ERL_NIF_TERMs belong to an environment (ErlNifEnv). A term cannot
541 be destructed individually, it is valid until its environment is
542 destructed.
543 ErlNifEnv:
545 ErlNifEnv represents an environment that can host Erlang terms. All
546 terms in an environment are valid as long as the environment is
547 valid. ErlNifEnv is an opaque type; pointers to it can only be
548 passed on to API functions. Three types of environments exist:
549 Process bound environment:
551 Passed as the first argument to all NIFs. All function arguments
552 passed to a NIF belong to that environment. The return value from
553 a NIF must also be a term belonging to the same environment.
554 A process bound environment contains transient information about
556 the calling Erlang process. The environment is only valid in the
557 thread where it was supplied as argument until the NIF returns.
558 It is thus useless and dangerous to store pointers to process
559 bound environments between NIF calls.
560 Callback environment:
562 Passed as the first argument to all the non-NIF callback func‐
563 tions (load, upgrade, unload, dtor, down, stop and dyncall).
564 Works like a process bound environment but with a temporary
565 pseudo process that "terminates" when the callback has returned.
566 Terms may be created in this environment but they will only be
567 accessible during the callback.
568 Process independent environment:
570 Created by calling enif_alloc_env. This environment can be used
571 to store terms between NIF calls and to send terms with
572 enif_send. A process independent environment with all its terms
573 is valid until you explicitly invalidate it with enif_free_env or
574 enif_send.
575 All contained terms of a list/tuple/map must belong to the same en‐
577 vironment as the list/tuple/map itself. Terms can be copied between
578 environments with enif_make_copy.
579 ErlNifFunc:
581 typedef struct {
584 const char* name;
585 unsigned arity;
586 ERL_NIF_TERM (*fptr)(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]);
587 unsigned flags;
588 } ErlNifFunc;
589 Describes a NIF by its name, arity, and implementation.
591 fptr:
593 A pointer to the function that implements the NIF.
594 argv:
596 Contains the function arguments passed to the NIF.
597 argc:
599 The array length, that is, the function arity. argv[N-1] thus de‐
600 notes the Nth argument to the NIF. Notice that the argument argc
601 allows for the same C function to implement several Erlang func‐
602 tions with different arity (but probably with the same name).
603 flags:
605 Is 0 for a regular NIF (and so its value can be omitted for stat‐
606 ically initialized ErlNifFunc instances).
607 flags can be used to indicate that the NIF is a dirty NIF that is
609 to be executed on a dirty scheduler thread.
610 If the dirty NIF is expected to be CPU-bound, its flags field is
612 to be set to ERL_NIF_DIRTY_JOB_CPU_BOUND or
613 ERL_NIF_DIRTY_JOB_IO_BOUND.
614 Note:
616 If one of the ERL_NIF_DIRTY_JOB_*_BOUND flags is set, and the run‐
617 time system has no support for dirty schedulers, the runtime system
618 refuses to load the NIF library.
619 ErlNifBinary:
622 typedef struct {
625 size_t size;
626 unsigned char* data;
627 } ErlNifBinary;
628 ErlNifBinary contains transient information about an inspected bi‐
630 nary term. data is a pointer to a buffer of size bytes with the raw
631 content of the binary.
632 Notice that ErlNifBinary is a semi-opaque type and you are only al‐
634 lowed to read fields size and data.
635 ErlNifBinaryToTerm:
637 An enumeration of the options that can be specified to enif_bi‐
638 nary_to_term. For default behavior, use value 0.
639 When receiving data from untrusted sources, use option
641 ERL_NIF_BIN2TERM_SAFE.
642 ErlNifMonitor:
644 This is an opaque data type that identifies a monitor.
645 The nif writer is to provide the memory for storing the monitor
647 when calling enif_monitor_process. The address of the data is not
648 stored by the runtime system, so ErlNifMonitor can be used as any
649 other data, it can be copied, moved in memory, forgotten, and so
650 on. To compare two monitors, enif_compare_monitors must be used.
651 ErlNifPid:
653 A process identifier (pid). In contrast to pid terms (instances of
654 ERL_NIF_TERM), ErlNifPids are self-contained and not bound to any
655 environment. ErlNifPid is an opaque type. It can be copied, moved
656 in memory, forgotten, and so on.
657 ErlNifPort:
659 A port identifier. In contrast to port ID terms (instances of
660 ERL_NIF_TERM), ErlNifPorts are self-contained and not bound to any
661 environment. ErlNifPort is an opaque type. It can be copied, moved
662 in memory, forgotten, and so on.
663 ErlNifResourceType:
665 Each instance of ErlNifResourceType represents a class of memory-
666 managed resource objects that can be garbage collected. Each re‐
667 source type has a unique name and a destructor function that is
668 called when objects of its type are released.
669 ErlNifResourceTypeInit:
671 typedef struct {
674 ErlNifResourceDtor* dtor; // #1 Destructor
675 ErlNifResourceStop* stop; // #2 Select stop
676 ErlNifResourceDown* down; // #3 Monitor down
677 int members;
678 ErlNifResourceDynCall* dyncall; // #4 Dynamic call
679 } ErlNifResourceTypeInit;
680 Initialization structure read by enif_open_resource_type_x
682 enif_init_resource_type.
683 ErlNifResourceDtor:
685 typedef void ErlNifResourceDtor(ErlNifEnv* caller_env, void* obj);
688 The function prototype of a resource destructor function.
690 The obj argument is a pointer to the resource. The only allowed use
692 for the resource in the destructor is to access its user data one
693 final time. The destructor is guaranteed to be the last callback
694 before the resource is deallocated.
695 ErlNifResourceDown:
697 typedef void ErlNifResourceDown(ErlNifEnv* caller_env, void* obj, ErlNifPid* pid, ErlNifMonitor* mon);
700 The function prototype of a resource down function, called on the
702 behalf of enif_monitor_process. obj is the resource, pid is the
703 identity of the monitored process that is exiting, and mon is the
704 identity of the monitor.
705 ErlNifResourceStop:
707 typedef void ErlNifResourceStop(ErlNifEnv* caller_env, void* obj, ErlNifEvent event, int is_direct_call);
710 The function prototype of a resource stop function, called on the
712 behalf of enif_select. obj is the resource, event is OS event,
713 is_direct_call is true if the call is made directly from enif_se‐
714 lect or false if it is a scheduled call (potentially from another
715 thread).
716 ErlNifResourceDynCall:
718 typedef void ErlNifResourceDynCall(ErlNifEnv* caller_env, void* obj, void* call_data);
721 The function prototype of a dynamic resource call function, called
723 by enif_dynamic_resource_call. Argument obj is the resource object
724 and call_data is the last argument to enif_dynamic_resource_call
725 passed through.
726 ErlNifCharEncoding:
728 typedef enum {
731 ERL_NIF_LATIN1
732 }ErlNifCharEncoding;
733 The character encoding used in strings and atoms. The only sup‐
735 ported encoding is ERL_NIF_LATIN1 for ISO Latin-1 (8-bit ASCII).
736 ErlNifSysInfo:
738 Used by enif_system_info to return information about the runtime
739 system. Contains the same content as ErlDrvSysInfo.
740 ErlNifSInt64:
742 A native signed 64-bit integer type.
743 ErlNifUInt64:
745 A native unsigned 64-bit integer type.
746 ErlNifTime:
748 A signed 64-bit integer type for representation of time.
749 ErlNifTimeUnit:
751 An enumeration of time units supported by the NIF API:
752 ERL_NIF_SEC:
754 Seconds
755 ERL_NIF_MSEC:
757 Milliseconds
758 ERL_NIF_USEC:
760 Microseconds
761 ERL_NIF_NSEC:
763 Nanoseconds
764 ErlNifUniqueInteger:
766 An enumeration of the properties that can be requested from
767 enif_make_unique_integer. For default properties, use value 0.
768 ERL_NIF_UNIQUE_POSITIVE:
770 Return only positive integers.
771 ERL_NIF_UNIQUE_MONOTONIC:
773 Return only strictly monotonically increasing integer corre‐
774 sponding to creation time.
775 ErlNifHash:
777 An enumeration of the supported hash types that can be generated
778 using enif_hash.
779 ERL_NIF_INTERNAL_HASH:
781 Non-portable hash function that only guarantees the same hash for
782 the same term within one Erlang VM instance.
783 It takes 32-bit salt values and generates hashes within
785 0..2^32-1.
786 ERL_NIF_PHASH2:
788 Portable hash function that gives the same hash for the same Er‐
789 lang term regardless of machine architecture and ERTS version.
790 It ignores salt values and generates hashes within 0..2^27-1.
792 Slower than ERL_NIF_INTERNAL_HASH. It corresponds to er‐
794 lang:phash2/1.
795 SysIOVec:
797 A system I/O vector, as used by writev on Unix and WSASend on
798 Win32. It is used in ErlNifIOVec and by enif_ioq_peek.
799 ErlNifIOVec:
801 typedef struct {
804 int iovcnt;
805 size_t size;
806 SysIOVec* iov;
807 } ErlNifIOVec;
808 An I/O vector containing iovcnt SysIOVecs pointing to the data. It
810 is used by enif_inspect_iovec and enif_ioq_enqv.
811 ErlNifIOQueueOpts:
813 Options to configure a ErlNifIOQueue.
814 ERL_NIF_IOQ_NORMAL:
816 Create a normal I/O Queue
817
819 void *enif_alloc(size_t size)
820 Allocates memory of size bytes.
822 Returns NULL if the allocation fails.
824 The returned pointer is suitably aligned for any built-in type
826 that fit in the allocated memory.
827 int enif_alloc_binary(size_t size, ErlNifBinary* bin)
829 Allocates a new binary of size size bytes. Initializes the
831 structure pointed to by bin to refer to the allocated binary.
832 The binary must either be released by enif_release_binary or
833 ownership transferred to an Erlang term with enif_make_binary.
834 An allocated (and owned) ErlNifBinary can be kept between NIF
835 calls.
836 If you do not need to reallocate or keep the data alive across
838 NIF calls, consider using enif_make_new_binary instead as it
839 will allocate small binaries on the process heap when possible.
840 Returns true on success, or false if allocation fails.
842 ErlNifEnv *enif_alloc_env()
844 Allocates a new process independent environment. The environment
846 can be used to hold terms that are not bound to any process.
847 Such terms can later be copied to a process environment with
848 enif_make_copy or be sent to a process as a message with
849 enif_send.
850 Returns pointer to the new environment.
852 void *enif_alloc_resource(ErlNifResourceType*
854 type, unsigned size)
855 Allocates a memory-managed resource object of type type and size
857 size bytes.
858 size_t enif_binary_to_term(ErlNifEnv *env,
860 const unsigned char* data, size_t size, ERL_NIF_TERM *term,
861 ErlNifBinaryToTerm opts)
862 Creates a term that is the result of decoding the binary data at
864 data, which must be encoded according to the Erlang external
865 term format. No more than size bytes are read from data. Argu‐
866 ment opts corresponds to the second argument to erlang:bi‐
867 nary_to_term/2 and must be either 0 or ERL_NIF_BIN2TERM_SAFE.
868 On success, stores the resulting term at *term and returns the
870 number of bytes read. Returns 0 if decoding fails or if opts is
871 invalid.
872 See also ErlNifBinaryToTerm, erlang:binary_to_term/2, and
874 enif_term_to_binary.
875 void enif_clear_env(ErlNifEnv* env)
877 Frees all terms in an environment and clears it for reuse. The
879 environment must have been allocated with enif_alloc_env.
880 int enif_compare(ERL_NIF_TERM lhs, ERL_NIF_TERM rhs)
882 Returns an integer < 0 if lhs < rhs, 0 if lhs = rhs, and > 0 if
884 lhs > rhs. Corresponds to the Erlang operators ==, /=, =<, <,
885 >=, and > (but not =:= or =/=).
886 int enif_compare_monitors(const ErlNifMonitor
888 *monitor1, const ErlNifMonitor *monitor2)
889 Compares two ErlNifMonitors. Can also be used to imply some ar‐
891 tificial order on monitors, for whatever reason.
892 Returns 0 if monitor1 and monitor2 are equal, < 0 if monitor1 <
894 monitor2, and > 0 if monitor1 > monitor2.
895 int enif_compare_pids(const ErlNifPid *pid1, const ErlNifPid *pid2)
897 Compares two ErlNifPids according to term order.
900 Returns 0 if pid1 and pid2 are equal, < 0 if pid1 < pid2, and >
902 0 if pid1 > pid2.
903 void enif_cond_broadcast(ErlNifCond *cnd)
905 Same as erl_drv_cond_broadcast.
907 ErlNifCond *enif_cond_create(char *name)
909 Same as erl_drv_cond_create.
911 void enif_cond_destroy(ErlNifCond *cnd)
913 Same as erl_drv_cond_destroy.
915 char*enif_cond_name(ErlNifCond* cnd)
917 Same as erl_drv_cond_name.
919 void enif_cond_signal(ErlNifCond *cnd)
921 Same as erl_drv_cond_signal.
923 void enif_cond_wait(ErlNifCond *cnd, ErlNifMutex *mtx)
925 Same as erl_drv_cond_wait.
927 int enif_consume_timeslice(ErlNifEnv *env, int percent)
929 Gives the runtime system a hint about how much CPU time the cur‐
931 rent NIF call has consumed since the last hint, or since the
932 start of the NIF if no previous hint has been specified. The
933 time is specified as a percent of the timeslice that a process
934 is allowed to execute Erlang code until it can be suspended to
935 give time for other runnable processes. The scheduling timeslice
936 is not an exact entity, but can usually be approximated to about
937 1 millisecond.
938 Notice that it is up to the runtime system to determine if and
940 how to use this information. Implementations on some platforms
941 can use other means to determine consumed CPU time. Lengthy NIFs
942 should regardless of this frequently call enif_consume_timeslice
943 to determine if it is allowed to continue execution.
944 Argument percent must be an integer between 1 and 100. This
946 function must only be called from a NIF-calling thread, and ar‐
947 gument env must be the environment of the calling process.
948 Returns 1 if the timeslice is exhausted, otherwise 0. If 1 is
950 returned, the NIF is to return as soon as possible in order for
951 the process to yield.
952 This function is provided to better support co-operative sched‐
954 uling, improve system responsiveness, and make it easier to pre‐
955 vent misbehaviors of the VM because of a NIF monopolizing a
956 scheduler thread. It can be used to divide length work into a
957 number of repeated NIF calls without the need to create threads.
958 See also the warning text at the beginning of this manual page.
960 ErlNifTime enif_convert_time_unit(ErlNifTime
962 val, ErlNifTimeUnit from, ErlNifTimeUnit to)
963 Converts the val value of time unit from to the corresponding
965 value of time unit to. The result is rounded using the floor
966 function.
967 val:
969 Value to convert time unit for.
970 from:
972 Time unit of val.
973 to:
975 Time unit of returned value.
976 Returns ERL_NIF_TIME_ERROR if called with an invalid time unit
978 argument.
979 See also ErlNifTime and ErlNifTimeUnit.
981 ERL_NIF_TERM enif_cpu_time(ErlNifEnv *)
983 Returns the CPU time in the same format as erlang:timestamp().
985 The CPU time is the time the current logical CPU has spent exe‐
986 cuting since some arbitrary point in the past. If the OS does
987 not support fetching this value, enif_cpu_time invokes
988 enif_make_badarg.
989 int enif_demonitor_process(ErlNifEnv* caller_env,
991 void* obj, const ErlNifMonitor* mon)
992 Cancels a monitor created earlier with enif_monitor_process. Ar‐
994 gument obj is a pointer to the resource holding the monitor and
995 *mon identifies the monitor.
996 Argument caller_env is the environment of the calling thread
998 (process bound or callback environment) or NULL if calling from
999 a custom thread not spawned by ERTS.
1000 Returns 0 if the monitor was successfully identified and re‐
1002 moved. Returns a non-zero value if the monitor could not be
1003 identified, which means it was either
1004 * never created for this resource
1006 * already cancelled
1008 * already triggered
1010 * just about to be triggered by a concurrent thread
1012 This function is thread-safe.
1014 int enif_dynamic_resource_call(ErlNifEnv* caller_env, ERL_NIF_MOD‐
1016 ULE rt_module, ERL_NIF_MODULE rt_name, ERL_NIF_TERM resource,
1017 void* call_data)
1018 Call code of a resource type implemented by another NIF module.
1020 The atoms rt_module and rt_name identifies the resource type to
1021 be called. Argument resource identifies a resource object of
1022 that type.
1023 The callback dyncall of the identified resource type will be
1025 called with a pointer to the resource objects obj and the argu‐
1026 ment call_data passed through. The call_data argument is typi‐
1027 cally a pointer to a struct used to passed both arguments to the
1028 dyncall function as well as results back to the caller.
1029 Returns 0 if the dyncall callback function was called. Returns a
1031 non-zero value if no call was made, which happens if rt_module
1032 and rt_name did not identify a resource type with a dyncall
1033 callback or if resource was not a resource object of that type.
1034 int enif_equal_tids(ErlNifTid tid1, ErlNifTid tid2)
1036 Same as erl_drv_equal_tids.
1038 int enif_fprintf(FILE *stream, const char *format, ...)
1040 Similar to fprintf but this format string also accepts "%T",
1042 which formats Erlang terms of type ERL_NIF_TERM.
1043 This function is primarily intended for debugging purpose. It is
1045 not recommended to print very large terms with %T. The function
1046 may change errno, even if successful.
1047 void enif_free(void* ptr)
1049 Frees memory allocated by enif_alloc.
1051 void enif_free_env(ErlNifEnv* env)
1053 Frees an environment allocated with enif_alloc_env. All terms
1055 created in the environment are freed as well.
1056 void enif_free_iovec(ErlNifIOVec* iov)
1058 Frees an io vector returned from enif_inspect_iovec. This is
1060 needed only if a NULL environment is passed to enif_in‐
1061 spect_iovec.
1062 ErlNifIOVec *iovec = NULL;
1064 size_t max_elements = 128;
1065 ERL_NIF_TERM tail;
1066 if (!enif_inspect_iovec(NULL, max_elements, term, &tail, &iovec))
1067 return 0;
1068 // Do things with the iovec
1070 /* Free the iovector, possibly in another thread or nif function call */
1072 enif_free_iovec(iovec);
1073 int enif_get_atom(ErlNifEnv* env, ERL_NIF_TERM
1075 term, char* buf, unsigned size, ErlNifCharEncoding encode)
1076 Writes a NULL-terminated string in the buffer pointed to by buf
1078 of size size, consisting of the string representation of the
1079 atom term with encoding encode.
1080 Returns the number of bytes written (including terminating NULL
1082 character) or 0 if term is not an atom with maximum length of
1083 size-1.
1084 int enif_get_atom_length(ErlNifEnv* env,
1086 ERL_NIF_TERM term, unsigned* len, ErlNifCharEncoding encode)
1087 Sets *len to the length (number of bytes excluding terminating
1089 NULL character) of the atom term with encoding encode.
1090 Returns true on success, or false if term is not an atom.
1092 int enif_get_double(ErlNifEnv* env,
1094 ERL_NIF_TERM term, double* dp)
1095 Sets *dp to the floating-point value of term.
1097 Returns true on success, or false if term is not a float.
1099 int enif_get_int(ErlNifEnv* env, ERL_NIF_TERM
1101 term, int* ip)
1102 Sets *ip to the integer value of term.
1104 Returns true on success, or false if term is not an integer or
1106 is outside the bounds of type int.
1107 int enif_get_int64(ErlNifEnv* env, ERL_NIF_TERM
1109 term, ErlNifSInt64* ip)
1110 Sets *ip to the integer value of term.
1112 Returns true on success, or false if term is not an integer or
1114 is outside the bounds of a signed 64-bit integer.
1115 int enif_get_local_pid(ErlNifEnv* env,
1117 ERL_NIF_TERM term, ErlNifPid* pid)
1118 If term is the pid of a node local process, this function ini‐
1120 tializes the pid variable *pid from it and returns true. Other‐
1121 wise returns false. No check is done to see if the process is
1122 alive.
1123 Note:
1125 enif_get_local_pid will return false if argument term is the
1126 atom undefined.
1127 int enif_get_local_port(ErlNifEnv* env,
1130 ERL_NIF_TERM term, ErlNifPort* port_id)
1131 If term identifies a node local port, this function initializes
1133 the port variable *port_id from it and returns true. Otherwise
1134 returns false. No check is done to see if the port is alive.
1135 int enif_get_list_cell(ErlNifEnv* env,
1137 ERL_NIF_TERM list, ERL_NIF_TERM* head, ERL_NIF_TERM* tail)
1138 Sets *head and *tail from list list.
1140 Returns true on success, or false if it is not a list or the
1142 list is empty.
1143 int enif_get_list_length(ErlNifEnv* env,
1145 ERL_NIF_TERM term, unsigned* len)
1146 Sets *len to the length of list term.
1148 Returns true on success, or false if term is not a proper list.
1150 int enif_get_long(ErlNifEnv* env, ERL_NIF_TERM
1152 term, long int* ip)
1153 Sets *ip to the long integer value of term.
1155 Returns true on success, or false if term is not an integer or
1157 is outside the bounds of type long int.
1158 int enif_get_map_size(ErlNifEnv* env,
1160 ERL_NIF_TERM term, size_t *size)
1161 Sets *size to the number of key-value pairs in the map term.
1163 Returns true on success, or false if term is not a map.
1165 int enif_get_map_value(ErlNifEnv* env,
1167 ERL_NIF_TERM map, ERL_NIF_TERM key, ERL_NIF_TERM* value)
1168 Sets *value to the value associated with key in the map map.
1170 Returns true on success, or false if map is not a map or if map
1172 does not contain key.
1173 int enif_get_resource(ErlNifEnv* env,
1175 ERL_NIF_TERM term, ErlNifResourceType* type, void** objp)
1176 Sets *objp to point to the resource object referred to by term.
1178 Returns true on success, or false if term is not a handle to a
1180 resource object of type type.
1181 enif_get_resource does not add a reference to the resource ob‐
1183 ject. However, the pointer received in *objp is guaranteed to be
1184 valid at least as long as the resource handle term is valid.
1185 int enif_get_string(ErlNifEnv* env,
1187 ERL_NIF_TERM list, char* buf, unsigned size,
1188 ErlNifCharEncoding encode)
1189 Writes a NULL-terminated string in the buffer pointed to by buf
1191 with size size, consisting of the characters in the string list.
1192 The characters are written using encoding encode.
1193 Returns one of the following:
1195 * The number of bytes written (including terminating NULL
1197 character)
1198 * -size if the string was truncated because of buffer space
1200 * 0 if list is not a string that can be encoded with encode or
1202 if size was < 1.
1203 The written string is always NULL-terminated, unless buffer size
1205 is < 1.
1206 int enif_get_tuple(ErlNifEnv* env, ERL_NIF_TERM
1208 term, int* arity, const ERL_NIF_TERM** array)
1209 If term is a tuple, this function sets *array to point to an ar‐
1211 ray containing the elements of the tuple, and sets *arity to the
1212 number of elements. Notice that the array is read-only and (*ar‐
1213 ray)[N-1] is the Nth element of the tuple. *array is undefined
1214 if the arity of the tuple is zero.
1215 Returns true on success, or false if term is not a tuple.
1217 int enif_get_uint(ErlNifEnv* env, ERL_NIF_TERM
1219 term, unsigned int* ip)
1220 Sets *ip to the unsigned integer value of term.
1222 Returns true on success, or false if term is not an unsigned in‐
1224 teger or is outside the bounds of type unsigned int.
1225 int enif_get_uint64(ErlNifEnv* env,
1227 ERL_NIF_TERM term, ErlNifUInt64* ip)
1228 Sets *ip to the unsigned integer value of term.
1230 Returns true on success, or false if term is not an unsigned in‐
1232 teger or is outside the bounds of an unsigned 64-bit integer.
1233 int enif_get_ulong(ErlNifEnv* env, ERL_NIF_TERM
1235 term, unsigned long* ip)
1236 Sets *ip to the unsigned long integer value of term.
1238 Returns true on success, or false if term is not an unsigned in‐
1240 teger or is outside the bounds of type unsigned long.
1241 int enif_getenv(const char* key, char* value,
1243 size_t *value_size)
1244 Same as erl_drv_getenv.
1246 int enif_has_pending_exception(ErlNifEnv* env,
1248 ERL_NIF_TERM* reason)
1249 Returns true if a pending exception is associated with the envi‐
1251 ronment env. If reason is a NULL pointer, ignore it. Otherwise,
1252 if a pending exception associated with env exists, set *reason
1253 to the value of the exception term. For example, if
1254 enif_make_badarg is called to set a pending badarg exception, a
1255 later call to enif_has_pending_exception(env, &reason) sets
1256 *reason to the atom badarg, then return true.
1257 See also enif_make_badarg and enif_raise_exception.
1259 ErlNifUInt64 enif_hash(ErlNifHash type, ERL_NIF_TERM term, ErlNifUInt64
1261 salt)
1262 Hashes term according to the specified ErlNifHash type.
1264 Ranges of taken salt (if any) and returned value depend on the
1266 hash type.
1267 int enif_inspect_binary(ErlNifEnv* env,
1269 ERL_NIF_TERM bin_term, ErlNifBinary* bin)
1270 Initializes the structure pointed to by bin with information
1272 about binary term bin_term.
1273 Returns true on success, or false if bin_term is not a binary.
1275 int enif_inspect_iolist_as_binary(ErlNifEnv*
1277 env, ERL_NIF_TERM term, ErlNifBinary* bin)
1278 Initializes the structure pointed to by bin with a continuous
1280 buffer with the same byte content as iolist. As with inspect_bi‐
1281 nary, the data pointed to by bin is transient and does not need
1282 to be released.
1283 Returns true on success, or false if iolist is not an iolist.
1285 int enif_inspect_iovec(ErlNifEnv*
1287 env, size_t max_elements, ERL_NIF_TERM iovec_term,
1288 ERL_NIF_TERM* tail,
1289 ErlNifIOVec** iovec)
1290 Fills iovec with the list of binaries provided in iovec_term.
1292 The number of elements handled in the call is limited to max_el‐
1293 ements, and tail is set to the remainder of the list. Note that
1294 the output may be longer than max_elements on some platforms.
1295 To create a list of binaries from an arbitrary iolist, use er‐
1297 lang:iolist_to_iovec/1.
1298 When calling this function, iovec should contain a pointer to
1300 NULL or a ErlNifIOVec structure that should be used if possible.
1301 e.g.
1302 /* Don't use a pre-allocated structure */
1304 ErlNifIOVec *iovec = NULL;
1305 enif_inspect_iovec(env, max_elements, term, &tail, &iovec);
1306 /* Use a stack-allocated vector as an optimization for vectors with few elements */
1308 ErlNifIOVec vec, *iovec = &vec;
1309 enif_inspect_iovec(env, max_elements, term, &tail, &iovec);
1310 The contents of the iovec is valid until the called nif function
1313 returns. If the iovec should be valid after the nif call re‐
1314 turns, it is possible to call this function with a NULL environ‐
1315 ment. If no environment is given the iovec owns the data in the
1316 vector and it has to be explicitly freed using enif_free_iovec.
1317 Returns true on success, or false if iovec_term not an iovec.
1319 ErlNifIOQueue *enif_ioq_create(ErlNifIOQueueOpts opts)
1321 Create a new I/O Queue that can be used to store data. opts has
1323 to be set to ERL_NIF_IOQ_NORMAL.
1324 void enif_ioq_destroy(ErlNifIOQueue *q)
1326 Destroy the I/O queue and free all of it's contents
1328 int enif_ioq_deq(ErlNifIOQueue *q, size_t count, size_t *size)
1330 Dequeue count bytes from the I/O queue. If size is not NULL, the
1332 new size of the queue is placed there.
1333 Returns true on success, or false if the I/O does not contain
1335 count bytes. On failure the queue is left un-altered.
1336 int enif_ioq_enq_binary(ErlNifIOQueue *q, ErlNifBinary *bin, size_t
1338 skip)
1339 Enqueue the bin into q skipping the first skip bytes.
1341 Returns true on success, or false if skip is greater than the
1343 size of bin. Any ownership of the binary data is transferred to
1344 the queue and bin is to be considered read-only for the rest of
1345 the NIF call and then as released.
1346 int enif_ioq_enqv(ErlNifIOQueue *q, ErlNifIOVec *iovec, size_t skip)
1348 Enqueue the iovec into q skipping the first skip bytes.
1350 Returns true on success, or false if skip is greater than the
1352 size of iovec.
1353 SysIOVec *enif_ioq_peek(ErlNifIOQueue *q, int *iovlen)
1355 Get the I/O queue as a pointer to an array of SysIOVecs. It also
1357 returns the number of elements in iovlen.
1358 Nothing is removed from the queue by this function, that must be
1360 done with enif_ioq_deq.
1361 The returned array is suitable to use with the Unix system call
1363 writev.
1364 int enif_ioq_peek_head(ErlNifEnv *env, ErlNifIOQueue *q, size_t *size,
1366 ERL_NIF_TERM *bin_term)
1367 Get the head of the IO Queue as a binary term.
1369 If size is not NULL, the size of the head is placed there.
1371 Nothing is removed from the queue by this function, that must be
1373 done with enif_ioq_deq.
1374 Returns true on success, or false if the queue is empty.
1376 size_t enif_ioq_size(ErlNifIOQueue *q)
1378 Get the size of q.
1380 int enif_is_atom(ErlNifEnv* env, ERL_NIF_TERM term)
1382 Returns true if term is an atom.
1384 int enif_is_binary(ErlNifEnv* env, ERL_NIF_TERM term)
1386 Returns true if term is a binary.
1388 int enif_is_current_process_alive(ErlNifEnv* env)
1390 Returns true if the currently executing process is currently
1392 alive, otherwise false.
1393 This function can only be used from a NIF-calling thread, and
1395 with an environment corresponding to currently executing pro‐
1396 cesses.
1397 int enif_is_empty_list(ErlNifEnv* env,
1399 ERL_NIF_TERM term)
1400 Returns true if term is an empty list.
1402 int enif_is_exception(ErlNifEnv* env,
1404 ERL_NIF_TERM term)
1405 Return true if term is an exception.
1407 int enif_is_fun(ErlNifEnv* env, ERL_NIF_TERM
1409 term)
1410 Returns true if term is a fun.
1412 int enif_is_identical(ERL_NIF_TERM lhs,
1414 ERL_NIF_TERM rhs)
1415 Returns true if the two terms are identical. Corresponds to the
1417 Erlang operators =:= and =/=.
1418 int enif_is_list(ErlNifEnv* env, ERL_NIF_TERM term)
1420 Returns true if term is a list.
1422 int enif_is_map(ErlNifEnv* env, ERL_NIF_TERM
1424 term)
1425 Returns true if term is a map, otherwise false.
1427 int enif_is_number(ErlNifEnv* env, ERL_NIF_TERM
1429 term)
1430 Returns true if term is a number.
1432 int enif_is_pid(ErlNifEnv* env, ERL_NIF_TERM term)
1434 Returns true if term is a pid.
1436 int enif_is_pid_undefined(const ErlNifPid* pid)
1438 Returns true if pid has been set as undefined by
1440 enif_set_pid_undefined.
1441 int enif_is_port(ErlNifEnv* env, ERL_NIF_TERM term)
1443 Returns true if term is a port.
1445 int enif_is_port_alive(ErlNifEnv* env,
1447 ErlNifPort *port_id)
1448 Returns true if port_id is alive.
1450 This function is thread-safe.
1452 int enif_is_process_alive(ErlNifEnv* env,
1454 ErlNifPid *pid)
1455 Returns true if pid is alive.
1457 This function is thread-safe.
1459 int enif_is_ref(ErlNifEnv* env, ERL_NIF_TERM term)
1461 Returns true if term is a reference.
1463 int enif_is_tuple(ErlNifEnv* env, ERL_NIF_TERM term)
1465 Returns true if term is a tuple.
1467 int enif_keep_resource(void* obj)
1469 Adds a reference to resource object obj obtained from enif_al‐
1471 loc_resource. Each call to enif_keep_resource for an object must
1472 be balanced by a call to enif_release_resource before the object
1473 is destructed.
1474 ERL_NIF_TERM enif_make_atom(ErlNifEnv* env, const char* name)
1476 Creates an atom term from the NULL-terminated C-string name with
1478 ISO Latin-1 encoding. If the length of name exceeds the maximum
1479 length allowed for an atom (255 characters), enif_make_atom in‐
1480 vokes enif_make_badarg.
1481 ERL_NIF_TERM enif_make_atom_len(ErlNifEnv* env,
1483 const char* name, size_t len)
1484 Create an atom term from the string name with length len. NULL
1486 characters are treated as any other characters. If len exceeds
1487 the maximum length allowed for an atom (255 characters),
1488 enif_make_atom invokes enif_make_badarg.
1489 ERL_NIF_TERM enif_make_badarg(ErlNifEnv* env)
1491 Makes a badarg exception to be returned from a NIF, and asso‐
1493 ciates it with environment env. Once a NIF or any function it
1494 calls invokes enif_make_badarg, the runtime ensures that a
1495 badarg exception is raised when the NIF returns, even if the NIF
1496 attempts to return a non-exception term instead.
1497 The return value from enif_make_badarg can be used only as the
1499 return value from the NIF that invoked it (directly or indi‐
1500 rectly) or be passed to enif_is_exception, but not to any other
1501 NIF API function.
1502 See also enif_has_pending_exception and enif_raise_exception.
1504 Note:
1506 Before ERTS 7.0 (Erlang/OTP 18), the return value from
1507 enif_make_badarg had to be returned from the NIF. This require‐
1508 ment is now lifted as the return value from the NIF is ignored
1509 if enif_make_badarg has been invoked.
1510 ERL_NIF_TERM enif_make_binary(ErlNifEnv* env, ErlNifBinary* bin)
1513 Makes a binary term from bin. Any ownership of the binary data
1515 is transferred to the created term and bin is to be considered
1516 read-only for the rest of the NIF call and then as released.
1517 ERL_NIF_TERM enif_make_copy(ErlNifEnv* dst_env,
1519 ERL_NIF_TERM src_term)
1520 Makes a copy of term src_term. The copy is created in environ‐
1522 ment dst_env. The source term can be located in any environment.
1523 ERL_NIF_TERM enif_make_double(ErlNifEnv* env, double d)
1525 Creates a floating-point term from a double. If argument double
1527 is not finite or is NaN, enif_make_double invokes
1528 enif_make_badarg.
1529 int enif_make_existing_atom(ErlNifEnv* env,
1531 const char* name, ERL_NIF_TERM* atom, ErlNifCharEncoding
1532 encode)
1533 Tries to create the term of an already existing atom from the
1535 NULL-terminated C-string name with encoding encode.
1536 If the atom already exists, this function stores the term in
1538 *atom and returns true, otherwise false. Also returns false if
1539 the length of name exceeds the maximum length allowed for an
1540 atom (255 characters).
1541 int enif_make_existing_atom_len(ErlNifEnv* env,
1543 const char* name, size_t len, ERL_NIF_TERM* atom, ErlNifCharEn‐
1544 coding
1545 encoding)
1546 Tries to create the term of an already existing atom from the
1548 string name with length len and encoding encode. NULL characters
1549 are treated as any other characters.
1550 If the atom already exists, this function stores the term in
1552 *atom and returns true, otherwise false. Also returns false if
1553 len exceeds the maximum length allowed for an atom (255 charac‐
1554 ters).
1555 ERL_NIF_TERM enif_make_int(ErlNifEnv* env, int i)
1557 Creates an integer term.
1559 ERL_NIF_TERM enif_make_int64(ErlNifEnv* env, ErlNifSInt64 i)
1561 Creates an integer term from a signed 64-bit integer.
1563 ERL_NIF_TERM enif_make_list(ErlNifEnv* env, unsigned cnt, ...)
1565 Creates an ordinary list term of length cnt. Expects cnt number
1567 of arguments (after cnt) of type ERL_NIF_TERM as the elements of
1568 the list.
1569 Returns an empty list if cnt is 0.
1571 ERL_NIF_TERM enif_make_list1(ErlNifEnv* env, ERL_NIF_TERM e1)
1573 ERL_NIF_TERM enif_make_list2(ErlNifEnv* env,
1574 ERL_NIF_TERM e1, ERL_NIF_TERM e2)
1575 ERL_NIF_TERM enif_make_list3(ErlNifEnv* env,
1576 ERL_NIF_TERM e1, ERL_NIF_TERM e2, ERL_NIF_TERM e3)
1577 ERL_NIF_TERM enif_make_list4(ErlNifEnv* env,
1578 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e4)
1579 ERL_NIF_TERM enif_make_list5(ErlNifEnv* env,
1580 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e5)
1581 ERL_NIF_TERM enif_make_list6(ErlNifEnv* env,
1582 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e6)
1583 ERL_NIF_TERM enif_make_list7(ErlNifEnv* env,
1584 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e7)
1585 ERL_NIF_TERM enif_make_list8(ErlNifEnv* env,
1586 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e8)
1587 ERL_NIF_TERM enif_make_list9(ErlNifEnv* env,
1588 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e9)
1589 Creates an ordinary list term with length indicated by the func‐
1591 tion name. Prefer these functions (macros) over the variadic
1592 enif_make_list to get a compile-time error if the number of ar‐
1593 guments does not match.
1594 ERL_NIF_TERM enif_make_list_cell(ErlNifEnv*
1596 env, ERL_NIF_TERM head, ERL_NIF_TERM tail)
1597 Creates a list cell [head | tail].
1599 ERL_NIF_TERM enif_make_list_from_array(ErlNifEnv* env, const
1601 ERL_NIF_TERM
1602 arr[], unsigned cnt)
1603 Creates an ordinary list containing the elements of array arr of
1605 length cnt.
1606 Returns an empty list if cnt is 0.
1608 ERL_NIF_TERM enif_make_long(ErlNifEnv* env, long int i)
1610 Creates an integer term from a long int.
1612 int enif_make_map_put(ErlNifEnv* env,
1614 ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM value,
1615 ERL_NIF_TERM* map_out)
1616 Makes a copy of map map_in and inserts key with value. If key
1618 already exists in map_in, the old associated value is replaced
1619 by value.
1620 If successful, this function sets *map_out to the new map and
1622 returns true. Returns false if map_in is not a map.
1623 The map_in term must belong to environment env.
1625 int enif_make_map_remove(ErlNifEnv* env,
1627 ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM* map_out)
1628 If map map_in contains key, this function makes a copy of map_in
1630 in *map_out, and removes key and the associated value. If map
1631 map_in does not contain key, *map_out is set to map_in.
1632 Returns true on success, or false if map_in is not a map.
1634 The map_in term must belong to environment env.
1636 int enif_make_map_update(ErlNifEnv* env,
1638 ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM new_value,
1639 ERL_NIF_TERM* map_out)
1640 Makes a copy of map map_in and replace the old associated value
1642 for key with new_value.
1643 If successful, this function sets *map_out to the new map and
1645 returns true. Returns false if map_in is not a map or if it does
1646 not contain key.
1647 The map_in term must belong to environment env.
1649 int enif_make_map_from_arrays(ErlNifEnv* env, ERL_NIF_TERM keys[],
1651 ERL_NIF_TERM values[], size_t cnt, ERL_NIF_TERM *map_out)
1652 Makes a map term from the given keys and values.
1654 If successful, this function sets *map_out to the new map and
1656 returns true. Returns false there are any duplicate keys.
1657 All keys and values must belong to env.
1659 ERL_NIF_TERM enif_make_monitor_term(ErlNifEnv* env, const ErlNifMoni‐
1661 tor* mon)
1662 Creates a term identifying the given monitor received from
1664 enif_monitor_process.
1665 This function is primarily intended for debugging purpose.
1667 unsigned char *enif_make_new_binary(ErlNifEnv*
1669 env, size_t size, ERL_NIF_TERM* termp)
1670 Allocates a binary of size size bytes and creates an owning
1672 term. The binary data is mutable until the calling NIF returns.
1673 This is a quick way to create a new binary without having to use
1674 ErlNifBinary. The drawbacks are that the binary cannot be kept
1675 between NIF calls and it cannot be reallocated.
1676 Returns a pointer to the raw binary data and sets *termp to the
1678 binary term.
1679 ERL_NIF_TERM enif_make_new_map(ErlNifEnv* env)
1681 Makes an empty map term.
1683 ERL_NIF_TERM enif_make_pid(ErlNifEnv* env, const ErlNifPid* pid)
1685 Makes a pid term or the atom undefined from *pid.
1687 ERL_NIF_TERM enif_make_ref(ErlNifEnv* env)
1689 Creates a reference like erlang:make_ref/0.
1691 ERL_NIF_TERM enif_make_resource(ErlNifEnv* env, void* obj)
1693 Creates an opaque handle to a memory-managed resource object ob‐
1695 tained by enif_alloc_resource. No ownership transfer is done, as
1696 the resource object still needs to be released by enif_re‐
1697 lease_resource. However, notice that the call to enif_re‐
1698 lease_resource can occur immediately after obtaining the term
1699 from enif_make_resource, in which case the resource object is
1700 deallocated when the term is garbage collected. For more de‐
1701 tails, see the example of creating and returning a resource ob‐
1702 ject in the User's Guide.
1703 Note:
1705 Since ERTS 9.0 (OTP-20.0), resource terms have a defined behav‐
1706 ior when compared and serialized through term_to_binary or
1707 passed between nodes.
1708 * Two resource terms will compare equal if and only if they
1710 would yield the same resource object pointer when passed to
1711 enif_get_resource.
1712 * A resource term can be serialized with term_to_binary and
1714 later be fully recreated if the resource object is still
1715 alive when binary_to_term is called. A stale resource term
1716 will be returned from binary_to_term if the resource object
1717 has been deallocated. enif_get_resource will return false
1718 for stale resource terms.
1719 The same principles of serialization apply when passing re‐
1721 source terms in messages to remote nodes and back again. A
1722 resource term will act stale on all nodes except the node
1723 where its resource object is still alive in memory.
1724 Before ERTS 9.0 (OTP-20.0), all resource terms did compare equal
1726 to each other and to empty binaries (<<>>). If serialized, they
1727 would be recreated as plain empty binaries.
1728 ERL_NIF_TERM enif_make_resource_binary(ErlNifEnv* env, void* obj, const
1731 void* data, size_t size)
1732 Creates a binary term that is memory-managed by a resource ob‐
1734 ject obj obtained by enif_alloc_resource. The returned binary
1735 term consists of size bytes pointed to by data. This raw binary
1736 data must be kept readable and unchanged until the destructor of
1737 the resource is called. The binary data can be stored external
1738 to the resource object, in which case the destructor is respon‐
1739 sible for releasing the data.
1740 Several binary terms can be managed by the same resource object.
1742 The destructor is not called until the last binary is garbage
1743 collected. This can be useful to return different parts of a
1744 larger binary buffer.
1745 As with enif_make_resource, no ownership transfer is done. The
1747 resource still needs to be released with enif_release_resource.
1748 int enif_make_reverse_list(ErlNifEnv* env, ERL_NIF_TERM list_in,
1750 ERL_NIF_TERM *list_out)
1751 Sets *list_out to the reverse list of the list list_in and re‐
1753 turns true, or returns false if list_in is not a list.
1754 This function is only to be used on short lists, as a copy is
1756 created of the list, which is not released until after the NIF
1757 returns.
1758 The list_in term must belong to environment env.
1760 ERL_NIF_TERM enif_make_string(ErlNifEnv* env,
1762 const char* string, ErlNifCharEncoding encoding)
1763 Creates a list containing the characters of the NULL-terminated
1765 string string with encoding encoding.
1766 ERL_NIF_TERM enif_make_string_len(ErlNifEnv*
1768 env, const char* string, size_t len, ErlNifCharEncoding
1769 encoding)
1770 Creates a list containing the characters of the string string
1772 with length len and encoding encoding. NULL characters are
1773 treated as any other characters.
1774 ERL_NIF_TERM enif_make_sub_binary(ErlNifEnv*
1776 env, ERL_NIF_TERM bin_term, size_t pos, size_t size)
1777 Makes a subbinary of binary bin_term, starting at zero-based po‐
1779 sition pos with a length of size bytes. bin_term must be a bi‐
1780 nary or bitstring. pos+size must be less or equal to the number
1781 of whole bytes in bin_term.
1782 ERL_NIF_TERM enif_make_tuple(ErlNifEnv* env,
1784 unsigned cnt, ...)
1785 Creates a tuple term of arity cnt. Expects cnt number of argu‐
1787 ments (after cnt) of type ERL_NIF_TERM as the elements of the
1788 tuple.
1789 ERL_NIF_TERM enif_make_tuple1(ErlNifEnv* env,
1791 ERL_NIF_TERM e1)
1792 ERL_NIF_TERM enif_make_tuple2(ErlNifEnv* env,
1793 ERL_NIF_TERM e1, ERL_NIF_TERM e2)
1794 ERL_NIF_TERM enif_make_tuple3(ErlNifEnv* env,
1795 ERL_NIF_TERM e1, ERL_NIF_TERM e2, ERL_NIF_TERM e3)
1796 ERL_NIF_TERM enif_make_tuple4(ErlNifEnv* env,
1797 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e4)
1798 ERL_NIF_TERM enif_make_tuple5(ErlNifEnv* env,
1799 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e5)
1800 ERL_NIF_TERM enif_make_tuple6(ErlNifEnv* env,
1801 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e6)
1802 ERL_NIF_TERM enif_make_tuple7(ErlNifEnv* env,
1803 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e7)
1804 ERL_NIF_TERM enif_make_tuple8(ErlNifEnv* env,
1805 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e8)
1806 ERL_NIF_TERM enif_make_tuple9(ErlNifEnv* env,
1807 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e9)
1808 Creates a tuple term with length indicated by the function name.
1810 Prefer these functions (macros) over the variadic enif_make_tu‐
1811 ple to get a compile-time error if the number of arguments does
1812 not match.
1813 ERL_NIF_TERM enif_make_tuple_from_array(ErlNifEnv* env, const
1815 ERL_NIF_TERM
1816 arr[], unsigned cnt)
1817 Creates a tuple containing the elements of array arr of length
1819 cnt.
1820 ERL_NIF_TERM enif_make_uint(ErlNifEnv* env, unsigned int i)
1822 Creates an integer term from an unsigned int.
1824 ERL_NIF_TERM enif_make_uint64(ErlNifEnv* env, ErlNifUInt64 i)
1826 Creates an integer term from an unsigned 64-bit integer.
1828 ERL_NIF_TERM enif_make_ulong(ErlNifEnv* env, unsigned long i)
1830 Creates an integer term from an unsigned long int.
1832 ERL_NIF_TERM enif_make_unique_integer(ErlNifEnv
1834 *env, ErlNifUniqueInteger properties)
1835 Returns a unique integer with the same properties as specified
1837 by erlang:unique_integer/1.
1838 env is the environment to create the integer in.
1840 ERL_NIF_UNIQUE_POSITIVE and ERL_NIF_UNIQUE_MONOTONIC can be
1842 passed as the second argument to change the properties of the
1843 integer returned. They can be combined by OR:ing the two values
1844 together.
1845 See also ErlNifUniqueInteger.
1847 int enif_map_iterator_create(ErlNifEnv *env,
1849 ERL_NIF_TERM map, ErlNifMapIterator *iter, ErlNifMapIteratorEn‐
1850 try
1851 entry)
1852 Creates an iterator for the map map by initializing the struc‐
1854 ture pointed to by iter. Argument entry determines the start po‐
1855 sition of the iterator: ERL_NIF_MAP_ITERATOR_FIRST or
1856 ERL_NIF_MAP_ITERATOR_LAST.
1857 Returns true on success, or false if map is not a map.
1859 A map iterator is only useful during the lifetime of environment
1861 env that the map belongs to. The iterator must be destroyed by
1862 calling enif_map_iterator_destroy:
1863 ERL_NIF_TERM key, value;
1865 ErlNifMapIterator iter;
1866 enif_map_iterator_create(env, my_map, &iter, ERL_NIF_MAP_ITERATOR_FIRST);
1867 while (enif_map_iterator_get_pair(env, &iter, &key, &value)) {
1869 do_something(key,value);
1870 enif_map_iterator_next(env, &iter);
1871 }
1872 enif_map_iterator_destroy(env, &iter);
1873 Note:
1875 The key-value pairs of a map have no defined iteration order.
1876 The only guarantee is that the iteration order of a single map
1877 instance is preserved during the lifetime of the environment
1878 that the map belongs to.
1879 void enif_map_iterator_destroy(ErlNifEnv *env,
1882 ErlNifMapIterator *iter)
1883 Destroys a map iterator created by enif_map_iterator_create.
1885 int enif_map_iterator_get_pair(ErlNifEnv *env,
1887 ErlNifMapIterator *iter, ERL_NIF_TERM *key, ERL_NIF_TERM
1888 *value)
1889 Gets key and value terms at the current map iterator position.
1891 On success, sets *key and *value and returns true. Returns false
1893 if the iterator is positioned at head (before first entry) or
1894 tail (beyond last entry).
1895 int enif_map_iterator_is_head(ErlNifEnv *env,
1897 ErlNifMapIterator *iter)
1898 Returns true if map iterator iter is positioned before the first
1900 entry.
1901 int enif_map_iterator_is_tail(ErlNifEnv *env,
1903 ErlNifMapIterator *iter)
1904 Returns true if map iterator iter is positioned after the last
1906 entry.
1907 int enif_map_iterator_next(ErlNifEnv *env,
1909 ErlNifMapIterator *iter)
1910 Increments map iterator to point to the next key-value entry.
1912 Returns true if the iterator is now positioned at a valid key-
1914 value entry, or false if the iterator is positioned at the tail
1915 (beyond the last entry).
1916 int enif_map_iterator_prev(ErlNifEnv *env,
1918 ErlNifMapIterator *iter)
1919 Decrements map iterator to point to the previous key-value en‐
1921 try.
1922 Returns true if the iterator is now positioned at a valid key-
1924 value entry, or false if the iterator is positioned at the head
1925 (before the first entry).
1926 int enif_monitor_process(ErlNifEnv* caller_env,
1928 void* obj, const ErlNifPid* target_pid, ErlNifMonitor* mon)
1929 Starts monitoring a process from a resource. When a process is
1931 monitored, a process exit results in a call to the provided down
1932 callback associated with the resource type.
1933 Argument obj is pointer to the resource to hold the monitor and
1935 *target_pid identifies the local process to be monitored.
1936 If mon is not NULL, a successful call stores the identity of the
1938 monitor in the ErlNifMonitor struct pointed to by mon. This
1939 identifier is used to refer to the monitor for later removal
1940 with enif_demonitor_process or compare with enif_compare_moni‐
1941 tors. A monitor is automatically removed when it triggers or
1942 when the resource is deallocated.
1943 Argument caller_env is the environment of the calling thread
1945 (process bound or callback environment) or NULL if calling from
1946 a custom thread not spawned by ERTS.
1947 Returns 0 on success, < 0 if no down callback is provided, and >
1949 0 if the process is no longer alive or if target_pid is unde‐
1950 fined.
1951 This function is thread-safe.
1953 ErlNifTime enif_monotonic_time(ErlNifTimeUnit time_unit)
1955 Returns the current Erlang monotonic time. Notice that it is
1957 not uncommon with negative values.
1958 time_unit is the time unit of the returned value.
1960 Returns ERL_NIF_TIME_ERROR if called with an invalid time unit
1962 argument, or if called from a thread that is not a scheduler
1963 thread.
1964 See also ErlNifTime and ErlNifTimeUnit.
1966 ErlNifMutex *enif_mutex_create(char *name)
1968 Same as erl_drv_mutex_create.
1970 void enif_mutex_destroy(ErlNifMutex *mtx)
1972 Same as erl_drv_mutex_destroy.
1974 void enif_mutex_lock(ErlNifMutex *mtx)
1976 Same as erl_drv_mutex_lock.
1978 char*enif_mutex_name(ErlNifMutex* mtx)
1980 Same as erl_drv_mutex_name.
1982 int enif_mutex_trylock(ErlNifMutex *mtx)
1984 Same as erl_drv_mutex_trylock.
1986 void enif_mutex_unlock(ErlNifMutex *mtx)
1988 Same as erl_drv_mutex_unlock.
1990 ERL_NIF_TERM enif_now_time(ErlNifEnv *env)
1992 Returns an erlang:now() time stamp.
1994 This function is deprecated.
1996 ErlNifResourceType *enif_open_resource_type(ErlNifEnv* env, const char*
1998 module_str, const char* name, ErlNifResourceDtor* dtor,
1999 ErlNifResourceFlags flags, ErlNifResourceFlags* tried)
2000 Creates or takes over a resource type identified by the string
2002 name and gives it the destructor function pointed to by dtor.
2003 Argument flags can have the following values:
2004 ERL_NIF_RT_CREATE:
2006 Creates a new resource type that does not already exist.
2007 ERL_NIF_RT_TAKEOVER:
2009 Opens an existing resource type and takes over ownership of
2010 all its instances. The supplied destructor dtor is called
2011 both for existing instances and new instances not yet cre‐
2012 ated by the calling NIF library.
2013 The two flag values can be combined with bitwise OR. The re‐
2015 source type name is local to the calling module. Argument mod‐
2016 ule_str is not (yet) used and must be NULL. dtor can be NULL if
2017 no destructor is needed.
2018 On success, the function returns a pointer to the resource type
2020 and *tried is set to either ERL_NIF_RT_CREATE or
2021 ERL_NIF_RT_TAKEOVER to indicate what was done. On failure, re‐
2022 turns NULL and sets *tried to flags. It is allowed to set tried
2023 to NULL.
2024 Notice that enif_open_resource_type is only allowed to be called
2026 in the two callbacks load and upgrade.
2027 See also enif_open_resource_type_x.
2029 ErlNifResourceType *enif_open_resource_type_x(ErlNifEnv* env, const
2031 char* name, const ErlNifResourceTypeInit* init,
2032 ErlNifResourceFlags flags, ErlNifResourceFlags* tried)
2033 Same as enif_open_resource_type except it accepts additional
2035 callback functions for resource types that are used together
2036 with enif_select and enif_monitor_process.
2037 Argument init is a pointer to an ErlNifResourceTypeInit struc‐
2039 ture that contains the function pointers for destructor, down
2040 and stop callbacks for the resource type.
2041 Note:
2043 Only members dtor, down and stop in ErlNifResourceTypeInit are
2044 read by enif_open_resource_type_x. To implement the new dyncall
2045 callback use enif_init_resource_type.
2046 ErlNifResourceType *enif_init_resource_type(ErlNifEnv* env, const char*
2049 name, const ErlNifResourceTypeInit* init,
2050 ErlNifResourceFlags flags, ErlNifResourceFlags* tried)
2051 Same as enif_open_resource_type_x except it accepts an addi‐
2053 tional callback function for resource types that are used to‐
2054 gether with enif_dynamic_resource_call.
2055 Argument init is a pointer to an ErlNifResourceTypeInit struc‐
2057 ture that contains the callback function pointers dtor, down,
2058 stop and the new dyncall. The struct also contains the field
2059 members that must be set to the number of initialized callbacks
2060 counted from the top of the struct. For example, to initialize
2061 all callbacks including dyncall, members should be set to 4. All
2062 callbacks are optional and may be set to NULL.
2063 int enif_port_command(ErlNifEnv* env, const
2065 ErlNifPort* to_port, ErlNifEnv *msg_env, ERL_NIF_TERM msg)
2066 Works as erlang:port_command/2, except that it is always com‐
2068 pletely asynchronous.
2069 env:
2071 The environment of the calling process. Must not be NULL.
2072 *to_port:
2074 The port ID of the receiving port. The port ID is to refer
2075 to a port on the local node.
2076 msg_env:
2078 The environment of the message term. Can be a process inde‐
2079 pendent environment allocated with enif_alloc_env or NULL.
2080 msg:
2082 The message term to send. The same limitations apply as on
2083 the payload to erlang:port_command/2.
2084 Using a msg_env of NULL is an optimization, which groups to‐
2086 gether calls to enif_alloc_env, enif_make_copy, enif_port_com‐
2087 mand, and enif_free_env into one call. This optimization is only
2088 useful when a majority of the terms are to be copied from env to
2089 msg_env.
2090 Returns true if the command is successfully sent. Returns false
2092 if the command fails, for example:
2093 * *to_port does not refer to a local port.
2095 * The currently executing process (that is, the sender) is not
2097 alive.
2098 * msg is invalid.
2100 See also enif_get_local_port.
2102 void *enif_priv_data(ErlNifEnv* env)
2104 Returns the pointer to the private data that was set by load or
2106 upgrade.
2107 ERL_NIF_TERM enif_raise_exception(ErlNifEnv*
2109 env, ERL_NIF_TERM reason)
2110 Creates an error exception with the term reason to be returned
2112 from a NIF, and associates it with environment env. Once a NIF
2113 or any function it calls invokes enif_raise_exception, the run‐
2114 time ensures that the exception it creates is raised when the
2115 NIF returns, even if the NIF attempts to return a non-exception
2116 term instead.
2117 The return value from enif_raise_exception can only be used as
2119 the return value from the NIF that invoked it (directly or indi‐
2120 rectly) or be passed to enif_is_exception, but not to any other
2121 NIF API function.
2122 See also enif_has_pending_exception and enif_make_badarg.
2124 void *enif_realloc(void* ptr, size_t size)
2126 Reallocates memory allocated by enif_alloc to size bytes.
2128 Returns NULL if the reallocation fails.
2130 The returned pointer is suitably aligned for any built-in type
2132 that fit in the allocated memory.
2133 int enif_realloc_binary(ErlNifBinary* bin, size_t size)
2135 Changes the size of a binary bin. The source binary can be read-
2137 only, in which case it is left untouched and a mutable copy is
2138 allocated and assigned to *bin.
2139 Returns true on success, or false if memory allocation failed.
2141 void enif_release_binary(ErlNifBinary* bin)
2143 Releases a binary obtained from enif_alloc_binary.
2145 void enif_release_resource(void* obj)
2147 Removes a reference to resource object obj obtained from
2149 enif_alloc_resource. The resource object is destructed when the
2150 last reference is removed. Each call to enif_release_resource
2151 must correspond to a previous call to enif_alloc_resource or
2152 enif_keep_resource. References made by enif_make_resource can
2153 only be removed by the garbage collector.
2154 There are no guarantees exactly when the destructor of an unref‐
2156 erenced resource is called. It could be called directly by
2157 enif_release_resource but it could also be scheduled to be
2158 called at a later time possibly by another thread.
2159 ErlNifRWLock *enif_rwlock_create(char *name)
2161 Same as erl_drv_rwlock_create.
2163 void enif_rwlock_destroy(ErlNifRWLock *rwlck)
2165 Same as erl_drv_rwlock_destroy.
2167 char*enif_rwlock_name(ErlNifRWLock* rwlck)
2169 Same as erl_drv_rwlock_name.
2171 void enif_rwlock_rlock(ErlNifRWLock *rwlck)
2173 Same as erl_drv_rwlock_rlock.
2175 void enif_rwlock_runlock(ErlNifRWLock *rwlck)
2177 Same as erl_drv_rwlock_runlock.
2179 void enif_rwlock_rwlock(ErlNifRWLock *rwlck)
2181 Same as erl_drv_rwlock_rwlock.
2183 void enif_rwlock_rwunlock(ErlNifRWLock *rwlck)
2185 Same as erl_drv_rwlock_rwunlock.
2187 int enif_rwlock_tryrlock(ErlNifRWLock *rwlck)
2189 Same as erl_drv_rwlock_tryrlock.
2191 int enif_rwlock_tryrwlock(ErlNifRWLock *rwlck)
2193 Same as erl_drv_rwlock_tryrwlock.
2195 ERL_NIF_TERM enif_schedule_nif(
2197 ErlNifEnv* caller_env, const char* fun_name, int flags,
2198 ERL_NIF_TERM (*fp)(ErlNifEnv* env, int argc, const ERL_NIF_TERM
2199 argv[]), int argc, const ERL_NIF_TERM argv[])
2200 Schedules NIF fp to execute. This function allows an application
2202 to break up long-running work into multiple regular NIF calls or
2203 to schedule a dirty NIF to execute on a dirty scheduler thread.
2204 caller_env:
2206 Must be process bound environment of the calling NIF.
2207 fun_name:
2209 Provides a name for the NIF that is scheduled for execution.
2210 If it cannot be converted to an atom, enif_schedule_nif re‐
2211 turns a badarg exception.
2212 flags:
2214 Must be set to 0 for a regular NIF. If the emulator was
2215 built with dirty scheduler support enabled, flags can be set
2216 to either ERL_NIF_DIRTY_JOB_CPU_BOUND if the job is expected
2217 to be CPU-bound, or ERL_NIF_DIRTY_JOB_IO_BOUND for jobs that
2218 will be I/O-bound. If dirty scheduler threads are not avail‐
2219 able in the emulator, an attempt to schedule such a job re‐
2220 sults in a notsup exception.
2221 argc and argv:
2223 Can either be the originals passed into the calling NIF, or
2224 can be values created by the calling NIF.
2225 The calling NIF must use the return value of enif_schedule_nif
2227 as its own return value.
2228 Be aware that enif_schedule_nif, as its name implies, only
2230 schedules the NIF for future execution. The calling NIF does not
2231 block waiting for the scheduled NIF to execute and return. This
2232 means that the calling NIF cannot expect to receive the sched‐
2233 uled NIF return value and use it for further operations.
2234 int enif_select(ErlNifEnv* env, ErlNifEvent event, enum ErlNifSelect‐
2236 Flags mode, void* obj, const ErlNifPid* pid, ERL_NIF_TERM ref)
2237 This function can be used to receive asynchronous notifications
2239 when OS-specific event objects become ready for either read or
2240 write operations.
2241 Argument event identifies the event object. On Unix systems, the
2243 functions select/poll are used. The event object must be a
2244 socket, pipe or other file descriptor object that select/poll
2245 can use.
2246 Argument mode describes the type of events to wait for. It can
2248 be ERL_NIF_SELECT_READ, ERL_NIF_SELECT_WRITE or a bitwise OR
2249 combination to wait for both. It can also be ERL_NIF_SELECT_STOP
2250 or ERL_NIF_SELECT_CANCEL which are described further below. When
2251 a read or write event is triggered, a notification message like
2252 this is sent to the process identified by pid:
2253 {select, Obj, Ref, ready_input | ready_output}
2255 ready_input or ready_output indicates if the event object is
2257 ready for reading or writing.
2258 Note:
2260 For complete control over the message format use the newer func‐
2261 tions enif_select_read or enif_select_write introduced in
2262 erts-11.0 (OTP-22.0).
2263 Argument pid may be NULL to indicate the calling process. It
2266 must not be set as undefined.
2267 Argument obj is a resource object obtained from enif_alloc_re‐
2269 source. The purpose of the resource objects is as a container of
2270 the event object to manage its state and lifetime. A handle to
2271 the resource is received in the notification message as Obj.
2272 Argument ref must be either a reference obtained from er‐
2274 lang:make_ref/0 or the atom undefined. It will be passed as Ref
2275 in the notifications. If a selective receive statement is used
2276 to wait for the notification then a reference created just be‐
2277 fore the receive will exploit a runtime optimization that by‐
2278 passes all earlier received messages in the queue.
2279 The notifications are one-shot only. To receive further notifi‐
2281 cations of the same type (read or write), repeated calls to
2282 enif_select must be made after receiving each notification.
2283 ERL_NIF_SELECT_CANCEL can be used to cancel previously selected
2285 events. It must be used in a bitwise OR combination with
2286 ERL_NIF_SELECT_READ and/or ERL_NIF_SELECT_WRITE to indicate
2287 which type of event to cancel. Arguments pid and ref are ignored
2288 when ERL_NIF_SELECT_CANCEL is specified. The return value will
2289 tell if the event was actualy cancelled or if a notification may
2290 already have been sent.
2291 Use ERL_NIF_SELECT_STOP as mode in order to safely close an
2293 event object that has been passed to enif_select. The stop call‐
2294 back of the resource obj will be called when it is safe to close
2295 the event object. This safe way of closing event objects must be
2296 used even if all notifications have been received (or cancelled)
2297 and no further calls to enif_select have been made. ERL_NIF_SE‐
2298 LECT_STOP will first cancel any selected events before it calls
2299 or schedules the stop callback. Arguments pid and ref are ig‐
2300 nored when ERL_NIF_SELECT_STOP is specified.
2301 The first call to enif_select for a specific OS event will es‐
2303 tablish a relation between the event object and the containing
2304 resource. All subsequent calls for an event must pass its con‐
2305 taining resource as argument obj. The relation is dissolved when
2306 enif_select has been called with mode as ERL_NIF_SELECT_STOP and
2307 the corresponding stop callback has returned. A resource can
2308 contain several event objects but one event object can only be
2309 contained within one resource. A resource will not be destructed
2310 until all its contained relations have been dissolved.
2311 Note:
2313 Use enif_monitor_process together with enif_select to detect
2314 failing Erlang processes and prevent them from causing permanent
2315 leakage of resources and their contained OS event objects.
2316 Returns a non-negative value on success where the following bits
2319 can be set:
2320 ERL_NIF_SELECT_STOP_CALLED:
2322 The stop callback was called directly by enif_select.
2323 ERL_NIF_SELECT_STOP_SCHEDULED:
2325 The stop callback was scheduled to run on some other thread
2326 or later by this thread.
2327 ERL_NIF_SELECT_READ_CANCELLED:
2329 A read event was cancelled by ERL_NIF_SELECT_CANCEL or
2330 ERL_NIF_SELECT_STOP and is guaranteed not to generate a
2331 ready_input notification message.
2332 ERL_NIF_SELECT_WRITE_CANCELLED:
2334 A write event was cancelled by ERL_NIF_SELECT_CANCEL or
2335 ERL_NIF_SELECT_STOP and is guaranteed not to generate a
2336 ready_output notification message.
2337 Returns a negative value if the call failed where the following
2339 bits can be set:
2340 ERL_NIF_SELECT_INVALID_EVENT:
2342 Argument event is not a valid OS event object.
2343 ERL_NIF_SELECT_FAILED:
2345 The system call failed to add the event object to the poll
2346 set.
2347 Note:
2349 Use bitwise AND to test for specific bits in the return value.
2350 New significant bits may be added in future releases to give
2351 more detailed information for both failed and successful calls.
2352 Do NOT use equality tests like ==, as that may cause your appli‐
2353 cation to stop working.
2354 Example:
2356 retval = enif_select(env, fd, ERL_NIF_SELECT_STOP, resource, ref);
2358 if (retval < 0) {
2359 /* handle error */
2360 }
2361 /* Success! */
2362 if (retval & ERL_NIF_SELECT_STOP_CALLED) {
2363 /* ... */
2364 }
2365 Note:
2369 The mode flag ERL_NIF_SELECT_CANCEL and the return flags
2370 ERL_NIF_SELECT_READ_CANCELLED and ERL_NIF_SELECT_WRITE_CANCELLED
2371 were introduced in erts-11.0 (OTP-22.0).
2372 int enif_select_read(ErlNifEnv* env, ErlNifEvent event, void* obj,
2375 const ErlNifPid* pid, ERL_NIF_TERM msg, ErlNifEnv* msg_env)
2376 int enif_select_write(ErlNifEnv* env, ErlNifEvent event, void* obj,
2377 const ErlNifPid* pid, ERL_NIF_TERM msg, ErlNifEnv* msg_env)
2378 These are variants of enif_select where you can supply your own
2380 message term msg that will be sent to the process instead of the
2381 predefined tuple {select,_,_,_}.
2382 Argument msg_env must either be NULL or the environment of msg
2384 allocated with enif_alloc_env. If argument msg_env is NULL the
2385 term msg will be copied, otherwise both msg and msg_env will be
2386 invalidated by a successful call to enif_select_read or enif_se‐
2387 lect_write. The environment is then to either be freed with
2388 enif_free_env or cleared for reuse with enif_clear_env. An un‐
2389 successful call will leave msg and msg_env still valid.
2390 Apart from the message format enif_select_read and enif_se‐
2392 lect_write behaves exactly the same as enif_select with argument
2393 mode as either ERL_NIF_SELECT_READ or ERL_NIF_SELECT_WRITE. To
2394 cancel or close events use enif_select.
2395 ErlNifPid *enif_self(ErlNifEnv* caller_env, ErlNifPid* pid)
2397 Initializes the ErlNifPid variable at *pid to represent the
2399 calling process.
2400 Returns pid if successful, or NULL if caller_env is not a
2402 process bound environment.
2403 int enif_send(ErlNifEnv* caller_env,
2405 ErlNifPid* to_pid, ErlNifEnv* msg_env, ERL_NIF_TERM msg)
2406 Sends a message to a process.
2408 caller_env:
2410 The environment of the calling thread (process bound or
2411 callback environment) or NULL if calling from a custom
2412 thread not spawned by ERTS.
2413 *to_pid:
2415 The pid of the receiving process. The pid is to refer to a
2416 process on the local node.
2417 msg_env:
2419 The environment of the message term. Must be a process inde‐
2420 pendent environment allocated with enif_alloc_env or NULL.
2421 msg:
2423 The message term to send.
2424 Returns true if the message is successfully sent. Returns false
2426 if the send operation fails, that is:
2427 * *to_pid does not refer to an alive local process.
2429 * The currently executing process (that is, the sender) is not
2431 alive.
2432 The message environment msg_env with all its terms (including
2434 msg) is invalidated by a successful call to enif_send. The envi‐
2435 ronment is to either be freed with enif_free_env or cleared for
2436 reuse with enif_clear_env. An unsuccessful call will leave msg
2437 and msg_env still valid.
2438 If msg_env is set to NULL, the msg term is copied and the origi‐
2440 nal term and its environment is still valid after the call.
2441 This function is thread-safe.
2443 Note:
2445 Passing msg_env as NULL is only supported as from ERTS 8.0 (Er‐
2446 lang/OTP 19).
2447 void enif_set_pid_undefined(ErlNifPid* pid)
2450 Sets an ErlNifPid variable as undefined. See enif_is_pid_unde‐
2452 fined.
2453 unsigned enif_sizeof_resource(void* obj)
2455 Gets the byte size of resource object obj obtained by enif_al‐
2457 loc_resource.
2458 int enif_snprintf(char *str, size_t size, const
2460 char *format, ...)
2461 Similar to snprintf but this format string also accepts "%T",
2463 which formats Erlang terms of type ERL_NIF_TERM.
2464 This function is primarily intended for debugging purpose. It is
2466 not recommended to print very large terms with %T. The function
2467 may change errno, even if successful.
2468 void enif_system_info(ErlNifSysInfo
2470 *sys_info_ptr, size_t size)
2471 Same as driver_system_info.
2473 int enif_term_to_binary(ErlNifEnv *env,
2475 ERL_NIF_TERM term, ErlNifBinary *bin)
2476 Allocates a new binary with enif_alloc_binary and stores the re‐
2478 sult of encoding term according to the Erlang external term for‐
2479 mat.
2480 Returns true on success, or false if the allocation fails.
2482 See also erlang:term_to_binary/1 and enif_binary_to_term.
2484 ErlNifTermType enif_term_type(ErlNifEnv *env, ERL_NIF_TERM term)
2486 Determines the type of the given term. The term must be an ordi‐
2488 nary Erlang term and not one of the special terms returned by
2489 enif_raise_exception, enif_schedule_nif, or similar.
2490 The following types are defined at the moment:
2492 ERL_NIF_TERM_TYPE_ATOM:
2494 ERL_NIF_TERM_TYPE_BITSTRING:
2497 A bitstring or binary
2498 ERL_NIF_TERM_TYPE_FLOAT:
2500 ERL_NIF_TERM_TYPE_FUN:
2503 ERL_NIF_TERM_TYPE_INTEGER:
2506 ERL_NIF_TERM_TYPE_LIST:
2509 A list, empty or not
2510 ERL_NIF_TERM_TYPE_MAP:
2512 ERL_NIF_TERM_TYPE_PID:
2515 ERL_NIF_TERM_TYPE_PORT:
2518 ERL_NIF_TERM_TYPE_REFERENCE:
2521 ERL_NIF_TERM_TYPE_TUPLE:
2524 Note that new types may be added in the future, so the caller
2527 must be prepared to handle unknown types.
2528 int enif_thread_create(char *name,ErlNifTid
2530 *tid,void * (*func)(void *),void *args,ErlNifThreadOpts
2531 *opts)
2532 Same as erl_drv_thread_create.
2534 void enif_thread_exit(void *resp)
2536 Same as erl_drv_thread_exit.
2538 int enif_thread_join(ErlNifTid, void **respp)
2540 Same as erl_drv_thread_join.
2542 char*enif_thread_name(ErlNifTid tid)
2544 Same as erl_drv_thread_name.
2546 ErlNifThreadOpts *enif_thread_opts_create(char *name)
2548 Same as erl_drv_thread_opts_create.
2550 void enif_thread_opts_destroy(ErlNifThreadOpts *opts)
2552 Same as erl_drv_thread_opts_destroy.
2554 ErlNifTid enif_thread_self(void)
2556 Same as erl_drv_thread_self.
2558 int enif_thread_type(void)
2560 Determine the type of currently executing thread. A positive
2562 value indicates a scheduler thread while a negative value or
2563 zero indicates another type of thread. Currently the following
2564 specific types exist (which may be extended in the future):
2565 ERL_NIF_THR_UNDEFINED:
2567 Undefined thread that is not a scheduler thread.
2568 ERL_NIF_THR_NORMAL_SCHEDULER:
2570 A normal scheduler thread.
2571 ERL_NIF_THR_DIRTY_CPU_SCHEDULER:
2573 A dirty CPU scheduler thread.
2574 ERL_NIF_THR_DIRTY_IO_SCHEDULER:
2576 A dirty I/O scheduler thread.
2577 ErlNifTime enif_time_offset(ErlNifTimeUnit time_unit)
2579 Returns the current time offset between Erlang monotonic time
2581 and Erlang system time converted into the time_unit passed as
2582 argument.
2583 time_unit is the time unit of the returned value.
2585 Returns ERL_NIF_TIME_ERROR if called with an invalid time unit
2587 argument or if called from a thread that is not a scheduler
2588 thread.
2589 See also ErlNifTime and ErlNifTimeUnit.
2591 void *enif_tsd_get(ErlNifTSDKey key)
2593 Same as erl_drv_tsd_get.
2595 int enif_tsd_key_create(char *name, ErlNifTSDKey *key)
2597 Same as erl_drv_tsd_key_create.
2599 void enif_tsd_key_destroy(ErlNifTSDKey key)
2601 Same as erl_drv_tsd_key_destroy.
2603 void enif_tsd_set(ErlNifTSDKey key, void *data)
2605 Same as erl_drv_tsd_set.
2607 int enif_vfprintf(FILE *stream, const char *format, va_list ap)
2609 Equivalent to enif_fprintf except that its called with a va_list
2612 instead of a variable number of arguments.
2613 int enif_vsnprintf(char *str, size_t size, const char *format, va_list
2615 ap)
2616 Equivalent to enif_snprintf except that its called with a
2619 va_list instead of a variable number of arguments.
2620 int enif_whereis_pid(ErlNifEnv *caller_env,
2622 ERL_NIF_TERM name, ErlNifPid *pid)
2623 Looks up a process by its registered name.
2625 caller_env:
2627 The environment of the calling thread (process bound or
2628 callback environment) or NULL if calling from a custom
2629 thread not spawned by ERTS.
2630 name:
2632 The name of a registered process, as an atom.
2633 *pid:
2635 The ErlNifPid in which the resolved process id is stored.
2636 On success, sets *pid to the local process registered with name
2638 and returns true. If name is not a registered process, or is not
2639 an atom, false is returned and *pid is unchanged.
2640 Works as erlang:whereis/1, but restricted to processes. See
2642 enif_whereis_port to resolve registered ports.
2643 int enif_whereis_port(ErlNifEnv *caller_env,
2645 ERL_NIF_TERM name, ErlNifPort *port)
2646 Looks up a port by its registered name.
2648 caller_env:
2650 The environment of the calling thread (process bound or
2651 callback environment) or NULL if calling from a custom
2652 thread not spawned by ERTS.
2653 name:
2655 The name of a registered port, as an atom.
2656 *port:
2658 The ErlNifPort in which the resolved port id is stored.
2659 On success, sets *port to the port registered with name and re‐
2661 turns true. If name is not a registered port, or is not an atom,
2662 false is returned and *port is unchanged.
2663 Works as erlang:whereis/1, but restricted to ports. See
2665 enif_whereis_pid to resolve registered processes.
2666
2668 erlang:load_nif/2
2669Ericsson AB erts 12.1.5 erl_nif(3)