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
33 responsiveness of the VM, and can cause miscellaneous strange
34 behaviors. Such strange behaviors include, but are not limited to,
35 extreme memory usage, and bad load balancing between schedulers.
36 Strange behaviors that can occur because of lengthy work can also
37 vary between Erlang/OTP releases.
38
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
102 All interaction between NIF code and the Erlang runtime system is per‐
103 formed by calling NIF API functions. Functions exist for the following
104 functionality:
105 Read and write Erlang terms:
107 Any Erlang terms can be passed to a NIF as function arguments and
108 be returned as function return values. The terms are of C-type
109 ERL_NIF_TERM and can only be read or written using API functions.
110 Most functions to read the content of a term are prefixed enif_get_
111 and usually return true (or false) if the term is of the expected
112 type (or not). The functions to write terms are all prefixed
113 enif_make_ and usually return the created ERL_NIF_TERM. There are
114 also some functions to query terms, like enif_is_atom,
115 enif_is_identical, and enif_compare.
116 All terms of type ERL_NIF_TERM belong to an environment of type
118 ErlNifEnv. The lifetime of a term is controlled by the lifetime of
119 its environment object. All API functions that read or write terms
120 has the environment that the term belongs to as the first function
121 argument.
122 Binaries:
124 Terms of type binary are accessed with the help of struct type Erl‐
125 NifBinary, which contains a pointer (data) to the raw binary data
126 and the length (size) of the data in bytes. Both data and size are
127 read-only and are only to be written using calls to API functions.
128 Instances of ErlNifBinary are, however, always allocated by the
129 user (usually as local variables).
130 The raw data pointed to by data is only mutable after a call to
132 enif_alloc_binary or enif_realloc_binary. All other functions that
133 operate on a binary leave the data as read-only. A mutable binary
134 must in the end either be freed with enif_release_binary or made
135 read-only by transferring it to an Erlang term with
136 enif_make_binary. However, it does not have to occur in the same
137 NIF call. Read-only binaries do not have to be released.
138 enif_make_new_binary can be used as a shortcut to allocate and
140 return a binary in the same NIF call.
141 Binaries are sequences of whole bytes. Bitstrings with an arbitrary
143 bit length have no support yet.
144 Resource objects:
146 The use of resource objects is a safe way to return pointers to
147 native data structures from a NIF. A resource object is only a
148 block of memory allocated with enif_alloc_resource. A handle ("safe
149 pointer") to this memory block can then be returned to Erlang by
150 the use of enif_make_resource. The term returned by
151 enif_make_resource is opaque in nature. It can be stored and passed
152 between processes, but the only real end usage is to pass it back
153 as an argument to a NIF. The NIF can then call enif_get_resource
154 and get back a pointer to the memory block, which is guaranteed to
155 still be valid. A resource object is not deallocated until the last
156 handle term is garbage collected by the VM and the resource is
157 released with enif_release_resource (not necessarily in that
158 order).
159 All resource objects are created as instances of some resource
161 type. This makes resources from different modules to be distin‐
162 guishable. A resource type is created by calling
163 enif_open_resource_type when a library is loaded. Objects of that
164 resource type can then later be allocated and enif_get_resource
165 verifies that the resource is of the expected type. A resource type
166 can have a user-supplied destructor function, which is automati‐
167 cally called when resources of that type are released (by either
168 the garbage collector or enif_release_resource). Resource types are
169 uniquely identified by a supplied name string and the name of the
170 implementing module.
171 The following is a template example of how to create and return a
173 resource object.
174 ERL_NIF_TERM term;
176 MyStruct* obj = enif_alloc_resource(my_resource_type, sizeof(MyStruct));
177 /* initialize struct ... */
179 term = enif_make_resource(env, obj);
181 if (keep_a_reference_of_our_own) {
183 /* store 'obj' in static variable, private data or other resource object */
184 }
185 else {
186 enif_release_resource(obj);
187 /* resource now only owned by "Erlang" */
188 }
189 return term;
190 Notice that once enif_make_resource creates the term to return to
192 Erlang, the code can choose to either keep its own native pointer
193 to the allocated struct and release it later, or release it immedi‐
194 ately and rely only on the garbage collector to deallocate the
195 resource object eventually when it collects the term.
196 Another use of resource objects is to create binary terms with
198 user-defined memory management. enif_make_resource_binary creates a
199 binary term that is connected to a resource object. The destructor
200 of the resource is called when the binary is garbage collected, at
201 which time the binary data can be released. An example of this can
202 be a binary term consisting of data from a mmap'ed file. The
203 destructor can then do munmap to release the memory region.
204 Resource types support upgrade in runtime by allowing a loaded NIF
206 library to take over an already existing resource type and by that
207 "inherit" all existing objects of that type. The destructor of the
208 new library is thereafter called for the inherited objects and the
209 library with the old destructor function can be safely unloaded.
210 Existing resource objects, of a module that is upgraded, must
211 either be deleted or taken over by the new NIF library. The unload‐
212 ing of a library is postponed as long as there exist resource
213 objects with a destructor function in the library.
214 Module upgrade and static data:
216 A loaded NIF library is tied to the Erlang module instance that
217 loaded it. If the module is upgraded, the new module instance needs
218 to load its own NIF library (or maybe choose not to). The new mod‐
219 ule instance can, however, choose to load the exact same NIF
220 library as the old code if it wants to. Sharing the dynamic library
221 means that static data defined by the library is shared as well. To
222 avoid unintentionally shared static data between module instances,
223 each Erlang module version can keep its own private data. This pri‐
224 vate data can be set when the NIF library is loaded and later
225 retrieved by calling enif_priv_data.
226 Threads and concurrency:
228 A NIF is thread-safe without any explicit synchronization as long
229 as it acts as a pure function and only reads the supplied argu‐
230 ments. When you write to a shared state either through static vari‐
231 ables or enif_priv_data, you need to supply your own explicit syn‐
232 chronization. This includes terms in process independent environ‐
233 ments that are shared between threads. Resource objects also
234 require synchronization if you treat them as mutable.
235 The library initialization callbacks load and upgrade are thread-
237 safe even for shared state data.
238 Version Management:
240 When a NIF library is built, information about the NIF API version
241 is compiled into the library. When a NIF library is loaded, the
242 runtime system verifies that the library is of a compatible ver‐
243 sion. erl_nif.h defines the following:
244 ERL_NIF_MAJOR_VERSION:
246 Incremented when NIF library incompatible changes are made to the
247 Erlang runtime system. Normally it suffices to recompile the NIF
248 library when the ERL_NIF_MAJOR_VERSION has changed, but it can,
249 under rare circumstances, mean that NIF libraries must be
250 slightly modified. If so, this will of course be documented.
251 ERL_NIF_MINOR_VERSION:
253 Incremented when new features are added. The runtime system uses
254 the minor version to determine what features to use.
255 The runtime system normally refuses to load a NIF library if the
257 major versions differ, or if the major versions are equal and the
258 minor version used by the NIF library is greater than the one used
259 by the runtime system. Old NIF libraries with lower major versions
260 are, however, allowed after a bump of the major version during a
261 transition period of two major releases. Such old NIF libraries can
262 however fail if deprecated features are used.
263 Time Measurement:
265 Support for time measurement in NIF libraries:
266 * ErlNifTime
268 * ErlNifTimeUnit
270 * enif_monotonic_time()
272 * enif_time_offset()
274 * enif_convert_time_unit()
276 I/O Queues:
278 The Erlang nif library contains function for easily working with
279 I/O vectors as used by the unix system call writev. The I/O Queue
280 is not thread safe, so some other synchronization mechanism has to
281 be used.
282 * SysIOVec
284 * ErlNifIOVec
286 * enif_ioq_create()
288 * enif_ioq_destroy()
290 * enif_ioq_enq_binary()
292 * enif_ioq_enqv()
294 * enif_ioq_deq()
296 * enif_ioq_peek()
298 * enif_ioq_peek_head()
300 * enif_inspect_iovec()
302 * enif_free_iovec()
304 Typical usage when writing to a file descriptor looks like this:
306 int writeiovec(ErlNifEnv *env, ERL_NIF_TERM term, ERL_NIF_TERM *tail,
308 ErlNifIOQueue *q, int fd) {
309 ErlNifIOVec vec, *iovec = &vec;
311 SysIOVec *sysiovec;
312 int saved_errno;
313 int iovcnt, n;
314 if (!enif_inspect_iovec(env, 64, term, tail, &iovec))
316 return -2;
317 if (enif_ioq_size(q) > 0) {
319 /* If the I/O queue contains data we enqueue the iovec and
320 then peek the data to write out of the queue. */
321 if (!enif_ioq_enqv(q, iovec, 0))
322 return -3;
323 sysiovec = enif_ioq_peek(q, &iovcnt);
325 } else {
326 /* If the I/O queue is empty we skip the trip through it. */
327 iovcnt = iovec->iovcnt;
328 sysiovec = iovec->iov;
329 }
330 /* Attempt to write the data */
332 n = writev(fd, sysiovec, iovcnt);
333 saved_errno = errno;
334 if (enif_ioq_size(q) == 0) {
336 /* If the I/O queue was initially empty we enqueue any
337 remaining data into the queue for writing later. */
338 if (n >= 0 && !enif_ioq_enqv(q, iovec, n))
339 return -3;
340 } else {
341 /* Dequeue any data that was written from the queue. */
342 if (n > 0 && !enif_ioq_deq(q, n, NULL))
343 return -4;
344 }
345 /* return n, which is either number of bytes written or -1 if
347 some error happened */
348 errno = saved_errno;
349 return n;
350 }
351 Long-running NIFs:
353 As mentioned in the warning text at the beginning of this manual
354 page, it is of vital importance that a native function returns rel‐
355 atively fast. It is difficult to give an exact maximum amount of
356 time that a native function is allowed to work, but usually a well-
357 behaving native function is to return to its caller within 1 mil‐
358 lisecond. This can be achieved using different approaches. If you
359 have full control over the code to execute in the native function,
360 the best approach is to divide the work into multiple chunks of
361 work and call the native function multiple times. This is, however,
362 not always possible, for example when calling third-party
363 libraries.
364 The enif_consume_timeslice() function can be used to inform the
366 runtime system about the length of the NIF call. It is typically
367 always to be used unless the NIF executes very fast.
368 If the NIF call is too lengthy, this must be handled in one of the
370 following ways to avoid degraded responsiveness, scheduler load
371 balancing problems, and other strange behaviors:
372 Yielding NIF:
374 If the functionality of a long-running NIF can be split so that
375 its work can be achieved through a series of shorter NIF calls,
376 the application has two options:
377 * Make that series of NIF calls from the Erlang level.
379 * Call a NIF that first performs a chunk of the work, then
381 invokes the enif_schedule_nif function to schedule another NIF
382 call to perform the next chunk. The final call scheduled in
383 this manner can then return the overall result.
384 Breaking up a long-running function in this manner enables the VM
386 to regain control between calls to the NIFs.
387 This approach is always preferred over the other alternatives
389 described below. This both from a performance perspective and a
390 system characteristics perspective.
391 Threaded NIF:
393 This is accomplished by dispatching the work to another thread
394 managed by the NIF library, return from the NIF, and wait for the
395 result. The thread can send the result back to the Erlang process
396 using enif_send. Information about thread primitives is provided
397 below.
398 Dirty NIF:
400 Note:
403 Dirty NIF support is available only when the emulator is configured
404 with dirty scheduler support. As of ERTS version 9.0, dirty sched‐
405 uler support is enabled by default on the runtime system with SMP
406 support. The Erlang runtime without SMP support does not support
407 dirty schedulers even when the dirty scheduler support is explic‐
408 itly enabled. To check at runtime for the presence of dirty sched‐
409 uler threads, code can use the enif_system_info() API function.
410 A NIF that cannot be split and cannot execute in a millisecond or
413 less is called a "dirty NIF", as it performs work that the ordi‐
414 nary schedulers of the Erlang runtime system cannot handle
415 cleanly. Applications that make use of such functions must indi‐
416 cate to the runtime that the functions are dirty so they can be
417 handled specially. This is handled by executing dirty jobs on a
418 separate set of schedulers called dirty schedulers. A dirty NIF
419 executing on a dirty scheduler does not have the same duration
420 restriction as a normal NIF.
421 It is important to classify the dirty job correct. An I/O bound
423 job should be classified as such, and a CPU bound job should be
424 classified as such. If you should classify CPU bound jobs as I/O
425 bound jobs, dirty I/O schedulers might starve ordinary sched‐
426 ulers. I/O bound jobs are expected to either block waiting for
427 I/O, and/or spend a limited amount of time moving data.
428 To schedule a dirty NIF for execution, the application has two
430 options:
431 * Set the appropriate flags value for the dirty NIF in its Erl‐
433 NifFunc entry.
434 * Call enif_schedule_nif, pass to it a pointer to the dirty NIF
436 to be executed, and indicate with argument flags whether it
437 expects the operation to be CPU-bound or I/O-bound.
438 A job that alternates between I/O bound and CPU bound can be
440 reclassified and rescheduled using enif_schedule_nif so that it
441 executes on the correct type of dirty scheduler at all times. For
442 more information see the documentation of the erl(1) command line
443 arguments +SDcpu, and +SDio.
444 While a process executes a dirty NIF, some operations that commu‐
446 nicate with it can take a very long time to complete. Suspend or
447 garbage collection of a process executing a dirty NIF cannot be
448 done until the dirty NIF has returned. Thus, other processes
449 waiting for such operations to complete might have to wait for a
450 very long time. Blocking multi-scheduling, that is, calling
451 erlang:system_flag(multi_scheduling, block), can also take a very
452 long time to complete. This is because all ongoing dirty opera‐
453 tions on all dirty schedulers must complete before the block
454 operation can complete.
455 Many operations communicating with a process executing a dirty
457 NIF can, however, complete while it executes the dirty NIF. For
458 example, retrieving information about it through process_info,
459 setting its group leader, register/unregister its name, and so
460 on.
461 Termination of a process executing a dirty NIF can only be com‐
463 pleted up to a certain point while it executes the dirty NIF. All
464 Erlang resources, such as its registered name and its ETS tables,
465 are released. All links and monitors are triggered. The execution
466 of the NIF is, however, not stopped. The NIF can safely continue
467 execution, allocate heap memory, and so on, but it is of course
468 better to stop executing as soon as possible. The NIF can check
469 whether a current process is alive using enif_is_cur‐
470 rent_process_alive. Communication using enif_send and
471 enif_port_command is also dropped when the sending process is not
472 alive. Deallocation of certain internal resources, such as
473 process heap and process control block, is delayed until the
474 dirty NIF has completed.
475
477 ERL_NIF_INIT(MODULE, ErlNifFunc funcs[], load, NULL, upgrade,
478 unload):
479 This is the magic macro to initialize a NIF library. It is to be
480 evaluated in global file scope.
481 MODULE is the name of the Erlang module as an identifier without
483 string quotations. It is stringified by the macro.
484 funcs is a static array of function descriptors for all the imple‐
486 mented NIFs in this library.
487 load, upgrade and unload are pointers to functions. One of load or
489 upgrade is called to initialize the library. unload is called to
490 release the library. All are described individually below.
491 The fourth argument NULL is ignored. It was earlier used for the
493 deprecated reload callback which is no longer supported since OTP
494 20.
495 If compiling a NIF for static inclusion through --enable-static-
497 nifs, you must define STATIC_ERLANG_NIF before the ERL_NIF_INIT
498 declaration.
499 int (*load)(ErlNifEnv* caller_env, void** priv_data, ERL_NIF_TERM
501 load_info):
502 load is called when the NIF library is loaded and no previously
503 loaded library exists for this module.
504 *priv_data can be set to point to some private data if the library
506 needs to keep a state between NIF calls. enif_priv_data returns
507 this pointer. *priv_data is initialized to NULL when load is
508 called.
509 load_info is the second argument to erlang:load_nif/2.
511 The library fails to load if load returns anything other than 0.
513 load can be NULL if initialization is not needed.
514 int (*upgrade)(ErlNifEnv* caller_env, void** priv_data, void**
516 old_priv_data, ERL_NIF_TERM load_info):
517 upgrade is called when the NIF library is loaded and there is old
518 code of this module with a loaded NIF library.
519 Works as load, except that *old_priv_data already contains the
521 value set by the last call to load or upgrade for the old module
522 code. *priv_data is initialized to NULL when upgrade is called. It
523 is allowed to write to both *priv_data and *old_priv_data.
524 The library fails to load if upgrade returns anything other than 0
526 or if upgrade is NULL.
527 void (*unload)(ErlNifEnv* caller_env, void* priv_data):
529 unload is called when the module code that the NIF library belongs
530 to is purged as old. New code of the same module may or may not
531 exist.
532
534 ERL_NIF_TERM:
535 Variables of type ERL_NIF_TERM can refer to any Erlang term. This
536 is an opaque type and values of it can only by used either as argu‐
537 ments to API functions or as return values from NIFs. All
538 ERL_NIF_TERMs belong to an environment (ErlNifEnv). A term cannot
539 be destructed individually, it is valid until its environment is
540 destructed.
541 ErlNifEnv:
543 ErlNifEnv represents an environment that can host Erlang terms. All
544 terms in an environment are valid as long as the environment is
545 valid. ErlNifEnv is an opaque type; pointers to it can only be
546 passed on to API functions. Three types of environments exist:
547 Process bound environment:
549 Passed as the first argument to all NIFs. All function arguments
550 passed to a NIF belong to that environment. The return value from
551 a NIF must also be a term belonging to the same environment.
552 A process bound environment contains transient information about
554 the calling Erlang process. The environment is only valid in the
555 thread where it was supplied as argument until the NIF returns.
556 It is thus useless and dangerous to store pointers to process
557 bound environments between NIF calls.
558 Callback environment:
560 Passed as the first argument to all the non-NIF callback func‐
561 tions (load, upgrade, unload, dtor, down and stop). Works like a
562 process bound environment but with a temporary pseudo process
563 that "terminates" when the callback has returned. Terms may be
564 created in this environment but they will only be accessible dur‐
565 ing the callback.
566 Process independent environment:
568 Created by calling enif_alloc_env. This environment can be used
569 to store terms between NIF calls and to send terms with
570 enif_send. A process independent environment with all its terms
571 is valid until you explicitly invalidate it with enif_free_env or
572 enif_send.
573 All contained terms of a list/tuple/map must belong to the same
575 environment as the list/tuple/map itself. Terms can be copied
576 between environments with enif_make_copy.
577 ErlNifFunc:
579 typedef struct {
582 const char* name;
583 unsigned arity;
584 ERL_NIF_TERM (*fptr)(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]);
585 unsigned flags;
586 } ErlNifFunc;
587 Describes a NIF by its name, arity, and implementation.
589 fptr:
591 A pointer to the function that implements the NIF.
592 argv:
594 Contains the function arguments passed to the NIF.
595 argc:
597 The array length, that is, the function arity. argv[N-1] thus
598 denotes the Nth argument to the NIF. Notice that the argument
599 argc allows for the same C function to implement several Erlang
600 functions with different arity (but probably with the same name).
601 flags:
603 Is 0 for a regular NIF (and so its value can be omitted for stat‐
604 ically initialized ErlNifFunc instances).
605 flags can be used to indicate that the NIF is a dirty NIF that is
607 to be executed on a dirty scheduler thread.
608 If the dirty NIF is expected to be CPU-bound, its flags field is
610 to be set to ERL_NIF_DIRTY_JOB_CPU_BOUND or
611 ERL_NIF_DIRTY_JOB_IO_BOUND.
612 Note:
614 If one of the ERL_NIF_DIRTY_JOB_*_BOUND flags is set, and the run‐
615 time system has no support for dirty schedulers, the runtime system
616 refuses to load the NIF library.
617 ErlNifBinary:
620 typedef struct {
623 size_t size;
624 unsigned char* data;
625 } ErlNifBinary;
626 ErlNifBinary contains transient information about an inspected
628 binary term. data is a pointer to a buffer of size bytes with the
629 raw content of the binary.
630 Notice that ErlNifBinary is a semi-opaque type and you are only
632 allowed to read fields size and data.
633 ErlNifBinaryToTerm:
635 An enumeration of the options that can be specified to
636 enif_binary_to_term. For default behavior, use value 0.
637 When receiving data from untrusted sources, use option
639 ERL_NIF_BIN2TERM_SAFE.
640 ErlNifMonitor:
642 This is an opaque data type that identifies a monitor.
643 The nif writer is to provide the memory for storing the monitor
645 when calling enif_monitor_process. The address of the data is not
646 stored by the runtime system, so ErlNifMonitor can be used as any
647 other data, it can be copied, moved in memory, forgotten, and so
648 on. To compare two monitors, enif_compare_monitors must be used.
649 ErlNifPid:
651 A process identifier (pid). In contrast to pid terms (instances of
652 ERL_NIF_TERM), ErlNifPids are self-contained and not bound to any
653 environment. ErlNifPid is an opaque type. It can be copied, moved
654 in memory, forgotten, and so on.
655 ErlNifPort:
657 A port identifier. In contrast to port ID terms (instances of
658 ERL_NIF_TERM), ErlNifPorts are self-contained and not bound to any
659 environment. ErlNifPort is an opaque type. It can be copied, moved
660 in memory, forgotten, and so on.
661 ErlNifResourceType:
663 Each instance of ErlNifResourceType represents a class of memory-
664 managed resource objects that can be garbage collected. Each
665 resource type has a unique name and a destructor function that is
666 called when objects of its type are released.
667 ErlNifResourceTypeInit:
669 typedef struct {
672 ErlNifResourceDtor* dtor;
673 ErlNifResourceStop* stop;
674 ErlNifResourceDown* down;
675 } ErlNifResourceTypeInit;
676 Initialization structure read by enif_open_resource_type_x.
678 ErlNifResourceDtor:
680 typedef void ErlNifResourceDtor(ErlNifEnv* caller_env, void* obj);
683 The function prototype of a resource destructor function.
685 The obj argument is a pointer to the resource. The only allowed use
687 for the resource in the destructor is to access its user data one
688 final time. The destructor is guaranteed to be the last callback
689 before the resource is deallocated.
690 ErlNifResourceDown:
692 typedef void ErlNifResourceDown(ErlNifEnv* caller_env, void* obj, ErlNifPid* pid, ErlNifMonitor* mon);
695 The function prototype of a resource down function, called on the
697 behalf of enif_monitor_process. obj is the resource, pid is the
698 identity of the monitored process that is exiting, and mon is the
699 identity of the monitor.
700 ErlNifResourceStop:
702 typedef void ErlNifResourceStop(ErlNifEnv* caller_env, void* obj, ErlNifEvent event, int is_direct_call);
705 The function prototype of a resource stop function, called on the
707 behalf of enif_select. obj is the resource, event is OS event,
708 is_direct_call is true if the call is made directly from
709 enif_select or false if it is a scheduled call (potentially from
710 another thread).
711 ErlNifCharEncoding:
713 typedef enum {
716 ERL_NIF_LATIN1
717 }ErlNifCharEncoding;
718 The character encoding used in strings and atoms. The only sup‐
720 ported encoding is ERL_NIF_LATIN1 for ISO Latin-1 (8-bit ASCII).
721 ErlNifSysInfo:
723 Used by enif_system_info to return information about the runtime
724 system. Contains the same content as ErlDrvSysInfo.
725 ErlNifSInt64:
727 A native signed 64-bit integer type.
728 ErlNifUInt64:
730 A native unsigned 64-bit integer type.
731 ErlNifTime:
733 A signed 64-bit integer type for representation of time.
734 ErlNifTimeUnit:
736 An enumeration of time units supported by the NIF API:
737 ERL_NIF_SEC:
739 Seconds
740 ERL_NIF_MSEC:
742 Milliseconds
743 ERL_NIF_USEC:
745 Microseconds
746 ERL_NIF_NSEC:
748 Nanoseconds
749 ErlNifUniqueInteger:
751 An enumeration of the properties that can be requested from
752 enif_make_unique_integer. For default properties, use value 0.
753 ERL_NIF_UNIQUE_POSITIVE:
755 Return only positive integers.
756 ERL_NIF_UNIQUE_MONOTONIC:
758 Return only strictly monotonically increasing integer corre‐
759 sponding to creation time.
760 ErlNifHash:
762 An enumeration of the supported hash types that can be generated
763 using enif_hash.
764 ERL_NIF_INTERNAL_HASH:
766 Non-portable hash function that only guarantees the same hash for
767 the same term within one Erlang VM instance.
768 It takes 32-bit salt values and generates hashes within
770 0..2^32-1.
771 ERL_NIF_PHASH2:
773 Portable hash function that gives the same hash for the same
774 Erlang term regardless of machine architecture and ERTS version.
775 It ignores salt values and generates hashes within 0..2^27-1.
777 Slower than ERL_NIF_INTERNAL_HASH. It corresponds to
779 erlang:phash2/1.
780 SysIOVec:
782 A system I/O vector, as used by writev on Unix and WSASend on
783 Win32. It is used in ErlNifIOVec and by enif_ioq_peek.
784 ErlNifIOVec:
786 typedef struct {
789 int iovcnt;
790 size_t size;
791 SysIOVec* iov;
792 } ErlNifIOVec;
793 An I/O vector containing iovcnt SysIOVecs pointing to the data. It
795 is used by enif_inspect_iovec and enif_ioq_enqv.
796 ErlNifIOQueueOpts:
798 Options to configure a ErlNifIOQueue.
799 ERL_NIF_IOQ_NORMAL:
801 Create a normal I/O Queue
802
804 void *enif_alloc(size_t size)
805 Allocates memory of size bytes.
807 Returns NULL if the allocation fails.
809 The returned pointer is suitably aligned for any built-in type
811 that fit in the allocated memory.
812 int enif_alloc_binary(size_t size, ErlNifBinary* bin)
814 Allocates a new binary of size size bytes. Initializes the
816 structure pointed to by bin to refer to the allocated binary.
817 The binary must either be released by enif_release_binary or
818 ownership transferred to an Erlang term with enif_make_binary.
819 An allocated (and owned) ErlNifBinary can be kept between NIF
820 calls.
821 If you do not need to reallocate or keep the data alive across
823 NIF calls, consider using enif_make_new_binary instead as it
824 will allocate small binaries on the process heap when possible.
825 Returns true on success, or false if allocation fails.
827 ErlNifEnv *enif_alloc_env()
829 Allocates a new process independent environment. The environment
831 can be used to hold terms that are not bound to any process.
832 Such terms can later be copied to a process environment with
833 enif_make_copy or be sent to a process as a message with
834 enif_send.
835 Returns pointer to the new environment.
837 void *enif_alloc_resource(ErlNifResourceType*
839 type, unsigned size)
840 Allocates a memory-managed resource object of type type and size
842 size bytes.
843 size_t enif_binary_to_term(ErlNifEnv *env,
845 const unsigned char* data, size_t size, ERL_NIF_TERM *term,
846 ErlNifBinaryToTerm opts)
847 Creates a term that is the result of decoding the binary data at
849 data, which must be encoded according to the Erlang external
850 term format. No more than size bytes are read from data. Argu‐
851 ment opts corresponds to the second argument to
852 erlang:binary_to_term/2 and must be either 0 or
853 ERL_NIF_BIN2TERM_SAFE.
854 On success, stores the resulting term at *term and returns the
856 number of bytes read. Returns 0 if decoding fails or if opts is
857 invalid.
858 See also ErlNifBinaryToTerm, erlang:binary_to_term/2, and
860 enif_term_to_binary.
861 void enif_clear_env(ErlNifEnv* env)
863 Frees all terms in an environment and clears it for reuse. The
865 environment must have been allocated with enif_alloc_env.
866 int enif_compare(ERL_NIF_TERM lhs, ERL_NIF_TERM rhs)
868 Returns an integer < 0 if lhs < rhs, 0 if lhs = rhs, and > 0 if
870 lhs > rhs. Corresponds to the Erlang operators ==, /=, =<, <,
871 >=, and > (but not =:= or =/=).
872 int enif_compare_monitors(const ErlNifMonitor
874 *monitor1, const ErlNifMonitor *monitor2)
875 Compares two ErlNifMonitors. Can also be used to imply some
877 artificial order on monitors, for whatever reason.
878 Returns 0 if monitor1 and monitor2 are equal, < 0 if monitor1 <
880 monitor2, and > 0 if monitor1 > monitor2.
881 int enif_compare_pids(const ErlNifPid *pid1, const ErlNifPid *pid2)
883 Compares two ErlNifPids according to term order.
886 Returns 0 if pid1 and pid2 are equal, < 0 if pid1 < pid2, and >
888 0 if pid1 > pid2.
889 void enif_cond_broadcast(ErlNifCond *cnd)
891 Same as erl_drv_cond_broadcast.
893 ErlNifCond *enif_cond_create(char *name)
895 Same as erl_drv_cond_create.
897 void enif_cond_destroy(ErlNifCond *cnd)
899 Same as erl_drv_cond_destroy.
901 char*enif_cond_name(ErlNifCond* cnd)
903 Same as erl_drv_cond_name.
905 void enif_cond_signal(ErlNifCond *cnd)
907 Same as erl_drv_cond_signal.
909 void enif_cond_wait(ErlNifCond *cnd, ErlNifMutex *mtx)
911 Same as erl_drv_cond_wait.
913 int enif_consume_timeslice(ErlNifEnv *env, int percent)
915 Gives the runtime system a hint about how much CPU time the cur‐
917 rent NIF call has consumed since the last hint, or since the
918 start of the NIF if no previous hint has been specified. The
919 time is specified as a percent of the timeslice that a process
920 is allowed to execute Erlang code until it can be suspended to
921 give time for other runnable processes. The scheduling timeslice
922 is not an exact entity, but can usually be approximated to about
923 1 millisecond.
924 Notice that it is up to the runtime system to determine if and
926 how to use this information. Implementations on some platforms
927 can use other means to determine consumed CPU time. Lengthy NIFs
928 should regardless of this frequently call enif_consume_timeslice
929 to determine if it is allowed to continue execution.
930 Argument percent must be an integer between 1 and 100. This
932 function must only be called from a NIF-calling thread, and
933 argument env must be the environment of the calling process.
934 Returns 1 if the timeslice is exhausted, otherwise 0. If 1 is
936 returned, the NIF is to return as soon as possible in order for
937 the process to yield.
938 This function is provided to better support co-operative sched‐
940 uling, improve system responsiveness, and make it easier to pre‐
941 vent misbehaviors of the VM because of a NIF monopolizing a
942 scheduler thread. It can be used to divide length work into a
943 number of repeated NIF calls without the need to create threads.
944 See also the warning text at the beginning of this manual page.
946 ErlNifTime enif_convert_time_unit(ErlNifTime
948 val, ErlNifTimeUnit from, ErlNifTimeUnit to)
949 Converts the val value of time unit from to the corresponding
951 value of time unit to. The result is rounded using the floor
952 function.
953 val:
955 Value to convert time unit for.
956 from:
958 Time unit of val.
959 to:
961 Time unit of returned value.
962 Returns ERL_NIF_TIME_ERROR if called with an invalid time unit
964 argument.
965 See also ErlNifTime and ErlNifTimeUnit.
967 ERL_NIF_TERM enif_cpu_time(ErlNifEnv *)
969 Returns the CPU time in the same format as erlang:timestamp().
971 The CPU time is the time the current logical CPU has spent exe‐
972 cuting since some arbitrary point in the past. If the OS does
973 not support fetching this value, enif_cpu_time invokes
974 enif_make_badarg.
975 int enif_demonitor_process(ErlNifEnv* caller_env,
977 void* obj, const ErlNifMonitor* mon)
978 Cancels a monitor created earlier with enif_monitor_process.
980 Argument obj is a pointer to the resource holding the monitor
981 and *mon identifies the monitor.
982 Argument caller_env is the environment of the calling process or
984 callback. Must only be NULL if calling from a custom thread.
985 Returns 0 if the monitor was successfully identified and
987 removed. Returns a non-zero value if the monitor could not be
988 identified, which means it was either
989 * never created for this resource
991 * already cancelled
993 * already triggered
995 * just about to be triggered by a concurrent thread
997 This function is only thread-safe when the emulator with SMP
999 support is used. It can only be used in a non-SMP emulator from
1000 a NIF-calling thread.
1001 int enif_equal_tids(ErlNifTid tid1, ErlNifTid tid2)
1003 Same as erl_drv_equal_tids.
1005 int enif_fprintf(FILE *stream, const char *format, ...)
1007 Similar to fprintf but this format string also accepts "%T",
1009 which formats Erlang terms of type ERL_NIF_TERM.
1010 This function is primarily intended for debugging purpose. It is
1012 not recommended to print very large terms with %T. The function
1013 may change errno, even if successful.
1014 void enif_free(void* ptr)
1016 Frees memory allocated by enif_alloc.
1018 void enif_free_env(ErlNifEnv* env)
1020 Frees an environment allocated with enif_alloc_env. All terms
1022 created in the environment are freed as well.
1023 void enif_free_iovec(ErlNifIOVec* iov)
1025 Frees an io vector returned from enif_inspect_iovec. This is
1027 needed only if a NULL environment is passed to
1028 enif_inspect_iovec.
1029 ErlNifIOVec *iovec = NULL;
1031 size_t max_elements = 128;
1032 ERL_NIF_TERM tail;
1033 if (!enif_inspect_iovec(NULL, max_elements, term, &tail, &iovec))
1034 return 0;
1035 // Do things with the iovec
1037 /* Free the iovector, possibly in another thread or nif function call */
1039 enif_free_iovec(iovec);
1040 int enif_get_atom(ErlNifEnv* env, ERL_NIF_TERM
1042 term, char* buf, unsigned size, ErlNifCharEncoding encode)
1043 Writes a NULL-terminated string in the buffer pointed to by buf
1045 of size size, consisting of the string representation of the
1046 atom term with encoding encode.
1047 Returns the number of bytes written (including terminating NULL
1049 character) or 0 if term is not an atom with maximum length of
1050 size-1.
1051 int enif_get_atom_length(ErlNifEnv* env,
1053 ERL_NIF_TERM term, unsigned* len, ErlNifCharEncoding encode)
1054 Sets *len to the length (number of bytes excluding terminating
1056 NULL character) of the atom term with encoding encode.
1057 Returns true on success, or false if term is not an atom.
1059 int enif_get_double(ErlNifEnv* env,
1061 ERL_NIF_TERM term, double* dp)
1062 Sets *dp to the floating-point value of term.
1064 Returns true on success, or false if term is not a float.
1066 int enif_get_int(ErlNifEnv* env, ERL_NIF_TERM
1068 term, int* ip)
1069 Sets *ip to the integer value of term.
1071 Returns true on success, or false if term is not an integer or
1073 is outside the bounds of type int.
1074 int enif_get_int64(ErlNifEnv* env, ERL_NIF_TERM
1076 term, ErlNifSInt64* ip)
1077 Sets *ip to the integer value of term.
1079 Returns true on success, or false if term is not an integer or
1081 is outside the bounds of a signed 64-bit integer.
1082 int enif_get_local_pid(ErlNifEnv* env,
1084 ERL_NIF_TERM term, ErlNifPid* pid)
1085 If term is the pid of a node local process, this function ini‐
1087 tializes the pid variable *pid from it and returns true. Other‐
1088 wise returns false. No check is done to see if the process is
1089 alive.
1090 Note:
1092 enif_get_local_pid will return false if argument term is the
1093 atom undefined.
1094 int enif_get_local_port(ErlNifEnv* env,
1097 ERL_NIF_TERM term, ErlNifPort* port_id)
1098 If term identifies a node local port, this function initializes
1100 the port variable *port_id from it and returns true. Otherwise
1101 returns false. No check is done to see if the port is alive.
1102 int enif_get_list_cell(ErlNifEnv* env,
1104 ERL_NIF_TERM list, ERL_NIF_TERM* head, ERL_NIF_TERM* tail)
1105 Sets *head and *tail from list list.
1107 Returns true on success, or false if it is not a list or the
1109 list is empty.
1110 int enif_get_list_length(ErlNifEnv* env,
1112 ERL_NIF_TERM term, unsigned* len)
1113 Sets *len to the length of list term.
1115 Returns true on success, or false if term is not a proper list.
1117 int enif_get_long(ErlNifEnv* env, ERL_NIF_TERM
1119 term, long int* ip)
1120 Sets *ip to the long integer value of term.
1122 Returns true on success, or false if term is not an integer or
1124 is outside the bounds of type long int.
1125 int enif_get_map_size(ErlNifEnv* env,
1127 ERL_NIF_TERM term, size_t *size)
1128 Sets *size to the number of key-value pairs in the map term.
1130 Returns true on success, or false if term is not a map.
1132 int enif_get_map_value(ErlNifEnv* env,
1134 ERL_NIF_TERM map, ERL_NIF_TERM key, ERL_NIF_TERM* value)
1135 Sets *value to the value associated with key in the map map.
1137 Returns true on success, or false if map is not a map or if map
1139 does not contain key.
1140 int enif_get_resource(ErlNifEnv* env,
1142 ERL_NIF_TERM term, ErlNifResourceType* type, void** objp)
1143 Sets *objp to point to the resource object referred to by term.
1145 Returns true on success, or false if term is not a handle to a
1147 resource object of type type.
1148 enif_get_resource does not add a reference to the resource
1150 object. However, the pointer received in *objp is guaranteed to
1151 be valid at least as long as the resource handle term is valid.
1152 int enif_get_string(ErlNifEnv* env,
1154 ERL_NIF_TERM list, char* buf, unsigned size,
1155 ErlNifCharEncoding encode)
1156 Writes a NULL-terminated string in the buffer pointed to by buf
1158 with size size, consisting of the characters in the string list.
1159 The characters are written using encoding encode.
1160 Returns one of the following:
1162 * The number of bytes written (including terminating NULL
1164 character)
1165 * -size if the string was truncated because of buffer space
1167 * 0 if list is not a string that can be encoded with encode or
1169 if size was < 1.
1170 The written string is always NULL-terminated, unless buffer size
1172 is < 1.
1173 int enif_get_tuple(ErlNifEnv* env, ERL_NIF_TERM
1175 term, int* arity, const ERL_NIF_TERM** array)
1176 If term is a tuple, this function sets *array to point to an
1178 array containing the elements of the tuple, and sets *arity to
1179 the number of elements. Notice that the array is read-only and
1180 (*array)[N-1] is the Nth element of the tuple. *array is unde‐
1181 fined if the arity of the tuple is zero.
1182 Returns true on success, or false if term is not a tuple.
1184 int enif_get_uint(ErlNifEnv* env, ERL_NIF_TERM
1186 term, unsigned int* ip)
1187 Sets *ip to the unsigned integer value of term.
1189 Returns true on success, or false if term is not an unsigned
1191 integer or is outside the bounds of type unsigned int.
1192 int enif_get_uint64(ErlNifEnv* env,
1194 ERL_NIF_TERM term, ErlNifUInt64* ip)
1195 Sets *ip to the unsigned integer value of term.
1197 Returns true on success, or false if term is not an unsigned
1199 integer or is outside the bounds of an unsigned 64-bit integer.
1200 int enif_get_ulong(ErlNifEnv* env, ERL_NIF_TERM
1202 term, unsigned long* ip)
1203 Sets *ip to the unsigned long integer value of term.
1205 Returns true on success, or false if term is not an unsigned
1207 integer or is outside the bounds of type unsigned long.
1208 int enif_getenv(const char* key, char* value,
1210 size_t *value_size)
1211 Same as erl_drv_getenv.
1213 int enif_has_pending_exception(ErlNifEnv* env,
1215 ERL_NIF_TERM* reason)
1216 Returns true if a pending exception is associated with the envi‐
1218 ronment env. If reason is a NULL pointer, ignore it. Otherwise,
1219 if a pending exception associated with env exists, set *reason
1220 to the value of the exception term. For example, if
1221 enif_make_badarg is called to set a pending badarg exception, a
1222 later call to enif_has_pending_exception(env, &reason) sets
1223 *reason to the atom badarg, then return true.
1224 See also enif_make_badarg and enif_raise_exception.
1226 ErlNifUInt64 enif_hash(ErlNifHash type, ERL_NIF_TERM term, ErlNifUInt64
1228 salt)
1229 Hashes term according to the specified ErlNifHash type.
1231 Ranges of taken salt (if any) and returned value depend on the
1233 hash type.
1234 int enif_inspect_binary(ErlNifEnv* env,
1236 ERL_NIF_TERM bin_term, ErlNifBinary* bin)
1237 Initializes the structure pointed to by bin with information
1239 about binary term bin_term.
1240 Returns true on success, or false if bin_term is not a binary.
1242 int enif_inspect_iolist_as_binary(ErlNifEnv*
1244 env, ERL_NIF_TERM term, ErlNifBinary* bin)
1245 Initializes the structure pointed to by bin with a continuous
1247 buffer with the same byte content as iolist. As with
1248 inspect_binary, the data pointed to by bin is transient and does
1249 not need to be released.
1250 Returns true on success, or false if iolist is not an iolist.
1252 int enif_inspect_iovec(ErlNifEnv*
1254 env, size_t max_elements, ERL_NIF_TERM iovec_term,
1255 ERL_NIF_TERM* tail,
1256 ErlNifIOVec** iovec)
1257 Fills iovec with the list of binaries provided in iovec_term.
1259 The number of elements handled in the call is limited to
1260 max_elements, and tail is set to the remainder of the list. Note
1261 that the output may be longer than max_elements on some plat‐
1262 forms.
1263 To create a list of binaries from an arbitrary iolist, use
1265 erlang:iolist_to_iovec/1.
1266 When calling this function, iovec should contain a pointer to
1268 NULL or a ErlNifIOVec structure that should be used if possible.
1269 e.g.
1270 /* Don't use a pre-allocated structure */
1272 ErlNifIOVec *iovec = NULL;
1273 enif_inspect_iovec(env, max_elements, term, &tail, &iovec);
1274 /* Use a stack-allocated vector as an optimization for vectors with few elements */
1276 ErlNifIOVec vec, *iovec = &vec;
1277 enif_inspect_iovec(env, max_elements, term, &tail, &iovec);
1278 The contents of the iovec is valid until the called nif function
1281 returns. If the iovec should be valid after the nif call
1282 returns, it is possible to call this function with a NULL envi‐
1283 ronment. If no environment is given the iovec owns the data in
1284 the vector and it has to be explicitly freed using
1285 enif_free_iovec.
1286 Returns true on success, or false if iovec_term not an iovec.
1288 ErlNifIOQueue *enif_ioq_create(ErlNifIOQueueOpts opts)
1290 Create a new I/O Queue that can be used to store data. opts has
1292 to be set to ERL_NIF_IOQ_NORMAL.
1293 void enif_ioq_destroy(ErlNifIOQueue *q)
1295 Destroy the I/O queue and free all of it's contents
1297 int enif_ioq_deq(ErlNifIOQueue *q, size_t count, size_t *size)
1299 Dequeue count bytes from the I/O queue. If size is not NULL, the
1301 new size of the queue is placed there.
1302 Returns true on success, or false if the I/O does not contain
1304 count bytes. On failure the queue is left un-altered.
1305 int enif_ioq_enq_binary(ErlNifIOQueue *q, ErlNifBinary *bin, size_t
1307 skip)
1308 Enqueue the bin into q skipping the first skip bytes.
1310 Returns true on success, or false if skip is greater than the
1312 size of bin. Any ownership of the binary data is transferred to
1313 the queue and bin is to be considered read-only for the rest of
1314 the NIF call and then as released.
1315 int enif_ioq_enqv(ErlNifIOQueue *q, ErlNifIOVec *iovec, size_t skip)
1317 Enqueue the iovec into q skipping the first skip bytes.
1319 Returns true on success, or false if skip is greater than the
1321 size of iovec.
1322 SysIOVec *enif_ioq_peek(ErlNifIOQueue *q, int *iovlen)
1324 Get the I/O queue as a pointer to an array of SysIOVecs. It also
1326 returns the number of elements in iovlen.
1327 Nothing is removed from the queue by this function, that must be
1329 done with enif_ioq_deq.
1330 The returned array is suitable to use with the Unix system call
1332 writev.
1333 int enif_ioq_peek_head(ErlNifEnv *env, ErlNifIOQueue *q, size_t *size,
1335 ERL_NIF_TERM *bin_term)
1336 Get the head of the IO Queue as a binary term.
1338 If size is not NULL, the size of the head is placed there.
1340 Nothing is removed from the queue by this function, that must be
1342 done with enif_ioq_deq.
1343 Returns true on success, or false if the queue is empty.
1345 size_t enif_ioq_size(ErlNifIOQueue *q)
1347 Get the size of q.
1349 int enif_is_atom(ErlNifEnv* env, ERL_NIF_TERM term)
1351 Returns true if term is an atom.
1353 int enif_is_binary(ErlNifEnv* env, ERL_NIF_TERM term)
1355 Returns true if term is a binary.
1357 int enif_is_current_process_alive(ErlNifEnv* env)
1359 Returns true if the currently executing process is currently
1361 alive, otherwise false.
1362 This function can only be used from a NIF-calling thread, and
1364 with an environment corresponding to currently executing pro‐
1365 cesses.
1366 int enif_is_empty_list(ErlNifEnv* env,
1368 ERL_NIF_TERM term)
1369 Returns true if term is an empty list.
1371 int enif_is_exception(ErlNifEnv* env,
1373 ERL_NIF_TERM term)
1374 Return true if term is an exception.
1376 int enif_is_fun(ErlNifEnv* env, ERL_NIF_TERM
1378 term)
1379 Returns true if term is a fun.
1381 int enif_is_identical(ERL_NIF_TERM lhs,
1383 ERL_NIF_TERM rhs)
1384 Returns true if the two terms are identical. Corresponds to the
1386 Erlang operators =:= and =/=.
1387 int enif_is_list(ErlNifEnv* env, ERL_NIF_TERM term)
1389 Returns true if term is a list.
1391 int enif_is_map(ErlNifEnv* env, ERL_NIF_TERM
1393 term)
1394 Returns true if term is a map, otherwise false.
1396 int enif_is_number(ErlNifEnv* env, ERL_NIF_TERM
1398 term)
1399 Returns true if term is a number.
1401 int enif_is_pid(ErlNifEnv* env, ERL_NIF_TERM term)
1403 Returns true if term is a pid.
1405 int enif_is_pid_undefined(const ErlNifPid* pid)
1407 Returns true if pid has been set as undefined by
1409 enif_set_pid_undefined.
1410 int enif_is_port(ErlNifEnv* env, ERL_NIF_TERM term)
1412 Returns true if term is a port.
1414 int enif_is_port_alive(ErlNifEnv* env,
1416 ErlNifPort *port_id)
1417 Returns true if port_id is alive.
1419 This function is only thread-safe when the emulator with SMP
1421 support is used. It can only be used in a non-SMP emulator from
1422 a NIF-calling thread.
1423 int enif_is_process_alive(ErlNifEnv* env,
1425 ErlNifPid *pid)
1426 Returns true if pid is alive.
1428 This function is only thread-safe when the emulator with SMP
1430 support is used. It can only be used in a non-SMP emulator from
1431 a NIF-calling thread.
1432 int enif_is_ref(ErlNifEnv* env, ERL_NIF_TERM term)
1434 Returns true if term is a reference.
1436 int enif_is_tuple(ErlNifEnv* env, ERL_NIF_TERM term)
1438 Returns true if term is a tuple.
1440 int enif_keep_resource(void* obj)
1442 Adds a reference to resource object obj obtained from
1444 enif_alloc_resource. Each call to enif_keep_resource for an
1445 object must be balanced by a call to enif_release_resource
1446 before the object is destructed.
1447 ERL_NIF_TERM enif_make_atom(ErlNifEnv* env, const char* name)
1449 Creates an atom term from the NULL-terminated C-string name with
1451 ISO Latin-1 encoding. If the length of name exceeds the maximum
1452 length allowed for an atom (255 characters), enif_make_atom
1453 invokes enif_make_badarg.
1454 ERL_NIF_TERM enif_make_atom_len(ErlNifEnv* env,
1456 const char* name, size_t len)
1457 Create an atom term from the string name with length len. NULL
1459 characters are treated as any other characters. If len exceeds
1460 the maximum length allowed for an atom (255 characters),
1461 enif_make_atom invokes enif_make_badarg.
1462 ERL_NIF_TERM enif_make_badarg(ErlNifEnv* env)
1464 Makes a badarg exception to be returned from a NIF, and asso‐
1466 ciates it with environment env. Once a NIF or any function it
1467 calls invokes enif_make_badarg, the runtime ensures that a
1468 badarg exception is raised when the NIF returns, even if the NIF
1469 attempts to return a non-exception term instead.
1470 The return value from enif_make_badarg can be used only as the
1472 return value from the NIF that invoked it (directly or indi‐
1473 rectly) or be passed to enif_is_exception, but not to any other
1474 NIF API function.
1475 See also enif_has_pending_exception and enif_raise_exception.
1477 Note:
1479 Before ERTS 7.0 (Erlang/OTP 18), the return value from
1480 enif_make_badarg had to be returned from the NIF. This require‐
1481 ment is now lifted as the return value from the NIF is ignored
1482 if enif_make_badarg has been invoked.
1483 ERL_NIF_TERM enif_make_binary(ErlNifEnv* env, ErlNifBinary* bin)
1486 Makes a binary term from bin. Any ownership of the binary data
1488 is transferred to the created term and bin is to be considered
1489 read-only for the rest of the NIF call and then as released.
1490 ERL_NIF_TERM enif_make_copy(ErlNifEnv* dst_env,
1492 ERL_NIF_TERM src_term)
1493 Makes a copy of term src_term. The copy is created in environ‐
1495 ment dst_env. The source term can be located in any environment.
1496 ERL_NIF_TERM enif_make_double(ErlNifEnv* env, double d)
1498 Creates a floating-point term from a double. If argument double
1500 is not finite or is NaN, enif_make_double invokes
1501 enif_make_badarg.
1502 int enif_make_existing_atom(ErlNifEnv* env,
1504 const char* name, ERL_NIF_TERM* atom, ErlNifCharEncoding
1505 encode)
1506 Tries to create the term of an already existing atom from the
1508 NULL-terminated C-string name with encoding encode.
1509 If the atom already exists, this function stores the term in
1511 *atom and returns true, otherwise false. Also returns false if
1512 the length of name exceeds the maximum length allowed for an
1513 atom (255 characters).
1514 int enif_make_existing_atom_len(ErlNifEnv* env,
1516 const char* name, size_t len, ERL_NIF_TERM* atom, ErlNifCharEn‐
1517 coding
1518 encoding)
1519 Tries to create the term of an already existing atom from the
1521 string name with length len and encoding encode. NULL characters
1522 are treated as any other characters.
1523 If the atom already exists, this function stores the term in
1525 *atom and returns true, otherwise false. Also returns false if
1526 len exceeds the maximum length allowed for an atom (255 charac‐
1527 ters).
1528 ERL_NIF_TERM enif_make_int(ErlNifEnv* env, int i)
1530 Creates an integer term.
1532 ERL_NIF_TERM enif_make_int64(ErlNifEnv* env, ErlNifSInt64 i)
1534 Creates an integer term from a signed 64-bit integer.
1536 ERL_NIF_TERM enif_make_list(ErlNifEnv* env, unsigned cnt, ...)
1538 Creates an ordinary list term of length cnt. Expects cnt number
1540 of arguments (after cnt) of type ERL_NIF_TERM as the elements of
1541 the list.
1542 Returns an empty list if cnt is 0.
1544 ERL_NIF_TERM enif_make_list1(ErlNifEnv* env, ERL_NIF_TERM e1)
1546 ERL_NIF_TERM enif_make_list2(ErlNifEnv* env,
1547 ERL_NIF_TERM e1, ERL_NIF_TERM e2)
1548 ERL_NIF_TERM enif_make_list3(ErlNifEnv* env,
1549 ERL_NIF_TERM e1, ERL_NIF_TERM e2, ERL_NIF_TERM e3)
1550 ERL_NIF_TERM enif_make_list4(ErlNifEnv* env,
1551 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e4)
1552 ERL_NIF_TERM enif_make_list5(ErlNifEnv* env,
1553 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e5)
1554 ERL_NIF_TERM enif_make_list6(ErlNifEnv* env,
1555 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e6)
1556 ERL_NIF_TERM enif_make_list7(ErlNifEnv* env,
1557 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e7)
1558 ERL_NIF_TERM enif_make_list8(ErlNifEnv* env,
1559 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e8)
1560 ERL_NIF_TERM enif_make_list9(ErlNifEnv* env,
1561 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e9)
1562 Creates an ordinary list term with length indicated by the func‐
1564 tion name. Prefer these functions (macros) over the variadic
1565 enif_make_list to get a compile-time error if the number of
1566 arguments does not match.
1567 ERL_NIF_TERM enif_make_list_cell(ErlNifEnv*
1569 env, ERL_NIF_TERM head, ERL_NIF_TERM tail)
1570 Creates a list cell [head | tail].
1572 ERL_NIF_TERM enif_make_list_from_array(ErlNifEnv* env, const
1574 ERL_NIF_TERM
1575 arr[], unsigned cnt)
1576 Creates an ordinary list containing the elements of array arr of
1578 length cnt.
1579 Returns an empty list if cnt is 0.
1581 ERL_NIF_TERM enif_make_long(ErlNifEnv* env, long int i)
1583 Creates an integer term from a long int.
1585 int enif_make_map_put(ErlNifEnv* env,
1587 ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM value,
1588 ERL_NIF_TERM* map_out)
1589 Makes a copy of map map_in and inserts key with value. If key
1591 already exists in map_in, the old associated value is replaced
1592 by value.
1593 If successful, this function sets *map_out to the new map and
1595 returns true. Returns false if map_in is not a map.
1596 The map_in term must belong to environment env.
1598 int enif_make_map_remove(ErlNifEnv* env,
1600 ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM* map_out)
1601 If map map_in contains key, this function makes a copy of map_in
1603 in *map_out, and removes key and the associated value. If map
1604 map_in does not contain key, *map_out is set to map_in.
1605 Returns true on success, or false if map_in is not a map.
1607 The map_in term must belong to environment env.
1609 int enif_make_map_update(ErlNifEnv* env,
1611 ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM new_value,
1612 ERL_NIF_TERM* map_out)
1613 Makes a copy of map map_in and replace the old associated value
1615 for key with new_value.
1616 If successful, this function sets *map_out to the new map and
1618 returns true. Returns false if map_in is not a map or if it does
1619 not contain key.
1620 The map_in term must belong to environment env.
1622 int enif_make_map_from_arrays(ErlNifEnv* env, ERL_NIF_TERM keys[],
1624 ERL_NIF_TERM values[], size_t cnt, ERL_NIF_TERM *map_out)
1625 Makes a map term from the given keys and values.
1627 If successful, this function sets *map_out to the new map and
1629 returns true. Returns false there are any duplicate keys.
1630 All keys and values must belong to env.
1632 ERL_NIF_TERM enif_make_monitor_term(ErlNifEnv* env, const ErlNifMoni‐
1634 tor* mon)
1635 Creates a term identifying the given monitor received from
1637 enif_monitor_process.
1638 This function is primarily intended for debugging purpose.
1640 unsigned char *enif_make_new_binary(ErlNifEnv*
1642 env, size_t size, ERL_NIF_TERM* termp)
1643 Allocates a binary of size size bytes and creates an owning
1645 term. The binary data is mutable until the calling NIF returns.
1646 This is a quick way to create a new binary without having to use
1647 ErlNifBinary. The drawbacks are that the binary cannot be kept
1648 between NIF calls and it cannot be reallocated.
1649 Returns a pointer to the raw binary data and sets *termp to the
1651 binary term.
1652 ERL_NIF_TERM enif_make_new_map(ErlNifEnv* env)
1654 Makes an empty map term.
1656 ERL_NIF_TERM enif_make_pid(ErlNifEnv* env, const ErlNifPid* pid)
1658 Makes a pid term or the atom undefined from *pid.
1660 ERL_NIF_TERM enif_make_ref(ErlNifEnv* env)
1662 Creates a reference like erlang:make_ref/0.
1664 ERL_NIF_TERM enif_make_resource(ErlNifEnv* env, void* obj)
1666 Creates an opaque handle to a memory-managed resource object
1668 obtained by enif_alloc_resource. No ownership transfer is done,
1669 as the resource object still needs to be released by
1670 enif_release_resource. However, notice that the call to
1671 enif_release_resource can occur immediately after obtaining the
1672 term from enif_make_resource, in which case the resource object
1673 is deallocated when the term is garbage collected. For more
1674 details, see the example of creating and returning a resource
1675 object in the User's Guide.
1676 Note:
1678 Since ERTS 9.0 (OTP-20.0), resource terms have a defined behav‐
1679 ior when compared and serialized through term_to_binary or
1680 passed between nodes.
1681 * Two resource terms will compare equal if and only if they
1683 would yield the same resource object pointer when passed to
1684 enif_get_resource.
1685 * A resource term can be serialized with term_to_binary and
1687 later be fully recreated if the resource object is still
1688 alive when binary_to_term is called. A stale resource term
1689 will be returned from binary_to_term if the resource object
1690 has been deallocated. enif_get_resource will return false
1691 for stale resource terms.
1692 The same principles of serialization apply when passing
1694 resource terms in messages to remote nodes and back again. A
1695 resource term will act stale on all nodes except the node
1696 where its resource object is still alive in memory.
1697 Before ERTS 9.0 (OTP-20.0), all resource terms did compare equal
1699 to each other and to empty binaries (<<>>). If serialized, they
1700 would be recreated as plain empty binaries.
1701 ERL_NIF_TERM enif_make_resource_binary(ErlNifEnv* env, void* obj, const
1704 void* data, size_t size)
1705 Creates a binary term that is memory-managed by a resource
1707 object obj obtained by enif_alloc_resource. The returned binary
1708 term consists of size bytes pointed to by data. This raw binary
1709 data must be kept readable and unchanged until the destructor of
1710 the resource is called. The binary data can be stored external
1711 to the resource object, in which case the destructor is respon‐
1712 sible for releasing the data.
1713 Several binary terms can be managed by the same resource object.
1715 The destructor is not called until the last binary is garbage
1716 collected. This can be useful to return different parts of a
1717 larger binary buffer.
1718 As with enif_make_resource, no ownership transfer is done. The
1720 resource still needs to be released with enif_release_resource.
1721 int enif_make_reverse_list(ErlNifEnv* env, ERL_NIF_TERM list_in,
1723 ERL_NIF_TERM *list_out)
1724 Sets *list_out to the reverse list of the list list_in and
1726 returns true, or returns false if list_in is not a list.
1727 This function is only to be used on short lists, as a copy is
1729 created of the list, which is not released until after the NIF
1730 returns.
1731 The list_in term must belong to environment env.
1733 ERL_NIF_TERM enif_make_string(ErlNifEnv* env,
1735 const char* string, ErlNifCharEncoding encoding)
1736 Creates a list containing the characters of the NULL-terminated
1738 string string with encoding encoding.
1739 ERL_NIF_TERM enif_make_string_len(ErlNifEnv*
1741 env, const char* string, size_t len, ErlNifCharEncoding
1742 encoding)
1743 Creates a list containing the characters of the string string
1745 with length len and encoding encoding. NULL characters are
1746 treated as any other characters.
1747 ERL_NIF_TERM enif_make_sub_binary(ErlNifEnv*
1749 env, ERL_NIF_TERM bin_term, size_t pos, size_t size)
1750 Makes a subbinary of binary bin_term, starting at zero-based
1752 position pos with a length of size bytes. bin_term must be a
1753 binary or bitstring. pos+size must be less or equal to the num‐
1754 ber of whole bytes in bin_term.
1755 ERL_NIF_TERM enif_make_tuple(ErlNifEnv* env,
1757 unsigned cnt, ...)
1758 Creates a tuple term of arity cnt. Expects cnt number of argu‐
1760 ments (after cnt) of type ERL_NIF_TERM as the elements of the
1761 tuple.
1762 ERL_NIF_TERM enif_make_tuple1(ErlNifEnv* env,
1764 ERL_NIF_TERM e1)
1765 ERL_NIF_TERM enif_make_tuple2(ErlNifEnv* env,
1766 ERL_NIF_TERM e1, ERL_NIF_TERM e2)
1767 ERL_NIF_TERM enif_make_tuple3(ErlNifEnv* env,
1768 ERL_NIF_TERM e1, ERL_NIF_TERM e2, ERL_NIF_TERM e3)
1769 ERL_NIF_TERM enif_make_tuple4(ErlNifEnv* env,
1770 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e4)
1771 ERL_NIF_TERM enif_make_tuple5(ErlNifEnv* env,
1772 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e5)
1773 ERL_NIF_TERM enif_make_tuple6(ErlNifEnv* env,
1774 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e6)
1775 ERL_NIF_TERM enif_make_tuple7(ErlNifEnv* env,
1776 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e7)
1777 ERL_NIF_TERM enif_make_tuple8(ErlNifEnv* env,
1778 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e8)
1779 ERL_NIF_TERM enif_make_tuple9(ErlNifEnv* env,
1780 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e9)
1781 Creates a tuple term with length indicated by the function name.
1783 Prefer these functions (macros) over the variadic
1784 enif_make_tuple to get a compile-time error if the number of
1785 arguments does not match.
1786 ERL_NIF_TERM enif_make_tuple_from_array(ErlNifEnv* env, const
1788 ERL_NIF_TERM
1789 arr[], unsigned cnt)
1790 Creates a tuple containing the elements of array arr of length
1792 cnt.
1793 ERL_NIF_TERM enif_make_uint(ErlNifEnv* env, unsigned int i)
1795 Creates an integer term from an unsigned int.
1797 ERL_NIF_TERM enif_make_uint64(ErlNifEnv* env, ErlNifUInt64 i)
1799 Creates an integer term from an unsigned 64-bit integer.
1801 ERL_NIF_TERM enif_make_ulong(ErlNifEnv* env, unsigned long i)
1803 Creates an integer term from an unsigned long int.
1805 ERL_NIF_TERM enif_make_unique_integer(ErlNifEnv
1807 *env, ErlNifUniqueInteger properties)
1808 Returns a unique integer with the same properties as specified
1810 by erlang:unique_integer/1.
1811 env is the environment to create the integer in.
1813 ERL_NIF_UNIQUE_POSITIVE and ERL_NIF_UNIQUE_MONOTONIC can be
1815 passed as the second argument to change the properties of the
1816 integer returned. They can be combined by OR:ing the two values
1817 together.
1818 See also ErlNifUniqueInteger.
1820 int enif_map_iterator_create(ErlNifEnv *env,
1822 ERL_NIF_TERM map, ErlNifMapIterator *iter, ErlNifMapIteratorEn‐
1823 try
1824 entry)
1825 Creates an iterator for the map map by initializing the struc‐
1827 ture pointed to by iter. Argument entry determines the start
1828 position of the iterator: ERL_NIF_MAP_ITERATOR_FIRST or
1829 ERL_NIF_MAP_ITERATOR_LAST.
1830 Returns true on success, or false if map is not a map.
1832 A map iterator is only useful during the lifetime of environment
1834 env that the map belongs to. The iterator must be destroyed by
1835 calling enif_map_iterator_destroy:
1836 ERL_NIF_TERM key, value;
1838 ErlNifMapIterator iter;
1839 enif_map_iterator_create(env, my_map, &iter, ERL_NIF_MAP_ITERATOR_FIRST);
1840 while (enif_map_iterator_get_pair(env, &iter, &key, &value)) {
1842 do_something(key,value);
1843 enif_map_iterator_next(env, &iter);
1844 }
1845 enif_map_iterator_destroy(env, &iter);
1846 Note:
1848 The key-value pairs of a map have no defined iteration order.
1849 The only guarantee is that the iteration order of a single map
1850 instance is preserved during the lifetime of the environment
1851 that the map belongs to.
1852 void enif_map_iterator_destroy(ErlNifEnv *env,
1855 ErlNifMapIterator *iter)
1856 Destroys a map iterator created by enif_map_iterator_create.
1858 int enif_map_iterator_get_pair(ErlNifEnv *env,
1860 ErlNifMapIterator *iter, ERL_NIF_TERM *key, ERL_NIF_TERM
1861 *value)
1862 Gets key and value terms at the current map iterator position.
1864 On success, sets *key and *value and returns true. Returns false
1866 if the iterator is positioned at head (before first entry) or
1867 tail (beyond last entry).
1868 int enif_map_iterator_is_head(ErlNifEnv *env,
1870 ErlNifMapIterator *iter)
1871 Returns true if map iterator iter is positioned before the first
1873 entry.
1874 int enif_map_iterator_is_tail(ErlNifEnv *env,
1876 ErlNifMapIterator *iter)
1877 Returns true if map iterator iter is positioned after the last
1879 entry.
1880 int enif_map_iterator_next(ErlNifEnv *env,
1882 ErlNifMapIterator *iter)
1883 Increments map iterator to point to the next key-value entry.
1885 Returns true if the iterator is now positioned at a valid key-
1887 value entry, or false if the iterator is positioned at the tail
1888 (beyond the last entry).
1889 int enif_map_iterator_prev(ErlNifEnv *env,
1891 ErlNifMapIterator *iter)
1892 Decrements map iterator to point to the previous key-value
1894 entry.
1895 Returns true if the iterator is now positioned at a valid key-
1897 value entry, or false if the iterator is positioned at the head
1898 (before the first entry).
1899 int enif_monitor_process(ErlNifEnv* caller_env,
1901 void* obj, const ErlNifPid* target_pid, ErlNifMonitor* mon)
1902 Starts monitoring a process from a resource. When a process is
1904 monitored, a process exit results in a call to the provided down
1905 callback associated with the resource type.
1906 Argument obj is pointer to the resource to hold the monitor and
1908 *target_pid identifies the local process to be monitored.
1909 If mon is not NULL, a successful call stores the identity of the
1911 monitor in the ErlNifMonitor struct pointed to by mon. This
1912 identifier is used to refer to the monitor for later removal
1913 with enif_demonitor_process or compare with enif_compare_moni‐
1914 tors. A monitor is automatically removed when it triggers or
1915 when the resource is deallocated.
1916 Argument caller_env is the environment of the calling process or
1918 callback. Must only be NULL if calling from a custom thread.
1919 Returns 0 on success, < 0 if no down callback is provided, and >
1921 0 if the process is no longer alive or if target_pid is unde‐
1922 fined.
1923 This function is only thread-safe when the emulator with SMP
1925 support is used. It can only be used in a non-SMP emulator from
1926 a NIF-calling thread.
1927 ErlNifTime enif_monotonic_time(ErlNifTimeUnit time_unit)
1929 Returns the current Erlang monotonic time. Notice that it is
1931 not uncommon with negative values.
1932 time_unit is the time unit of the returned value.
1934 Returns ERL_NIF_TIME_ERROR if called with an invalid time unit
1936 argument, or if called from a thread that is not a scheduler
1937 thread.
1938 See also ErlNifTime and ErlNifTimeUnit.
1940 ErlNifMutex *enif_mutex_create(char *name)
1942 Same as erl_drv_mutex_create.
1944 void enif_mutex_destroy(ErlNifMutex *mtx)
1946 Same as erl_drv_mutex_destroy.
1948 void enif_mutex_lock(ErlNifMutex *mtx)
1950 Same as erl_drv_mutex_lock.
1952 char*enif_mutex_name(ErlNifMutex* mtx)
1954 Same as erl_drv_mutex_name.
1956 int enif_mutex_trylock(ErlNifMutex *mtx)
1958 Same as erl_drv_mutex_trylock.
1960 void enif_mutex_unlock(ErlNifMutex *mtx)
1962 Same as erl_drv_mutex_unlock.
1964 ERL_NIF_TERM enif_now_time(ErlNifEnv *env)
1966 Returns an erlang:now() time stamp.
1968 This function is deprecated.
1970 ErlNifResourceType *enif_open_resource_type(ErlNifEnv* env, const char*
1972 module_str, const char* name, ErlNifResourceDtor* dtor,
1973 ErlNifResourceFlags flags, ErlNifResourceFlags* tried)
1974 Creates or takes over a resource type identified by the string
1976 name and gives it the destructor function pointed to by dtor.
1977 Argument flags can have the following values:
1978 ERL_NIF_RT_CREATE:
1980 Creates a new resource type that does not already exist.
1981 ERL_NIF_RT_TAKEOVER:
1983 Opens an existing resource type and takes over ownership of
1984 all its instances. The supplied destructor dtor is called
1985 both for existing instances and new instances not yet cre‐
1986 ated by the calling NIF library.
1987 The two flag values can be combined with bitwise OR. The
1989 resource type name is local to the calling module. Argument mod‐
1990 ule_str is not (yet) used and must be NULL. dtor can be NULL if
1991 no destructor is needed.
1992 On success, the function returns a pointer to the resource type
1994 and *tried is set to either ERL_NIF_RT_CREATE or
1995 ERL_NIF_RT_TAKEOVER to indicate what was done. On failure,
1996 returns NULL and sets *tried to flags. It is allowed to set
1997 tried to NULL.
1998 Notice that enif_open_resource_type is only allowed to be called
2000 in the two callbacks load and upgrade.
2001 See also enif_open_resource_type_x.
2003 ErlNifResourceType *enif_open_resource_type_x(ErlNifEnv* env, const
2005 char* name, const ErlNifResourceTypeInit* init,
2006 ErlNifResourceFlags flags, ErlNifResourceFlags* tried)
2007 Same as enif_open_resource_type except it accepts additional
2009 callback functions for resource types that are used together
2010 with enif_select and enif_monitor_process.
2011 Argument init is a pointer to an ErlNifResourceTypeInit struc‐
2013 ture that contains the function pointers for destructor, down
2014 and stop callbacks for the resource type.
2015 int enif_port_command(ErlNifEnv* env, const
2017 ErlNifPort* to_port, ErlNifEnv *msg_env, ERL_NIF_TERM msg)
2018 Works as erlang:port_command/2, except that it is always com‐
2020 pletely asynchronous.
2021 env:
2023 The environment of the calling process. Must not be NULL.
2024 *to_port:
2026 The port ID of the receiving port. The port ID is to refer
2027 to a port on the local node.
2028 msg_env:
2030 The environment of the message term. Can be a process inde‐
2031 pendent environment allocated with enif_alloc_env or NULL.
2032 msg:
2034 The message term to send. The same limitations apply as on
2035 the payload to erlang:port_command/2.
2036 Using a msg_env of NULL is an optimization, which groups
2038 together calls to enif_alloc_env, enif_make_copy, enif_port_com‐
2039 mand, and enif_free_env into one call. This optimization is only
2040 useful when a majority of the terms are to be copied from env to
2041 msg_env.
2042 Returns true if the command is successfully sent. Returns false
2044 if the command fails, for example:
2045 * *to_port does not refer to a local port.
2047 * The currently executing process (that is, the sender) is not
2049 alive.
2050 * msg is invalid.
2052 See also enif_get_local_port.
2054 void *enif_priv_data(ErlNifEnv* env)
2056 Returns the pointer to the private data that was set by load or
2058 upgrade.
2059 ERL_NIF_TERM enif_raise_exception(ErlNifEnv*
2061 env, ERL_NIF_TERM reason)
2062 Creates an error exception with the term reason to be returned
2064 from a NIF, and associates it with environment env. Once a NIF
2065 or any function it calls invokes enif_raise_exception, the run‐
2066 time ensures that the exception it creates is raised when the
2067 NIF returns, even if the NIF attempts to return a non-exception
2068 term instead.
2069 The return value from enif_raise_exception can only be used as
2071 the return value from the NIF that invoked it (directly or indi‐
2072 rectly) or be passed to enif_is_exception, but not to any other
2073 NIF API function.
2074 See also enif_has_pending_exception and enif_make_badarg.
2076 void *enif_realloc(void* ptr, size_t size)
2078 Reallocates memory allocated by enif_alloc to size bytes.
2080 Returns NULL if the reallocation fails.
2082 The returned pointer is suitably aligned for any built-in type
2084 that fit in the allocated memory.
2085 int enif_realloc_binary(ErlNifBinary* bin, size_t size)
2087 Changes the size of a binary bin. The source binary can be read-
2089 only, in which case it is left untouched and a mutable copy is
2090 allocated and assigned to *bin.
2091 Returns true on success, or false if memory allocation failed.
2093 void enif_release_binary(ErlNifBinary* bin)
2095 Releases a binary obtained from enif_alloc_binary.
2097 void enif_release_resource(void* obj)
2099 Removes a reference to resource object obj obtained from
2101 enif_alloc_resource. The resource object is destructed when the
2102 last reference is removed. Each call to enif_release_resource
2103 must correspond to a previous call to enif_alloc_resource or
2104 enif_keep_resource. References made by enif_make_resource can
2105 only be removed by the garbage collector.
2106 There are no guarantees exactly when the destructor of an unref‐
2108 erenced resource is called. It could be called directly by
2109 enif_release_resource but it could also be scheduled to be
2110 called at a later time possibly by another thread.
2111 ErlNifRWLock *enif_rwlock_create(char *name)
2113 Same as erl_drv_rwlock_create.
2115 void enif_rwlock_destroy(ErlNifRWLock *rwlck)
2117 Same as erl_drv_rwlock_destroy.
2119 char*enif_rwlock_name(ErlNifRWLock* rwlck)
2121 Same as erl_drv_rwlock_name.
2123 void enif_rwlock_rlock(ErlNifRWLock *rwlck)
2125 Same as erl_drv_rwlock_rlock.
2127 void enif_rwlock_runlock(ErlNifRWLock *rwlck)
2129 Same as erl_drv_rwlock_runlock.
2131 void enif_rwlock_rwlock(ErlNifRWLock *rwlck)
2133 Same as erl_drv_rwlock_rwlock.
2135 void enif_rwlock_rwunlock(ErlNifRWLock *rwlck)
2137 Same as erl_drv_rwlock_rwunlock.
2139 int enif_rwlock_tryrlock(ErlNifRWLock *rwlck)
2141 Same as erl_drv_rwlock_tryrlock.
2143 int enif_rwlock_tryrwlock(ErlNifRWLock *rwlck)
2145 Same as erl_drv_rwlock_tryrwlock.
2147 ERL_NIF_TERM enif_schedule_nif(ErlNifEnv* env,
2149 const char* fun_name, int flags, ERL_NIF_TERM (*fp)(ErlNifEnv*
2150 env, int
2151 argc, const ERL_NIF_TERM argv[]), int argc, const ERL_NIF_TERM
2152 argv[])
2153 Schedules NIF fp to execute. This function allows an application
2155 to break up long-running work into multiple regular NIF calls or
2156 to schedule a dirty NIF to execute on a dirty scheduler thread.
2157 fun_name:
2159 Provides a name for the NIF that is scheduled for execution.
2160 If it cannot be converted to an atom, enif_schedule_nif
2161 returns a badarg exception.
2162 flags:
2164 Must be set to 0 for a regular NIF. If the emulator was
2165 built with dirty scheduler support enabled, flags can be set
2166 to either ERL_NIF_DIRTY_JOB_CPU_BOUND if the job is expected
2167 to be CPU-bound, or ERL_NIF_DIRTY_JOB_IO_BOUND for jobs that
2168 will be I/O-bound. If dirty scheduler threads are not avail‐
2169 able in the emulator, an attempt to schedule such a job
2170 results in a notsup exception.
2171 argc and argv:
2173 Can either be the originals passed into the calling NIF, or
2174 can be values created by the calling NIF.
2175 The calling NIF must use the return value of enif_schedule_nif
2177 as its own return value.
2178 Be aware that enif_schedule_nif, as its name implies, only
2180 schedules the NIF for future execution. The calling NIF does not
2181 block waiting for the scheduled NIF to execute and return. This
2182 means that the calling NIF cannot expect to receive the sched‐
2183 uled NIF return value and use it for further operations.
2184 int enif_select(ErlNifEnv* env, ErlNifEvent event, enum ErlNifSelect‐
2186 Flags mode, void* obj, const ErlNifPid* pid, ERL_NIF_TERM ref)
2187 This function can be used to receive asynchronous notifications
2189 when OS-specific event objects become ready for either read or
2190 write operations.
2191 Argument event identifies the event object. On Unix systems, the
2193 functions select/poll are used. The event object must be a
2194 socket, pipe or other file descriptor object that select/poll
2195 can use.
2196 Argument mode describes the type of events to wait for. It can
2198 be ERL_NIF_SELECT_READ, ERL_NIF_SELECT_WRITE or a bitwise OR
2199 combination to wait for both. It can also be ERL_NIF_SELECT_STOP
2200 or ERL_NIF_SELECT_CANCEL which are described further below. When
2201 a read or write event is triggered, a notification message like
2202 this is sent to the process identified by pid:
2203 {select, Obj, Ref, ready_input | ready_output}
2205 ready_input or ready_output indicates if the event object is
2207 ready for reading or writing.
2208 Note:
2210 For complete control over the message format use the newer func‐
2211 tions enif_select_read or enif_select_write introduced in
2212 erts-11.0 (OTP-22.0).
2213 Argument pid may be NULL to indicate the calling process. It
2216 must not be set as undefined.
2217 Argument obj is a resource object obtained from
2219 enif_alloc_resource. The purpose of the resource objects is as a
2220 container of the event object to manage its state and lifetime.
2221 A handle to the resource is received in the notification message
2222 as Obj.
2223 Argument ref must be either a reference obtained from
2225 erlang:make_ref/0 or the atom undefined. It will be passed as
2226 Ref in the notifications. If a selective receive statement is
2227 used to wait for the notification then a reference created just
2228 before the receive will exploit a runtime optimization that
2229 bypasses all earlier received messages in the queue.
2230 The notifications are one-shot only. To receive further notifi‐
2232 cations of the same type (read or write), repeated calls to
2233 enif_select must be made after receiving each notification.
2234 ERL_NIF_SELECT_CANCEL can be used to cancel previously selected
2236 events. It must be used in a bitwise OR combination with
2237 ERL_NIF_SELECT_READ and/or ERL_NIF_SELECT_WRITE to indicate
2238 which type of event to cancel. Arguments pid and ref are ignored
2239 when ERL_NIF_SELECT_CANCEL is specified. The return value will
2240 tell if the event was actualy cancelled or if a notification may
2241 already have been sent.
2242 Use ERL_NIF_SELECT_STOP as mode in order to safely close an
2244 event object that has been passed to enif_select. The stop call‐
2245 back of the resource obj will be called when it is safe to close
2246 the event object. This safe way of closing event objects must be
2247 used even if all notifications have been received (or cancelled)
2248 and no further calls to enif_select have been made.
2249 ERL_NIF_SELECT_STOP will first cancel any selected events before
2250 it calls or schedules the stop callback. Arguments pid and ref
2251 are ignored when ERL_NIF_SELECT_STOP is specified.
2252 The first call to enif_select for a specific OS event will
2254 establish a relation between the event object and the containing
2255 resource. All subsequent calls for an event must pass its con‐
2256 taining resource as argument obj. The relation is dissolved when
2257 enif_select has been called with mode as ERL_NIF_SELECT_STOP and
2258 the corresponding stop callback has returned. A resource can
2259 contain several event objects but one event object can only be
2260 contained within one resource. A resource will not be destructed
2261 until all its contained relations have been dissolved.
2262 Note:
2264 Use enif_monitor_process together with enif_select to detect
2265 failing Erlang processes and prevent them from causing permanent
2266 leakage of resources and their contained OS event objects.
2267 Returns a non-negative value on success where the following bits
2270 can be set:
2271 ERL_NIF_SELECT_STOP_CALLED:
2273 The stop callback was called directly by enif_select.
2274 ERL_NIF_SELECT_STOP_SCHEDULED:
2276 The stop callback was scheduled to run on some other thread
2277 or later by this thread.
2278 ERL_NIF_SELECT_READ_CANCELLED:
2280 A read event was cancelled by ERL_NIF_SELECT_CANCEL or
2281 ERL_NIF_SELECT_STOP and is guaranteed not to generate a
2282 ready_input notification message.
2283 ERL_NIF_SELECT_WRITE_CANCELLED:
2285 A write event was cancelled by ERL_NIF_SELECT_CANCEL or
2286 ERL_NIF_SELECT_STOP and is guaranteed not to generate a
2287 ready_output notification message.
2288 Returns a negative value if the call failed where the following
2290 bits can be set:
2291 ERL_NIF_SELECT_INVALID_EVENT:
2293 Argument event is not a valid OS event object.
2294 ERL_NIF_SELECT_FAILED:
2296 The system call failed to add the event object to the poll
2297 set.
2298 Note:
2300 Use bitwise AND to test for specific bits in the return value.
2301 New significant bits may be added in future releases to give
2302 more detailed information for both failed and successful calls.
2303 Do NOT use equality tests like ==, as that may cause your appli‐
2304 cation to stop working.
2305 Example:
2307 retval = enif_select(env, fd, ERL_NIF_SELECT_STOP, resource, ref);
2309 if (retval < 0) {
2310 /* handle error */
2311 }
2312 /* Success! */
2313 if (retval & ERL_NIF_SELECT_STOP_CALLED) {
2314 /* ... */
2315 }
2316 Note:
2320 The mode flag ERL_NIF_SELECT_CANCEL and the return flags
2321 ERL_NIF_SELECT_READ_CANCELLED and ERL_NIF_SELECT_WRITE_CANCELLED
2322 were introduced in erts-11.0 (OTP-22.0).
2323 int enif_select_read(ErlNifEnv* env, ErlNifEvent event, void* obj,
2326 const ErlNifPid* pid, ERL_NIF_TERM msg, ErlNifEnv* msg_env)
2327 int enif_select_write(ErlNifEnv* env, ErlNifEvent event, void* obj,
2328 const ErlNifPid* pid, ERL_NIF_TERM msg, ErlNifEnv* msg_env)
2329 These are variants of enif_select where you can supply your own
2331 message term msg that will be sent to the process instead of the
2332 predefined tuple {select,_,_,_}.
2333 Argument msg_env must either be NULL or the environment of msg
2335 allocated with enif_alloc_env. If argument msg_env is NULL the
2336 term msg will be copied, otherwise both msg and msg_env will be
2337 invalidated by a successful call to enif_select_read or
2338 enif_select_write. The environment is then to either be freed
2339 with enif_free_env or cleared for reuse with enif_clear_env. An
2340 unsuccessful call will leave msg and msg_env still valid.
2341 Apart from the message format enif_select_read and
2343 enif_select_write behaves exactly the same as enif_select with
2344 argument mode as either ERL_NIF_SELECT_READ or
2345 ERL_NIF_SELECT_WRITE. To cancel or close events use enif_select.
2346 ErlNifPid *enif_self(ErlNifEnv* caller_env, ErlNifPid* pid)
2348 Initializes the ErlNifPid variable at *pid to represent the
2350 calling process.
2351 Returns pid if successful, or NULL if caller_env is not a
2353 process bound environment.
2354 int enif_send(ErlNifEnv* caller_env,
2356 ErlNifPid* to_pid, ErlNifEnv* msg_env, ERL_NIF_TERM msg)
2357 Sends a message to a process.
2359 caller_env:
2361 The environment of the calling process or callback. Must be
2362 NULL only if calling from a custom thread not spawned by
2363 ERTS.
2364 *to_pid:
2366 The pid of the receiving process. The pid is to refer to a
2367 process on the local node.
2368 msg_env:
2370 The environment of the message term. Must be a process inde‐
2371 pendent environment allocated with enif_alloc_env or NULL.
2372 msg:
2374 The message term to send.
2375 Returns true if the message is successfully sent. Returns false
2377 if the send operation fails, that is:
2378 * *to_pid does not refer to an alive local process.
2380 * The currently executing process (that is, the sender) is not
2382 alive.
2383 The message environment msg_env with all its terms (including
2385 msg) is invalidated by a successful call to enif_send. The envi‐
2386 ronment is to either be freed with enif_free_env or cleared for
2387 reuse with enif_clear_env. An unsuccessful call will leave msg
2388 and msg_env still valid.
2389 If msg_env is set to NULL, the msg term is copied and the origi‐
2391 nal term and its environment is still valid after the call.
2392 This function is only thread-safe when the emulator with SMP
2394 support is used. It can only be used in a non-SMP emulator from
2395 a NIF-calling thread.
2396 Note:
2398 Passing msg_env as NULL is only supported as from ERTS 8.0
2399 (Erlang/OTP 19).
2400 void enif_set_pid_undefined(ErlNifPid* pid)
2403 Sets an ErlNifPid variable as undefined. See enif_is_pid_unde‐
2405 fined.
2406 unsigned enif_sizeof_resource(void* obj)
2408 Gets the byte size of resource object obj obtained by
2410 enif_alloc_resource.
2411 int enif_snprintf(char *str, size_t size, const
2413 char *format, ...)
2414 Similar to snprintf but this format string also accepts "%T",
2416 which formats Erlang terms of type ERL_NIF_TERM.
2417 This function is primarily intended for debugging purpose. It is
2419 not recommended to print very large terms with %T. The function
2420 may change errno, even if successful.
2421 void enif_system_info(ErlNifSysInfo
2423 *sys_info_ptr, size_t size)
2424 Same as driver_system_info.
2426 int enif_term_to_binary(ErlNifEnv *env,
2428 ERL_NIF_TERM term, ErlNifBinary *bin)
2429 Allocates a new binary with enif_alloc_binary and stores the
2431 result of encoding term according to the Erlang external term
2432 format.
2433 Returns true on success, or false if the allocation fails.
2435 See also erlang:term_to_binary/1 and enif_binary_to_term.
2437 ErlNifTermType enif_term_type(ErlNifEnv *env, ERL_NIF_TERM term)
2439 Determines the type of the given term. The term must be an ordi‐
2441 nary Erlang term and not one of the special terms returned by
2442 enif_raise_exception, enif_schedule_nif, or similar.
2443 The following types are defined at the moment:
2445 ERL_NIF_TERM_TYPE_ATOM:
2447 ERL_NIF_TERM_TYPE_BITSTRING:
2450 A bitstring or binary
2451 ERL_NIF_TERM_TYPE_FLOAT:
2453 ERL_NIF_TERM_TYPE_FUN:
2456 ERL_NIF_TERM_TYPE_INTEGER:
2459 ERL_NIF_TERM_TYPE_LIST:
2462 A list, empty or not
2463 ERL_NIF_TERM_TYPE_MAP:
2465 ERL_NIF_TERM_TYPE_PID:
2468 ERL_NIF_TERM_TYPE_PORT:
2471 ERL_NIF_TERM_TYPE_REFERENCE:
2474 ERL_NIF_TERM_TYPE_TUPLE:
2477 Note that new types may be added in the future, so the caller
2480 must be prepared to handle unknown types.
2481 int enif_thread_create(char *name,ErlNifTid
2483 *tid,void * (*func)(void *),void *args,ErlNifThreadOpts
2484 *opts)
2485 Same as erl_drv_thread_create.
2487 void enif_thread_exit(void *resp)
2489 Same as erl_drv_thread_exit.
2491 int enif_thread_join(ErlNifTid, void **respp)
2493 Same as erl_drv_thread_join.
2495 char*enif_thread_name(ErlNifTid tid)
2497 Same as erl_drv_thread_name.
2499 ErlNifThreadOpts *enif_thread_opts_create(char *name)
2501 Same as erl_drv_thread_opts_create.
2503 void enif_thread_opts_destroy(ErlNifThreadOpts *opts)
2505 Same as erl_drv_thread_opts_destroy.
2507 ErlNifTid enif_thread_self(void)
2509 Same as erl_drv_thread_self.
2511 int enif_thread_type(void)
2513 Determine the type of currently executing thread. A positive
2515 value indicates a scheduler thread while a negative value or
2516 zero indicates another type of thread. Currently the following
2517 specific types exist (which may be extended in the future):
2518 ERL_NIF_THR_UNDEFINED:
2520 Undefined thread that is not a scheduler thread.
2521 ERL_NIF_THR_NORMAL_SCHEDULER:
2523 A normal scheduler thread.
2524 ERL_NIF_THR_DIRTY_CPU_SCHEDULER:
2526 A dirty CPU scheduler thread.
2527 ERL_NIF_THR_DIRTY_IO_SCHEDULER:
2529 A dirty I/O scheduler thread.
2530 ErlNifTime enif_time_offset(ErlNifTimeUnit time_unit)
2532 Returns the current time offset between Erlang monotonic time
2534 and Erlang system time converted into the time_unit passed as
2535 argument.
2536 time_unit is the time unit of the returned value.
2538 Returns ERL_NIF_TIME_ERROR if called with an invalid time unit
2540 argument or if called from a thread that is not a scheduler
2541 thread.
2542 See also ErlNifTime and ErlNifTimeUnit.
2544 void *enif_tsd_get(ErlNifTSDKey key)
2546 Same as erl_drv_tsd_get.
2548 int enif_tsd_key_create(char *name, ErlNifTSDKey *key)
2550 Same as erl_drv_tsd_key_create.
2552 void enif_tsd_key_destroy(ErlNifTSDKey key)
2554 Same as erl_drv_tsd_key_destroy.
2556 void enif_tsd_set(ErlNifTSDKey key, void *data)
2558 Same as erl_drv_tsd_set.
2560 int enif_vfprintf(FILE *stream, const char *format, va_list ap)
2562 Equivalent to enif_fprintf except that its called with a va_list
2565 instead of a variable number of arguments.
2566 int enif_vsnprintf(char *str, size_t size, const char *format, va_list
2568 ap)
2569 Equivalent to enif_snprintf except that its called with a
2572 va_list instead of a variable number of arguments.
2573 int enif_whereis_pid(ErlNifEnv *env,
2575 ERL_NIF_TERM name, ErlNifPid *pid)
2576 Looks up a process by its registered name.
2578 env:
2580 The environment of the calling process. Must be NULL only if
2581 calling from a created thread.
2582 name:
2584 The name of a registered process, as an atom.
2585 *pid:
2587 The ErlNifPid in which the resolved process id is stored.
2588 On success, sets *pid to the local process registered with name
2590 and returns true. If name is not a registered process, or is not
2591 an atom, false is returned and *pid is unchanged.
2592 Works as erlang:whereis/1, but restricted to processes. See
2594 enif_whereis_port to resolve registered ports.
2595 int enif_whereis_port(ErlNifEnv *env,
2597 ERL_NIF_TERM name, ErlNifPort *port)
2598 Looks up a port by its registered name.
2600 env:
2602 The environment of the calling process. Must be NULL only if
2603 calling from a created thread.
2604 name:
2606 The name of a registered port, as an atom.
2607 *port:
2609 The ErlNifPort in which the resolved port id is stored.
2610 On success, sets *port to the port registered with name and
2612 returns true. If name is not a registered port, or is not an
2613 atom, false is returned and *port is unchanged.
2614 Works as erlang:whereis/1, but restricted to ports. See
2616 enif_whereis_pid to resolve registered processes.
2617
2619 erlang:load_nif/2
2620Ericsson AB erts 10.7.1 erl_nif(3)