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