1erl_nif(3) C Library Functions erl_nif(3)
2
6 erl_nif - API functions for an Erlang NIF library.
7
9 A NIF library contains native implementation of some functions of an
10 Erlang module. The native implemented functions (NIFs) are called like
11 any other functions without any difference to the caller. A NIF library
12 is built as a dynamically linked library file and loaded in runtime by
13 calling erlang:load_nif/2.
14 Warning:
16 Use this functionality with extreme care.
18 A native function is executed as a direct extension of the native code
20 of the VM. Execution is not made in a safe environment. The VM cannot
21 provide the same services as provided when executing Erlang code, such
22 as pre-emptive scheduling or memory protection. If the native function
23 does not behave well, the whole VM will misbehave.
24 * A native function that crashes will crash the whole VM.
26 * An erroneously implemented native function can cause a VM internal
28 state inconsistency, which can cause a crash of the VM, or miscel‐
29 laneous misbehaviors of the VM at any point after the call to the
30 native function.
31 * A native function doing lengthy work before returning degrades re‐
33 sponsiveness of the VM, and can cause miscellaneous strange behav‐
34 iors. Such strange behaviors include, but are not limited to, ex‐
35 treme memory usage, and bad load balancing between schedulers.
36 Strange behaviors that can occur because of lengthy work can also
37 vary between Erlang/OTP releases.
38
40 A minimal example of a NIF library can look as follows:
41 /* niftest.c */
43 #include <erl_nif.h>
44 static ERL_NIF_TERM hello(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[])
46 {
47 return enif_make_string(env, "Hello world!", ERL_NIF_LATIN1);
48 }
49 static ErlNifFunc nif_funcs[] =
51 {
52 {"hello", 0, hello}
53 };
54 ERL_NIF_INIT(niftest,nif_funcs,NULL,NULL,NULL,NULL)
56 The Erlang module can look as follows:
58 -module(niftest).
60 -export([init/0, hello/0]).
62 -nifs([hello/0]).
64 -on_load(init/0).
66 init() ->
68 erlang:load_nif("./niftest", 0).
69 hello() ->
71 erlang:nif_error("NIF library not loaded").
72 Compile and test can look as follows (on Linux):
74 $> gcc -fPIC -shared -o niftest.so niftest.c -I $ERL_ROOT/usr/include/
76 $> erl
77 1> c(niftest).
79 {ok,niftest}
80 2> niftest:hello().
81 "Hello world!"
82 In the example above the on_load directive is used get function init
84 called automatically when the module is loaded. Function init in turn
85 calls erlang:load_nif/2 which loads the NIF library and replaces the
86 hello function with its native implementation in C. Once loaded, a NIF
87 library is persistent. It will not be unloaded until the module code
88 version that it belongs to is purged.
89 The -nifs() attribute specifies which functions in the module that are
91 to be replaced by NIFs.
92 Each NIF must have an implementation in Erlang to be invoked if the
94 function is called before the NIF library is successfully loaded. A
95 typical such stub implementation is to call erlang:nif_error which will
96 raise an exception. The Erlang function can also be used as a fallback
97 implementation if the NIF library lacks implementation for some OS or
98 hardware architecture for example.
99 Note:
101 A NIF does not have to be exported, it can be local to the module. How‐
102 ever, unused local stub functions will be optimized away by the com‐
103 piler, causing loading of the NIF library to fail.
104
107 All interaction between NIF code and the Erlang runtime system is per‐
108 formed by calling NIF API functions. Functions exist for the following
109 functionality:
110 Read and write Erlang terms:
112 Any Erlang terms can be passed to a NIF as function arguments and
113 be returned as function return values. The terms are of C-type
114 ERL_NIF_TERM and can only be read or written using API functions.
115 Most functions to read the content of a term are prefixed enif_get_
116 and usually return true (or false) if the term is of the expected
117 type (or not). The functions to write terms are all prefixed
118 enif_make_ and usually return the created ERL_NIF_TERM. There are
119 also some functions to query terms, like enif_is_atom,
120 enif_is_identical, and enif_compare.
121 All terms of type ERL_NIF_TERM belong to an environment of type
123 ErlNifEnv, except atoms created during loading (by callbacks load
124 or upgrade). The lifetime of a term is controlled by the lifetime
125 of its environment object. All API functions that read or write
126 terms have the environment that the term belongs to as the first
127 function argument. However, the atoms created during loading can be
128 referred as a term in any ErlNifEnv. That is, the best practice it
129 to create all your atoms during loading and store them in
130 static/global variables, for example:
131 #include <erl_nif.h>
133 ERL_NIF_TERM world_atom;
135 static int load(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info)
137 {
138 world_atom = enif_make_atom(env, "world");
139 return 0;
140 }
141 static ERL_NIF_TERM hello(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[])
143 {
144 ERL_NIF_TERM hello_string = enif_make_string(env, "Hello", ERL_NIF_LATIN1);
145 return enif_make_tuple2(env, hello_string, world_atom);
146 }
147 static ErlNifFunc nif_funcs[] = { { "hello", 0, hello } };
149 ERL_NIF_INIT(niftest, nif_funcs, load, NULL, NULL, NULL)
151 Binaries:
154 Terms of type binary are accessed with the help of struct type Erl‐
155 NifBinary, which contains a pointer (data) to the raw binary data
156 and the length (size) of the data in bytes. Both data and size are
157 read-only and are only to be written using calls to API functions.
158 Instances of ErlNifBinary are, however, always allocated by the
159 user (usually as local variables).
160 The raw data pointed to by data is only mutable after a call to
162 enif_alloc_binary or enif_realloc_binary. All other functions that
163 operate on a binary leave the data as read-only. A mutable binary
164 must in the end either be freed with enif_release_binary or made
165 read-only by transferring it to an Erlang term with enif_make_bi‐
166 nary. However, it does not have to occur in the same NIF call.
167 Read-only binaries do not have to be released.
168 enif_make_new_binary can be used as a shortcut to allocate and re‐
170 turn a binary in the same NIF call.
171 Binaries are sequences of whole bytes. Bitstrings with an arbitrary
173 bit length have no support yet.
174 Resource objects:
176 The use of resource objects is a safe way to return pointers to na‐
177 tive data structures from a NIF. A resource object is only a block
178 of memory allocated with enif_alloc_resource. A handle ("safe
179 pointer") to this memory block can then be returned to Erlang by
180 the use of enif_make_resource. The term returned by enif_make_re‐
181 source is opaque in nature. It can be stored and passed between
182 processes, but the only real end usage is to pass it back as an ar‐
183 gument to a NIF. The NIF can then call enif_get_resource and get
184 back a pointer to the memory block, which is guaranteed to still be
185 valid. A resource object is not deallocated until the last handle
186 term is garbage collected by the VM and the resource is released
187 with enif_release_resource (not necessarily in that order).
188 All resource objects are created as instances of some resource
190 type. This makes resources from different modules to be distin‐
191 guishable. A resource type is created by calling enif_open_re‐
192 source_type when a library is loaded. Objects of that resource type
193 can then later be allocated and enif_get_resource verifies that the
194 resource is of the expected type. A resource type can have a user-
195 supplied destructor function, which is automatically called when
196 resources of that type are released (by either the garbage collec‐
197 tor or enif_release_resource). Resource types are uniquely identi‐
198 fied by a supplied name string and the name of the implementing
199 module.
200 The following is a template example of how to create and return a
202 resource object.
203 ERL_NIF_TERM term;
205 MyStruct* obj = enif_alloc_resource(my_resource_type, sizeof(MyStruct));
206 /* initialize struct ... */
208 term = enif_make_resource(env, obj);
210 if (keep_a_reference_of_our_own) {
212 /* store 'obj' in static variable, private data or other resource object */
213 }
214 else {
215 enif_release_resource(obj);
216 /* resource now only owned by "Erlang" */
217 }
218 return term;
219 Notice that once enif_make_resource creates the term to return to
221 Erlang, the code can choose to either keep its own native pointer
222 to the allocated struct and release it later, or release it immedi‐
223 ately and rely only on the garbage collector to deallocate the re‐
224 source object eventually when it collects the term.
225 Another use of resource objects is to create binary terms with
227 user-defined memory management. enif_make_resource_binary creates a
228 binary term that is connected to a resource object. The destructor
229 of the resource is called when the binary is garbage collected, at
230 which time the binary data can be released. An example of this can
231 be a binary term consisting of data from a mmap'ed file. The de‐
232 structor can then do munmap to release the memory region.
233 Resource types support upgrade in runtime by allowing a loaded NIF
235 library to take over an already existing resource type and by that
236 "inherit" all existing objects of that type. The destructor of the
237 new library is thereafter called for the inherited objects and the
238 library with the old destructor function can be safely unloaded.
239 Existing resource objects, of a module that is upgraded, must ei‐
240 ther be deleted or taken over by the new NIF library. The unloading
241 of a library is postponed as long as there exist resource objects
242 with a destructor function in the library.
243 Module upgrade and static data:
245 A loaded NIF library is tied to the Erlang module instance that
246 loaded it. If the module is upgraded, the new module instance needs
247 to load its own NIF library (or maybe choose not to). The new mod‐
248 ule instance can, however, choose to load the exact same NIF li‐
249 brary as the old code if it wants to. Sharing the dynamic library
250 means that static data defined by the library is shared as well. To
251 avoid unintentionally shared static data between module instances,
252 each Erlang module version can keep its own private data. This pri‐
253 vate data can be set when the NIF library is loaded and later re‐
254 trieved by calling enif_priv_data.
255 Threads and concurrency:
257 A NIF is thread-safe without any explicit synchronization as long
258 as it acts as a pure function and only reads the supplied argu‐
259 ments. When you write to a shared state either through static vari‐
260 ables or enif_priv_data, you need to supply your own explicit syn‐
261 chronization. This includes terms in process independent environ‐
262 ments that are shared between threads. Resource objects also re‐
263 quire synchronization if you treat them as mutable.
264 The library initialization callbacks load and upgrade are thread-
266 safe even for shared state data.
267 Version Management:
269 When a NIF library is built, information about the NIF API version
270 is compiled into the library. When a NIF library is loaded, the
271 runtime system verifies that the library is of a compatible ver‐
272 sion. erl_nif.h defines the following:
273 ERL_NIF_MAJOR_VERSION:
275 Incremented when NIF library incompatible changes are made to the
276 Erlang runtime system. Normally it suffices to recompile the NIF
277 library when the ERL_NIF_MAJOR_VERSION has changed, but it can,
278 under rare circumstances, mean that NIF libraries must be
279 slightly modified. If so, this will of course be documented.
280 ERL_NIF_MINOR_VERSION:
282 Incremented when new features are added. The runtime system uses
283 the minor version to determine what features to use.
284 The runtime system normally refuses to load a NIF library if the
286 major versions differ, or if the major versions are equal and the
287 minor version used by the NIF library is greater than the one used
288 by the runtime system. Old NIF libraries with lower major versions
289 are, however, allowed after a bump of the major version during a
290 transition period of two major releases. Such old NIF libraries can
291 however fail if deprecated features are used.
292 Time Measurement:
294 Support for time measurement in NIF libraries:
295 * ErlNifTime
297 * ErlNifTimeUnit
299 * enif_monotonic_time()
301 * enif_time_offset()
303 * enif_convert_time_unit()
305 I/O Queues:
307 The Erlang nif library contains function for easily working with
308 I/O vectors as used by the unix system call writev. The I/O Queue
309 is not thread safe, so some other synchronization mechanism has to
310 be used.
311 * SysIOVec
313 * ErlNifIOVec
315 * enif_ioq_create()
317 * enif_ioq_destroy()
319 * enif_ioq_enq_binary()
321 * enif_ioq_enqv()
323 * enif_ioq_deq()
325 * enif_ioq_peek()
327 * enif_ioq_peek_head()
329 * enif_inspect_iovec()
331 * enif_free_iovec()
333 Typical usage when writing to a file descriptor looks like this:
335 int writeiovec(ErlNifEnv *env, ERL_NIF_TERM term, ERL_NIF_TERM *tail,
337 ErlNifIOQueue *q, int fd) {
338 ErlNifIOVec vec, *iovec = &vec;
340 SysIOVec *sysiovec;
341 int saved_errno;
342 int iovcnt, n;
343 if (!enif_inspect_iovec(env, 64, term, tail, &iovec))
345 return -2;
346 if (enif_ioq_size(q) > 0) {
348 /* If the I/O queue contains data we enqueue the iovec and
349 then peek the data to write out of the queue. */
350 if (!enif_ioq_enqv(q, iovec, 0))
351 return -3;
352 sysiovec = enif_ioq_peek(q, &iovcnt);
354 } else {
355 /* If the I/O queue is empty we skip the trip through it. */
356 iovcnt = iovec->iovcnt;
357 sysiovec = iovec->iov;
358 }
359 /* Attempt to write the data */
361 n = writev(fd, sysiovec, iovcnt);
362 saved_errno = errno;
363 if (enif_ioq_size(q) == 0) {
365 /* If the I/O queue was initially empty we enqueue any
366 remaining data into the queue for writing later. */
367 if (n >= 0 && !enif_ioq_enqv(q, iovec, n))
368 return -3;
369 } else {
370 /* Dequeue any data that was written from the queue. */
371 if (n > 0 && !enif_ioq_deq(q, n, NULL))
372 return -4;
373 }
374 /* return n, which is either number of bytes written or -1 if
376 some error happened */
377 errno = saved_errno;
378 return n;
379 }
380 Long-running NIFs:
382 As mentioned in the warning text at the beginning of this manual
383 page, it is of vital importance that a native function returns rel‐
384 atively fast. It is difficult to give an exact maximum amount of
385 time that a native function is allowed to work, but usually a well-
386 behaving native function is to return to its caller within 1 mil‐
387 lisecond. This can be achieved using different approaches. If you
388 have full control over the code to execute in the native function,
389 the best approach is to divide the work into multiple chunks of
390 work and call the native function multiple times. This is, however,
391 not always possible, for example when calling third-party li‐
392 braries.
393 The enif_consume_timeslice() function can be used to inform the
395 runtime system about the length of the NIF call. It is typically
396 always to be used unless the NIF executes very fast.
397 If the NIF call is too lengthy, this must be handled in one of the
399 following ways to avoid degraded responsiveness, scheduler load
400 balancing problems, and other strange behaviors:
401 Yielding NIF:
403 If the functionality of a long-running NIF can be split so that
404 its work can be achieved through a series of shorter NIF calls,
405 the application has two options:
406 * Make that series of NIF calls from the Erlang level.
408 * Call a NIF that first performs a chunk of the work, then in‐
410 vokes the enif_schedule_nif function to schedule another NIF
411 call to perform the next chunk. The final call scheduled in
412 this manner can then return the overall result.
413 Breaking up a long-running function in this manner enables the VM
415 to regain control between calls to the NIFs.
416 This approach is always preferred over the other alternatives de‐
418 scribed below. This both from a performance perspective and a
419 system characteristics perspective.
420 Threaded NIF:
422 This is accomplished by dispatching the work to another thread
423 managed by the NIF library, return from the NIF, and wait for the
424 result. The thread can send the result back to the Erlang process
425 using enif_send. Information about thread primitives is provided
426 below.
427 Dirty NIF:
429 A NIF that cannot be split and cannot execute in a millisecond or
430 less is called a "dirty NIF", as it performs work that the ordi‐
431 nary schedulers of the Erlang runtime system cannot handle
432 cleanly. Applications that make use of such functions must indi‐
433 cate to the runtime that the functions are dirty so they can be
434 handled specially. This is handled by executing dirty jobs on a
435 separate set of schedulers called dirty schedulers. A dirty NIF
436 executing on a dirty scheduler does not have the same duration
437 restriction as a normal NIF.
438 It is important to classify the dirty job correct. An I/O bound
440 job should be classified as such, and a CPU bound job should be
441 classified as such. If you should classify CPU bound jobs as I/O
442 bound jobs, dirty I/O schedulers might starve ordinary sched‐
443 ulers. I/O bound jobs are expected to either block waiting for
444 I/O, and/or spend a limited amount of time moving data.
445 To schedule a dirty NIF for execution, the application has two
447 options:
448 * Set the appropriate flags value for the dirty NIF in its Erl‐
450 NifFunc entry.
451 * Call enif_schedule_nif, pass to it a pointer to the dirty NIF
453 to be executed, and indicate with argument flags whether it ex‐
454 pects the operation to be CPU-bound or I/O-bound.
455 A job that alternates between I/O bound and CPU bound can be re‐
457 classified and rescheduled using enif_schedule_nif so that it ex‐
458 ecutes on the correct type of dirty scheduler at all times. For
459 more information see the documentation of the erl(1) command line
460 arguments +SDcpu, and +SDio.
461 While a process executes a dirty NIF, some operations that commu‐
463 nicate with it can take a very long time to complete. Suspend or
464 garbage collection of a process executing a dirty NIF cannot be
465 done until the dirty NIF has returned. Thus, other processes
466 waiting for such operations to complete might have to wait for a
467 very long time. Blocking multi-scheduling, that is, calling er‐
468 lang:system_flag(multi_scheduling, block), can also take a very
469 long time to complete. This is because all ongoing dirty opera‐
470 tions on all dirty schedulers must complete before the block op‐
471 eration can complete.
472 Many operations communicating with a process executing a dirty
474 NIF can, however, complete while it executes the dirty NIF. For
475 example, retrieving information about it through process_info,
476 setting its group leader, register/unregister its name, and so
477 on.
478 Termination of a process executing a dirty NIF can only be com‐
480 pleted up to a certain point while it executes the dirty NIF. All
481 Erlang resources, such as its registered name and its ETS tables,
482 are released. All links and monitors are triggered. The execution
483 of the NIF is, however, not stopped. The NIF can safely continue
484 execution, allocate heap memory, and so on, but it is of course
485 better to stop executing as soon as possible. The NIF can check
486 whether a current process is alive using enif_is_cur‐
487 rent_process_alive. Communication using enif_send and
488 enif_port_command is also dropped when the sending process is not
489 alive. Deallocation of certain internal resources, such as
490 process heap and process control block, is delayed until the
491 dirty NIF has completed.
492
494 ERL_NIF_INIT(MODULE, ErlNifFunc funcs[], load, NULL, upgrade, un‐
495 load):
496 This is the magic macro to initialize a NIF library. It is to be
497 evaluated in global file scope.
498 MODULE is the name of the Erlang module as an identifier without
500 string quotations. It is stringified by the macro.
501 funcs is a static array of function descriptors for all the imple‐
503 mented NIFs in this library.
504 load, upgrade and unload are pointers to functions. One of load or
506 upgrade is called to initialize the library. unload is called to
507 release the library. All are described individually below.
508 The fourth argument NULL is ignored. It was earlier used for the
510 deprecated reload callback which is no longer supported since OTP
511 20.
512 If compiling a NIF lib for static inclusion through --enable-
514 static-nifs, then the macro STATIC_ERLANG_NIF_LIBNAME must be de‐
515 fined as the name of the archive file (excluding file extension .a)
516 without string quotations. It must only contain characters allowed
517 in a C indentifier. The macro must be defined before erl_nif.h is
518 included. If the older macro STATIC_ERLANG_NIF is instead used,
519 then the name of the archive file must match the name of the mod‐
520 ule.
521 int (*load)(ErlNifEnv* caller_env, void** priv_data, ERL_NIF_TERM
523 load_info):
524 load is called when the NIF library is loaded and no previously
525 loaded library exists for this module.
526 *priv_data can be set to point to some private data if the library
528 needs to keep a state between NIF calls. enif_priv_data returns
529 this pointer. *priv_data is initialized to NULL when load is
530 called.
531 load_info is the second argument to erlang:load_nif/2.
533 The library fails to load if load returns anything other than 0.
535 load can be NULL if initialization is not needed.
536 int (*upgrade)(ErlNifEnv* caller_env, void** priv_data, void**
538 old_priv_data, ERL_NIF_TERM load_info):
539 upgrade is called when the NIF library is loaded and there is old
540 code of this module with a loaded NIF library.
541 Works as load, except that *old_priv_data already contains the
543 value set by the last call to load or upgrade for the old module
544 code. *priv_data is initialized to NULL when upgrade is called. It
545 is allowed to write to both *priv_data and *old_priv_data.
546 The library fails to load if upgrade returns anything other than 0
548 or if upgrade is NULL.
549 void (*unload)(ErlNifEnv* caller_env, void* priv_data):
551 unload is called when the module code that the NIF library belongs
552 to is purged as old. New code of the same module may or may not ex‐
553 ist.
554
556 ERL_NIF_TERM:
557 Variables of type ERL_NIF_TERM can refer to any Erlang term. This
558 is an opaque type and values of it can only by used either as argu‐
559 ments to API functions or as return values from NIFs. All
560 ERL_NIF_TERMs belong to an environment (ErlNifEnv). A term cannot
561 be destructed individually, it is valid until its environment is
562 destructed.
563 ErlNifEnv:
565 ErlNifEnv represents an environment that can host Erlang terms. All
566 terms in an environment are valid as long as the environment is
567 valid. ErlNifEnv is an opaque type; pointers to it can only be
568 passed on to API functions. Three types of environments exist:
569 Process bound environment:
571 Passed as the first argument to all NIFs. All function arguments
572 passed to a NIF belong to that environment. The return value from
573 a NIF must also be a term belonging to the same environment.
574 A process bound environment contains transient information about
576 the calling Erlang process. The environment is only valid in the
577 thread where it was supplied as argument until the NIF returns.
578 It is thus useless and dangerous to store pointers to process
579 bound environments between NIF calls.
580 Callback environment:
582 Passed as the first argument to all the non-NIF callback func‐
583 tions (load, upgrade, unload, dtor, down, stop and dyncall).
584 Works like a process bound environment but with a temporary
585 pseudo process that "terminates" when the callback has returned.
586 Terms may be created in this environment but they will only be
587 accessible during the callback.
588 Process independent environment:
590 Created by calling enif_alloc_env. This environment can be used
591 to store terms between NIF calls and to send terms with
592 enif_send. A process independent environment with all its terms
593 is valid until you explicitly invalidate it with enif_free_env or
594 enif_send.
595 All contained terms of a list/tuple/map must belong to the same en‐
597 vironment as the list/tuple/map itself. Terms can be copied between
598 environments with enif_make_copy.
599 ErlNifFunc:
601 typedef struct {
604 const char* name;
605 unsigned arity;
606 ERL_NIF_TERM (*fptr)(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]);
607 unsigned flags;
608 } ErlNifFunc;
609 Describes a NIF by its name, arity, and implementation.
611 fptr:
613 A pointer to the function that implements the NIF.
614 argv:
616 Contains the function arguments passed to the NIF.
617 argc:
619 The array length, that is, the function arity. argv[N-1] thus de‐
620 notes the Nth argument to the NIF. Notice that the argument argc
621 allows for the same C function to implement several Erlang func‐
622 tions with different arity (but probably with the same name).
623 flags:
625 Is 0 for a regular NIF (and so its value can be omitted for stat‐
626 ically initialized ErlNifFunc instances).
627 flags can be used to indicate that the NIF is a dirty NIF that is
629 to be executed on a dirty scheduler thread.
630 If the dirty NIF is expected to be CPU-bound, its flags field is
632 to be set to ERL_NIF_DIRTY_JOB_CPU_BOUND or
633 ERL_NIF_DIRTY_JOB_IO_BOUND.
634 Note:
636 If one of the ERL_NIF_DIRTY_JOB_*_BOUND flags is set, and the run‐
637 time system has no support for dirty schedulers, the runtime system
638 refuses to load the NIF library.
639 ErlNifBinary:
642 typedef struct {
645 size_t size;
646 unsigned char* data;
647 } ErlNifBinary;
648 ErlNifBinary contains transient information about an inspected bi‐
650 nary term. data is a pointer to a buffer of size bytes with the raw
651 content of the binary.
652 Notice that ErlNifBinary is a semi-opaque type and you are only al‐
654 lowed to read fields size and data.
655 ErlNifBinaryToTerm:
657 An enumeration of the options that can be specified to enif_bi‐
658 nary_to_term. For default behavior, use value 0.
659 When receiving data from untrusted sources, use option
661 ERL_NIF_BIN2TERM_SAFE.
662 ErlNifMonitor:
664 This is an opaque data type that identifies a monitor.
665 The nif writer is to provide the memory for storing the monitor
667 when calling enif_monitor_process. The address of the data is not
668 stored by the runtime system, so ErlNifMonitor can be used as any
669 other data, it can be copied, moved in memory, forgotten, and so
670 on. To compare two monitors, enif_compare_monitors must be used.
671 ErlNifOnHaltCallback:
673 typedef void ErlNifOnHaltCallback(void *priv_data);
676 The function prototype of an on halt callback function.
678 An on halt callback can be installed using enif_set_option(). Such
680 an installed callback will be called when the runtime system is
681 halting.
682 ErlNifOption:
684 An enumeration of the options that can be set using enif_set_op‐
685 tion().
686 Currently valid options:
688 ERL_NIF_OPT_DELAY_HALT:
690 Enable delay of runtime system halt with flushing enabled until
691 all calls to NIFs in the NIF library have returned.
692 ERL_NIF_OPT_ON_HALT:
694 Install a callback that will be called when the runtime system
695 halts with flushing enabled.
696 ErlNifPid:
698 A process identifier (pid). In contrast to pid terms (instances of
699 ERL_NIF_TERM), ErlNifPids are self-contained and not bound to any
700 environment. ErlNifPid is an opaque type. It can be copied, moved
701 in memory, forgotten, and so on.
702 ErlNifPort:
704 A port identifier. In contrast to port ID terms (instances of
705 ERL_NIF_TERM), ErlNifPorts are self-contained and not bound to any
706 environment. ErlNifPort is an opaque type. It can be copied, moved
707 in memory, forgotten, and so on.
708 ErlNifResourceType:
710 Each instance of ErlNifResourceType represents a class of memory-
711 managed resource objects that can be garbage collected. Each re‐
712 source type has a unique name and a destructor function that is
713 called when objects of its type are released.
714 ErlNifResourceTypeInit:
716 typedef struct {
719 ErlNifResourceDtor* dtor; // #1 Destructor
720 ErlNifResourceStop* stop; // #2 Select stop
721 ErlNifResourceDown* down; // #3 Monitor down
722 int members;
723 ErlNifResourceDynCall* dyncall; // #4 Dynamic call
724 } ErlNifResourceTypeInit;
725 Initialization structure read by enif_open_resource_type_x
727 enif_init_resource_type.
728 ErlNifResourceDtor:
730 typedef void ErlNifResourceDtor(ErlNifEnv* caller_env, void* obj);
733 The function prototype of a resource destructor function.
735 The obj argument is a pointer to the resource. The only allowed use
737 for the resource in the destructor is to access its user data one
738 final time. The destructor is guaranteed to be the last callback
739 before the resource is deallocated.
740 ErlNifResourceDown:
742 typedef void ErlNifResourceDown(ErlNifEnv* caller_env, void* obj, ErlNifPid* pid, ErlNifMonitor* mon);
745 The function prototype of a resource down function, called on the
747 behalf of enif_monitor_process. obj is the resource, pid is the
748 identity of the monitored process that is exiting, and mon is the
749 identity of the monitor.
750 ErlNifResourceStop:
752 typedef void ErlNifResourceStop(ErlNifEnv* caller_env, void* obj, ErlNifEvent event, int is_direct_call);
755 The function prototype of a resource stop function, called on the
757 behalf of enif_select. obj is the resource, event is OS event,
758 is_direct_call is true if the call is made directly from enif_se‐
759 lect or false if it is a scheduled call (potentially from another
760 thread).
761 ErlNifResourceDynCall:
763 typedef void ErlNifResourceDynCall(ErlNifEnv* caller_env, void* obj, void* call_data);
766 The function prototype of a dynamic resource call function, called
768 by enif_dynamic_resource_call. Argument obj is the resource object
769 and call_data is the last argument to enif_dynamic_resource_call
770 passed through.
771 ErlNifCharEncoding:
773 typedef enum {
776 ERL_NIF_LATIN1,
777 ERL_NIF_UTF8,
778 }ErlNifCharEncoding;
779 The character encoding used in strings and atoms. The only sup‐
781 ported encodings are ERL_NIF_LATIN1 for ISO Latin-1 (8-bit ASCII)
782 and ERL_NIF_UTF8 for UTF-8.
783 ErlNifSysInfo:
785 Used by enif_system_info to return information about the runtime
786 system. Contains the same content as ErlDrvSysInfo.
787 ErlNifSInt64:
789 A native signed 64-bit integer type.
790 ErlNifUInt64:
792 A native unsigned 64-bit integer type.
793 ErlNifTime:
795 A signed 64-bit integer type for representation of time.
796 ErlNifTimeUnit:
798 An enumeration of time units supported by the NIF API:
799 ERL_NIF_SEC:
801 Seconds
802 ERL_NIF_MSEC:
804 Milliseconds
805 ERL_NIF_USEC:
807 Microseconds
808 ERL_NIF_NSEC:
810 Nanoseconds
811 ErlNifUniqueInteger:
813 An enumeration of the properties that can be requested from
814 enif_make_unique_integer. For default properties, use value 0.
815 ERL_NIF_UNIQUE_POSITIVE:
817 Return only positive integers.
818 ERL_NIF_UNIQUE_MONOTONIC:
820 Return only strictly monotonically increasing integer corre‐
821 sponding to creation time.
822 ErlNifHash:
824 An enumeration of the supported hash types that can be generated
825 using enif_hash.
826 ERL_NIF_INTERNAL_HASH:
828 Non-portable hash function that only guarantees the same hash for
829 the same term within one Erlang VM instance.
830 It takes 32-bit salt values and generates hashes within
832 0..2^32-1.
833 ERL_NIF_PHASH2:
835 Portable hash function that gives the same hash for the same Er‐
836 lang term regardless of machine architecture and ERTS version.
837 It ignores salt values and generates hashes within 0..2^27-1.
839 Slower than ERL_NIF_INTERNAL_HASH. It corresponds to er‐
841 lang:phash2/1.
842 SysIOVec:
844 A system I/O vector, as used by writev on Unix and WSASend on
845 Win32. It is used in ErlNifIOVec and by enif_ioq_peek.
846 ErlNifIOVec:
848 typedef struct {
851 int iovcnt;
852 size_t size;
853 SysIOVec* iov;
854 } ErlNifIOVec;
855 An I/O vector containing iovcnt SysIOVecs pointing to the data. It
857 is used by enif_inspect_iovec and enif_ioq_enqv.
858 ErlNifIOQueueOpts:
860 Options to configure a ErlNifIOQueue.
861 ERL_NIF_IOQ_NORMAL:
863 Create a normal I/O Queue
864
866 void *enif_alloc(size_t size)
867 Allocates memory of size bytes.
869 Returns NULL if the allocation fails.
871 The returned pointer is suitably aligned for any built-in type
873 that fit in the allocated memory.
874 int enif_alloc_binary(size_t size, ErlNifBinary* bin)
876 Allocates a new binary of size size bytes. Initializes the
878 structure pointed to by bin to refer to the allocated binary.
879 The binary must either be released by enif_release_binary or
880 ownership transferred to an Erlang term with enif_make_binary.
881 An allocated (and owned) ErlNifBinary can be kept between NIF
882 calls.
883 If you do not need to reallocate or keep the data alive across
885 NIF calls, consider using enif_make_new_binary instead as it
886 will allocate small binaries on the process heap when possible.
887 Returns true on success, or false if allocation fails.
889 ErlNifEnv *enif_alloc_env()
891 Allocates a new process independent environment. The environment
893 can be used to hold terms that are not bound to any process.
894 Such terms can later be copied to a process environment with
895 enif_make_copy or be sent to a process as a message with
896 enif_send.
897 Returns pointer to the new environment.
899 void *enif_alloc_resource(ErlNifResourceType*
901 type, unsigned size)
902 Allocates a memory-managed resource object of type type and size
904 size bytes.
905 size_t enif_binary_to_term(ErlNifEnv *env,
907 const unsigned char* data, size_t size, ERL_NIF_TERM *term,
908 ErlNifBinaryToTerm opts)
909 Creates a term that is the result of decoding the binary data at
911 data, which must be encoded according to the Erlang external
912 term format. No more than size bytes are read from data. Argu‐
913 ment opts corresponds to the second argument to erlang:bi‐
914 nary_to_term/2 and must be either 0 or ERL_NIF_BIN2TERM_SAFE.
915 On success, stores the resulting term at *term and returns the
917 number of bytes read. Returns 0 if decoding fails or if opts is
918 invalid.
919 See also ErlNifBinaryToTerm, erlang:binary_to_term/2, and
921 enif_term_to_binary.
922 void enif_clear_env(ErlNifEnv* env)
924 Frees all terms in an environment and clears it for reuse. The
926 environment must have been allocated with enif_alloc_env.
927 int enif_compare(ERL_NIF_TERM lhs, ERL_NIF_TERM rhs)
929 Returns an integer < 0 if lhs < rhs, 0 if lhs = rhs, and > 0 if
931 lhs > rhs. Corresponds to the Erlang operators ==, /=, =<, <,
932 >=, and > (but not =:= or =/=).
933 int enif_compare_monitors(const ErlNifMonitor
935 *monitor1, const ErlNifMonitor *monitor2)
936 Compares two ErlNifMonitors. Can also be used to imply some ar‐
938 tificial order on monitors, for whatever reason.
939 Returns 0 if monitor1 and monitor2 are equal, < 0 if monitor1 <
941 monitor2, and > 0 if monitor1 > monitor2.
942 int enif_compare_pids(const ErlNifPid *pid1, const ErlNifPid *pid2)
944 Compares two ErlNifPids according to term order.
947 Returns 0 if pid1 and pid2 are equal, < 0 if pid1 < pid2, and >
949 0 if pid1 > pid2.
950 void enif_cond_broadcast(ErlNifCond *cnd)
952 Same as erl_drv_cond_broadcast.
954 ErlNifCond *enif_cond_create(char *name)
956 Same as erl_drv_cond_create.
958 void enif_cond_destroy(ErlNifCond *cnd)
960 Same as erl_drv_cond_destroy.
962 char*enif_cond_name(ErlNifCond* cnd)
964 Same as erl_drv_cond_name.
966 void enif_cond_signal(ErlNifCond *cnd)
968 Same as erl_drv_cond_signal.
970 void enif_cond_wait(ErlNifCond *cnd, ErlNifMutex *mtx)
972 Same as erl_drv_cond_wait.
974 int enif_consume_timeslice(ErlNifEnv *env, int percent)
976 Gives the runtime system a hint about how much CPU time the cur‐
978 rent NIF call has consumed since the last hint, or since the
979 start of the NIF if no previous hint has been specified. The
980 time is specified as a percent of the timeslice that a process
981 is allowed to execute Erlang code until it can be suspended to
982 give time for other runnable processes. The scheduling timeslice
983 is not an exact entity, but can usually be approximated to about
984 1 millisecond.
985 Notice that it is up to the runtime system to determine if and
987 how to use this information. Implementations on some platforms
988 can use other means to determine consumed CPU time. Lengthy NIFs
989 should regardless of this frequently call enif_consume_timeslice
990 to determine if it is allowed to continue execution.
991 Argument percent must be an integer between 1 and 100. This
993 function must only be called from a NIF-calling thread, and ar‐
994 gument env must be the environment of the calling process.
995 Returns 1 if the timeslice is exhausted, otherwise 0. If 1 is
997 returned, the NIF is to return as soon as possible in order for
998 the process to yield.
999 This function is provided to better support co-operative sched‐
1001 uling, improve system responsiveness, and make it easier to pre‐
1002 vent misbehaviors of the VM because of a NIF monopolizing a
1003 scheduler thread. It can be used to divide length work into a
1004 number of repeated NIF calls without the need to create threads.
1005 See also the warning text at the beginning of this manual page.
1007 ErlNifTime enif_convert_time_unit(ErlNifTime
1009 val, ErlNifTimeUnit from, ErlNifTimeUnit to)
1010 Converts the val value of time unit from to the corresponding
1012 value of time unit to. The result is rounded using the floor
1013 function.
1014 val:
1016 Value to convert time unit for.
1017 from:
1019 Time unit of val.
1020 to:
1022 Time unit of returned value.
1023 Returns ERL_NIF_TIME_ERROR if called with an invalid time unit
1025 argument.
1026 See also ErlNifTime and ErlNifTimeUnit.
1028 ERL_NIF_TERM enif_cpu_time(ErlNifEnv *)
1030 Returns the CPU time in the same format as erlang:timestamp().
1032 The CPU time is the time the current logical CPU has spent exe‐
1033 cuting since some arbitrary point in the past. If the OS does
1034 not support fetching this value, enif_cpu_time invokes
1035 enif_make_badarg.
1036 int enif_demonitor_process(ErlNifEnv* caller_env,
1038 void* obj, const ErlNifMonitor* mon)
1039 Cancels a monitor created earlier with enif_monitor_process. Ar‐
1041 gument obj is a pointer to the resource holding the monitor and
1042 *mon identifies the monitor.
1043 Argument caller_env is the environment of the calling thread
1045 (process bound or callback environment) or NULL if calling from
1046 a custom thread not spawned by ERTS.
1047 Returns 0 if the monitor was successfully identified and re‐
1049 moved. Returns a non-zero value if the monitor could not be
1050 identified, which means it was either
1051 * never created for this resource
1053 * already cancelled
1055 * already triggered
1057 * just about to be triggered by a concurrent thread
1059 This function is thread-safe.
1061 int enif_dynamic_resource_call(ErlNifEnv* caller_env, ERL_NIF_TERM
1063 rt_module, ERL_NIF_TERM rt_name, ERL_NIF_TERM resource, void*
1064 call_data)
1065 Call code of a resource type implemented by another NIF module.
1067 The atoms rt_module and rt_name identifies the resource type to
1068 be called. Argument resource identifies a resource object of
1069 that type.
1070 The callback dyncall of the identified resource type will be
1072 called with a pointer to the resource objects obj and the argu‐
1073 ment call_data passed through. The call_data argument is typi‐
1074 cally a pointer to a struct used to passed both arguments to the
1075 dyncall function as well as results back to the caller.
1076 Returns 0 if the dyncall callback function was called. Returns a
1078 non-zero value if no call was made, which happens if rt_module
1079 and rt_name did not identify a resource type with a dyncall
1080 callback or if resource was not a resource object of that type.
1081 int enif_equal_tids(ErlNifTid tid1, ErlNifTid tid2)
1083 Same as erl_drv_equal_tids.
1085 int enif_fprintf(FILE *stream, const char *format, ...)
1087 Similar to fprintf but this format string also accepts "%T",
1089 which formats Erlang terms of type ERL_NIF_TERM.
1090 This function is primarily intended for debugging purpose. It is
1092 not recommended to print very large terms with %T. The function
1093 may change errno, even if successful.
1094 void enif_free(void* ptr)
1096 Frees memory allocated by enif_alloc.
1098 void enif_free_env(ErlNifEnv* env)
1100 Frees an environment allocated with enif_alloc_env. All terms
1102 created in the environment are freed as well.
1103 void enif_free_iovec(ErlNifIOVec* iov)
1105 Frees an io vector returned from enif_inspect_iovec. This is
1107 needed only if a NULL environment is passed to enif_in‐
1108 spect_iovec.
1109 ErlNifIOVec *iovec = NULL;
1111 size_t max_elements = 128;
1112 ERL_NIF_TERM tail;
1113 if (!enif_inspect_iovec(NULL, max_elements, term, &tail, &iovec))
1114 return 0;
1115 // Do things with the iovec
1117 /* Free the iovector, possibly in another thread or nif function call */
1119 enif_free_iovec(iovec);
1120 int enif_get_atom(ErlNifEnv *env, ERL_NIF_TERM
1122 term, char *buf, unsigned size, ErlNifCharEncoding encoding)
1123 Writes a NULL-terminated string in the buffer pointed to by buf
1125 of size size bytes, consisting of the string representation of
1126 the atom term with encoding.
1127 Returns the number of bytes written (including terminating NULL
1129 character) or 0 if term is not an atom with maximum length of
1130 size-1 bytes in encoding.
1131 int enif_get_atom_length(ErlNifEnv *env,
1133 ERL_NIF_TERM term, unsigned *len, ErlNifCharEncoding encoding)
1134 Sets *len to the length (number of bytes excluding terminating
1136 NULL character) of the atom term with encoding.
1137 Returns true on success, or false if term is not an atom or if
1139 the atom cannot be encoded using encoding.
1140 int enif_get_double(ErlNifEnv* env,
1142 ERL_NIF_TERM term, double* dp)
1143 Sets *dp to the floating-point value of term.
1145 Returns true on success, or false if term is not a float.
1147 int enif_get_int(ErlNifEnv* env, ERL_NIF_TERM
1149 term, int* ip)
1150 Sets *ip to the integer value of term.
1152 Returns true on success, or false if term is not an integer or
1154 is outside the bounds of type int.
1155 int enif_get_int64(ErlNifEnv* env, ERL_NIF_TERM
1157 term, ErlNifSInt64* ip)
1158 Sets *ip to the integer value of term.
1160 Returns true on success, or false if term is not an integer or
1162 is outside the bounds of a signed 64-bit integer.
1163 int enif_get_local_pid(ErlNifEnv* env,
1165 ERL_NIF_TERM term, ErlNifPid* pid)
1166 If term is the pid of a node local process, this function ini‐
1168 tializes the pid variable *pid from it and returns true. Other‐
1169 wise returns false. No check is done to see if the process is
1170 alive.
1171 Note:
1173 enif_get_local_pid will return false if argument term is the
1174 atom undefined.
1175 int enif_get_local_port(ErlNifEnv* env,
1178 ERL_NIF_TERM term, ErlNifPort* port_id)
1179 If term identifies a node local port, this function initializes
1181 the port variable *port_id from it and returns true. Otherwise
1182 returns false. No check is done to see if the port is alive.
1183 int enif_get_list_cell(ErlNifEnv* env,
1185 ERL_NIF_TERM list, ERL_NIF_TERM* head, ERL_NIF_TERM* tail)
1186 Sets *head and *tail from list list.
1188 Returns true on success, or false if it is not a list or the
1190 list is empty.
1191 int enif_get_list_length(ErlNifEnv* env,
1193 ERL_NIF_TERM term, unsigned* len)
1194 Sets *len to the length of list term.
1196 Returns true on success, or false if term is not a proper list.
1198 int enif_get_long(ErlNifEnv* env, ERL_NIF_TERM
1200 term, long int* ip)
1201 Sets *ip to the long integer value of term.
1203 Returns true on success, or false if term is not an integer or
1205 is outside the bounds of type long int.
1206 int enif_get_map_size(ErlNifEnv* env,
1208 ERL_NIF_TERM term, size_t *size)
1209 Sets *size to the number of key-value pairs in the map term.
1211 Returns true on success, or false if term is not a map.
1213 int enif_get_map_value(ErlNifEnv* env,
1215 ERL_NIF_TERM map, ERL_NIF_TERM key, ERL_NIF_TERM* value)
1216 Sets *value to the value associated with key in the map map.
1218 Returns true on success, or false if map is not a map or if map
1220 does not contain key.
1221 int enif_get_resource(ErlNifEnv* env,
1223 ERL_NIF_TERM term, ErlNifResourceType* type, void** objp)
1224 Sets *objp to point to the resource object referred to by term.
1226 Returns true on success, or false if term is not a handle to a
1228 resource object of type type.
1229 enif_get_resource does not add a reference to the resource ob‐
1231 ject. However, the pointer received in *objp is guaranteed to be
1232 valid at least as long as the resource handle term is valid.
1233 int enif_get_string(ErlNifEnv* env,
1235 ERL_NIF_TERM list, char* buf, unsigned size,
1236 ErlNifCharEncoding encoding)
1237 Writes a NULL-terminated string in the buffer pointed to by buf
1239 with size size, consisting of the characters in the string list.
1240 The characters are written using encoding.
1241 Returns one of the following:
1243 * The number of bytes written (including terminating NULL
1245 character)
1246 * -size if the string was truncated because of buffer space
1248 * 0 if list is not a string that can be encoded with encoding
1250 or if size was < 1.
1251 The written string is always NULL-terminated, unless buffer size
1253 is < 1.
1254 int enif_get_string_length(ErlNifEnv *env,
1256 ERL_NIF_TERM list, unsigned *len, ErlNifCharEncoding encoding)
1257 Sets *len to the length (number of bytes excluding terminating
1259 NULL character) of the string list with encoding.
1260 Returns true on success, or false if list is not a string that
1262 can be encoded with encoding.
1263 int enif_get_tuple(ErlNifEnv* env, ERL_NIF_TERM
1265 term, int* arity, const ERL_NIF_TERM** array)
1266 If term is a tuple, this function sets *array to point to an ar‐
1268 ray containing the elements of the tuple, and sets *arity to the
1269 number of elements. Notice that the array is read-only and (*ar‐
1270 ray)[N-1] is the Nth element of the tuple. *array is undefined
1271 if the arity of the tuple is zero.
1272 Returns true on success, or false if term is not a tuple.
1274 int enif_get_uint(ErlNifEnv* env, ERL_NIF_TERM
1276 term, unsigned int* ip)
1277 Sets *ip to the unsigned integer value of term.
1279 Returns true on success, or false if term is not an unsigned in‐
1281 teger or is outside the bounds of type unsigned int.
1282 int enif_get_uint64(ErlNifEnv* env,
1284 ERL_NIF_TERM term, ErlNifUInt64* ip)
1285 Sets *ip to the unsigned integer value of term.
1287 Returns true on success, or false if term is not an unsigned in‐
1289 teger or is outside the bounds of an unsigned 64-bit integer.
1290 int enif_get_ulong(ErlNifEnv* env, ERL_NIF_TERM
1292 term, unsigned long* ip)
1293 Sets *ip to the unsigned long integer value of term.
1295 Returns true on success, or false if term is not an unsigned in‐
1297 teger or is outside the bounds of type unsigned long.
1298 int enif_getenv(const char* key, char* value,
1300 size_t *value_size)
1301 Same as erl_drv_getenv.
1303 int enif_has_pending_exception(ErlNifEnv* env,
1305 ERL_NIF_TERM* reason)
1306 Returns true if a pending exception is associated with the envi‐
1308 ronment env. If reason is a NULL pointer, ignore it. Otherwise,
1309 if a pending exception associated with env exists, set *reason
1310 to the value of the exception term. For example, if
1311 enif_make_badarg is called to set a pending badarg exception, a
1312 later call to enif_has_pending_exception(env, &reason) sets
1313 *reason to the atom badarg, then return true.
1314 See also enif_make_badarg and enif_raise_exception.
1316 ErlNifUInt64 enif_hash(ErlNifHash type, ERL_NIF_TERM term, ErlNifUInt64
1318 salt)
1319 Hashes term according to the specified ErlNifHash type.
1321 Ranges of taken salt (if any) and returned value depend on the
1323 hash type.
1324 int enif_inspect_binary(ErlNifEnv* env,
1326 ERL_NIF_TERM bin_term, ErlNifBinary* bin)
1327 Initializes the structure pointed to by bin with information
1329 about binary term bin_term.
1330 Returns true on success, or false if bin_term is not a binary.
1332 int enif_inspect_iolist_as_binary(ErlNifEnv*
1334 env, ERL_NIF_TERM term, ErlNifBinary* bin)
1335 Initializes the structure pointed to by bin with a continuous
1337 buffer with the same byte content as iolist. As with inspect_bi‐
1338 nary, the data pointed to by bin is transient and does not need
1339 to be released.
1340 Returns true on success, or false if iolist is not an iolist.
1342 int enif_inspect_iovec(ErlNifEnv*
1344 env, size_t max_elements, ERL_NIF_TERM iovec_term,
1345 ERL_NIF_TERM* tail,
1346 ErlNifIOVec** iovec)
1347 Fills iovec with the list of binaries provided in iovec_term.
1349 The number of elements handled in the call is limited to max_el‐
1350 ements, and tail is set to the remainder of the list. Note that
1351 the output may be longer than max_elements on some platforms.
1352 To create a list of binaries from an arbitrary iolist, use er‐
1354 lang:iolist_to_iovec/1.
1355 When calling this function, iovec should contain a pointer to
1357 NULL or a ErlNifIOVec structure that should be used if possible.
1358 e.g.
1359 /* Don't use a pre-allocated structure */
1361 ErlNifIOVec *iovec = NULL;
1362 enif_inspect_iovec(env, max_elements, term, &tail, &iovec);
1363 /* Use a stack-allocated vector as an optimization for vectors with few elements */
1365 ErlNifIOVec vec, *iovec = &vec;
1366 enif_inspect_iovec(env, max_elements, term, &tail, &iovec);
1367 The contents of the iovec is valid until the called nif function
1370 returns. If the iovec should be valid after the nif call re‐
1371 turns, it is possible to call this function with a NULL environ‐
1372 ment. If no environment is given the iovec owns the data in the
1373 vector and it has to be explicitly freed using enif_free_iovec.
1374 Returns true on success, or false if iovec_term not an iovec.
1376 ErlNifIOQueue *enif_ioq_create(ErlNifIOQueueOpts opts)
1378 Create a new I/O Queue that can be used to store data. opts has
1380 to be set to ERL_NIF_IOQ_NORMAL.
1381 void enif_ioq_destroy(ErlNifIOQueue *q)
1383 Destroy the I/O queue and free all of it's contents
1385 int enif_ioq_deq(ErlNifIOQueue *q, size_t count, size_t *size)
1387 Dequeue count bytes from the I/O queue. If size is not NULL, the
1389 new size of the queue is placed there.
1390 Returns true on success, or false if the I/O does not contain
1392 count bytes. On failure the queue is left un-altered.
1393 int enif_ioq_enq_binary(ErlNifIOQueue *q, ErlNifBinary *bin, size_t
1395 skip)
1396 Enqueue the bin into q skipping the first skip bytes.
1398 Returns true on success, or false if skip is greater than the
1400 size of bin. Any ownership of the binary data is transferred to
1401 the queue and bin is to be considered read-only for the rest of
1402 the NIF call and then as released.
1403 int enif_ioq_enqv(ErlNifIOQueue *q, ErlNifIOVec *iovec, size_t skip)
1405 Enqueue the iovec into q skipping the first skip bytes.
1407 Returns true on success, or false if skip is greater than the
1409 size of iovec.
1410 SysIOVec *enif_ioq_peek(ErlNifIOQueue *q, int *iovlen)
1412 Get the I/O queue as a pointer to an array of SysIOVecs. It also
1414 returns the number of elements in iovlen.
1415 Nothing is removed from the queue by this function, that must be
1417 done with enif_ioq_deq.
1418 The returned array is suitable to use with the Unix system call
1420 writev.
1421 int enif_ioq_peek_head(ErlNifEnv *env, ErlNifIOQueue *q, size_t *size,
1423 ERL_NIF_TERM *bin_term)
1424 Get the head of the IO Queue as a binary term.
1426 If size is not NULL, the size of the head is placed there.
1428 Nothing is removed from the queue by this function, that must be
1430 done with enif_ioq_deq.
1431 Returns true on success, or false if the queue is empty.
1433 size_t enif_ioq_size(ErlNifIOQueue *q)
1435 Get the size of q.
1437 int enif_is_atom(ErlNifEnv* env, ERL_NIF_TERM term)
1439 Returns true if term is an atom.
1441 int enif_is_binary(ErlNifEnv* env, ERL_NIF_TERM term)
1443 Returns true if term is a binary.
1445 int enif_is_current_process_alive(ErlNifEnv* env)
1447 Returns true if the currently executing process is currently
1449 alive, otherwise false.
1450 This function can only be used from a NIF-calling thread, and
1452 with an environment corresponding to currently executing pro‐
1453 cesses.
1454 int enif_is_empty_list(ErlNifEnv* env,
1456 ERL_NIF_TERM term)
1457 Returns true if term is an empty list.
1459 int enif_is_exception(ErlNifEnv* env,
1461 ERL_NIF_TERM term)
1462 Return true if term is an exception.
1464 int enif_is_fun(ErlNifEnv* env, ERL_NIF_TERM
1466 term)
1467 Returns true if term is a fun.
1469 int enif_is_identical(ERL_NIF_TERM lhs,
1471 ERL_NIF_TERM rhs)
1472 Returns true if the two terms are identical. Corresponds to the
1474 Erlang operators =:= and =/=.
1475 int enif_is_list(ErlNifEnv* env, ERL_NIF_TERM term)
1477 Returns true if term is a list.
1479 int enif_is_map(ErlNifEnv* env, ERL_NIF_TERM
1481 term)
1482 Returns true if term is a map, otherwise false.
1484 int enif_is_number(ErlNifEnv* env, ERL_NIF_TERM
1486 term)
1487 Returns true if term is a number.
1489 int enif_is_pid(ErlNifEnv* env, ERL_NIF_TERM term)
1491 Returns true if term is a pid.
1493 int enif_is_pid_undefined(const ErlNifPid* pid)
1495 Returns true if pid has been set as undefined by
1497 enif_set_pid_undefined.
1498 int enif_is_port(ErlNifEnv* env, ERL_NIF_TERM term)
1500 Returns true if term is a port.
1502 int enif_is_port_alive(ErlNifEnv* env,
1504 ErlNifPort *port_id)
1505 Returns true if port_id is alive.
1507 This function is thread-safe.
1509 int enif_is_process_alive(ErlNifEnv* env,
1511 ErlNifPid *pid)
1512 Returns true if pid is alive.
1514 This function is thread-safe.
1516 int enif_is_ref(ErlNifEnv* env, ERL_NIF_TERM term)
1518 Returns true if term is a reference.
1520 int enif_is_tuple(ErlNifEnv* env, ERL_NIF_TERM term)
1522 Returns true if term is a tuple.
1524 int enif_keep_resource(void* obj)
1526 Adds a reference to resource object obj obtained from enif_al‐
1528 loc_resource. Each call to enif_keep_resource for an object must
1529 be balanced by a call to enif_release_resource before the object
1530 is destructed.
1531 ERL_NIF_TERM enif_make_atom(ErlNifEnv *env, const char *name)
1533 Creates an atom term from the NULL-terminated C-string name with
1535 ISO Latin-1 encoding. If the length of name exceeds the maximum
1536 length allowed for an atom (255 characters), enif_make_atom in‐
1537 vokes enif_make_badarg.
1538 ERL_NIF_TERM enif_make_atom_len(ErlNifEnv *env,
1540 const char *name, size_t len)
1541 Create an atom term from the string name with length len and ISO
1543 Latin-1 encoding. NULL characters are treated as any other char‐
1544 acters. If len exceeds the maximum length allowed for an atom
1545 (255 characters), enif_make_atom invokes enif_make_badarg.
1546 ERL_NIF_TERM enif_make_badarg(ErlNifEnv* env)
1548 Makes a badarg exception to be returned from a NIF, and asso‐
1550 ciates it with environment env. Once a NIF or any function it
1551 calls invokes enif_make_badarg, the runtime ensures that a
1552 badarg exception is raised when the NIF returns, even if the NIF
1553 attempts to return a non-exception term instead.
1554 The return value from enif_make_badarg can be used only as the
1556 return value from the NIF that invoked it (directly or indi‐
1557 rectly) or be passed to enif_is_exception, but not to any other
1558 NIF API function.
1559 See also enif_has_pending_exception and enif_raise_exception.
1561 Note:
1563 Before ERTS 7.0 (Erlang/OTP 18), the return value from
1564 enif_make_badarg had to be returned from the NIF. This require‐
1565 ment is now lifted as the return value from the NIF is ignored
1566 if enif_make_badarg has been invoked.
1567 ERL_NIF_TERM enif_make_binary(ErlNifEnv* env, ErlNifBinary* bin)
1570 Makes a binary term from bin. Any ownership of the binary data
1572 is transferred to the created term and bin is to be considered
1573 read-only for the rest of the NIF call and then as released.
1574 ERL_NIF_TERM enif_make_copy(ErlNifEnv* dst_env,
1576 ERL_NIF_TERM src_term)
1577 Makes a copy of term src_term. The copy is created in environ‐
1579 ment dst_env. The source term can be located in any environment.
1580 ERL_NIF_TERM enif_make_double(ErlNifEnv* env, double d)
1582 Creates a floating-point term from a double. If argument double
1584 is not finite or is NaN, enif_make_double invokes
1585 enif_make_badarg.
1586 int enif_make_existing_atom(ErlNifEnv *env,
1588 const char *name, ERL_NIF_TERM *atom, ErlNifCharEncoding
1589 encoding)
1590 Tries to create the term of an already existing atom from the
1592 NULL-terminated C-string name with encoding.
1593 If the atom already exists, this function stores the term in
1595 *atom and returns true, otherwise returns false. It also returns
1596 false if the string name exceeds the maximum length allowed for
1597 an atom (255 characters) or if name is not correctly encoded.
1598 int enif_make_existing_atom_len(ErlNifEnv *env,
1600 const char *name, size_t len, ERL_NIF_TERM *atom, ErlNifCharEn‐
1601 coding
1602 encoding)
1603 Tries to create the term of an already existing atom from the
1605 string name with length len bytes and encoding. NULL characters
1606 are treated as any other characters.
1607 If the atom already exists, this function stores the term in
1609 *atom and returns true, otherwise returns false. It also returns
1610 false if the string name exceeds the maximum length allowed for
1611 an atom (255 characters) or if name is not correctly encoded.
1612 ERL_NIF_TERM enif_make_int(ErlNifEnv* env, int i)
1614 Creates an integer term.
1616 ERL_NIF_TERM enif_make_int64(ErlNifEnv* env, ErlNifSInt64 i)
1618 Creates an integer term from a signed 64-bit integer.
1620 ERL_NIF_TERM enif_make_list(ErlNifEnv* env, unsigned cnt, ...)
1622 Creates an ordinary list term of length cnt. Expects cnt number
1624 of arguments (after cnt) of type ERL_NIF_TERM as the elements of
1625 the list.
1626 Returns an empty list if cnt is 0.
1628 ERL_NIF_TERM enif_make_list1(ErlNifEnv* env, ERL_NIF_TERM e1)
1630 ERL_NIF_TERM enif_make_list2(ErlNifEnv* env,
1631 ERL_NIF_TERM e1, ERL_NIF_TERM e2)
1632 ERL_NIF_TERM enif_make_list3(ErlNifEnv* env,
1633 ERL_NIF_TERM e1, ERL_NIF_TERM e2, ERL_NIF_TERM e3)
1634 ERL_NIF_TERM enif_make_list4(ErlNifEnv* env,
1635 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e4)
1636 ERL_NIF_TERM enif_make_list5(ErlNifEnv* env,
1637 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e5)
1638 ERL_NIF_TERM enif_make_list6(ErlNifEnv* env,
1639 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e6)
1640 ERL_NIF_TERM enif_make_list7(ErlNifEnv* env,
1641 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e7)
1642 ERL_NIF_TERM enif_make_list8(ErlNifEnv* env,
1643 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e8)
1644 ERL_NIF_TERM enif_make_list9(ErlNifEnv* env,
1645 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e9)
1646 Creates an ordinary list term with length indicated by the func‐
1648 tion name. Prefer these functions (macros) over the variadic
1649 enif_make_list to get a compile-time error if the number of ar‐
1650 guments does not match.
1651 ERL_NIF_TERM enif_make_list_cell(ErlNifEnv*
1653 env, ERL_NIF_TERM head, ERL_NIF_TERM tail)
1654 Creates a list cell [head | tail].
1656 ERL_NIF_TERM enif_make_list_from_array(ErlNifEnv* env, const
1658 ERL_NIF_TERM
1659 arr[], unsigned cnt)
1660 Creates an ordinary list containing the elements of array arr of
1662 length cnt.
1663 Returns an empty list if cnt is 0.
1665 ERL_NIF_TERM enif_make_long(ErlNifEnv* env, long int i)
1667 Creates an integer term from a long int.
1669 int enif_make_map_put(ErlNifEnv* env,
1671 ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM value,
1672 ERL_NIF_TERM* map_out)
1673 Makes a copy of map map_in and inserts key with value. If key
1675 already exists in map_in, the old associated value is replaced
1676 by value.
1677 If successful, this function sets *map_out to the new map and
1679 returns true. Returns false if map_in is not a map.
1680 The map_in term must belong to environment env.
1682 int enif_make_map_remove(ErlNifEnv* env,
1684 ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM* map_out)
1685 If map map_in contains key, this function makes a copy of map_in
1687 in *map_out, and removes key and the associated value. If map
1688 map_in does not contain key, *map_out is set to map_in.
1689 Returns true on success, or false if map_in is not a map.
1691 The map_in term must belong to environment env.
1693 int enif_make_map_update(ErlNifEnv* env,
1695 ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM new_value,
1696 ERL_NIF_TERM* map_out)
1697 Makes a copy of map map_in and replace the old associated value
1699 for key with new_value.
1700 If successful, this function sets *map_out to the new map and
1702 returns true. Returns false if map_in is not a map or if it does
1703 not contain key.
1704 The map_in term must belong to environment env.
1706 int enif_make_map_from_arrays(ErlNifEnv* env, ERL_NIF_TERM keys[],
1708 ERL_NIF_TERM values[], size_t cnt, ERL_NIF_TERM *map_out)
1709 Makes a map term from the given keys and values.
1711 If successful, this function sets *map_out to the new map and
1713 returns true. Returns false there are any duplicate keys.
1714 All keys and values must belong to env.
1716 ERL_NIF_TERM enif_make_monitor_term(ErlNifEnv* env, const ErlNifMoni‐
1718 tor* mon)
1719 Creates a term identifying the given monitor received from
1721 enif_monitor_process.
1722 This function is primarily intended for debugging purpose.
1724 int enif_make_new_atom(ErlNifEnv *env,
1726 const char *name, ERL_NIF_TERM *atom, ErlNifCharEncoding
1727 encoding)
1728 Creates an atom term from the NULL-terminated C-string name with
1730 encoding.
1731 If successful, true is returned and the atom term is stored in
1733 *atom.
1734 Otherwise, false is returned if the length of name exceeds the
1736 maximum length allowed for an atom (255 characters) or if name
1737 is not correctly encoded.
1738 int enif_make_new_atom_len(ErlNifEnv *env,
1740 const char *name, size_t len, ERL_NIF_TERM *atom, ErlNifCharEn‐
1741 coding
1742 encoding)
1743 Create an atom term from string name with length len bytes and
1745 encoding.
1746 If successful, true is returned and atom term is stored in
1748 *atom.
1749 Otherwise, false is returned if the string exceeds the maximum
1751 length allowed for an atom (255 characters) or if the string is
1752 not correctly encoded.
1753 unsigned char *enif_make_new_binary(ErlNifEnv*
1755 env, size_t size, ERL_NIF_TERM* termp)
1756 Allocates a binary of size size bytes and creates an owning
1758 term. The binary data is mutable until the calling NIF returns.
1759 This is a quick way to create a new binary without having to use
1760 ErlNifBinary. The drawbacks are that the binary cannot be kept
1761 between NIF calls and it cannot be reallocated.
1762 Returns a pointer to the raw binary data and sets *termp to the
1764 binary term.
1765 ERL_NIF_TERM enif_make_new_map(ErlNifEnv* env)
1767 Makes an empty map term.
1769 ERL_NIF_TERM enif_make_pid(ErlNifEnv* env, const ErlNifPid* pid)
1771 Makes a pid term or the atom undefined from *pid.
1773 ERL_NIF_TERM enif_make_ref(ErlNifEnv* env)
1775 Creates a reference like erlang:make_ref/0.
1777 ERL_NIF_TERM enif_make_resource(ErlNifEnv* env, void* obj)
1779 Creates an opaque handle to a memory-managed resource object ob‐
1781 tained by enif_alloc_resource. No ownership transfer is done, as
1782 the resource object still needs to be released by enif_re‐
1783 lease_resource. However, notice that the call to enif_re‐
1784 lease_resource can occur immediately after obtaining the term
1785 from enif_make_resource, in which case the resource object is
1786 deallocated when the term is garbage collected. For more de‐
1787 tails, see the example of creating and returning a resource ob‐
1788 ject in the User's Guide.
1789 Note:
1791 Since ERTS 9.0 (OTP-20.0), resource terms have a defined behav‐
1792 ior when compared and serialized through term_to_binary or
1793 passed between nodes.
1794 * Two resource terms will compare equal if and only if they
1796 would yield the same resource object pointer when passed to
1797 enif_get_resource.
1798 * A resource term can be serialized with term_to_binary and
1800 later be fully recreated if the resource object is still
1801 alive when binary_to_term is called. A stale resource term
1802 will be returned from binary_to_term if the resource object
1803 has been deallocated. enif_get_resource will return false
1804 for stale resource terms.
1805 The same principles of serialization apply when passing re‐
1807 source terms in messages to remote nodes and back again. A
1808 resource term will act stale on all nodes except the node
1809 where its resource object is still alive in memory.
1810 Before ERTS 9.0 (OTP-20.0), all resource terms did compare equal
1812 to each other and to empty binaries (<<>>). If serialized, they
1813 would be recreated as plain empty binaries.
1814 ERL_NIF_TERM enif_make_resource_binary(ErlNifEnv* env, void* obj, const
1817 void* data, size_t size)
1818 Creates a binary term that is memory-managed by a resource ob‐
1820 ject obj obtained by enif_alloc_resource. The returned binary
1821 term consists of size bytes pointed to by data. This raw binary
1822 data must be kept readable and unchanged until the destructor of
1823 the resource is called. The binary data can be stored external
1824 to the resource object, in which case the destructor is respon‐
1825 sible for releasing the data.
1826 Several binary terms can be managed by the same resource object.
1828 The destructor is not called until the last binary is garbage
1829 collected. This can be useful to return different parts of a
1830 larger binary buffer.
1831 As with enif_make_resource, no ownership transfer is done. The
1833 resource still needs to be released with enif_release_resource.
1834 int enif_make_reverse_list(ErlNifEnv* env, ERL_NIF_TERM list_in,
1836 ERL_NIF_TERM *list_out)
1837 Sets *list_out to the reverse list of the list list_in and re‐
1839 turns true, or returns false if list_in is not a list.
1840 This function is only to be used on short lists, as a copy is
1842 created of the list, which is not released until after the NIF
1843 returns.
1844 The list_in term must belong to environment env.
1846 ERL_NIF_TERM enif_make_string(ErlNifEnv *env,
1848 const char *string, ErlNifCharEncoding encoding)
1849 Creates a list containing the characters of the NULL-terminated
1851 string string with encoding.
1852 ERL_NIF_TERM enif_make_string_len(ErlNifEnv
1854 *env, const char *string, size_t len, ErlNifCharEncoding
1855 encoding)
1856 Creates a list containing the characters of the string string
1858 with length len and encoding. NULL characters are treated as any
1859 other characters.
1860 ERL_NIF_TERM enif_make_sub_binary(ErlNifEnv*
1862 env, ERL_NIF_TERM bin_term, size_t pos, size_t size)
1863 Makes a subbinary of binary bin_term, starting at zero-based po‐
1865 sition pos with a length of size bytes. bin_term must be a bi‐
1866 nary or bitstring. pos+size must be less or equal to the number
1867 of whole bytes in bin_term.
1868 ERL_NIF_TERM enif_make_tuple(ErlNifEnv* env,
1870 unsigned cnt, ...)
1871 Creates a tuple term of arity cnt. Expects cnt number of argu‐
1873 ments (after cnt) of type ERL_NIF_TERM as the elements of the
1874 tuple.
1875 ERL_NIF_TERM enif_make_tuple1(ErlNifEnv* env,
1877 ERL_NIF_TERM e1)
1878 ERL_NIF_TERM enif_make_tuple2(ErlNifEnv* env,
1879 ERL_NIF_TERM e1, ERL_NIF_TERM e2)
1880 ERL_NIF_TERM enif_make_tuple3(ErlNifEnv* env,
1881 ERL_NIF_TERM e1, ERL_NIF_TERM e2, ERL_NIF_TERM e3)
1882 ERL_NIF_TERM enif_make_tuple4(ErlNifEnv* env,
1883 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e4)
1884 ERL_NIF_TERM enif_make_tuple5(ErlNifEnv* env,
1885 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e5)
1886 ERL_NIF_TERM enif_make_tuple6(ErlNifEnv* env,
1887 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e6)
1888 ERL_NIF_TERM enif_make_tuple7(ErlNifEnv* env,
1889 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e7)
1890 ERL_NIF_TERM enif_make_tuple8(ErlNifEnv* env,
1891 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e8)
1892 ERL_NIF_TERM enif_make_tuple9(ErlNifEnv* env,
1893 ERL_NIF_TERM e1, ..., ERL_NIF_TERM e9)
1894 Creates a tuple term with length indicated by the function name.
1896 Prefer these functions (macros) over the variadic enif_make_tu‐
1897 ple to get a compile-time error if the number of arguments does
1898 not match.
1899 ERL_NIF_TERM enif_make_tuple_from_array(ErlNifEnv* env, const
1901 ERL_NIF_TERM
1902 arr[], unsigned cnt)
1903 Creates a tuple containing the elements of array arr of length
1905 cnt.
1906 ERL_NIF_TERM enif_make_uint(ErlNifEnv* env, unsigned int i)
1908 Creates an integer term from an unsigned int.
1910 ERL_NIF_TERM enif_make_uint64(ErlNifEnv* env, ErlNifUInt64 i)
1912 Creates an integer term from an unsigned 64-bit integer.
1914 ERL_NIF_TERM enif_make_ulong(ErlNifEnv* env, unsigned long i)
1916 Creates an integer term from an unsigned long int.
1918 ERL_NIF_TERM enif_make_unique_integer(ErlNifEnv
1920 *env, ErlNifUniqueInteger properties)
1921 Returns a unique integer with the same properties as specified
1923 by erlang:unique_integer/1.
1924 env is the environment to create the integer in.
1926 ERL_NIF_UNIQUE_POSITIVE and ERL_NIF_UNIQUE_MONOTONIC can be
1928 passed as the second argument to change the properties of the
1929 integer returned. They can be combined by OR:ing the two values
1930 together.
1931 See also ErlNifUniqueInteger.
1933 int enif_map_iterator_create(ErlNifEnv *env,
1935 ERL_NIF_TERM map, ErlNifMapIterator *iter, ErlNifMapIteratorEn‐
1936 try
1937 entry)
1938 Creates an iterator for the map map by initializing the struc‐
1940 ture pointed to by iter. Argument entry determines the start po‐
1941 sition of the iterator: ERL_NIF_MAP_ITERATOR_FIRST or
1942 ERL_NIF_MAP_ITERATOR_LAST.
1943 Returns true on success, or false if map is not a map.
1945 A map iterator is only useful during the lifetime of environment
1947 env that the map belongs to. The iterator must be destroyed by
1948 calling enif_map_iterator_destroy:
1949 ERL_NIF_TERM key, value;
1951 ErlNifMapIterator iter;
1952 enif_map_iterator_create(env, my_map, &iter, ERL_NIF_MAP_ITERATOR_FIRST);
1953 while (enif_map_iterator_get_pair(env, &iter, &key, &value)) {
1955 do_something(key,value);
1956 enif_map_iterator_next(env, &iter);
1957 }
1958 enif_map_iterator_destroy(env, &iter);
1959 Note:
1961 The key-value pairs of a map have no defined iteration order.
1962 The only guarantee is that the iteration order of a single map
1963 instance is preserved during the lifetime of the environment
1964 that the map belongs to.
1965 void enif_map_iterator_destroy(ErlNifEnv *env,
1968 ErlNifMapIterator *iter)
1969 Destroys a map iterator created by enif_map_iterator_create.
1971 int enif_map_iterator_get_pair(ErlNifEnv *env,
1973 ErlNifMapIterator *iter, ERL_NIF_TERM *key, ERL_NIF_TERM
1974 *value)
1975 Gets key and value terms at the current map iterator position.
1977 On success, sets *key and *value and returns true. Returns false
1979 if the iterator is positioned at head (before first entry) or
1980 tail (beyond last entry).
1981 int enif_map_iterator_is_head(ErlNifEnv *env,
1983 ErlNifMapIterator *iter)
1984 Returns true if map iterator iter is positioned before the first
1986 entry.
1987 int enif_map_iterator_is_tail(ErlNifEnv *env,
1989 ErlNifMapIterator *iter)
1990 Returns true if map iterator iter is positioned after the last
1992 entry.
1993 int enif_map_iterator_next(ErlNifEnv *env,
1995 ErlNifMapIterator *iter)
1996 Increments map iterator to point to the next key-value entry.
1998 Returns true if the iterator is now positioned at a valid key-
2000 value entry, or false if the iterator is positioned at the tail
2001 (beyond the last entry).
2002 int enif_map_iterator_prev(ErlNifEnv *env,
2004 ErlNifMapIterator *iter)
2005 Decrements map iterator to point to the previous key-value en‐
2007 try.
2008 Returns true if the iterator is now positioned at a valid key-
2010 value entry, or false if the iterator is positioned at the head
2011 (before the first entry).
2012 int enif_monitor_process(ErlNifEnv* caller_env,
2014 void* obj, const ErlNifPid* target_pid, ErlNifMonitor* mon)
2015 Starts monitoring a process from a resource. When a process is
2017 monitored, a process exit results in a call to the provided down
2018 callback associated with the resource type.
2019 Argument obj is pointer to the resource to hold the monitor and
2021 *target_pid identifies the local process to be monitored.
2022 If mon is not NULL, a successful call stores the identity of the
2024 monitor in the ErlNifMonitor struct pointed to by mon. This
2025 identifier is used to refer to the monitor for later removal
2026 with enif_demonitor_process or compare with enif_compare_moni‐
2027 tors. A monitor is automatically removed when it triggers or
2028 when the resource is deallocated.
2029 Argument caller_env is the environment of the calling thread
2031 (process bound or callback environment) or NULL if calling from
2032 a custom thread not spawned by ERTS.
2033 Returns 0 on success, < 0 if no down callback is provided, and >
2035 0 if the process is no longer alive or if target_pid is unde‐
2036 fined.
2037 This function is thread-safe.
2039 ErlNifTime enif_monotonic_time(ErlNifTimeUnit time_unit)
2041 Returns the current Erlang monotonic time. Notice that it is
2043 not uncommon with negative values.
2044 time_unit is the time unit of the returned value.
2046 Returns ERL_NIF_TIME_ERROR if called with an invalid time unit
2048 argument, or if called from a thread that is not a scheduler
2049 thread.
2050 See also ErlNifTime and ErlNifTimeUnit.
2052 ErlNifMutex *enif_mutex_create(char *name)
2054 Same as erl_drv_mutex_create.
2056 void enif_mutex_destroy(ErlNifMutex *mtx)
2058 Same as erl_drv_mutex_destroy.
2060 void enif_mutex_lock(ErlNifMutex *mtx)
2062 Same as erl_drv_mutex_lock.
2064 char*enif_mutex_name(ErlNifMutex* mtx)
2066 Same as erl_drv_mutex_name.
2068 int enif_mutex_trylock(ErlNifMutex *mtx)
2070 Same as erl_drv_mutex_trylock.
2072 void enif_mutex_unlock(ErlNifMutex *mtx)
2074 Same as erl_drv_mutex_unlock.
2076 ERL_NIF_TERM enif_now_time(ErlNifEnv *env)
2078 Returns an erlang:now() time stamp.
2080 This function is deprecated.
2082 ErlNifResourceType *enif_open_resource_type(ErlNifEnv* env, const char*
2084 module_str, const char* name, ErlNifResourceDtor* dtor,
2085 ErlNifResourceFlags flags, ErlNifResourceFlags* tried)
2086 Creates or takes over a resource type identified by the string
2088 name and gives it the destructor function pointed to by dtor.
2089 Argument flags can have the following values:
2090 ERL_NIF_RT_CREATE:
2092 Creates a new resource type that does not already exist.
2093 ERL_NIF_RT_TAKEOVER:
2095 Opens an existing resource type and takes over ownership of
2096 all its instances. The supplied destructor dtor is called
2097 both for existing instances and new instances not yet cre‐
2098 ated by the calling NIF library.
2099 The two flag values can be combined with bitwise OR. The re‐
2101 source type name is local to the calling module. Argument mod‐
2102 ule_str is not (yet) used and must be NULL. dtor can be NULL if
2103 no destructor is needed.
2104 On success, the function returns a pointer to the resource type
2106 and *tried is set to either ERL_NIF_RT_CREATE or
2107 ERL_NIF_RT_TAKEOVER to indicate what was done. On failure, re‐
2108 turns NULL and sets *tried to flags. It is allowed to set tried
2109 to NULL.
2110 Notice that enif_open_resource_type is only allowed to be called
2112 in the two callbacks load and upgrade. The resource type is only
2113 created or taken over if the calling load/upgrade function re‐
2114 turns successfully.
2115 See also enif_open_resource_type_x.
2117 ErlNifResourceType *enif_open_resource_type_x(ErlNifEnv* env, const
2119 char* name, const ErlNifResourceTypeInit* init,
2120 ErlNifResourceFlags flags, ErlNifResourceFlags* tried)
2121 Same as enif_open_resource_type except it accepts additional
2123 callback functions for resource types that are used together
2124 with enif_select and enif_monitor_process.
2125 Argument init is a pointer to an ErlNifResourceTypeInit struc‐
2127 ture that contains the function pointers for destructor, down
2128 and stop callbacks for the resource type.
2129 Note:
2131 Only members dtor, down and stop in ErlNifResourceTypeInit are
2132 read by enif_open_resource_type_x. To implement the new dyncall
2133 callback use enif_init_resource_type.
2134 ErlNifResourceType *enif_init_resource_type(ErlNifEnv* env, const char*
2137 name, const ErlNifResourceTypeInit* init,
2138 ErlNifResourceFlags flags, ErlNifResourceFlags* tried)
2139 Same as enif_open_resource_type_x except it accepts an addi‐
2141 tional callback function for resource types that are used to‐
2142 gether with enif_dynamic_resource_call.
2143 Argument init is a pointer to an ErlNifResourceTypeInit struc‐
2145 ture that contains the callback function pointers dtor, down,
2146 stop and the new dyncall. The struct also contains the field
2147 members that must be set to the number of initialized callbacks
2148 counted from the top of the struct. For example, to initialize
2149 all callbacks including dyncall, members should be set to 4. All
2150 callbacks are optional and may be set to NULL.
2151 int enif_port_command(ErlNifEnv* env, const
2153 ErlNifPort* to_port, ErlNifEnv *msg_env, ERL_NIF_TERM msg)
2154 Works as erlang:port_command/2, except that it is always com‐
2156 pletely asynchronous.
2157 env:
2159 The environment of the calling process. Must not be NULL.
2160 *to_port:
2162 The port ID of the receiving port. The port ID is to refer
2163 to a port on the local node.
2164 msg_env:
2166 The environment of the message term. Can be a process inde‐
2167 pendent environment allocated with enif_alloc_env or NULL.
2168 msg:
2170 The message term to send. The same limitations apply as on
2171 the payload to erlang:port_command/2.
2172 Using a msg_env of NULL is an optimization, which groups to‐
2174 gether calls to enif_alloc_env, enif_make_copy, enif_port_com‐
2175 mand, and enif_free_env into one call. This optimization is only
2176 useful when a majority of the terms are to be copied from env to
2177 msg_env.
2178 Returns true if the command is successfully sent. Returns false
2180 if the command fails, for example:
2181 * *to_port does not refer to a local port.
2183 * The currently executing process (that is, the sender) is not
2185 alive.
2186 * msg is invalid.
2188 See also enif_get_local_port.
2190 void *enif_priv_data(ErlNifEnv* env)
2192 Returns the pointer to the private data that was set by load or
2194 upgrade.
2195 ERL_NIF_TERM enif_raise_exception(ErlNifEnv*
2197 env, ERL_NIF_TERM reason)
2198 Creates an error exception with the term reason to be returned
2200 from a NIF, and associates it with environment env. Once a NIF
2201 or any function it calls invokes enif_raise_exception, the run‐
2202 time ensures that the exception it creates is raised when the
2203 NIF returns, even if the NIF attempts to return a non-exception
2204 term instead.
2205 The return value from enif_raise_exception can only be used as
2207 the return value from the NIF that invoked it (directly or indi‐
2208 rectly) or be passed to enif_is_exception, but not to any other
2209 NIF API function.
2210 See also enif_has_pending_exception and enif_make_badarg.
2212 void *enif_realloc(void* ptr, size_t size)
2214 Reallocates memory allocated by enif_alloc to size bytes.
2216 Returns NULL if the reallocation fails.
2218 The returned pointer is suitably aligned for any built-in type
2220 that fit in the allocated memory.
2221 int enif_realloc_binary(ErlNifBinary* bin, size_t size)
2223 Changes the size of a binary bin. The source binary can be read-
2225 only, in which case it is left untouched and a mutable copy is
2226 allocated and assigned to *bin.
2227 Returns true on success, or false if memory allocation failed.
2229 void enif_release_binary(ErlNifBinary* bin)
2231 Releases a binary obtained from enif_alloc_binary.
2233 void enif_release_resource(void* obj)
2235 Removes a reference to resource object obj obtained from
2237 enif_alloc_resource. The resource object is destructed when the
2238 last reference is removed. Each call to enif_release_resource
2239 must correspond to a previous call to enif_alloc_resource or
2240 enif_keep_resource. References made by enif_make_resource can
2241 only be removed by the garbage collector.
2242 There are no guarantees exactly when the destructor of an unref‐
2244 erenced resource is called. It could be called directly by
2245 enif_release_resource but it could also be scheduled to be
2246 called at a later time possibly by another thread.
2247 ErlNifRWLock *enif_rwlock_create(char *name)
2249 Same as erl_drv_rwlock_create.
2251 void enif_rwlock_destroy(ErlNifRWLock *rwlck)
2253 Same as erl_drv_rwlock_destroy.
2255 char*enif_rwlock_name(ErlNifRWLock* rwlck)
2257 Same as erl_drv_rwlock_name.
2259 void enif_rwlock_rlock(ErlNifRWLock *rwlck)
2261 Same as erl_drv_rwlock_rlock.
2263 void enif_rwlock_runlock(ErlNifRWLock *rwlck)
2265 Same as erl_drv_rwlock_runlock.
2267 void enif_rwlock_rwlock(ErlNifRWLock *rwlck)
2269 Same as erl_drv_rwlock_rwlock.
2271 void enif_rwlock_rwunlock(ErlNifRWLock *rwlck)
2273 Same as erl_drv_rwlock_rwunlock.
2275 int enif_rwlock_tryrlock(ErlNifRWLock *rwlck)
2277 Same as erl_drv_rwlock_tryrlock.
2279 int enif_rwlock_tryrwlock(ErlNifRWLock *rwlck)
2281 Same as erl_drv_rwlock_tryrwlock.
2283 ERL_NIF_TERM enif_schedule_nif(
2285 ErlNifEnv* caller_env, const char* fun_name, int flags,
2286 ERL_NIF_TERM (*fp)(ErlNifEnv* env, int argc, const ERL_NIF_TERM
2287 argv[]), int argc, const ERL_NIF_TERM argv[])
2288 Schedules NIF fp to execute. This function allows an application
2290 to break up long-running work into multiple regular NIF calls or
2291 to schedule a dirty NIF to execute on a dirty scheduler thread.
2292 caller_env:
2294 Must be process bound environment of the calling NIF.
2295 fun_name:
2297 Provides a name for the NIF that is scheduled for execution.
2298 If it cannot be converted to an atom, enif_schedule_nif re‐
2299 turns a badarg exception.
2300 flags:
2302 Must be set to 0 for a regular NIF. If the emulator was
2303 built with dirty scheduler support enabled, flags can be set
2304 to either ERL_NIF_DIRTY_JOB_CPU_BOUND if the job is expected
2305 to be CPU-bound, or ERL_NIF_DIRTY_JOB_IO_BOUND for jobs that
2306 will be I/O-bound. If dirty scheduler threads are not avail‐
2307 able in the emulator, an attempt to schedule such a job re‐
2308 sults in a notsup exception.
2309 argc and argv:
2311 Can either be the originals passed into the calling NIF, or
2312 can be values created by the calling NIF.
2313 The calling NIF must use the return value of enif_schedule_nif
2315 as its own return value.
2316 Be aware that enif_schedule_nif, as its name implies, only
2318 schedules the NIF for future execution. The calling NIF does not
2319 block waiting for the scheduled NIF to execute and return. This
2320 means that the calling NIF cannot expect to receive the sched‐
2321 uled NIF return value and use it for further operations.
2322 int enif_select(ErlNifEnv* env, ErlNifEvent event, enum ErlNifSelect‐
2324 Flags mode, void* obj, const ErlNifPid* pid, ERL_NIF_TERM ref)
2325 This function can be used to receive asynchronous notifications
2327 when OS-specific event objects become ready for either read or
2328 write operations.
2329 Argument event identifies the event object. On Unix systems, the
2331 functions select/poll are used. The event object must be a
2332 socket, pipe or other file descriptor object that select/poll
2333 can use.
2334 Argument mode describes the type of events to wait for. It can
2336 be ERL_NIF_SELECT_READ, ERL_NIF_SELECT_WRITE or a bitwise OR
2337 combination to wait for both. It can also be ERL_NIF_SELECT_STOP
2338 or ERL_NIF_SELECT_CANCEL which are described further below. When
2339 a read or write event is triggered, a notification message like
2340 this is sent to the process identified by pid:
2341 {select, Obj, Ref, ready_input | ready_output}
2343 ready_input or ready_output indicates if the event object is
2345 ready for reading or writing.
2346 Note:
2348 For complete control over the message format use the newer func‐
2349 tions enif_select_read or enif_select_write introduced in
2350 erts-11.0 (OTP-22.0).
2351 Argument pid may be NULL to indicate the calling process. It
2354 must not be set as undefined.
2355 Argument obj is a resource object obtained from enif_alloc_re‐
2357 source. The purpose of the resource objects is as a container of
2358 the event object to manage its state and lifetime. A handle to
2359 the resource is received in the notification message as Obj.
2360 Argument ref must be either a reference obtained from er‐
2362 lang:make_ref/0 or the atom undefined. It will be passed as Ref
2363 in the notifications. If a selective receive statement is used
2364 to wait for the notification then a reference created just be‐
2365 fore the receive will exploit a runtime optimization that by‐
2366 passes all earlier received messages in the queue.
2367 The notifications are one-shot only. To receive further notifi‐
2369 cations of the same type (read or write), repeated calls to
2370 enif_select must be made after receiving each notification.
2371 ERL_NIF_SELECT_CANCEL can be used to cancel previously selected
2373 events. It must be used in a bitwise OR combination with
2374 ERL_NIF_SELECT_READ and/or ERL_NIF_SELECT_WRITE to indicate
2375 which type of event to cancel. Arguments pid and ref are ignored
2376 when ERL_NIF_SELECT_CANCEL is specified. The return value will
2377 tell if the event was actually cancelled or if a notification
2378 may already have been sent.
2379 Use ERL_NIF_SELECT_STOP as mode in order to safely close an
2381 event object that has been passed to enif_select. The stop call‐
2382 back of the resource obj will be called when it is safe to close
2383 the event object. This safe way of closing event objects must be
2384 used even if all notifications have been received (or cancelled)
2385 and no further calls to enif_select have been made. ERL_NIF_SE‐
2386 LECT_STOP will first cancel any selected events before it calls
2387 or schedules the stop callback. Arguments pid and ref are ig‐
2388 nored when ERL_NIF_SELECT_STOP is specified.
2389 The first call to enif_select for a specific OS event will es‐
2391 tablish a relation between the event object and the containing
2392 resource. All subsequent calls for an event must pass its con‐
2393 taining resource as argument obj. The relation is dissolved when
2394 enif_select has been called with mode as ERL_NIF_SELECT_STOP and
2395 the corresponding stop callback has returned. A resource can
2396 contain several event objects but one event object can only be
2397 contained within one resource. A resource will not be destructed
2398 until all its contained relations have been dissolved.
2399 Note:
2401 Use enif_monitor_process together with enif_select to detect
2402 failing Erlang processes and prevent them from causing permanent
2403 leakage of resources and their contained OS event objects.
2404 Returns a non-negative value on success where the following bits
2407 can be set:
2408 ERL_NIF_SELECT_STOP_CALLED:
2410 The stop callback was called directly by enif_select.
2411 ERL_NIF_SELECT_STOP_SCHEDULED:
2413 The stop callback was scheduled to run on some other thread
2414 or later by this thread.
2415 ERL_NIF_SELECT_READ_CANCELLED:
2417 A read event was cancelled by ERL_NIF_SELECT_CANCEL or
2418 ERL_NIF_SELECT_STOP and is guaranteed not to generate a
2419 ready_input notification message.
2420 ERL_NIF_SELECT_WRITE_CANCELLED:
2422 A write event was cancelled by ERL_NIF_SELECT_CANCEL or
2423 ERL_NIF_SELECT_STOP and is guaranteed not to generate a
2424 ready_output notification message.
2425 Returns a negative value if the call failed where the following
2427 bits can be set:
2428 ERL_NIF_SELECT_INVALID_EVENT:
2430 Argument event is not a valid OS event object.
2431 ERL_NIF_SELECT_FAILED:
2433 The system call failed to add the event object to the poll
2434 set.
2435 Note:
2437 Use bitwise AND to test for specific bits in the return value.
2438 New significant bits may be added in future releases to give
2439 more detailed information for both failed and successful calls.
2440 Do NOT use equality tests like ==, as that may cause your appli‐
2441 cation to stop working.
2442 Example:
2444 retval = enif_select(env, fd, ERL_NIF_SELECT_STOP, resource, ref);
2446 if (retval < 0) {
2447 /* handle error */
2448 }
2449 /* Success! */
2450 if (retval & ERL_NIF_SELECT_STOP_CALLED) {
2451 /* ... */
2452 }
2453 Note:
2457 The mode flag ERL_NIF_SELECT_CANCEL and the return flags
2458 ERL_NIF_SELECT_READ_CANCELLED and ERL_NIF_SELECT_WRITE_CANCELLED
2459 were introduced in erts-11.0 (OTP-22.0).
2460 int enif_select_read(ErlNifEnv* env, ErlNifEvent event, void* obj,
2463 const ErlNifPid* pid, ERL_NIF_TERM msg, ErlNifEnv* msg_env)
2464 int enif_select_write(ErlNifEnv* env, ErlNifEvent event, void* obj,
2465 const ErlNifPid* pid, ERL_NIF_TERM msg, ErlNifEnv* msg_env)
2466 These are variants of enif_select where you can supply your own
2468 message term msg that will be sent to the process instead of the
2469 predefined tuple {select,_,_,_}.
2470 Argument msg_env must either be NULL or the environment of msg
2472 allocated with enif_alloc_env. If argument msg_env is NULL the
2473 term msg will be copied, otherwise both msg and msg_env will be
2474 invalidated by a successful call to enif_select_read or enif_se‐
2475 lect_write. The environment is then to either be freed with
2476 enif_free_env or cleared for reuse with enif_clear_env. An un‐
2477 successful call will leave msg and msg_env still valid.
2478 Apart from the message format enif_select_read and enif_se‐
2480 lect_write behaves exactly the same as enif_select with argument
2481 mode as either ERL_NIF_SELECT_READ or ERL_NIF_SELECT_WRITE. To
2482 cancel or close events use enif_select.
2483 ErlNifPid *enif_self(ErlNifEnv* caller_env, ErlNifPid* pid)
2485 Initializes the ErlNifPid variable at *pid to represent the
2487 calling process.
2488 Returns pid if successful, or NULL if caller_env is not a
2490 process bound environment.
2491 int enif_send(ErlNifEnv* caller_env,
2493 ErlNifPid* to_pid, ErlNifEnv* msg_env, ERL_NIF_TERM msg)
2494 Sends a message to a process.
2496 caller_env:
2498 The environment of the calling thread (process bound or
2499 callback environment) or NULL if calling from a custom
2500 thread not spawned by ERTS.
2501 *to_pid:
2503 The pid of the receiving process. The pid is to refer to a
2504 process on the local node.
2505 msg_env:
2507 The environment of the message term. Must be a process inde‐
2508 pendent environment allocated with enif_alloc_env or NULL.
2509 msg:
2511 The message term to send.
2512 Returns true if the message is successfully sent. Returns false
2514 if the send operation fails, that is:
2515 * *to_pid does not refer to an alive local process.
2517 * The currently executing process (that is, the sender) is not
2519 alive.
2520 The message environment msg_env with all its terms (including
2522 msg) is invalidated by a successful call to enif_send. The envi‐
2523 ronment is to either be freed with enif_free_env or cleared for
2524 reuse with enif_clear_env. An unsuccessful call will leave msg
2525 and msg_env still valid.
2526 If msg_env is set to NULL, the msg term is copied and the origi‐
2528 nal term and its environment is still valid after the call.
2529 This function is thread-safe.
2531 Note:
2533 Passing msg_env as NULL is only supported as from ERTS 8.0 (Er‐
2534 lang/OTP 19).
2535 int enif_set_option(ErlNifEnv *env, ErlNifOption opt, ...)
2538 Set an option. On success, zero will be returned. On failure, a
2540 non zero value will be returned. Currently the following options
2541 can be set:
2542 int enif_set_option(ErlNifEnv *env, ERL_NIF_OPT_DELAY_HALT):
2544 Enable delay of runtime system halt with flushing enabled
2545 until all calls to NIFs in the NIF library have returned. If
2546 the delay halt feature has not been enabled, a halt with
2547 flushing enabled may complete even though processes are
2548 still executing inside NIFs in the NIF library. Note that by
2549 returning we here mean the first point where the NIF re‐
2550 turns control back to the runtime system, and not the point
2551 where a call to a NIF return a value back to the Erlang code
2552 that called the NIF. That is, if you schedule execution of a
2553 NIF, using enif_schedule_nif(), from within a NIF while the
2554 system is halting, the scheduled NIF call will not be exe‐
2555 cuted even though delay halt has been enabled for the NIF
2556 library.
2557 The runtime system halts when one of the erlang:halt() BIFs
2559 are called. By default flushing is enabled, but can be dis‐
2560 abled using the erlang:halt/2 BIF. When flushing has been
2561 disabled, the delay halt setting will have no effect. That
2562 is, the runtime system will halt without waiting for NIFs to
2563 return even if the delay halt setting has been enabled. See
2564 the {flush, boolean()} option of erlang:halt/2 for more in‐
2565 formation.
2566 The ERL_NIF_OPT_DELAY_HALT option can only be set during
2568 loading of a NIF library in a call to enif_set_option() in‐
2569 side a NIF library load() or upgrade() call, and will fail
2570 if set somewhere else. The env argument must be the call‐
2571 back environment passed to the load() or the upgrade() call.
2572 This option can also only be set once. That is, the delay
2573 halt setting cannot be changed once it has been enabled.
2574 The delay halt setting is tied to the module instance with
2575 which the NIF library instance has been loaded. That is, in
2576 case both a new and old version of a module using the NIF
2577 library are loaded, they can have the same or different de‐
2578 lay halt settings.
2579 The delay halt feature can be used in combination with an
2581 on halt callback. The on halt callback is in this case
2582 typically used to notify processes blocked in NIFs in the
2583 library that it is time to return in order to let the run‐
2584 time system complete the halting. Such NIFs should be dirty
2585 NIFs, since ordinary NIFs should never block for a long
2586 time.
2587 int enif_set_option(ErlNifEnv *env, ERL_NIF_OPT_ON_HALT, Erl‐
2589 NifOnHaltCallback *on_halt):
2590 Install a callback that will be called when the runtime sys‐
2591 tem halts with flushing enabled.
2592 The runtime system halts when one of the erlang:halt() BIFs
2594 are called. By default flushing is enabled, but can be dis‐
2595 abled using the erlang:halt/2 BIF. When flushing has been
2596 disabled, the runtime system will halt without calling any
2597 on halt callbacks even if such are installed. See the
2598 {flush, boolean()} option of erlang:halt/2 for more informa‐
2599 tion.
2600 The ERL_NIF_OPT_ON_HALT option can only be set during load‐
2602 ing of a NIF library in a call to enif_set_option() inside a
2603 NIF library load() or upgrade() call, and will fail if
2604 called somewhere else. The env argument must be the call‐
2605 back environment passed to the load() or the upgrade() call.
2606 The on_halt argument should be a function pointer to the
2607 callback to install. The on halt callback will be tied to
2608 the module instance with which the NIF library instance has
2609 been loaded. That is, in case both a new and old version of
2610 a module using the NIF library are loaded, they can both
2611 have different, none, or the same on halt callbacks in‐
2612 stalled. When unloading the NIF library during a code purge,
2613 an installed on halt callback will be uninstalled. The
2614 ERL_NIF_OPT_ON_HALT option can also only be set once. That
2615 is, the on halt callback cannot be changed or removed once
2616 it has been installed by any other means than purging the
2617 module instance that loaded the NIF library.
2618 When the installed on halt callback is called, it will be
2620 passed a pointer to priv_data as argument. The priv_data
2621 pointer can be set when loading the NIF library.
2622 The on halt callback can be used in combination with delay
2624 of halt until all calls into the library have returned. The
2625 on halt callback is in this case typically used to notify
2626 processes blocked in NIFs in the library that it is time to
2627 return in order to let the runtime system complete the halt‐
2628 ing. Such NIFs should be dirty NIFs, since ordinary NIFs
2629 should never block for a long time.
2630 void enif_set_pid_undefined(ErlNifPid* pid)
2632 Sets an ErlNifPid variable as undefined. See enif_is_pid_unde‐
2634 fined.
2635 unsigned enif_sizeof_resource(void* obj)
2637 Gets the byte size of resource object obj obtained by enif_al‐
2639 loc_resource.
2640 int enif_snprintf(char *str, size_t size, const
2642 char *format, ...)
2643 Similar to snprintf but this format string also accepts "%T",
2645 which formats Erlang terms of type ERL_NIF_TERM.
2646 This function is primarily intended for debugging purpose. It is
2648 not recommended to print very large terms with %T. The function
2649 may change errno, even if successful.
2650 void enif_system_info(ErlNifSysInfo
2652 *sys_info_ptr, size_t size)
2653 Same as driver_system_info.
2655 int enif_term_to_binary(ErlNifEnv *env,
2657 ERL_NIF_TERM term, ErlNifBinary *bin)
2658 Allocates a new binary with enif_alloc_binary and stores the re‐
2660 sult of encoding term according to the Erlang external term for‐
2661 mat.
2662 Returns true on success, or false if the allocation fails.
2664 See also erlang:term_to_binary/1 and enif_binary_to_term.
2666 ErlNifTermType enif_term_type(ErlNifEnv *env, ERL_NIF_TERM term)
2668 Determines the type of the given term. The term must be an ordi‐
2670 nary Erlang term and not one of the special terms returned by
2671 enif_raise_exception, enif_schedule_nif, or similar.
2672 The following types are defined at the moment:
2674 ERL_NIF_TERM_TYPE_ATOM:
2676 ERL_NIF_TERM_TYPE_BITSTRING:
2679 A bitstring or binary
2680 ERL_NIF_TERM_TYPE_FLOAT:
2682 ERL_NIF_TERM_TYPE_FUN:
2685 ERL_NIF_TERM_TYPE_INTEGER:
2688 ERL_NIF_TERM_TYPE_LIST:
2691 A list, empty or not
2692 ERL_NIF_TERM_TYPE_MAP:
2694 ERL_NIF_TERM_TYPE_PID:
2697 ERL_NIF_TERM_TYPE_PORT:
2700 ERL_NIF_TERM_TYPE_REFERENCE:
2703 ERL_NIF_TERM_TYPE_TUPLE:
2706 Note that new types may be added in the future, so the caller
2709 must be prepared to handle unknown types.
2710 int enif_thread_create(char *name,ErlNifTid
2712 *tid,void * (*func)(void *),void *args,ErlNifThreadOpts
2713 *opts)
2714 Same as erl_drv_thread_create.
2716 void enif_thread_exit(void *resp)
2718 Same as erl_drv_thread_exit.
2720 int enif_thread_join(ErlNifTid, void **respp)
2722 Same as erl_drv_thread_join.
2724 char*enif_thread_name(ErlNifTid tid)
2726 Same as erl_drv_thread_name.
2728 ErlNifThreadOpts *enif_thread_opts_create(char *name)
2730 Same as erl_drv_thread_opts_create.
2732 void enif_thread_opts_destroy(ErlNifThreadOpts *opts)
2734 Same as erl_drv_thread_opts_destroy.
2736 ErlNifTid enif_thread_self(void)
2738 Same as erl_drv_thread_self.
2740 int enif_thread_type(void)
2742 Determine the type of currently executing thread. A positive
2744 value indicates a scheduler thread while a negative value or
2745 zero indicates another type of thread. Currently the following
2746 specific types exist (which may be extended in the future):
2747 ERL_NIF_THR_UNDEFINED:
2749 Undefined thread that is not a scheduler thread.
2750 ERL_NIF_THR_NORMAL_SCHEDULER:
2752 A normal scheduler thread.
2753 ERL_NIF_THR_DIRTY_CPU_SCHEDULER:
2755 A dirty CPU scheduler thread.
2756 ERL_NIF_THR_DIRTY_IO_SCHEDULER:
2758 A dirty I/O scheduler thread.
2759 ErlNifTime enif_time_offset(ErlNifTimeUnit time_unit)
2761 Returns the current time offset between Erlang monotonic time
2763 and Erlang system time converted into the time_unit passed as
2764 argument.
2765 time_unit is the time unit of the returned value.
2767 Returns ERL_NIF_TIME_ERROR if called with an invalid time unit
2769 argument or if called from a thread that is not a scheduler
2770 thread.
2771 See also ErlNifTime and ErlNifTimeUnit.
2773 void *enif_tsd_get(ErlNifTSDKey key)
2775 Same as erl_drv_tsd_get.
2777 int enif_tsd_key_create(char *name, ErlNifTSDKey *key)
2779 Same as erl_drv_tsd_key_create.
2781 void enif_tsd_key_destroy(ErlNifTSDKey key)
2783 Same as erl_drv_tsd_key_destroy.
2785 void enif_tsd_set(ErlNifTSDKey key, void *data)
2787 Same as erl_drv_tsd_set.
2789 int enif_vfprintf(FILE *stream, const char *format, va_list ap)
2791 Equivalent to enif_fprintf except that its called with a va_list
2794 instead of a variable number of arguments.
2795 int enif_vsnprintf(char *str, size_t size, const char *format, va_list
2797 ap)
2798 Equivalent to enif_snprintf except that its called with a
2801 va_list instead of a variable number of arguments.
2802 int enif_whereis_pid(ErlNifEnv *caller_env,
2804 ERL_NIF_TERM name, ErlNifPid *pid)
2805 Looks up a process by its registered name.
2807 caller_env:
2809 The environment of the calling thread (process bound or
2810 callback environment) or NULL if calling from a custom
2811 thread not spawned by ERTS.
2812 name:
2814 The name of a registered process, as an atom.
2815 *pid:
2817 The ErlNifPid in which the resolved process id is stored.
2818 On success, sets *pid to the local process registered with name
2820 and returns true. If name is not a registered process, or is not
2821 an atom, false is returned and *pid is unchanged.
2822 Works as erlang:whereis/1, but restricted to processes. See
2824 enif_whereis_port to resolve registered ports.
2825 int enif_whereis_port(ErlNifEnv *caller_env,
2827 ERL_NIF_TERM name, ErlNifPort *port)
2828 Looks up a port by its registered name.
2830 caller_env:
2832 The environment of the calling thread (process bound or
2833 callback environment) or NULL if calling from a custom
2834 thread not spawned by ERTS.
2835 name:
2837 The name of a registered port, as an atom.
2838 *port:
2840 The ErlNifPort in which the resolved port id is stored.
2841 On success, sets *port to the port registered with name and re‐
2843 turns true. If name is not a registered port, or is not an atom,
2844 false is returned and *port is unchanged.
2845 Works as erlang:whereis/1, but restricted to ports. See
2847 enif_whereis_pid to resolve registered processes.
2848
2850 erlang:load_nif/2
2851 NIFs (tutorial)
2852 Debugging NIFs and Port Drivers
2853Ericsson AB erts 14.1.1 erl_nif(3)