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 Warning:
102 There is a known limitation for Erlang fallback functions of NIFs.
103 Avoid functions involved in traversal of binaries by matching and
104 recursion. If a NIF is loaded over such function, binary arguments to
105 the NIF may get corrupted and cause VM crash or other misbehavior.
106 Example of such bad fallback function:
108 skip_until(Byte, <<Byte, Rest/binary>>) ->
110 Rest;
111 skip_until(Byte, <<_, Rest/binary>>) ->
112 skip_until(Byte, Rest).
113
117 All interaction between NIF code and the Erlang runtime system is per‐
118 formed by calling NIF API functions. Functions exist for the following
119 functionality:
120 Read and write Erlang terms:
122 Any Erlang terms can be passed to a NIF as function arguments and
123 be returned as function return values. The terms are of C-type
124 ERL_NIF_TERM and can only be read or written using API functions.
125 Most functions to read the content of a term are prefixed enif_get_
126 and usually return true (or false) if the term is of the expected
127 type (or not). The functions to write terms are all prefixed
128 enif_make_ and usually return the created ERL_NIF_TERM. There are
129 also some functions to query terms, like enif_is_atom,
130 enif_is_identical, and enif_compare.
131 All terms of type ERL_NIF_TERM belong to an environment of type
133 ErlNifEnv. The lifetime of a term is controlled by the lifetime of
134 its environment object. All API functions that read or write terms
135 has the environment that the term belongs to as the first function
136 argument.
137 Binaries:
139 Terms of type binary are accessed with the help of struct type Erl‐
140 NifBinary, which contains a pointer (data) to the raw binary data
141 and the length (size) of the data in bytes. Both data and size are
142 read-only and are only to be written using calls to API functions.
143 Instances of ErlNifBinary are, however, always allocated by the
144 user (usually as local variables).
145 The raw data pointed to by data is only mutable after a call to
147 enif_alloc_binary or enif_realloc_binary. All other functions that
148 operate on a binary leave the data as read-only. A mutable binary
149 must in the end either be freed with enif_release_binary or made
150 read-only by transferring it to an Erlang term with
151 enif_make_binary. However, it does not have to occur in the same
152 NIF call. Read-only binaries do not have to be released.
153 enif_make_new_binary can be used as a shortcut to allocate and
155 return a binary in the same NIF call.
156 Binaries are sequences of whole bytes. Bitstrings with an arbitrary
158 bit length have no support yet.
159 Resource objects:
161 The use of resource objects is a safe way to return pointers to
162 native data structures from a NIF. A resource object is only a
163 block of memory allocated with enif_alloc_resource. A handle ("safe
164 pointer") to this memory block can then be returned to Erlang by
165 the use of enif_make_resource. The term returned by
166 enif_make_resource is opaque in nature. It can be stored and passed
167 between processes, but the only real end usage is to pass it back
168 as an argument to a NIF. The NIF can then call enif_get_resource
169 and get back a pointer to the memory block, which is guaranteed to
170 still be valid. A resource object is not deallocated until the last
171 handle term is garbage collected by the VM and the resource is
172 released with enif_release_resource (not necessarily in that
173 order).
174 All resource objects are created as instances of some resource
176 type. This makes resources from different modules to be distin‐
177 guishable. A resource type is created by calling
178 enif_open_resource_type when a library is loaded. Objects of that
179 resource type can then later be allocated and enif_get_resource
180 verifies that the resource is of the expected type. A resource type
181 can have a user-supplied destructor function, which is automati‐
182 cally called when resources of that type are released (by either
183 the garbage collector or enif_release_resource). Resource types are
184 uniquely identified by a supplied name string and the name of the
185 implementing module.
186 The following is a template example of how to create and return a
188 resource object.
189 ERL_NIF_TERM term;
191 MyStruct* obj = enif_alloc_resource(my_resource_type, sizeof(MyStruct));
192 /* initialize struct ... */
194 term = enif_make_resource(env, obj);
196 if (keep_a_reference_of_our_own) {
198 /* store 'obj' in static variable, private data or other resource object */
199 }
200 else {
201 enif_release_resource(obj);
202 /* resource now only owned by "Erlang" */
203 }
204 return term;
205 Notice that once enif_make_resource creates the term to return to
207 Erlang, the code can choose to either keep its own native pointer
208 to the allocated struct and release it later, or release it immedi‐
209 ately and rely only on the garbage collector to deallocate the
210 resource object eventually when it collects the term.
211 Another use of resource objects is to create binary terms with
213 user-defined memory management. enif_make_resource_binary creates a
214 binary term that is connected to a resource object. The destructor
215 of the resource is called when the binary is garbage collected, at
216 which time the binary data can be released. An example of this can
217 be a binary term consisting of data from a mmap'ed file. The
218 destructor can then do munmap to release the memory region.
219 Resource types support upgrade in runtime by allowing a loaded NIF
221 library to take over an already existing resource type and by that
222 "inherit" all existing objects of that type. The destructor of the
223 new library is thereafter called for the inherited objects and the
224 library with the old destructor function can be safely unloaded.
225 Existing resource objects, of a module that is upgraded, must
226 either be deleted or taken over by the new NIF library. The unload‐
227 ing of a library is postponed as long as there exist resource
228 objects with a destructor function in the library.
229 Module upgrade and static data:
231 A loaded NIF library is tied to the Erlang module instance that
232 loaded it. If the module is upgraded, the new module instance needs
233 to load its own NIF library (or maybe choose not to). The new mod‐
234 ule instance can, however, choose to load the exact same NIF
235 library as the old code if it wants to. Sharing the dynamic library
236 means that static data defined by the library is shared as well. To
237 avoid unintentionally shared static data between module instances,
238 each Erlang module version can keep its own private data. This pri‐
239 vate data can be set when the NIF library is loaded and later
240 retrieved by calling enif_priv_data.
241 Threads and concurrency:
243 A NIF is thread-safe without any explicit synchronization as long
244 as it acts as a pure function and only reads the supplied argu‐
245 ments. When you write to a shared state either through static vari‐
246 ables or enif_priv_data, you need to supply your own explicit syn‐
247 chronization. This includes terms in process independent environ‐
248 ments that are shared between threads. Resource objects also
249 require synchronization if you treat them as mutable.
250 The library initialization callbacks load and upgrade are thread-
252 safe even for shared state data.
253 Version Management:
255 When a NIF library is built, information about the NIF API version
256 is compiled into the library. When a NIF library is loaded, the
257 runtime system verifies that the library is of a compatible ver‐
258 sion. erl_nif.h defines the following:
259 ERL_NIF_MAJOR_VERSION:
261 Incremented when NIF library incompatible changes are made to the
262 Erlang runtime system. Normally it suffices to recompile the NIF
263 library when the ERL_NIF_MAJOR_VERSION has changed, but it can,
264 under rare circumstances, mean that NIF libraries must be
265 slightly modified. If so, this will of course be documented.
266 ERL_NIF_MINOR_VERSION:
268 Incremented when new features are added. The runtime system uses
269 the minor version to determine what features to use.
270 The runtime system normally refuses to load a NIF library if the
272 major versions differ, or if the major versions are equal and the
273 minor version used by the NIF library is greater than the one used
274 by the runtime system. Old NIF libraries with lower major versions
275 are, however, allowed after a bump of the major version during a
276 transition period of two major releases. Such old NIF libraries can
277 however fail if deprecated features are used.
278 Time Measurement:
280 Support for time measurement in NIF libraries:
281 * ErlNifTime
283 * ErlNifTimeUnit
285 * enif_monotonic_time()
287 * enif_time_offset()
289 * enif_convert_time_unit()
291 I/O Queues:
293 The Erlang nif library contains function for easily working with
294 I/O vectors as used by the unix system call writev. The I/O Queue
295 is not thread safe, so some other synchronization mechanism has to
296 be used.
297 * SysIOVec
299 * ErlNifIOVec
301 * enif_ioq_create()
303 * enif_ioq_destroy()
305 * enif_ioq_enq_binary()
307 * enif_ioq_enqv()
309 * enif_ioq_deq()
311 * enif_ioq_peek()
313 * enif_ioq_peek_head()
315 * enif_inspect_iovec()
317 * enif_free_iovec()
319 Typical usage when writing to a file descriptor looks like this:
321 int writeiovec(ErlNifEnv *env, ERL_NIF_TERM term, ERL_NIF_TERM *tail,
323 ErlNifIOQueue *q, int fd) {
324 ErlNifIOVec vec, *iovec = &vec;
326 SysIOVec *sysiovec;
327 int saved_errno;
328 int iovcnt, n;
329 if (!enif_inspect_iovec(env, 64, term, tail, &iovec))
331 return -2;
332 if (enif_ioq_size(q) > 0) {
334 /* If the I/O queue contains data we enqueue the iovec and
335 then peek the data to write out of the queue. */
336 if (!enif_ioq_enqv(q, iovec, 0))
337 return -3;
338 sysiovec = enif_ioq_peek(q, &iovcnt);
340 } else {
341 /* If the I/O queue is empty we skip the trip through it. */
342 iovcnt = iovec->iovcnt;
343 sysiovec = iovec->iov;
344 }
345 /* Attempt to write the data */
347 n = writev(fd, sysiovec, iovcnt);
348 saved_errno = errno;
349 if (enif_ioq_size(q) == 0) {
351 /* If the I/O queue was initially empty we enqueue any
352 remaining data into the queue for writing later. */
353 if (n >= 0 && !enif_ioq_enqv(q, iovec, n))
354 return -3;
355 } else {
356 /* Dequeue any data that was written from the queue. */
357 if (n > 0 && !enif_ioq_deq(q, n, NULL))
358 return -4;
359 }
360 /* return n, which is either number of bytes written or -1 if
362 some error happened */
363 errno = saved_errno;
364 return n;
365 }
366 Long-running NIFs:
368 As mentioned in the warning text at the beginning of this manual
369 page, it is of vital importance that a native function returns rel‐
370 atively fast. It is difficult to give an exact maximum amount of
371 time that a native function is allowed to work, but usually a well-
372 behaving native function is to return to its caller within 1 mil‐
373 lisecond. This can be achieved using different approaches. If you
374 have full control over the code to execute in the native function,
375 the best approach is to divide the work into multiple chunks of
376 work and call the native function multiple times. This is, however,
377 not always possible, for example when calling third-party
378 libraries.
379 The enif_consume_timeslice() function can be used to inform the
381 runtime system about the length of the NIF call. It is typically
382 always to be used unless the NIF executes very fast.
383 If the NIF call is too lengthy, this must be handled in one of the
385 following ways to avoid degraded responsiveness, scheduler load
386 balancing problems, and other strange behaviors:
387 Yielding NIF:
389 If the functionality of a long-running NIF can be split so that
390 its work can be achieved through a series of shorter NIF calls,
391 the application has two options:
392 * Make that series of NIF calls from the Erlang level.
394 * Call a NIF that first performs a chunk of the work, then
396 invokes the enif_schedule_nif function to schedule another NIF
397 call to perform the next chunk. The final call scheduled in
398 this manner can then return the overall result.
399 Breaking up a long-running function in this manner enables the VM
401 to regain control between calls to the NIFs.
402 This approach is always preferred over the other alternatives
404 described below. This both from a performance perspective and a
405 system characteristics perspective.
406 Threaded NIF:
408 This is accomplished by dispatching the work to another thread
409 managed by the NIF library, return from the NIF, and wait for the
410 result. The thread can send the result back to the Erlang process
411 using enif_send. Information about thread primitives is provided
412 below.
413 Dirty NIF:
415 Note:
418 Dirty NIF support is available only when the emulator is configured
419 with dirty scheduler support. As of ERTS version 9.0, dirty sched‐
420 uler support is enabled by default on the runtime system with SMP
421 support. The Erlang runtime without SMP support does not support
422 dirty schedulers even when the dirty scheduler support is explic‐
423 itly enabled. To check at runtime for the presence of dirty sched‐
424 uler threads, code can use the enif_system_info() API function.
425 A NIF that cannot be split and cannot execute in a millisecond or
428 less is called a "dirty NIF", as it performs work that the ordi‐
429 nary schedulers of the Erlang runtime system cannot handle
430 cleanly. Applications that make use of such functions must indi‐
431 cate to the runtime that the functions are dirty so they can be
432 handled specially. This is handled by executing dirty jobs on a
433 separate set of schedulers called dirty schedulers. A dirty NIF
434 executing on a dirty scheduler does not have the same duration
435 restriction as a normal NIF.
436 It is important to classify the dirty job correct. An I/O bound
438 job should be classified as such, and a CPU bound job should be
439 classified as such. If you should classify CPU bound jobs as I/O
440 bound jobs, dirty I/O schedulers might starve ordinary sched‐
441 ulers. I/O bound jobs are expected to either block waiting for
442 I/O, and/or spend a limited amount of time moving data.
443 To schedule a dirty NIF for execution, the application has two
445 options:
446 * Set the appropriate flags value for the dirty NIF in its Erl‐
448 NifFunc entry.
449 * Call enif_schedule_nif, pass to it a pointer to the dirty NIF
451 to be executed, and indicate with argument flags whether it
452 expects the operation to be CPU-bound or I/O-bound.
453 A job that alternates between I/O bound and CPU bound can be
455 reclassified and rescheduled using enif_schedule_nif so that it
456 executes on the correct type of dirty scheduler at all times. For
457 more information see the documentation of the erl(1) command line
458 arguments +SDcpu, and +SDio.
459 While a process executes a dirty NIF, some operations that commu‐
461 nicate with it can take a very long time to complete. Suspend or
462 garbage collection of a process executing a dirty NIF cannot be
463 done until the dirty NIF has returned. Thus, other processes
464 waiting for such operations to complete might have to wait for a
465 very long time. Blocking multi-scheduling, that is, calling
466 erlang:system_flag(multi_scheduling, block), can also take a very
467 long time to complete. This is because all ongoing dirty opera‐
468 tions on all dirty schedulers must complete before the block
469 operation can complete.
470 Many operations communicating with a process executing a dirty
472 NIF can, however, complete while it executes the dirty NIF. For
473 example, retrieving information about it through process_info,
474 setting its group leader, register/unregister its name, and so
475 on.
476 Termination of a process executing a dirty NIF can only be com‐
478 pleted up to a certain point while it executes the dirty NIF. All
479 Erlang resources, such as its registered name and its ETS tables,
480 are released. All links and monitors are triggered. The execution
481 of the NIF is, however, not stopped. The NIF can safely continue
482 execution, allocate heap memory, and so on, but it is of course
483 better to stop executing as soon as possible. The NIF can check
484 whether a current process is alive using enif_is_cur‐
485 rent_process_alive. Communication using enif_send and
486 enif_port_command is also dropped when the sending process is not
487 alive. Deallocation of certain internal resources, such as
488 process heap and process control block, is delayed until the
489 dirty NIF has completed.
490
492 ERL_NIF_INIT(MODULE, ErlNifFunc funcs[], load, NULL, upgrade,
493 unload):
494 This is the magic macro to initialize a NIF library. It is to be
495 evaluated in global file scope.
496 MODULE is the name of the Erlang module as an identifier without
498 string quotations. It is stringified by the macro.
499 funcs is a static array of function descriptors for all the imple‐
501 mented NIFs in this library.
502 load, upgrade and unload are pointers to functions. One of load or
504 upgrade is called to initialize the library. unload is called to
505 release the library. All are described individually below.
506 The fourth argument NULL is ignored. It was earlier used for the
508 deprecated reload callback which is no longer supported since OTP
509 20.
510 If compiling a NIF for static inclusion through --enable-static-
512 nifs, you must define STATIC_ERLANG_NIF before the ERL_NIF_INIT
513 declaration.
514 int (*load)(ErlNifEnv* caller_env, void** priv_data, ERL_NIF_TERM
516 load_info):
517 load is called when the NIF library is loaded and no previously
518 loaded library exists for this module.
519 *priv_data can be set to point to some private data if the library
521 needs to keep a state between NIF calls. enif_priv_data returns
522 this pointer. *priv_data is initialized to NULL when load is
523 called.
524 load_info is the second argument to erlang:load_nif/2.
526 The library fails to load if load returns anything other than 0.
528 load can be NULL if initialization is not needed.
529 int (*upgrade)(ErlNifEnv* caller_env, void** priv_data, void**
531 old_priv_data, ERL_NIF_TERM load_info):
532 upgrade is called when the NIF library is loaded and there is old
533 code of this module with a loaded NIF library.
534 Works as load, except that *old_priv_data already contains the
536 value set by the last call to load or upgrade for the old module
537 code. *priv_data is initialized to NULL when upgrade is called. It
538 is allowed to write to both *priv_data and *old_priv_data.
539 The library fails to load if upgrade returns anything other than 0
541 or if upgrade is NULL.
542 void (*unload)(ErlNifEnv* caller_env, void* priv_data):
544 unload is called when the module code that the NIF library belongs
545 to is purged as old. New code of the same module may or may not
546 exist.
547
549 ERL_NIF_TERM:
550 Variables of type ERL_NIF_TERM can refer to any Erlang term. This
551 is an opaque type and values of it can only by used either as argu‐
552 ments to API functions or as return values from NIFs. All
553 ERL_NIF_TERMs belong to an environment (ErlNifEnv). A term cannot
554 be destructed individually, it is valid until its environment is
555 destructed.
556 ErlNifEnv:
558 ErlNifEnv represents an environment that can host Erlang terms. All
559 terms in an environment are valid as long as the environment is
560 valid. ErlNifEnv is an opaque type; pointers to it can only be
561 passed on to API functions. Three types of environments exist:
562 Process bound environment:
564 Passed as the first argument to all NIFs. All function arguments
565 passed to a NIF belong to that environment. The return value from
566 a NIF must also be a term belonging to the same environment.
567 A process bound environment contains transient information about
569 the calling Erlang process. The environment is only valid in the
570 thread where it was supplied as argument until the NIF returns.
571 It is thus useless and dangerous to store pointers to process
572 bound environments between NIF calls.
573 Callback environment:
575 Passed as the first argument to all the non-NIF callback func‐
576 tions (load, upgrade, unload, dtor, down and stop). Works like a
577 process bound environment but with a temporary pseudo process
578 that "terminates" when the callback has returned. Terms may be
579 created in this environment but they will only be accessible dur‐
580 ing the callback.
581 Process independent environment:
583 Created by calling enif_alloc_env. This environment can be used
584 to store terms between NIF calls and to send terms with
585 enif_send. A process independent environment with all its terms
586 is valid until you explicitly invalidate it with enif_free_env or
587 enif_send.
588 All contained terms of a list/tuple/map must belong to the same
590 environment as the list/tuple/map itself. Terms can be copied
591 between environments with enif_make_copy.
592 ErlNifFunc:
594 typedef struct {
597 const char* name;
598 unsigned arity;
599 ERL_NIF_TERM (*fptr)(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]);
600 unsigned flags;
601 } ErlNifFunc;
602 Describes a NIF by its name, arity, and implementation.
604 fptr:
606 A pointer to the function that implements the NIF.
607 argv:
609 Contains the function arguments passed to the NIF.
610 argc:
612 The array length, that is, the function arity. argv[N-1] thus
613 denotes the Nth argument to the NIF. Notice that the argument
614 argc allows for the same C function to implement several Erlang
615 functions with different arity (but probably with the same name).
616 flags:
618 Is 0 for a regular NIF (and so its value can be omitted for stat‐
619 ically initialized ErlNifFunc instances).
620 flags can be used to indicate that the NIF is a dirty NIF that is
622 to be executed on a dirty scheduler thread.
623 If the dirty NIF is expected to be CPU-bound, its flags field is
625 to be set to ERL_NIF_DIRTY_JOB_CPU_BOUND or
626 ERL_NIF_DIRTY_JOB_IO_BOUND.
627 Note:
629 If one of the ERL_NIF_DIRTY_JOB_*_BOUND flags is set, and the run‐
630 time system has no support for dirty schedulers, the runtime system
631 refuses to load the NIF library.
632 ErlNifBinary:
635 typedef struct {
638 size_t size;
639 unsigned char* data;
640 } ErlNifBinary;
641 ErlNifBinary contains transient information about an inspected
643 binary term. data is a pointer to a buffer of size bytes with the
644 raw content of the binary.
645 Notice that ErlNifBinary is a semi-opaque type and you are only
647 allowed to read fields size and data.
648 ErlNifBinaryToTerm:
650 An enumeration of the options that can be specified to
651 enif_binary_to_term. For default behavior, use value 0.
652 When receiving data from untrusted sources, use option
654 ERL_NIF_BIN2TERM_SAFE.
655 ErlNifMonitor:
657 This is an opaque data type that identifies a monitor.
658 The nif writer is to provide the memory for storing the monitor
660 when calling enif_monitor_process. The address of the data is not
661 stored by the runtime system, so ErlNifMonitor can be used as any
662 other data, it can be copied, moved in memory, forgotten, and so
663 on. To compare two monitors, enif_compare_monitors must be used.
664 ErlNifPid:
666 A process identifier (pid). In contrast to pid terms (instances of
667 ERL_NIF_TERM), ErlNifPids are self-contained and not bound to any
668 environment. ErlNifPid is an opaque type. It can be copied, moved
669 in memory, forgotten, and so on.
670 ErlNifPort:
672 A port identifier. In contrast to port ID terms (instances of
673 ERL_NIF_TERM), ErlNifPorts are self-contained and not bound to any
674 environment. ErlNifPort is an opaque type. It can be copied, moved
675 in memory, forgotten, and so on.
676 ErlNifResourceType:
678 Each instance of ErlNifResourceType represents a class of memory-
679 managed resource objects that can be garbage collected. Each
680 resource type has a unique name and a destructor function that is
681 called when objects of its type are released.
682 ErlNifResourceTypeInit:
684 typedef struct {
687 ErlNifResourceDtor* dtor;
688 ErlNifResourceStop* stop;
689 ErlNifResourceDown* down;
690 } ErlNifResourceTypeInit;
691 Initialization structure read by enif_open_resource_type_x.
693 ErlNifResourceDtor:
695 typedef void ErlNifResourceDtor(ErlNifEnv* caller_env, void* obj);
698 The function prototype of a resource destructor function.
700 The obj argument is a pointer to the resource. The only allowed use
702 for the resource in the destructor is to access its user data one
703 final time. The destructor is guaranteed to be the last callback
704 before the resource is deallocated.
705 ErlNifResourceDown:
707 typedef void ErlNifResourceDown(ErlNifEnv* caller_env, void* obj, ErlNifPid* pid, ErlNifMonitor* mon);
710 The function prototype of a resource down function, called on the
712 behalf of enif_monitor_process. obj is the resource, pid is the
713 identity of the monitored process that is exiting, and mon is the
714 identity of the monitor.
715 ErlNifResourceStop:
717 typedef void ErlNifResourceStop(ErlNifEnv* caller_env, void* obj, ErlNifEvent event, int is_direct_call);
720 The function prototype of a resource stop function, called on the
722 behalf of enif_select. obj is the resource, event is OS event,
723 is_direct_call is true if the call is made directly from
724 enif_select or false if it is a scheduled call (potentially from
725 another thread).
726 ErlNifCharEncoding:
728 typedef enum {
731 ERL_NIF_LATIN1
732 }ErlNifCharEncoding;
733 The character encoding used in strings and atoms. The only sup‐
735 ported encoding is ERL_NIF_LATIN1 for ISO Latin-1 (8-bit ASCII).
736 ErlNifSysInfo:
738 Used by enif_system_info to return information about the runtime
739 system. Contains the same content as ErlDrvSysInfo.
740 ErlNifSInt64:
742 A native signed 64-bit integer type.
743 ErlNifUInt64:
745 A native unsigned 64-bit integer type.
746 ErlNifTime:
748 A signed 64-bit integer type for representation of time.
749 ErlNifTimeUnit:
751 An enumeration of time units supported by the NIF API:
752 ERL_NIF_SEC:
754 Seconds
755 ERL_NIF_MSEC:
757 Milliseconds
758 ERL_NIF_USEC:
760 Microseconds
761 ERL_NIF_NSEC:
763 Nanoseconds
764 ErlNifUniqueInteger:
766 An enumeration of the properties that can be requested from
767 enif_make_unique_integer. For default properties, use value 0.
768 ERL_NIF_UNIQUE_POSITIVE:
770 Return only positive integers.
771 ERL_NIF_UNIQUE_MONOTONIC:
773 Return only strictly monotonically increasing integer corre‐
774 sponding to creation time.
775 ErlNifHash:
777 An enumeration of the supported hash types that can be generated
778 using enif_hash.
779 ERL_NIF_INTERNAL_HASH:
781 Non-portable hash function that only guarantees the same hash for
782 the same term within one Erlang VM instance.
783 It takes 32-bit salt values and generates hashes within
785 0..2^32-1.
786 ERL_NIF_PHASH2:
788 Portable hash function that gives the same hash for the same
789 Erlang term regardless of machine architecture and ERTS version.
790 It ignores salt values and generates hashes within 0..2^27-1.
792 Slower than ERL_NIF_INTERNAL_HASH. It corresponds to
794 erlang:phash2/1.
795 SysIOVec:
797 A system I/O vector, as used by writev on Unix and WSASend on
798 Win32. It is used in ErlNifIOVec and by enif_ioq_peek.
799 ErlNifIOVec:
801 typedef struct {
804 int iovcnt;
805 size_t size;
806 SysIOVec* iov;
807 } ErlNifIOVec;
808 An I/O vector containing iovcnt SysIOVecs pointing to the data. It
810 is used by enif_inspect_iovec and enif_ioq_enqv.
811 ErlNifIOQueueOpts:
813 Options to configure a ErlNifIOQueue.
814 ERL_NIF_IOQ_NORMAL:
816 Create a normal I/O Queue
817
819 void *enif_alloc(size_t size)
820 Allocates memory of size bytes.
822 Returns NULL if the allocation fails.
824 The returned pointer is suitably aligned for any built-in type
826 that fit in the allocated memory.
827 int enif_alloc_binary(size_t size, ErlNifBinary* bin)
829 Allocates a new binary of size size bytes. Initializes the
831 structure pointed to by bin to refer to the allocated binary.
832 The binary must either be released by enif_release_binary or
833 ownership transferred to an Erlang term with enif_make_binary.
834 An allocated (and owned) ErlNifBinary can be kept between NIF
835 calls.
836 If you do not need to reallocate or keep the data alive across
838 NIF calls, consider using enif_make_new_binary instead as it
839 will allocate small binaries on the process heap when possible.
840 Returns true on success, or false if allocation fails.
842 ErlNifEnv *enif_alloc_env()
844 Allocates a new process independent environment. The environment
846 can be used to hold terms that are not bound to any process.
847 Such terms can later be copied to a process environment with
848 enif_make_copy or be sent to a process as a message with
849 enif_send.
850 Returns pointer to the new environment.
852 void *enif_alloc_resource(ErlNifResourceType*
854 type, unsigned size)
855 Allocates a memory-managed resource object of type type and size
857 size bytes.
858 size_t enif_binary_to_term(ErlNifEnv *env,
860 const unsigned char* data, size_t size, ERL_NIF_TERM *term,
861 ErlNifBinaryToTerm opts)
862 Creates a term that is the result of decoding the binary data at
864 data, which must be encoded according to the Erlang external
865 term format. No more than size bytes are read from data. Argu‐
866 ment opts corresponds to the second argument to
867 erlang:binary_to_term/2 and must be either 0 or
868 ERL_NIF_BIN2TERM_SAFE.
869 On success, stores the resulting term at *term and returns the
871 number of bytes read. Returns 0 if decoding fails or if opts is
872 invalid.
873 See also ErlNifBinaryToTerm, erlang:binary_to_term/2, and
875 enif_term_to_binary.
876 void enif_clear_env(ErlNifEnv* env)
878 Frees all terms in an environment and clears it for reuse. The
880 environment must have been allocated with enif_alloc_env.
881 int enif_compare(ERL_NIF_TERM lhs, ERL_NIF_TERM rhs)
883 Returns an integer < 0 if lhs < rhs, 0 if lhs = rhs, and > 0 if
885 lhs > rhs. Corresponds to the Erlang operators ==, /=, =<, <,
886 >=, and > (but not =:= or =/=).
887 int enif_compare_monitors(const ErlNifMonitor
889 *monitor1, const ErlNifMonitor *monitor2)
890 Compares two ErlNifMonitors. Can also be used to imply some
892 artificial order on monitors, for whatever reason.
893 Returns 0 if monitor1 and monitor2 are equal, < 0 if monitor1 <
895 monitor2, and > 0 if monitor1 > monitor2.
896 int enif_compare_pids(const ErlNifPid *pid1, const ErlNifPid *pid2)
898 Compares two ErlNifPids according to term order.
901 Returns 0 if pid1 and pid2 are equal, < 0 if pid1 < pid2, and >
903 0 if pid1 > pid2.
904 void enif_cond_broadcast(ErlNifCond *cnd)
906 Same as erl_drv_cond_broadcast.
908 ErlNifCond *enif_cond_create(char *name)
910 Same as erl_drv_cond_create.
912 void enif_cond_destroy(ErlNifCond *cnd)
914 Same as erl_drv_cond_destroy.
916 char*enif_cond_name(ErlNifCond* cnd)
918 Same as erl_drv_cond_name.
920 void enif_cond_signal(ErlNifCond *cnd)
922 Same as erl_drv_cond_signal.
924 void enif_cond_wait(ErlNifCond *cnd, ErlNifMutex *mtx)
926 Same as erl_drv_cond_wait.
928 int enif_consume_timeslice(ErlNifEnv *env, int percent)
930 Gives the runtime system a hint about how much CPU time the cur‐
932 rent NIF call has consumed since the last hint, or since the
933 start of the NIF if no previous hint has been specified. The
934 time is specified as a percent of the timeslice that a process
935 is allowed to execute Erlang code until it can be suspended to
936 give time for other runnable processes. The scheduling timeslice
937 is not an exact entity, but can usually be approximated to about
938 1 millisecond.
939 Notice that it is up to the runtime system to determine if and
941 how to use this information. Implementations on some platforms
942 can use other means to determine consumed CPU time. Lengthy NIFs
943 should regardless of this frequently call enif_consume_timeslice
944 to determine if it is allowed to continue execution.
945 Argument percent must be an integer between 1 and 100. This
947 function must only be called from a NIF-calling thread, and
948 argument env must be the environment of the calling process.
949 Returns 1 if the timeslice is exhausted, otherwise 0. If 1 is
951 returned, the NIF is to return as soon as possible in order for
952 the process to yield.
953 This function is provided to better support co-operative sched‐
955 uling, improve system responsiveness, and make it easier to pre‐
956 vent misbehaviors of the VM because of a NIF monopolizing a
957 scheduler thread. It can be used to divide length work into a
958 number of repeated NIF calls without the need to create threads.
959 See also the warning text at the beginning of this manual page.
961 ErlNifTime enif_convert_time_unit(ErlNifTime
963 val, ErlNifTimeUnit from, ErlNifTimeUnit to)
964 Converts the val value of time unit from to the corresponding
966 value of time unit to. The result is rounded using the floor
967 function.
968 val:
970 Value to convert time unit for.
971 from:
973 Time unit of val.
974 to:
976 Time unit of returned value.
977 Returns ERL_NIF_TIME_ERROR if called with an invalid time unit
979 argument.
980 See also ErlNifTime and ErlNifTimeUnit.
982 ERL_NIF_TERM enif_cpu_time(ErlNifEnv *)
984 Returns the CPU time in the same format as erlang:timestamp().
986 The CPU time is the time the current logical CPU has spent exe‐
987 cuting since some arbitrary point in the past. If the OS does
988 not support fetching this value, enif_cpu_time invokes
989 enif_make_badarg.
990 int enif_demonitor_process(ErlNifEnv* caller_env,
992 void* obj, const ErlNifMonitor* mon)
993 Cancels a monitor created earlier with enif_monitor_process.
995 Argument obj is a pointer to the resource holding the monitor
996 and *mon identifies the monitor.
997 Argument caller_env is the environment of the calling thread
999 (process bound or callback environment) or NULL if calling from
1000 a custom thread not spawned by ERTS.
1001 Returns 0 if the monitor was successfully identified and
1003 removed. Returns a non-zero value if the monitor could not be
1004 identified, which means it was either
1005 * never created for this resource
1007 * already cancelled
1009 * already triggered
1011 * just about to be triggered by a concurrent thread
1013 This function is only thread-safe when the emulator with SMP
1015 support is used. It can only be used in a non-SMP emulator from
1016 a NIF-calling thread.
1017 int enif_equal_tids(ErlNifTid tid1, ErlNifTid tid2)
1019 Same as erl_drv_equal_tids.
1021 int enif_fprintf(FILE *stream, const char *format, ...)
1023 Similar to fprintf but this format string also accepts "%T",
1025 which formats Erlang terms of type ERL_NIF_TERM.
1026 This function is primarily intended for debugging purpose. It is
1028 not recommended to print very large terms with %T. The function
1029 may change errno, even if successful.
1030 void enif_free(void* ptr)
1032 Frees memory allocated by enif_alloc.
1034 void enif_free_env(ErlNifEnv* env)
1036 Frees an environment allocated with enif_alloc_env. All terms
1038 created in the environment are freed as well.
1039 void enif_free_iovec(ErlNifIOVec* iov)
1041 Frees an io vector returned from enif_inspect_iovec. This is
1043 needed only if a NULL environment is passed to
1044 enif_inspect_iovec.
1045 ErlNifIOVec *iovec = NULL;
1047 size_t max_elements = 128;
1048 ERL_NIF_TERM tail;
1049 if (!enif_inspect_iovec(NULL, max_elements, term, &tail, &iovec))
1050 return 0;
1051 // Do things with the iovec
1053 /* Free the iovector, possibly in another thread or nif function call */
1055 enif_free_iovec(iovec);
1056 int enif_get_atom(ErlNifEnv* env, ERL_NIF_TERM
1058 term, char* buf, unsigned size, ErlNifCharEncoding encode)
1059 Writes a NULL-terminated string in the buffer pointed to by buf
1061 of size size, consisting of the string representation of the
1062 atom term with encoding encode.
1063 Returns the number of bytes written (including terminating NULL
1065 character) or 0 if term is not an atom with maximum length of
1066 size-1.
1067 int enif_get_atom_length(ErlNifEnv* env,
1069 ERL_NIF_TERM term, unsigned* len, ErlNifCharEncoding encode)
1070 Sets *len to the length (number of bytes excluding terminating
1072 NULL character) of the atom term with encoding encode.
1073 Returns true on success, or false if term is not an atom.
1075 int enif_get_double(ErlNifEnv* env,
1077 ERL_NIF_TERM term, double* dp)
1078 Sets *dp to the floating-point value of term.
1080 Returns true on success, or false if term is not a float.
1082 int enif_get_int(ErlNifEnv* env, ERL_NIF_TERM
1084 term, int* ip)
1085 Sets *ip to the integer value of term.
1087 Returns true on success, or false if term is not an integer or
1089 is outside the bounds of type int.
1090 int enif_get_int64(ErlNifEnv* env, ERL_NIF_TERM
1092 term, ErlNifSInt64* ip)
1093 Sets *ip to the integer value of term.
1095 Returns true on success, or false if term is not an integer or
1097 is outside the bounds of a signed 64-bit integer.
1098 int enif_get_local_pid(ErlNifEnv* env,
1100 ERL_NIF_TERM term, ErlNifPid* pid)
1101 If term is the pid of a node local process, this function ini‐
1103 tializes the pid variable *pid from it and returns true. Other‐
1104 wise returns false. No check is done to see if the process is
1105 alive.
1106 Note:
1108 enif_get_local_pid will return false if argument term is the
1109 atom undefined.
1110 int enif_get_local_port(ErlNifEnv* env,
1113 ERL_NIF_TERM term, ErlNifPort* port_id)
1114 If term identifies a node local port, this function initializes
1116 the port variable *port_id from it and returns true. Otherwise
1117 returns false. No check is done to see if the port is alive.
1118 int enif_get_list_cell(ErlNifEnv* env,
1120 ERL_NIF_TERM list, ERL_NIF_TERM* head, ERL_NIF_TERM* tail)
1121 Sets *head and *tail from list list.
1123 Returns true on success, or false if it is not a list or the
1125 list is empty.
1126 int enif_get_list_length(ErlNifEnv* env,
1128 ERL_NIF_TERM term, unsigned* len)
1129 Sets *len to the length of list term.
1131 Returns true on success, or false if term is not a proper list.
1133 int enif_get_long(ErlNifEnv* env, ERL_NIF_TERM
1135 term, long int* ip)
1136 Sets *ip to the long integer value of term.
1138 Returns true on success, or false if term is not an integer or
1140 is outside the bounds of type long int.
1141 int enif_get_map_size(ErlNifEnv* env,
1143 ERL_NIF_TERM term, size_t *size)
1144 Sets *size to the number of key-value pairs in the map term.
1146 Returns true on success, or false if term is not a map.
1148 int enif_get_map_value(ErlNifEnv* env,
1150 ERL_NIF_TERM map, ERL_NIF_TERM key, ERL_NIF_TERM* value)
1151 Sets *value to the value associated with key in the map map.
1153 Returns true on success, or false if map is not a map or if map
1155 does not contain key.
1156 int enif_get_resource(ErlNifEnv* env,
1158 ERL_NIF_TERM term, ErlNifResourceType* type, void** objp)
1159 Sets *objp to point to the resource object referred to by term.
1161 Returns true on success, or false if term is not a handle to a
1163 resource object of type type.
1164 enif_get_resource does not add a reference to the resource
1166 object. However, the pointer received in *objp is guaranteed to
1167 be valid at least as long as the resource handle term is valid.
1168 int enif_get_string(ErlNifEnv* env,
1170 ERL_NIF_TERM list, char* buf, unsigned size,
1171 ErlNifCharEncoding encode)
1172 Writes a NULL-terminated string in the buffer pointed to by buf
1174 with size size, consisting of the characters in the string list.
1175 The characters are written using encoding encode.
1176 Returns one of the following:
1178 * The number of bytes written (including terminating NULL
1180 character)
1181 * -size if the string was truncated because of buffer space
1183 * 0 if list is not a string that can be encoded with encode or
1185 if size was < 1.
1186 The written string is always NULL-terminated, unless buffer size
1188 is < 1.
1189 int enif_get_tuple(ErlNifEnv* env, ERL_NIF_TERM
1191 term, int* arity, const ERL_NIF_TERM** array)
1192 If term is a tuple, this function sets *array to point to an
1194 array containing the elements of the tuple, and sets *arity to
1195 the number of elements. Notice that the array is read-only and
1196 (*array)[N-1] is the Nth element of the tuple. *array is unde‐
1197 fined if the arity of the tuple is zero.
1198 Returns true on success, or false if term is not a tuple.
1200 int enif_get_uint(ErlNifEnv* env, ERL_NIF_TERM
1202 term, unsigned int* ip)
1203 Sets *ip to the unsigned 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 int.
1208 int enif_get_uint64(ErlNifEnv* env,
1210 ERL_NIF_TERM term, ErlNifUInt64* ip)
1211 Sets *ip to the unsigned integer value of term.
1213 Returns true on success, or false if term is not an unsigned
1215 integer or is outside the bounds of an unsigned 64-bit integer.
1216 int enif_get_ulong(ErlNifEnv* env, ERL_NIF_TERM
1218 term, unsigned long* ip)
1219 Sets *ip to the unsigned long integer value of term.
1221 Returns true on success, or false if term is not an unsigned
1223 integer or is outside the bounds of type unsigned long.
1224 int enif_getenv(const char* key, char* value,
1226 size_t *value_size)
1227 Same as erl_drv_getenv.
1229 int enif_has_pending_exception(ErlNifEnv* env,
1231 ERL_NIF_TERM* reason)
1232 Returns true if a pending exception is associated with the envi‐
1234 ronment env. If reason is a NULL pointer, ignore it. Otherwise,
1235 if a pending exception associated with env exists, set *reason
1236 to the value of the exception term. For example, if
1237 enif_make_badarg is called to set a pending badarg exception, a
1238 later call to enif_has_pending_exception(env, &reason) sets
1239 *reason to the atom badarg, then return true.
1240 See also enif_make_badarg and enif_raise_exception.
1242 ErlNifUInt64 enif_hash(ErlNifHash type, ERL_NIF_TERM term, ErlNifUInt64
1244 salt)
1245 Hashes term according to the specified ErlNifHash type.
1247 Ranges of taken salt (if any) and returned value depend on the
1249 hash type.
1250 int enif_inspect_binary(ErlNifEnv* env,
1252 ERL_NIF_TERM bin_term, ErlNifBinary* bin)
1253 Initializes the structure pointed to by bin with information
1255 about binary term bin_term.
1256 Returns true on success, or false if bin_term is not a binary.
1258 int enif_inspect_iolist_as_binary(ErlNifEnv*
1260 env, ERL_NIF_TERM term, ErlNifBinary* bin)
1261 Initializes the structure pointed to by bin with a continuous
1263 buffer with the same byte content as iolist. As with
1264 inspect_binary, the data pointed to by bin is transient and does
1265 not need to be released.
1266 Returns true on success, or false if iolist is not an iolist.
1268 int enif_inspect_iovec(ErlNifEnv*
1270 env, size_t max_elements, ERL_NIF_TERM iovec_term,
1271 ERL_NIF_TERM* tail,
1272 ErlNifIOVec** iovec)
1273 Fills iovec with the list of binaries provided in iovec_term.
1275 The number of elements handled in the call is limited to
1276 max_elements, and tail is set to the remainder of the list. Note
1277 that the output may be longer than max_elements on some plat‐
1278 forms.
1279 To create a list of binaries from an arbitrary iolist, use
1281 erlang:iolist_to_iovec/1.
1282 When calling this function, iovec should contain a pointer to
1284 NULL or a ErlNifIOVec structure that should be used if possible.
1285 e.g.
1286 /* Don't use a pre-allocated structure */
1288 ErlNifIOVec *iovec = NULL;
1289 enif_inspect_iovec(env, max_elements, term, &tail, &iovec);
1290 /* Use a stack-allocated vector as an optimization for vectors with few elements */
1292 ErlNifIOVec vec, *iovec = &vec;
1293 enif_inspect_iovec(env, max_elements, term, &tail, &iovec);
1294 The contents of the iovec is valid until the called nif function
1297 returns. If the iovec should be valid after the nif call
1298 returns, it is possible to call this function with a NULL envi‐
1299 ronment. If no environment is given the iovec owns the data in
1300 the vector and it has to be explicitly freed using
1301 enif_free_iovec.
1302 Returns true on success, or false if iovec_term not an iovec.
1304 ErlNifIOQueue *enif_ioq_create(ErlNifIOQueueOpts opts)
1306 Create a new I/O Queue that can be used to store data. opts has
1308 to be set to ERL_NIF_IOQ_NORMAL.
1309 void enif_ioq_destroy(ErlNifIOQueue *q)
1311 Destroy the I/O queue and free all of it's contents
1313 int enif_ioq_deq(ErlNifIOQueue *q, size_t count, size_t *size)
1315 Dequeue count bytes from the I/O queue. If size is not NULL, the
1317 new size of the queue is placed there.
1318 Returns true on success, or false if the I/O does not contain
1320 count bytes. On failure the queue is left un-altered.
1321 int enif_ioq_enq_binary(ErlNifIOQueue *q, ErlNifBinary *bin, size_t
1323 skip)
1324 Enqueue the bin into q skipping the first skip bytes.
1326 Returns true on success, or false if skip is greater than the
1328 size of bin. Any ownership of the binary data is transferred to
1329 the queue and bin is to be considered read-only for the rest of
1330 the NIF call and then as released.
1331 int enif_ioq_enqv(ErlNifIOQueue *q, ErlNifIOVec *iovec, size_t skip)
1333 Enqueue the iovec into q skipping the first skip bytes.
1335 Returns true on success, or false if skip is greater than the
1337 size of iovec.
1338 SysIOVec *enif_ioq_peek(ErlNifIOQueue *q, int *iovlen)
1340 Get the I/O queue as a pointer to an array of SysIOVecs. It also
1342 returns the number of elements in iovlen.
1343 Nothing is removed from the queue by this function, that must be
1345 done with enif_ioq_deq.
1346 The returned array is suitable to use with the Unix system call
1348 writev.
1349 int enif_ioq_peek_head(ErlNifEnv *env, ErlNifIOQueue *q, size_t *size,
1351 ERL_NIF_TERM *bin_term)
1352 Get the head of the IO Queue as a binary term.
1354 If size is not NULL, the size of the head is placed there.
1356 Nothing is removed from the queue by this function, that must be
1358 done with enif_ioq_deq.
1359 Returns true on success, or false if the queue is empty.
1361 size_t enif_ioq_size(ErlNifIOQueue *q)
1363 Get the size of q.
1365 int enif_is_atom(ErlNifEnv* env, ERL_NIF_TERM term)
1367 Returns true if term is an atom.
1369 int enif_is_binary(ErlNifEnv* env, ERL_NIF_TERM term)
1371 Returns true if term is a binary.
1373 int enif_is_current_process_alive(ErlNifEnv* env)
1375 Returns true if the currently executing process is currently
1377 alive, otherwise false.
1378 This function can only be used from a NIF-calling thread, and
1380 with an environment corresponding to currently executing pro‐
1381 cesses.
1382 int enif_is_empty_list(ErlNifEnv* env,
1384 ERL_NIF_TERM term)
1385 Returns true if term is an empty list.
1387 int enif_is_exception(ErlNifEnv* env,
1389 ERL_NIF_TERM term)
1390 Return true if term is an exception.
1392 int enif_is_fun(ErlNifEnv* env, ERL_NIF_TERM
1394 term)
1395 Returns true if term is a fun.
1397 int enif_is_identical(ERL_NIF_TERM lhs,
1399 ERL_NIF_TERM rhs)
1400 Returns true if the two terms are identical. Corresponds to the
1402 Erlang operators =:= and =/=.
1403 int enif_is_list(ErlNifEnv* env, ERL_NIF_TERM term)
1405 Returns true if term is a list.
1407 int enif_is_map(ErlNifEnv* env, ERL_NIF_TERM
1409 term)
1410 Returns true if term is a map, otherwise false.
1412 int enif_is_number(ErlNifEnv* env, ERL_NIF_TERM
1414 term)
1415 Returns true if term is a number.
1417 int enif_is_pid(ErlNifEnv* env, ERL_NIF_TERM term)
1419 Returns true if term is a pid.
1421 int enif_is_pid_undefined(const ErlNifPid* pid)
1423 Returns true if pid has been set as undefined by
1425 enif_set_pid_undefined.
1426 int enif_is_port(ErlNifEnv* env, ERL_NIF_TERM term)
1428 Returns true if term is a port.
1430 int enif_is_port_alive(ErlNifEnv* env,
1432 ErlNifPort *port_id)
1433 Returns true if port_id is alive.
1435 This function is only thread-safe when the emulator with SMP
1437 support is used. It can only be used in a non-SMP emulator from
1438 a NIF-calling thread.
1439 int enif_is_process_alive(ErlNifEnv* env,
1441 ErlNifPid *pid)
1442 Returns true if pid is alive.
1444 This function is only thread-safe when the emulator with SMP
1446 support is used. It can only be used in a non-SMP emulator from
1447 a NIF-calling thread.
1448 int enif_is_ref(ErlNifEnv* env, ERL_NIF_TERM term)
1450 Returns true if term is a reference.
1452 int enif_is_tuple(ErlNifEnv* env, ERL_NIF_TERM term)
1454 Returns true if term is a tuple.
1456 int enif_keep_resource(void* obj)
1458 Adds a reference to resource object obj obtained from
1460 enif_alloc_resource. Each call to enif_keep_resource for an
1461 object must be balanced by a call to enif_release_resource
1462 before the object is destructed.
1463 ERL_NIF_TERM enif_make_atom(ErlNifEnv* env, const char* name)
1465 Creates an atom term from the NULL-terminated C-string name with
1467 ISO Latin-1 encoding. If the length of name exceeds the maximum
1468 length allowed for an atom (255 characters), enif_make_atom
1469 invokes enif_make_badarg.
1470 ERL_NIF_TERM enif_make_atom_len(ErlNifEnv* env,
1472 const char* name, size_t len)
1473 Create an atom term from the string name with length len. NULL
1475 characters are treated as any other characters. If len exceeds
1476 the maximum length allowed for an atom (255 characters),
1477 enif_make_atom invokes enif_make_badarg.
1478 ERL_NIF_TERM enif_make_badarg(ErlNifEnv* env)
1480 Makes a badarg exception to be returned from a NIF, and asso‐
1482 ciates it with environment env. Once a NIF or any function it
1483 calls invokes enif_make_badarg, the runtime ensures that a
1484 badarg exception is raised when the NIF returns, even if the NIF
1485 attempts to return a non-exception term instead.
1486 The return value from enif_make_badarg can be used only as the
1488 return value from the NIF that invoked it (directly or indi‐
1489 rectly) or be passed to enif_is_exception, but not to any other
1490 NIF API function.
1491 See also enif_has_pending_exception and enif_raise_exception.
1493 Note:
1495 Before ERTS 7.0 (Erlang/OTP 18), the return value from
1496 enif_make_badarg had to be returned from the NIF. This require‐
1497 ment is now lifted as the return value from the NIF is ignored
1498 if enif_make_badarg has been invoked.
1499 ERL_NIF_TERM enif_make_binary(ErlNifEnv* env, ErlNifBinary* bin)
1502 Makes a binary term from bin. Any ownership of the binary data
1504 is transferred to the created term and bin is to be considered
1505 read-only for the rest of the NIF call and then as released.
1506 ERL_NIF_TERM enif_make_copy(ErlNifEnv* dst_env,
1508 ERL_NIF_TERM src_term)
1509 Makes a copy of term src_term. The copy is created in environ‐
1511 ment dst_env. The source term can be located in any environment.
1512 ERL_NIF_TERM enif_make_double(ErlNifEnv* env, double d)
1514 Creates a floating-point term from a double. If argument double
1516 is not finite or is NaN, enif_make_double invokes
1517 enif_make_badarg.
1518 int enif_make_existing_atom(ErlNifEnv* env,
1520 const char* name, ERL_NIF_TERM* atom, ErlNifCharEncoding
1521 encode)
1522 Tries to create the term of an already existing atom from the
1524 NULL-terminated C-string name with encoding encode.
1525 If the atom already exists, this function stores the term in
1527 *atom and returns true, otherwise false. Also returns false if
1528 the length of name exceeds the maximum length allowed for an
1529 atom (255 characters).
1530 int enif_make_existing_atom_len(ErlNifEnv* env,
1532 const char* name, size_t len, ERL_NIF_TERM* atom, ErlNifCharEn‐
1533 coding
1534 encoding)
1535 Tries to create the term of an already existing atom from the
1537 string name with length len and encoding encode. NULL characters
1538 are treated as any other characters.
1539 If the atom already exists, this function stores the term in
1541 *atom and returns true, otherwise false. Also returns false if
1542 len exceeds the maximum length allowed for an atom (255 charac‐
1543 ters).
1544 ERL_NIF_TERM enif_make_int(ErlNifEnv* env, int i)
1546 Creates an integer term.
1548 ERL_NIF_TERM enif_make_int64(ErlNifEnv* env, ErlNifSInt64 i)
1550 Creates an integer term from a signed 64-bit integer.
1552 ERL_NIF_TERM enif_make_list(ErlNifEnv* env, unsigned cnt, ...)
1554 Creates an ordinary list term of length cnt. Expects cnt number
1556 of arguments (after cnt) of type ERL_NIF_TERM as the elements of
1557 the list.
1558 Returns an empty list if cnt is 0.
1560 ERL_NIF_TERM enif_make_list1(ErlNifEnv* env, ERL_NIF_TERM e1)
1562 ERL_NIF_TERM enif_make_list2(ErlNifEnv* env,
1563 ERL_NIF_TERM e1, ERL_NIF_TERM e2)
1564 ERL_NIF_TERM enif_make_list3(ErlNifEnv* env,
1565 ERL_NIF_TERM e1, ERL_NIF_TERM e2, ERL_NIF_TERM e3)
1566 ERL_NIF_TERM enif_make_list4(ErlNifEnv* env,
1567 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e4)
1568 ERL_NIF_TERM enif_make_list5(ErlNifEnv* env,
1569 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e5)
1570 ERL_NIF_TERM enif_make_list6(ErlNifEnv* env,
1571 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e6)
1572 ERL_NIF_TERM enif_make_list7(ErlNifEnv* env,
1573 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e7)
1574 ERL_NIF_TERM enif_make_list8(ErlNifEnv* env,
1575 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e8)
1576 ERL_NIF_TERM enif_make_list9(ErlNifEnv* env,
1577 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e9)
1578 Creates an ordinary list term with length indicated by the func‐
1580 tion name. Prefer these functions (macros) over the variadic
1581 enif_make_list to get a compile-time error if the number of
1582 arguments does not match.
1583 ERL_NIF_TERM enif_make_list_cell(ErlNifEnv*
1585 env, ERL_NIF_TERM head, ERL_NIF_TERM tail)
1586 Creates a list cell [head | tail].
1588 ERL_NIF_TERM enif_make_list_from_array(ErlNifEnv* env, const
1590 ERL_NIF_TERM
1591 arr[], unsigned cnt)
1592 Creates an ordinary list containing the elements of array arr of
1594 length cnt.
1595 Returns an empty list if cnt is 0.
1597 ERL_NIF_TERM enif_make_long(ErlNifEnv* env, long int i)
1599 Creates an integer term from a long int.
1601 int enif_make_map_put(ErlNifEnv* env,
1603 ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM value,
1604 ERL_NIF_TERM* map_out)
1605 Makes a copy of map map_in and inserts key with value. If key
1607 already exists in map_in, the old associated value is replaced
1608 by value.
1609 If successful, this function sets *map_out to the new map and
1611 returns true. Returns false if map_in is not a map.
1612 The map_in term must belong to environment env.
1614 int enif_make_map_remove(ErlNifEnv* env,
1616 ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM* map_out)
1617 If map map_in contains key, this function makes a copy of map_in
1619 in *map_out, and removes key and the associated value. If map
1620 map_in does not contain key, *map_out is set to map_in.
1621 Returns true on success, or false if map_in is not a map.
1623 The map_in term must belong to environment env.
1625 int enif_make_map_update(ErlNifEnv* env,
1627 ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM new_value,
1628 ERL_NIF_TERM* map_out)
1629 Makes a copy of map map_in and replace the old associated value
1631 for key with new_value.
1632 If successful, this function sets *map_out to the new map and
1634 returns true. Returns false if map_in is not a map or if it does
1635 not contain key.
1636 The map_in term must belong to environment env.
1638 int enif_make_map_from_arrays(ErlNifEnv* env, ERL_NIF_TERM keys[],
1640 ERL_NIF_TERM values[], size_t cnt, ERL_NIF_TERM *map_out)
1641 Makes a map term from the given keys and values.
1643 If successful, this function sets *map_out to the new map and
1645 returns true. Returns false there are any duplicate keys.
1646 All keys and values must belong to env.
1648 ERL_NIF_TERM enif_make_monitor_term(ErlNifEnv* env, const ErlNifMoni‐
1650 tor* mon)
1651 Creates a term identifying the given monitor received from
1653 enif_monitor_process.
1654 This function is primarily intended for debugging purpose.
1656 unsigned char *enif_make_new_binary(ErlNifEnv*
1658 env, size_t size, ERL_NIF_TERM* termp)
1659 Allocates a binary of size size bytes and creates an owning
1661 term. The binary data is mutable until the calling NIF returns.
1662 This is a quick way to create a new binary without having to use
1663 ErlNifBinary. The drawbacks are that the binary cannot be kept
1664 between NIF calls and it cannot be reallocated.
1665 Returns a pointer to the raw binary data and sets *termp to the
1667 binary term.
1668 ERL_NIF_TERM enif_make_new_map(ErlNifEnv* env)
1670 Makes an empty map term.
1672 ERL_NIF_TERM enif_make_pid(ErlNifEnv* env, const ErlNifPid* pid)
1674 Makes a pid term or the atom undefined from *pid.
1676 ERL_NIF_TERM enif_make_ref(ErlNifEnv* env)
1678 Creates a reference like erlang:make_ref/0.
1680 ERL_NIF_TERM enif_make_resource(ErlNifEnv* env, void* obj)
1682 Creates an opaque handle to a memory-managed resource object
1684 obtained by enif_alloc_resource. No ownership transfer is done,
1685 as the resource object still needs to be released by
1686 enif_release_resource. However, notice that the call to
1687 enif_release_resource can occur immediately after obtaining the
1688 term from enif_make_resource, in which case the resource object
1689 is deallocated when the term is garbage collected. For more
1690 details, see the example of creating and returning a resource
1691 object in the User's Guide.
1692 Note:
1694 Since ERTS 9.0 (OTP-20.0), resource terms have a defined behav‐
1695 ior when compared and serialized through term_to_binary or
1696 passed between nodes.
1697 * Two resource terms will compare equal if and only if they
1699 would yield the same resource object pointer when passed to
1700 enif_get_resource.
1701 * A resource term can be serialized with term_to_binary and
1703 later be fully recreated if the resource object is still
1704 alive when binary_to_term is called. A stale resource term
1705 will be returned from binary_to_term if the resource object
1706 has been deallocated. enif_get_resource will return false
1707 for stale resource terms.
1708 The same principles of serialization apply when passing
1710 resource terms in messages to remote nodes and back again. A
1711 resource term will act stale on all nodes except the node
1712 where its resource object is still alive in memory.
1713 Before ERTS 9.0 (OTP-20.0), all resource terms did compare equal
1715 to each other and to empty binaries (<<>>). If serialized, they
1716 would be recreated as plain empty binaries.
1717 ERL_NIF_TERM enif_make_resource_binary(ErlNifEnv* env, void* obj, const
1720 void* data, size_t size)
1721 Creates a binary term that is memory-managed by a resource
1723 object obj obtained by enif_alloc_resource. The returned binary
1724 term consists of size bytes pointed to by data. This raw binary
1725 data must be kept readable and unchanged until the destructor of
1726 the resource is called. The binary data can be stored external
1727 to the resource object, in which case the destructor is respon‐
1728 sible for releasing the data.
1729 Several binary terms can be managed by the same resource object.
1731 The destructor is not called until the last binary is garbage
1732 collected. This can be useful to return different parts of a
1733 larger binary buffer.
1734 As with enif_make_resource, no ownership transfer is done. The
1736 resource still needs to be released with enif_release_resource.
1737 int enif_make_reverse_list(ErlNifEnv* env, ERL_NIF_TERM list_in,
1739 ERL_NIF_TERM *list_out)
1740 Sets *list_out to the reverse list of the list list_in and
1742 returns true, or returns false if list_in is not a list.
1743 This function is only to be used on short lists, as a copy is
1745 created of the list, which is not released until after the NIF
1746 returns.
1747 The list_in term must belong to environment env.
1749 ERL_NIF_TERM enif_make_string(ErlNifEnv* env,
1751 const char* string, ErlNifCharEncoding encoding)
1752 Creates a list containing the characters of the NULL-terminated
1754 string string with encoding encoding.
1755 ERL_NIF_TERM enif_make_string_len(ErlNifEnv*
1757 env, const char* string, size_t len, ErlNifCharEncoding
1758 encoding)
1759 Creates a list containing the characters of the string string
1761 with length len and encoding encoding. NULL characters are
1762 treated as any other characters.
1763 ERL_NIF_TERM enif_make_sub_binary(ErlNifEnv*
1765 env, ERL_NIF_TERM bin_term, size_t pos, size_t size)
1766 Makes a subbinary of binary bin_term, starting at zero-based
1768 position pos with a length of size bytes. bin_term must be a
1769 binary or bitstring. pos+size must be less or equal to the num‐
1770 ber of whole bytes in bin_term.
1771 ERL_NIF_TERM enif_make_tuple(ErlNifEnv* env,
1773 unsigned cnt, ...)
1774 Creates a tuple term of arity cnt. Expects cnt number of argu‐
1776 ments (after cnt) of type ERL_NIF_TERM as the elements of the
1777 tuple.
1778 ERL_NIF_TERM enif_make_tuple1(ErlNifEnv* env,
1780 ERL_NIF_TERM e1)
1781 ERL_NIF_TERM enif_make_tuple2(ErlNifEnv* env,
1782 ERL_NIF_TERM e1, ERL_NIF_TERM e2)
1783 ERL_NIF_TERM enif_make_tuple3(ErlNifEnv* env,
1784 ERL_NIF_TERM e1, ERL_NIF_TERM e2, ERL_NIF_TERM e3)
1785 ERL_NIF_TERM enif_make_tuple4(ErlNifEnv* env,
1786 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e4)
1787 ERL_NIF_TERM enif_make_tuple5(ErlNifEnv* env,
1788 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e5)
1789 ERL_NIF_TERM enif_make_tuple6(ErlNifEnv* env,
1790 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e6)
1791 ERL_NIF_TERM enif_make_tuple7(ErlNifEnv* env,
1792 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e7)
1793 ERL_NIF_TERM enif_make_tuple8(ErlNifEnv* env,
1794 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e8)
1795 ERL_NIF_TERM enif_make_tuple9(ErlNifEnv* env,
1796 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e9)
1797 Creates a tuple term with length indicated by the function name.
1799 Prefer these functions (macros) over the variadic
1800 enif_make_tuple to get a compile-time error if the number of
1801 arguments does not match.
1802 ERL_NIF_TERM enif_make_tuple_from_array(ErlNifEnv* env, const
1804 ERL_NIF_TERM
1805 arr[], unsigned cnt)
1806 Creates a tuple containing the elements of array arr of length
1808 cnt.
1809 ERL_NIF_TERM enif_make_uint(ErlNifEnv* env, unsigned int i)
1811 Creates an integer term from an unsigned int.
1813 ERL_NIF_TERM enif_make_uint64(ErlNifEnv* env, ErlNifUInt64 i)
1815 Creates an integer term from an unsigned 64-bit integer.
1817 ERL_NIF_TERM enif_make_ulong(ErlNifEnv* env, unsigned long i)
1819 Creates an integer term from an unsigned long int.
1821 ERL_NIF_TERM enif_make_unique_integer(ErlNifEnv
1823 *env, ErlNifUniqueInteger properties)
1824 Returns a unique integer with the same properties as specified
1826 by erlang:unique_integer/1.
1827 env is the environment to create the integer in.
1829 ERL_NIF_UNIQUE_POSITIVE and ERL_NIF_UNIQUE_MONOTONIC can be
1831 passed as the second argument to change the properties of the
1832 integer returned. They can be combined by OR:ing the two values
1833 together.
1834 See also ErlNifUniqueInteger.
1836 int enif_map_iterator_create(ErlNifEnv *env,
1838 ERL_NIF_TERM map, ErlNifMapIterator *iter, ErlNifMapIteratorEn‐
1839 try
1840 entry)
1841 Creates an iterator for the map map by initializing the struc‐
1843 ture pointed to by iter. Argument entry determines the start
1844 position of the iterator: ERL_NIF_MAP_ITERATOR_FIRST or
1845 ERL_NIF_MAP_ITERATOR_LAST.
1846 Returns true on success, or false if map is not a map.
1848 A map iterator is only useful during the lifetime of environment
1850 env that the map belongs to. The iterator must be destroyed by
1851 calling enif_map_iterator_destroy:
1852 ERL_NIF_TERM key, value;
1854 ErlNifMapIterator iter;
1855 enif_map_iterator_create(env, my_map, &iter, ERL_NIF_MAP_ITERATOR_FIRST);
1856 while (enif_map_iterator_get_pair(env, &iter, &key, &value)) {
1858 do_something(key,value);
1859 enif_map_iterator_next(env, &iter);
1860 }
1861 enif_map_iterator_destroy(env, &iter);
1862 Note:
1864 The key-value pairs of a map have no defined iteration order.
1865 The only guarantee is that the iteration order of a single map
1866 instance is preserved during the lifetime of the environment
1867 that the map belongs to.
1868 void enif_map_iterator_destroy(ErlNifEnv *env,
1871 ErlNifMapIterator *iter)
1872 Destroys a map iterator created by enif_map_iterator_create.
1874 int enif_map_iterator_get_pair(ErlNifEnv *env,
1876 ErlNifMapIterator *iter, ERL_NIF_TERM *key, ERL_NIF_TERM
1877 *value)
1878 Gets key and value terms at the current map iterator position.
1880 On success, sets *key and *value and returns true. Returns false
1882 if the iterator is positioned at head (before first entry) or
1883 tail (beyond last entry).
1884 int enif_map_iterator_is_head(ErlNifEnv *env,
1886 ErlNifMapIterator *iter)
1887 Returns true if map iterator iter is positioned before the first
1889 entry.
1890 int enif_map_iterator_is_tail(ErlNifEnv *env,
1892 ErlNifMapIterator *iter)
1893 Returns true if map iterator iter is positioned after the last
1895 entry.
1896 int enif_map_iterator_next(ErlNifEnv *env,
1898 ErlNifMapIterator *iter)
1899 Increments map iterator to point to the next key-value entry.
1901 Returns true if the iterator is now positioned at a valid key-
1903 value entry, or false if the iterator is positioned at the tail
1904 (beyond the last entry).
1905 int enif_map_iterator_prev(ErlNifEnv *env,
1907 ErlNifMapIterator *iter)
1908 Decrements map iterator to point to the previous key-value
1910 entry.
1911 Returns true if the iterator is now positioned at a valid key-
1913 value entry, or false if the iterator is positioned at the head
1914 (before the first entry).
1915 int enif_monitor_process(ErlNifEnv* caller_env,
1917 void* obj, const ErlNifPid* target_pid, ErlNifMonitor* mon)
1918 Starts monitoring a process from a resource. When a process is
1920 monitored, a process exit results in a call to the provided down
1921 callback associated with the resource type.
1922 Argument obj is pointer to the resource to hold the monitor and
1924 *target_pid identifies the local process to be monitored.
1925 If mon is not NULL, a successful call stores the identity of the
1927 monitor in the ErlNifMonitor struct pointed to by mon. This
1928 identifier is used to refer to the monitor for later removal
1929 with enif_demonitor_process or compare with enif_compare_moni‐
1930 tors. A monitor is automatically removed when it triggers or
1931 when the resource is deallocated.
1932 Argument caller_env is the environment of the calling thread
1934 (process bound or callback environment) or NULL if calling from
1935 a custom thread not spawned by ERTS.
1936 Returns 0 on success, < 0 if no down callback is provided, and >
1938 0 if the process is no longer alive or if target_pid is unde‐
1939 fined.
1940 This function is only thread-safe when the emulator with SMP
1942 support is used. It can only be used in a non-SMP emulator from
1943 a NIF-calling thread.
1944 ErlNifTime enif_monotonic_time(ErlNifTimeUnit time_unit)
1946 Returns the current Erlang monotonic time. Notice that it is
1948 not uncommon with negative values.
1949 time_unit is the time unit of the returned value.
1951 Returns ERL_NIF_TIME_ERROR if called with an invalid time unit
1953 argument, or if called from a thread that is not a scheduler
1954 thread.
1955 See also ErlNifTime and ErlNifTimeUnit.
1957 ErlNifMutex *enif_mutex_create(char *name)
1959 Same as erl_drv_mutex_create.
1961 void enif_mutex_destroy(ErlNifMutex *mtx)
1963 Same as erl_drv_mutex_destroy.
1965 void enif_mutex_lock(ErlNifMutex *mtx)
1967 Same as erl_drv_mutex_lock.
1969 char*enif_mutex_name(ErlNifMutex* mtx)
1971 Same as erl_drv_mutex_name.
1973 int enif_mutex_trylock(ErlNifMutex *mtx)
1975 Same as erl_drv_mutex_trylock.
1977 void enif_mutex_unlock(ErlNifMutex *mtx)
1979 Same as erl_drv_mutex_unlock.
1981 ERL_NIF_TERM enif_now_time(ErlNifEnv *env)
1983 Returns an erlang:now() time stamp.
1985 This function is deprecated.
1987 ErlNifResourceType *enif_open_resource_type(ErlNifEnv* env, const char*
1989 module_str, const char* name, ErlNifResourceDtor* dtor,
1990 ErlNifResourceFlags flags, ErlNifResourceFlags* tried)
1991 Creates or takes over a resource type identified by the string
1993 name and gives it the destructor function pointed to by dtor.
1994 Argument flags can have the following values:
1995 ERL_NIF_RT_CREATE:
1997 Creates a new resource type that does not already exist.
1998 ERL_NIF_RT_TAKEOVER:
2000 Opens an existing resource type and takes over ownership of
2001 all its instances. The supplied destructor dtor is called
2002 both for existing instances and new instances not yet cre‐
2003 ated by the calling NIF library.
2004 The two flag values can be combined with bitwise OR. The
2006 resource type name is local to the calling module. Argument mod‐
2007 ule_str is not (yet) used and must be NULL. dtor can be NULL if
2008 no destructor is needed.
2009 On success, the function returns a pointer to the resource type
2011 and *tried is set to either ERL_NIF_RT_CREATE or
2012 ERL_NIF_RT_TAKEOVER to indicate what was done. On failure,
2013 returns NULL and sets *tried to flags. It is allowed to set
2014 tried to NULL.
2015 Notice that enif_open_resource_type is only allowed to be called
2017 in the two callbacks load and upgrade.
2018 See also enif_open_resource_type_x.
2020 ErlNifResourceType *enif_open_resource_type_x(ErlNifEnv* env, const
2022 char* name, const ErlNifResourceTypeInit* init,
2023 ErlNifResourceFlags flags, ErlNifResourceFlags* tried)
2024 Same as enif_open_resource_type except it accepts additional
2026 callback functions for resource types that are used together
2027 with enif_select and enif_monitor_process.
2028 Argument init is a pointer to an ErlNifResourceTypeInit struc‐
2030 ture that contains the function pointers for destructor, down
2031 and stop callbacks for the resource type.
2032 int enif_port_command(ErlNifEnv* env, const
2034 ErlNifPort* to_port, ErlNifEnv *msg_env, ERL_NIF_TERM msg)
2035 Works as erlang:port_command/2, except that it is always com‐
2037 pletely asynchronous.
2038 env:
2040 The environment of the calling process. Must not be NULL.
2041 *to_port:
2043 The port ID of the receiving port. The port ID is to refer
2044 to a port on the local node.
2045 msg_env:
2047 The environment of the message term. Can be a process inde‐
2048 pendent environment allocated with enif_alloc_env or NULL.
2049 msg:
2051 The message term to send. The same limitations apply as on
2052 the payload to erlang:port_command/2.
2053 Using a msg_env of NULL is an optimization, which groups
2055 together calls to enif_alloc_env, enif_make_copy, enif_port_com‐
2056 mand, and enif_free_env into one call. This optimization is only
2057 useful when a majority of the terms are to be copied from env to
2058 msg_env.
2059 Returns true if the command is successfully sent. Returns false
2061 if the command fails, for example:
2062 * *to_port does not refer to a local port.
2064 * The currently executing process (that is, the sender) is not
2066 alive.
2067 * msg is invalid.
2069 See also enif_get_local_port.
2071 void *enif_priv_data(ErlNifEnv* env)
2073 Returns the pointer to the private data that was set by load or
2075 upgrade.
2076 ERL_NIF_TERM enif_raise_exception(ErlNifEnv*
2078 env, ERL_NIF_TERM reason)
2079 Creates an error exception with the term reason to be returned
2081 from a NIF, and associates it with environment env. Once a NIF
2082 or any function it calls invokes enif_raise_exception, the run‐
2083 time ensures that the exception it creates is raised when the
2084 NIF returns, even if the NIF attempts to return a non-exception
2085 term instead.
2086 The return value from enif_raise_exception can only be used as
2088 the return value from the NIF that invoked it (directly or indi‐
2089 rectly) or be passed to enif_is_exception, but not to any other
2090 NIF API function.
2091 See also enif_has_pending_exception and enif_make_badarg.
2093 void *enif_realloc(void* ptr, size_t size)
2095 Reallocates memory allocated by enif_alloc to size bytes.
2097 Returns NULL if the reallocation fails.
2099 The returned pointer is suitably aligned for any built-in type
2101 that fit in the allocated memory.
2102 int enif_realloc_binary(ErlNifBinary* bin, size_t size)
2104 Changes the size of a binary bin. The source binary can be read-
2106 only, in which case it is left untouched and a mutable copy is
2107 allocated and assigned to *bin.
2108 Returns true on success, or false if memory allocation failed.
2110 void enif_release_binary(ErlNifBinary* bin)
2112 Releases a binary obtained from enif_alloc_binary.
2114 void enif_release_resource(void* obj)
2116 Removes a reference to resource object obj obtained from
2118 enif_alloc_resource. The resource object is destructed when the
2119 last reference is removed. Each call to enif_release_resource
2120 must correspond to a previous call to enif_alloc_resource or
2121 enif_keep_resource. References made by enif_make_resource can
2122 only be removed by the garbage collector.
2123 There are no guarantees exactly when the destructor of an unref‐
2125 erenced resource is called. It could be called directly by
2126 enif_release_resource but it could also be scheduled to be
2127 called at a later time possibly by another thread.
2128 ErlNifRWLock *enif_rwlock_create(char *name)
2130 Same as erl_drv_rwlock_create.
2132 void enif_rwlock_destroy(ErlNifRWLock *rwlck)
2134 Same as erl_drv_rwlock_destroy.
2136 char*enif_rwlock_name(ErlNifRWLock* rwlck)
2138 Same as erl_drv_rwlock_name.
2140 void enif_rwlock_rlock(ErlNifRWLock *rwlck)
2142 Same as erl_drv_rwlock_rlock.
2144 void enif_rwlock_runlock(ErlNifRWLock *rwlck)
2146 Same as erl_drv_rwlock_runlock.
2148 void enif_rwlock_rwlock(ErlNifRWLock *rwlck)
2150 Same as erl_drv_rwlock_rwlock.
2152 void enif_rwlock_rwunlock(ErlNifRWLock *rwlck)
2154 Same as erl_drv_rwlock_rwunlock.
2156 int enif_rwlock_tryrlock(ErlNifRWLock *rwlck)
2158 Same as erl_drv_rwlock_tryrlock.
2160 int enif_rwlock_tryrwlock(ErlNifRWLock *rwlck)
2162 Same as erl_drv_rwlock_tryrwlock.
2164 ERL_NIF_TERM enif_schedule_nif(ErlNifEnv* env,
2166 const char* fun_name, int flags, ERL_NIF_TERM (*fp)(ErlNifEnv*
2167 env, int
2168 argc, const ERL_NIF_TERM argv[]), int argc, const ERL_NIF_TERM
2169 argv[])
2170 Schedules NIF fp to execute. This function allows an application
2172 to break up long-running work into multiple regular NIF calls or
2173 to schedule a dirty NIF to execute on a dirty scheduler thread.
2174 fun_name:
2176 Provides a name for the NIF that is scheduled for execution.
2177 If it cannot be converted to an atom, enif_schedule_nif
2178 returns a badarg exception.
2179 flags:
2181 Must be set to 0 for a regular NIF. If the emulator was
2182 built with dirty scheduler support enabled, flags can be set
2183 to either ERL_NIF_DIRTY_JOB_CPU_BOUND if the job is expected
2184 to be CPU-bound, or ERL_NIF_DIRTY_JOB_IO_BOUND for jobs that
2185 will be I/O-bound. If dirty scheduler threads are not avail‐
2186 able in the emulator, an attempt to schedule such a job
2187 results in a notsup exception.
2188 argc and argv:
2190 Can either be the originals passed into the calling NIF, or
2191 can be values created by the calling NIF.
2192 The calling NIF must use the return value of enif_schedule_nif
2194 as its own return value.
2195 Be aware that enif_schedule_nif, as its name implies, only
2197 schedules the NIF for future execution. The calling NIF does not
2198 block waiting for the scheduled NIF to execute and return. This
2199 means that the calling NIF cannot expect to receive the sched‐
2200 uled NIF return value and use it for further operations.
2201 int enif_select(ErlNifEnv* env, ErlNifEvent event, enum ErlNifSelect‐
2203 Flags mode, void* obj, const ErlNifPid* pid, ERL_NIF_TERM ref)
2204 This function can be used to receive asynchronous notifications
2206 when OS-specific event objects become ready for either read or
2207 write operations.
2208 Argument event identifies the event object. On Unix systems, the
2210 functions select/poll are used. The event object must be a
2211 socket, pipe or other file descriptor object that select/poll
2212 can use.
2213 Argument mode describes the type of events to wait for. It can
2215 be ERL_NIF_SELECT_READ, ERL_NIF_SELECT_WRITE or a bitwise OR
2216 combination to wait for both. It can also be ERL_NIF_SELECT_STOP
2217 or ERL_NIF_SELECT_CANCEL which are described further below. When
2218 a read or write event is triggered, a notification message like
2219 this is sent to the process identified by pid:
2220 {select, Obj, Ref, ready_input | ready_output}
2222 ready_input or ready_output indicates if the event object is
2224 ready for reading or writing.
2225 Note:
2227 For complete control over the message format use the newer func‐
2228 tions enif_select_read or enif_select_write introduced in
2229 erts-11.0 (OTP-22.0).
2230 Argument pid may be NULL to indicate the calling process. It
2233 must not be set as undefined.
2234 Argument obj is a resource object obtained from
2236 enif_alloc_resource. The purpose of the resource objects is as a
2237 container of the event object to manage its state and lifetime.
2238 A handle to the resource is received in the notification message
2239 as Obj.
2240 Argument ref must be either a reference obtained from
2242 erlang:make_ref/0 or the atom undefined. It will be passed as
2243 Ref in the notifications. If a selective receive statement is
2244 used to wait for the notification then a reference created just
2245 before the receive will exploit a runtime optimization that
2246 bypasses all earlier received messages in the queue.
2247 The notifications are one-shot only. To receive further notifi‐
2249 cations of the same type (read or write), repeated calls to
2250 enif_select must be made after receiving each notification.
2251 ERL_NIF_SELECT_CANCEL can be used to cancel previously selected
2253 events. It must be used in a bitwise OR combination with
2254 ERL_NIF_SELECT_READ and/or ERL_NIF_SELECT_WRITE to indicate
2255 which type of event to cancel. Arguments pid and ref are ignored
2256 when ERL_NIF_SELECT_CANCEL is specified. The return value will
2257 tell if the event was actualy cancelled or if a notification may
2258 already have been sent.
2259 Use ERL_NIF_SELECT_STOP as mode in order to safely close an
2261 event object that has been passed to enif_select. The stop call‐
2262 back of the resource obj will be called when it is safe to close
2263 the event object. This safe way of closing event objects must be
2264 used even if all notifications have been received (or cancelled)
2265 and no further calls to enif_select have been made.
2266 ERL_NIF_SELECT_STOP will first cancel any selected events before
2267 it calls or schedules the stop callback. Arguments pid and ref
2268 are ignored when ERL_NIF_SELECT_STOP is specified.
2269 The first call to enif_select for a specific OS event will
2271 establish a relation between the event object and the containing
2272 resource. All subsequent calls for an event must pass its con‐
2273 taining resource as argument obj. The relation is dissolved when
2274 enif_select has been called with mode as ERL_NIF_SELECT_STOP and
2275 the corresponding stop callback has returned. A resource can
2276 contain several event objects but one event object can only be
2277 contained within one resource. A resource will not be destructed
2278 until all its contained relations have been dissolved.
2279 Note:
2281 Use enif_monitor_process together with enif_select to detect
2282 failing Erlang processes and prevent them from causing permanent
2283 leakage of resources and their contained OS event objects.
2284 Returns a non-negative value on success where the following bits
2287 can be set:
2288 ERL_NIF_SELECT_STOP_CALLED:
2290 The stop callback was called directly by enif_select.
2291 ERL_NIF_SELECT_STOP_SCHEDULED:
2293 The stop callback was scheduled to run on some other thread
2294 or later by this thread.
2295 ERL_NIF_SELECT_READ_CANCELLED:
2297 A read event was cancelled by ERL_NIF_SELECT_CANCEL or
2298 ERL_NIF_SELECT_STOP and is guaranteed not to generate a
2299 ready_input notification message.
2300 ERL_NIF_SELECT_WRITE_CANCELLED:
2302 A write event was cancelled by ERL_NIF_SELECT_CANCEL or
2303 ERL_NIF_SELECT_STOP and is guaranteed not to generate a
2304 ready_output notification message.
2305 Returns a negative value if the call failed where the following
2307 bits can be set:
2308 ERL_NIF_SELECT_INVALID_EVENT:
2310 Argument event is not a valid OS event object.
2311 ERL_NIF_SELECT_FAILED:
2313 The system call failed to add the event object to the poll
2314 set.
2315 Note:
2317 Use bitwise AND to test for specific bits in the return value.
2318 New significant bits may be added in future releases to give
2319 more detailed information for both failed and successful calls.
2320 Do NOT use equality tests like ==, as that may cause your appli‐
2321 cation to stop working.
2322 Example:
2324 retval = enif_select(env, fd, ERL_NIF_SELECT_STOP, resource, ref);
2326 if (retval < 0) {
2327 /* handle error */
2328 }
2329 /* Success! */
2330 if (retval & ERL_NIF_SELECT_STOP_CALLED) {
2331 /* ... */
2332 }
2333 Note:
2337 The mode flag ERL_NIF_SELECT_CANCEL and the return flags
2338 ERL_NIF_SELECT_READ_CANCELLED and ERL_NIF_SELECT_WRITE_CANCELLED
2339 were introduced in erts-11.0 (OTP-22.0).
2340 int enif_select_read(ErlNifEnv* env, ErlNifEvent event, void* obj,
2343 const ErlNifPid* pid, ERL_NIF_TERM msg, ErlNifEnv* msg_env)
2344 int enif_select_write(ErlNifEnv* env, ErlNifEvent event, void* obj,
2345 const ErlNifPid* pid, ERL_NIF_TERM msg, ErlNifEnv* msg_env)
2346 These are variants of enif_select where you can supply your own
2348 message term msg that will be sent to the process instead of the
2349 predefined tuple {select,_,_,_}.
2350 Argument msg_env must either be NULL or the environment of msg
2352 allocated with enif_alloc_env. If argument msg_env is NULL the
2353 term msg will be copied, otherwise both msg and msg_env will be
2354 invalidated by a successful call to enif_select_read or
2355 enif_select_write. The environment is then to either be freed
2356 with enif_free_env or cleared for reuse with enif_clear_env. An
2357 unsuccessful call will leave msg and msg_env still valid.
2358 Apart from the message format enif_select_read and
2360 enif_select_write behaves exactly the same as enif_select with
2361 argument mode as either ERL_NIF_SELECT_READ or
2362 ERL_NIF_SELECT_WRITE. To cancel or close events use enif_select.
2363 ErlNifPid *enif_self(ErlNifEnv* caller_env, ErlNifPid* pid)
2365 Initializes the ErlNifPid variable at *pid to represent the
2367 calling process.
2368 Returns pid if successful, or NULL if caller_env is not a
2370 process bound environment.
2371 int enif_send(ErlNifEnv* caller_env,
2373 ErlNifPid* to_pid, ErlNifEnv* msg_env, ERL_NIF_TERM msg)
2374 Sends a message to a process.
2376 caller_env:
2378 The environment of the calling thread (process bound or
2379 callback environment) or NULL if calling from a custom
2380 thread not spawned by ERTS.
2381 *to_pid:
2383 The pid of the receiving process. The pid is to refer to a
2384 process on the local node.
2385 msg_env:
2387 The environment of the message term. Must be a process inde‐
2388 pendent environment allocated with enif_alloc_env or NULL.
2389 msg:
2391 The message term to send.
2392 Returns true if the message is successfully sent. Returns false
2394 if the send operation fails, that is:
2395 * *to_pid does not refer to an alive local process.
2397 * The currently executing process (that is, the sender) is not
2399 alive.
2400 The message environment msg_env with all its terms (including
2402 msg) is invalidated by a successful call to enif_send. The envi‐
2403 ronment is to either be freed with enif_free_env or cleared for
2404 reuse with enif_clear_env. An unsuccessful call will leave msg
2405 and msg_env still valid.
2406 If msg_env is set to NULL, the msg term is copied and the origi‐
2408 nal term and its environment is still valid after the call.
2409 This function is only thread-safe when the emulator with SMP
2411 support is used. It can only be used in a non-SMP emulator from
2412 a NIF-calling thread.
2413 Note:
2415 Passing msg_env as NULL is only supported as from ERTS 8.0
2416 (Erlang/OTP 19).
2417 void enif_set_pid_undefined(ErlNifPid* pid)
2420 Sets an ErlNifPid variable as undefined. See enif_is_pid_unde‐
2422 fined.
2423 unsigned enif_sizeof_resource(void* obj)
2425 Gets the byte size of resource object obj obtained by
2427 enif_alloc_resource.
2428 int enif_snprintf(char *str, size_t size, const
2430 char *format, ...)
2431 Similar to snprintf but this format string also accepts "%T",
2433 which formats Erlang terms of type ERL_NIF_TERM.
2434 This function is primarily intended for debugging purpose. It is
2436 not recommended to print very large terms with %T. The function
2437 may change errno, even if successful.
2438 void enif_system_info(ErlNifSysInfo
2440 *sys_info_ptr, size_t size)
2441 Same as driver_system_info.
2443 int enif_term_to_binary(ErlNifEnv *env,
2445 ERL_NIF_TERM term, ErlNifBinary *bin)
2446 Allocates a new binary with enif_alloc_binary and stores the
2448 result of encoding term according to the Erlang external term
2449 format.
2450 Returns true on success, or false if the allocation fails.
2452 See also erlang:term_to_binary/1 and enif_binary_to_term.
2454 ErlNifTermType enif_term_type(ErlNifEnv *env, ERL_NIF_TERM term)
2456 Determines the type of the given term. The term must be an ordi‐
2458 nary Erlang term and not one of the special terms returned by
2459 enif_raise_exception, enif_schedule_nif, or similar.
2460 The following types are defined at the moment:
2462 ERL_NIF_TERM_TYPE_ATOM:
2464 ERL_NIF_TERM_TYPE_BITSTRING:
2467 A bitstring or binary
2468 ERL_NIF_TERM_TYPE_FLOAT:
2470 ERL_NIF_TERM_TYPE_FUN:
2473 ERL_NIF_TERM_TYPE_INTEGER:
2476 ERL_NIF_TERM_TYPE_LIST:
2479 A list, empty or not
2480 ERL_NIF_TERM_TYPE_MAP:
2482 ERL_NIF_TERM_TYPE_PID:
2485 ERL_NIF_TERM_TYPE_PORT:
2488 ERL_NIF_TERM_TYPE_REFERENCE:
2491 ERL_NIF_TERM_TYPE_TUPLE:
2494 Note that new types may be added in the future, so the caller
2497 must be prepared to handle unknown types.
2498 int enif_thread_create(char *name,ErlNifTid
2500 *tid,void * (*func)(void *),void *args,ErlNifThreadOpts
2501 *opts)
2502 Same as erl_drv_thread_create.
2504 void enif_thread_exit(void *resp)
2506 Same as erl_drv_thread_exit.
2508 int enif_thread_join(ErlNifTid, void **respp)
2510 Same as erl_drv_thread_join.
2512 char*enif_thread_name(ErlNifTid tid)
2514 Same as erl_drv_thread_name.
2516 ErlNifThreadOpts *enif_thread_opts_create(char *name)
2518 Same as erl_drv_thread_opts_create.
2520 void enif_thread_opts_destroy(ErlNifThreadOpts *opts)
2522 Same as erl_drv_thread_opts_destroy.
2524 ErlNifTid enif_thread_self(void)
2526 Same as erl_drv_thread_self.
2528 int enif_thread_type(void)
2530 Determine the type of currently executing thread. A positive
2532 value indicates a scheduler thread while a negative value or
2533 zero indicates another type of thread. Currently the following
2534 specific types exist (which may be extended in the future):
2535 ERL_NIF_THR_UNDEFINED:
2537 Undefined thread that is not a scheduler thread.
2538 ERL_NIF_THR_NORMAL_SCHEDULER:
2540 A normal scheduler thread.
2541 ERL_NIF_THR_DIRTY_CPU_SCHEDULER:
2543 A dirty CPU scheduler thread.
2544 ERL_NIF_THR_DIRTY_IO_SCHEDULER:
2546 A dirty I/O scheduler thread.
2547 ErlNifTime enif_time_offset(ErlNifTimeUnit time_unit)
2549 Returns the current time offset between Erlang monotonic time
2551 and Erlang system time converted into the time_unit passed as
2552 argument.
2553 time_unit is the time unit of the returned value.
2555 Returns ERL_NIF_TIME_ERROR if called with an invalid time unit
2557 argument or if called from a thread that is not a scheduler
2558 thread.
2559 See also ErlNifTime and ErlNifTimeUnit.
2561 void *enif_tsd_get(ErlNifTSDKey key)
2563 Same as erl_drv_tsd_get.
2565 int enif_tsd_key_create(char *name, ErlNifTSDKey *key)
2567 Same as erl_drv_tsd_key_create.
2569 void enif_tsd_key_destroy(ErlNifTSDKey key)
2571 Same as erl_drv_tsd_key_destroy.
2573 void enif_tsd_set(ErlNifTSDKey key, void *data)
2575 Same as erl_drv_tsd_set.
2577 int enif_vfprintf(FILE *stream, const char *format, va_list ap)
2579 Equivalent to enif_fprintf except that its called with a va_list
2582 instead of a variable number of arguments.
2583 int enif_vsnprintf(char *str, size_t size, const char *format, va_list
2585 ap)
2586 Equivalent to enif_snprintf except that its called with a
2589 va_list instead of a variable number of arguments.
2590 int enif_whereis_pid(ErlNifEnv *caller_env,
2592 ERL_NIF_TERM name, ErlNifPid *pid)
2593 Looks up a process by its registered name.
2595 caller_env:
2597 The environment of the calling thread (process bound or
2598 callback environment) or NULL if calling from a custom
2599 thread not spawned by ERTS.
2600 name:
2602 The name of a registered process, as an atom.
2603 *pid:
2605 The ErlNifPid in which the resolved process id is stored.
2606 On success, sets *pid to the local process registered with name
2608 and returns true. If name is not a registered process, or is not
2609 an atom, false is returned and *pid is unchanged.
2610 Works as erlang:whereis/1, but restricted to processes. See
2612 enif_whereis_port to resolve registered ports.
2613 int enif_whereis_port(ErlNifEnv *caller_env,
2615 ERL_NIF_TERM name, ErlNifPort *port)
2616 Looks up a port by its registered name.
2618 caller_env:
2620 The environment of the calling thread (process bound or
2621 callback environment) or NULL if calling from a custom
2622 thread not spawned by ERTS.
2623 name:
2625 The name of a registered port, as an atom.
2626 *port:
2628 The ErlNifPort in which the resolved port id is stored.
2629 On success, sets *port to the port registered with name and
2631 returns true. If name is not a registered port, or is not an
2632 atom, false is returned and *port is unchanged.
2633 Works as erlang:whereis/1, but restricted to ports. See
2635 enif_whereis_pid to resolve registered processes.
2636
2638 erlang:load_nif/2
2639Ericsson AB erts 11.2 erl_nif(3)