102
119
<p>A better solution for a real module is to take advantage of
103
the new attribute <c>on_load</c> to automatically load the NIF
104
library when the module is loaded.</p>
120
the new directive <seealso
121
marker="doc/reference_manual:code_loading#on_load">on_load</seealso> to automatically
122
load the NIF library when the module is loaded.</p>
123
<note><p>A NIF does not have to be exported, it can be local to the module.
124
Note however that unused local stub functions will be optimized
125
away by the compiler causing loading of the NIF library to fail.</p>
105
127
<p>A loaded NIF library is tied to the Erlang module code version
106
128
that loaded it. If the module is upgraded with a new version, the
107
new code will have to load its own NIF library (or maybe choose not
129
new Erlang code will have to load its own NIF library (or maybe choose not
108
130
to). The new code version can however choose to load the exact
109
131
same NIF library as the old code if it wants to. Sharing the same
110
132
dynamic library will mean that static data defined by the library
111
133
will be shared as well. To avoid unintentionally shared static
112
134
data, each Erlang module code can keep its own private data. This
113
global private data can be set when the NIF library is loaded and
114
then retrieved by calling <seealso marker="erl_nif#enif_get_data">enif_get_data()</seealso>.</p>
115
<p>There is currently no way to explicitly unload a NIF
116
library. A library will be automatically unloaded when the module
117
code that it belongs to is purged by the code server. A NIF
118
library will can also be unloaded by replacing it with another
119
version of the library by a second call to
135
private data can be set when the NIF library is loaded and
136
then retrieved by calling <seealso marker="#enif_priv_data">enif_priv_data</seealso>.</p>
137
<p>There is no way to explicitly unload a NIF library. A library will be
138
automatically unloaded when the module code that it belongs to is purged
139
by the code server. A NIF library will also be unloaded if it is replaced
140
by another version of the library by a second call to
120
141
<c>erlang:load_nif/2</c> from the same module code.</p>
144
<title>FUNCTIONALITY</title>
145
<p>All functions that a NIF library needs to do with Erlang are
146
performed through the NIF API functions. There are functions
147
for the following functionality:</p>
149
<tag>Read and write Erlang terms</tag>
150
<item><p>Any Erlang terms can be passed to a NIF as function arguments and
151
be returned as function return values. The terms are of C-type
152
<seealso marker="#ERL_NIF_TERM">ERL_NIF_TERM</seealso>
153
and can only be read or written using API functions. Most functions to read
154
the content of a term are prefixed <c>enif_get_</c> and usually return
155
true (or false) if the term was of the expected type (or not).
156
The functions to write terms are all prefixed <c>enif_make_</c> and usually
157
return the created <c>ERL_NIF_TERM</c>. There are also some functions
158
to query terms, like <c>enif_is_atom</c>, <c>enif_is_identical</c> and
159
<c>enif_compare</c>.</p>
160
<p>All terms of type <c>ERL_NIF_TERM</c> belong to an environment of type
161
<seealso marker="#ErlNifEnv">ErlNifEnv</seealso>. The lifetime of a term is
162
controlled by the lifetime of its environment object. All API functions that read
163
or write terms has the environment, that the term belongs to, as the first
164
function argument.</p></item>
166
<item><p>Terms of type binary are accessed with the help of the struct type
167
<seealso marker="#ErlNifBinary">ErlNifBinary</seealso>
168
that contains a pointer (<c>data</c>) to the raw binary data and the length
169
(<c>size</c>) of the data in bytes. Both <c>data</c> and <c>size</c> are
170
read-only and should only be written using calls to API functions.
171
Instances of <c>ErlNifBinary</c> are however always allocated by the user
172
(usually as local variables).</p>
173
<p>The raw data pointed to by <c>data</c> is only mutable after a call to
174
<seealso marker="#enif_alloc_binary">enif_alloc_binary</seealso> or
175
<seealso marker="#enif_realloc_binary">enif_realloc_binary</seealso>.
176
All other functions that operates on a binary will leave the data as read-only.
177
A mutable binary must in the end either be freed with
178
<seealso marker="#enif_release_binary">enif_release_binary</seealso>
179
or made read-only by transferring it to an Erlang term with
180
<seealso marker="#enif_make_binary">enif_make_binary</seealso>.
181
But it does not have to happen in the same NIF call. Read-only binaries
182
do not have to be released.</p>
183
<p><seealso marker="#enif_make_new_binary">enif_make_new_binary</seealso>
184
can be used as a shortcut to allocate and return a binary in the same NIF call.</p>
185
<p>Binaries are sequences of whole bytes. Bitstrings with an arbitrary
186
bit length have no support yet.</p>
188
<tag>Resource objects</tag>
189
<item><p>The use of resource objects is a way to return pointers to
190
native data structures from a NIF in a safe way. A resource object is
191
just a block of memory allocated with
192
<seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>.
193
A handle ("safe pointer") to this memory block can then be returned to Erlang by the use of
194
<seealso marker="#enif_make_resource">enif_make_resource</seealso>.
195
The term returned by <c>enif_make_resource</c>
196
is totally opaque in nature. It can be stored and passed between processes
197
on the same node, but the only real end usage is to pass it back as an argument to a NIF.
198
The NIF can then call <seealso marker="#enif_get_resource">enif_get_resource</seealso>
199
and get back a pointer to the memory block that is guaranteed to still be
200
valid. A resource object will not be deallocated until the last handle term
201
has been garbage collected by the VM and the resource has been
202
released with <seealso marker="#enif_release_resource">enif_release_resource</seealso>
203
(not necessarily in that order).</p>
204
<p>All resource objects are created as instances of some <em>resource type</em>.
205
This makes resources from different modules to be distinguishable.
206
A resource type is created by calling
207
<seealso marker="#enif_open_resource_type">enif_open_resource_type</seealso>
208
when a library is loaded. Objects of that resource type can then later be allocated
209
and <c>enif_get_resource</c> verifies that the resource is of the expected type.
210
A resource type can have a user supplied destructor function that is
211
automatically called when resources of that type are released (by either
212
the garbage collector or <c>enif_release_resource</c>). Resource types
213
are uniquely identified by a supplied name string and the name of the
214
implementing module.</p>
215
<marker id="enif_resource_example"/><p>Here is a template example of how to create and return a resource object.</p>
219
MyStruct* ptr = enif_alloc_resource(my_resource_type, sizeof(MyStruct));
221
/* initialize struct ... */
223
term = enif_make_resource(env, ptr);
225
if (keep_a_reference_of_our_own) {
226
/* store 'ptr' in static variable, private data or other resource object */
229
enif_release_resource(obj);
230
/* resource now only owned by "Erlang" */
234
<p>Note that once <c>enif_make_resource</c> creates the term to
235
return to Erlang, the code can choose to either keep its own
236
native pointer to the allocated struct and release it later, or
237
release it immediately and rely solely on the garbage collector
238
to eventually deallocate the resource object when it collects
240
<p>Another usage of resource objects is to create binary terms with
241
user defined memory management.
242
<seealso marker="#enif_make_resource_binary">enif_make_resource_binary</seealso>
243
will create a binary term that is connected to a resource object. The
244
destructor of the resource will be called when the binary is garbage
245
collected, at which time the binary data can be released. An example of
246
this can be a binary term consisting of data from a <c>mmap</c>'ed file.
247
The destructor can then do <c>munmap</c> to release the memory
249
<p>Resource types support upgrade in runtime by allowing a loaded NIF
250
library to takeover an already existing resource type and thereby
251
"inherit" all existing objects of that type. The destructor of the new
252
library will thereafter be called for the inherited objects and the
253
library with the old destructor function can be safely unloaded. Existing
254
resource objects, of a module that is upgraded, must either be deleted
255
or taken over by the new NIF library. The unloading of a library will be
256
postponed as long as there exist resource objects with a destructor
257
function in the library.
260
<tag>Threads and concurrency</tag>
261
<item><p>A NIF is thread-safe without any explicit synchronization as
262
long as it acts as a pure function and only reads the supplied
263
arguments. As soon as you write towards a shared state either through
264
static variables or <seealso marker="#enif_priv_data">enif_priv_data</seealso>
265
you need to supply your own explicit synchronization. This includes terms
266
in process independent environments that are shared between threads.
267
Resource objects will also require synchronization if you treat them as
269
<p>The library initialization callbacks <c>load</c>, <c>reload</c> and
270
<c>upgrade</c> are all thread-safe even for shared state data.</p>
271
<p>Avoid doing lengthy work in NIF calls as that may degrade the
272
responsiveness of the VM. NIFs are called directly by the same scheduler
273
thread that executed the calling Erlang code. The calling scheduler will thus
274
be blocked from doing any other work until the NIF returns.</p>
124
279
<title>INITIALIZATION</title>
190
346
<title>DATA TYPES</title>
193
<tag><marker id="ErlDrvEnv"/>ErlDrvEnv</tag>
349
<tag><marker id="ERL_NIF_TERM"/>ERL_NIF_TERM</tag>
351
<p>Variables of type <c>ERL_NIF_TERM</c> can refer to any Erlang term.
352
This is an opaque type and values of it can only by used either as
353
arguments to API functions or as return values from NIFs. All
354
<c>ERL_NIF_TERM</c>'s belong to an environment
355
(<seealso marker="#ErlNifEnv">ErlNifEnv</seealso>). A term can not be
356
destructed individually, it is valid until its environment is destructed.</p>
358
<tag><marker id="ErlNifEnv"/>ErlNifEnv</tag>
195
<p><c>ErlNifEnv</c> contains information about the context in
196
which a NIF call is made. This pointer should not be
197
dereferenced in any way, but only passed on to API
198
functions. An <c>ErlNifEnv</c> pointer is only valid until
199
the function, where is what supplied as argument,
200
returns. There is thus useless and dangerous to store <c>ErlNifEnv</c>
201
pointers in between NIF calls.</p>
360
<p><c>ErlNifEnv</c> represents an environment that can host Erlang terms.
361
All terms in an environment are valid as long as the environment is valid.
362
<c>ErlNifEnv</c> is an opaque type and pointers to it can only be passed
363
on to API functions. There are two types of environments; process
364
bound and process independent.</p>
365
<p>A <em>process bound environment</em> is passed as the first argument to all NIFs.
366
All function arguments passed to a NIF will belong to that environment.
367
The return value from a NIF must also be a term belonging to the same
369
In addition a process bound environment contains transient information
370
about the calling Erlang process. The environment is only valid in the
371
thread where it was supplied as argument until the NIF returns. It is
372
thus useless and dangerous to store pointers to process bound
373
environments between NIF calls. </p>
374
<p>A <em>process independent environment</em> is created by calling
375
<seealso marker="#enif_alloc_env">enif_alloc_env</seealso>. It can be
376
used to store terms between NIF calls and to send terms with
377
<seealso marker="#enif_send">enif_send</seealso>. A process
378
independent environment with all its terms is valid until you explicitly
379
invalidates it with <seealso marker="#enif_free_env">enif_free_env</seealso>
380
or <c>enif_send</c>.</p>
381
<p>All elements of a list/tuple must belong to the same environment as the
382
list/tuple itself. Terms can be copied between environments with
383
<seealso marker="#enif_make_copy">enif_make_copy</seealso>.</p>
203
385
<tag><marker id="ErlNifFunc"/>ErlNifFunc</tag>
206
388
<code type="none">
210
ERL_NIF_TERM (*fptr)(ErlNifEnv* env, ...);
390
const char* <em>name</em>;
391
unsigned <em>arity</em>;
392
ERL_NIF_TERM (*<em>fptr</em>)(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]);
213
395
<p>Describes a NIF by its name, arity and implementation.
214
396
<c>fptr</c> is a pointer to the function that implements the
215
NIF. The number of arguments must match the arity. A NIF of
216
arity 2 will thus look like:</p>
219
ERL_NIF_TERM my_nif(ErlNifEnv* env, ERL_NIF_TERM arg1, ERL_NIF_TERM arg2)
224
<p>The maximum allowed arity for a NIF is 3 in current implementation.</p>
397
NIF. The argument <c>argv</c> of a NIF will contain the
398
function arguments passed to the NIF and <c>argc</c> is the
399
length of the array, i.e. the function arity. <c>argv[N-1]</c>
400
will thus denote the Nth argument to the NIF. Note that the
401
<c>argc</c> argument allows for the same C function to
402
implement several Erlang functions with different arity (but
403
same name probably).</p>
226
405
<tag><marker id="ErlNifBinary"/>ErlNifBinary</tag>
229
408
<code type="none">
410
unsigned <em>size</em>;
411
unsigned char* <em>data</em>;
235
414
<p><c>ErlNifBinary</c> contains transient information about an
236
415
inspected binary term. <c>data</c> is a pointer to a buffer
237
416
of <c>size</c> bytes with the raw content of the binary.</p>
239
<tag><marker id="ERL_NIF_TERM"/>ERL_NIF_TERM</tag>
241
<p>Variables of type <c>ERL_NIF_TERM</c> can refere to any
242
Erlang term. This is an opaque type and values of it can only
243
by used either as arguments to API functions or as return
244
values from NIFs. A variable of type <c>ERL_NIF_TERM</c> is
245
only valid until the NIF call, where it was obtained,
417
<p>Note that <c>ErlNifBinary</c> is a semi-opaque type and you are
418
only allowed to read fields <c>size</c> and <c>data</c>.</p>
420
<tag><marker id="ErlNifPid"/>ErlNifPid</tag>
422
<p><c>ErlNifPid</c> is a process identifier (pid). In contrast to
423
pid terms (instances of <c>ERL_NIF_TERM</c>), <c>ErlNifPid</c>'s are self
424
contained and not bound to any
425
<seealso marker="#ErlNifEnv">environment</seealso>. <c>ErlNifPid</c>
426
is an opaque type.</p>
429
<tag><marker id="ErlNifResourceType"/>ErlNifResourceType</tag>
431
<p>Each instance of <c>ErlNifResourceType</c> represent a class of
432
memory managed resource objects that can be garbage collected.
433
Each resource type has a unique name and a destructor function that
434
is called when objects of its type are released.</p>
436
<tag><marker id="ErlNifResourceDtor"/>ErlNifResourceDtor</tag>
440
typedef void ErlNifResourceDtor(ErlNifEnv* env, void* obj);
442
<p>The function prototype of a resource destructor function.
443
A destructor function is not allowed to call any term-making functions.</p>
445
<tag><marker id="ErlNifCharEncoding"/>ErlNifCharEncoding</tag>
453
<p>The character encoding used in strings and atoms. The only
454
supported encoding is currently <c>ERL_NIF_LATIN1</c> for
455
iso-latin-1 (8-bit ascii).</p>
457
<tag><marker id="ErlNifSysInfo"/>ErlNifSysInfo</tag>
459
<p>Used by <seealso marker="#enif_system_info">enif_system_info</seealso>
460
to return information about the runtime system. Contains currently
461
the exact same content as <seealso marker="erl_driver#ErlDrvSysInfo">ErlDrvSysInfo</seealso>.</p>
463
<tag><marker id="ErlNifSInt64"/>ErlNifSInt64</tag>
464
<item><p>A native signed 64-bit integer type.</p></item>
465
<tag><marker id="ErlNifUInt64"/>ErlNifUInt64</tag>
466
<item><p>A native unsigned 64-bit integer type.</p></item>
252
<func><name><ret>void*</ret><nametext>enif_get_data(ErlNifEnv* env)</nametext></name>
253
<fsummary>Get the private data of a NIF library</fsummary>
254
<desc><p>Returns the pointer to the private data that was set by <c>load</c>, <c>reload</c> or <c>upgrade</c>.</p></desc>
256
<func><name><ret>void*</ret><nametext>enif_alloc(ErlNifEnv* env, size_t size)</nametext></name>
472
<func><name><ret>void*</ret><nametext>enif_alloc(size_t size)</nametext></name>
257
473
<fsummary>Allocate dynamic memory.</fsummary>
258
<desc><p>Allocate memory of <c>size</c> bytes.</p></desc>
260
<func><name><ret>void</ret><nametext>enif_free(ErlNifEnv* env, void* ptr)</nametext></name>
474
<desc><p>Allocate memory of <c>size</c> bytes. Return NULL if allocation failed.</p></desc>
476
<func><name><ret>int</ret><nametext>enif_alloc_binary(size_t size, ErlNifBinary* bin)</nametext></name>
477
<fsummary>Create a new binary.</fsummary>
478
<desc><p>Allocate a new binary of size <c>size</c>
479
bytes. Initialize the structure pointed to by <c>bin</c> to
480
refer to the allocated binary. The binary must either be released by
481
<seealso marker="#enif_release_binary">enif_release_binary</seealso>
482
or ownership transferred to an Erlang term with
483
<seealso marker="#enif_make_binary">enif_make_binary</seealso>.
484
An allocated (and owned) <c>ErlNifBinary</c> can be kept between NIF
486
<p>Return true on success or false if allocation failed.</p>
489
<func><name><ret>ErlNifEnv*</ret><nametext>enif_alloc_env()</nametext></name>
490
<fsummary>Create a new environment</fsummary>
491
<desc><p>Allocate a new process independent environment. The environment can
492
be used to hold terms that is not bound to any process. Such terms can
493
later be copied to a process environment with
494
<seealso marker="#enif_make_copy">enif_make_copy</seealso>
495
or be sent to a process as a message with <seealso marker="#enif_send">enif_send</seealso>.</p>
496
<p>Return pointer to the new environment.</p>
499
<func><name><ret>void*</ret><nametext>enif_alloc_resource(ErlNifResourceType* type, unsigned size)</nametext></name>
500
<fsummary>Allocate a memory managed resource object</fsummary>
501
<desc><p>Allocate a memory managed resource object of type <c>type</c> and size <c>size</c> bytes.</p></desc>
503
<func><name><ret>void</ret><nametext>enif_clear_env(ErlNifEnv* env)</nametext></name>
504
<fsummary>Clear an environment for reuse.</fsummary>
505
<desc><p>Free all terms in an environment and clear it for reuse. The environment must
506
have been allocated with <seealso marker="#enif_alloc_env">enif_alloc_env</seealso>.
509
<func><name><ret>int</ret><nametext>enif_compare(ERL_NIF_TERM lhs, ERL_NIF_TERM rhs)</nametext></name>
510
<fsummary>Compare two terms</fsummary>
511
<desc><p>Return an integer less than, equal to, or greater than
512
zero if <c>lhs</c> is found, respectively, to be less than,
513
equal, or greater than <c>rhs</c>. Corresponds to the Erlang
514
operators <c>==</c>, <c>/=</c>, <c>=<</c>, <c><</c>,
515
<c>>=</c> and <c>></c> (but <em>not</em> <c>=:=</c> or <c>=/=</c>).</p></desc>
517
<func><name><ret>void</ret><nametext>enif_cond_broadcast(ErlNifCond *cnd)</nametext></name>
518
<fsummary></fsummary>
519
<desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_broadcast">erl_drv_cond_broadcast</seealso>.
522
<func><name><ret>ErlNifCond*</ret><nametext>enif_cond_create(char *name)</nametext></name>
523
<fsummary></fsummary>
524
<desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_create">erl_drv_cond_create</seealso>.
527
<func><name><ret>void</ret><nametext>enif_cond_destroy(ErlNifCond *cnd)</nametext></name>
528
<fsummary></fsummary>
529
<desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_destroy">erl_drv_cond_destroy</seealso>.
532
<func><name><ret>void</ret><nametext>enif_cond_signal(ErlNifCond *cnd)</nametext></name>
533
<fsummary></fsummary>
534
<desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_signal">erl_drv_cond_signal</seealso>.
537
<func><name><ret>void</ret><nametext>enif_cond_wait(ErlNifCond *cnd, ErlNifMutex *mtx)</nametext></name>
538
<fsummary></fsummary>
539
<desc><p>Same as <seealso marker="erl_driver#erl_drv_cond_wait">erl_drv_cond_wait</seealso>.
542
<func><name><ret>int</ret><nametext>enif_equal_tids(ErlNifTid tid1, ErlNifTid tid2)</nametext></name>
543
<fsummary></fsummary>
544
<desc><p>Same as <seealso marker="erl_driver#erl_drv_equal_tids">erl_drv_equal_tids</seealso>.
547
<func><name><ret>void</ret><nametext>enif_free(void* ptr)</nametext></name>
261
548
<fsummary>Free dynamic memory</fsummary>
262
549
<desc><p>Free memory allocated by <c>enif_alloc</c>.</p></desc>
264
<func><name><ret>int</ret><nametext>enif_is_binary(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name>
265
<fsummary>Determine if a term is a binary</fsummary>
266
<desc><p>Return true if <c>term</c> is a binary</p></desc>
268
<func><name><ret>int</ret><nametext>enif_inspect_binary(ErlNifEnv* env, ERL_NIF_TERM bin_term, ErlNifBinary* bin)</nametext></name>
269
<fsummary>Inspect the content of a binary</fsummary>
270
<desc><p>Initialize the structure pointed to by <c>bin</c> with
271
transient information about the binary term
272
<c>bin_term</c>. Return false if <c>bin_term</c> is not a binary.</p></desc>
274
<func><name><ret>int</ret><nametext>enif_alloc_binary(ErlNifEnv* env, unsigned size, ErlNifBinary* bin)</nametext></name>
275
<fsummary>Create a new binary.</fsummary>
276
<desc><p>Allocate a new binary of size of <c>size</c>
277
bytes. Initialize the structure pointed to by <c>bin</c> to
278
refer to the allocated binary.</p></desc>
280
<func><name><ret>void</ret><nametext>enif_release_binary(ErlNifEnv* env, ErlNifBinary* bin)</nametext></name>
281
<fsummary>Release a binary.</fsummary>
282
<desc><p>Release a binary obtained from <c>enif_alloc_binary</c> or <c>enif_inspect_binary</c>.</p></desc>
551
<func><name><ret>void</ret><nametext>enif_free_env(ErlNifEnv* env)</nametext></name>
552
<fsummary>Free an environment allocated with enif_alloc_env</fsummary>
553
<desc><p>Free an environment allocated with <seealso marker="#enif_alloc_env">enif_alloc_env</seealso>.
554
All terms created in the environment will be freed as well.</p></desc>
556
<func><name><ret>int</ret><nametext>enif_get_atom(ErlNifEnv* env, ERL_NIF_TERM term, char* buf, unsigned size, ErlNifCharEncoding encode)</nametext></name>
557
<fsummary>Get the text representation of an atom term</fsummary>
558
<desc><p>Write a null-terminated string, in the buffer pointed to by
559
<c>buf</c> of size <c>size</c>, consisting of the string
560
representation of the atom <c>term</c> with encoding
561
<seealso marker="#ErlNifCharEncoding">encode</seealso>. Return
562
the number of bytes written (including terminating null character) or 0 if
563
<c>term</c> is not an atom with maximum length of
564
<c>size-1</c>.</p></desc>
566
<func><name><ret>int</ret><nametext>enif_get_atom_length(ErlNifEnv* env, ERL_NIF_TERM term, unsigned* len, ErlNifCharEncoding encode)</nametext></name>
567
<fsummary>Get the length of atom <c>term</c>.</fsummary>
568
<desc><p>Set <c>*len</c> to the length (number of bytes excluding
569
terminating null character) of the atom <c>term</c> with encoding
570
<c>encode</c>. Return true on success or false if <c>term</c> is not an
573
<func><name><ret>int</ret><nametext>enif_get_double(ErlNifEnv* env, ERL_NIF_TERM term, double* dp)</nametext></name>
574
<fsummary>Read a floating-point number term.</fsummary>
575
<desc><p>Set <c>*dp</c> to the floating point value of
576
<c>term</c>. Return true on success or false if <c>term</c> is not a float.</p></desc>
284
578
<func><name><ret>int</ret><nametext>enif_get_int(ErlNifEnv* env, ERL_NIF_TERM term, int* ip)</nametext></name>
285
<fsummary>Read an integer term.</fsummary>
286
<desc><p>Set <c>*ip</c> to the integer value of
287
<c>term</c> or return false if <c>term</c> is not an integer or is
288
outside the bounds of type <c>int</c></p></desc>
290
<func><name><ret>int</ret><nametext>enif_get_ulong(ErlNifEnv* env, ERL_NIF_TERM term, unsigned long* ip)</nametext></name>
291
<fsummary>Read an unsigned long integer</fsummary>
292
<desc><p>Set <c>*ip</c> to the unsigned long integer value of
293
<c>term</c> or return false if <c>term</c> is not an unsigned
294
integer or is outside the bounds of type <c>unsigned long</c></p></desc>
579
<fsummary>Read an integer term</fsummary>
580
<desc><p>Set <c>*ip</c> to the integer value of
581
<c>term</c>. Return true on success or false if <c>term</c> is not an
582
integer or is outside the bounds of type <c>int</c>.</p></desc>
584
<func><name><ret>int</ret><nametext>enif_get_int64(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifSInt64* ip)</nametext></name>
585
<fsummary>Read a 64-bit integer term</fsummary>
586
<desc><p>Set <c>*ip</c> to the integer value of
587
<c>term</c>. Return true on success or false if <c>term</c> is not an
588
integer or is outside the bounds of a signed 64-bit integer.</p></desc>
590
<func><name><ret>int</ret><nametext>enif_get_local_pid(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifPid* pid)</nametext></name>
591
<fsummary>Read an local pid term</fsummary>
592
<desc><p>If <c>term</c> is the pid of a node local process, initialize the
593
pid variable <c>*pid</c> from it and return true. Otherwise return false.
594
No check if the process is alive is done.</p></desc>
296
596
<func><name><ret>int</ret><nametext>enif_get_list_cell(ErlNifEnv* env, ERL_NIF_TERM list, ERL_NIF_TERM* head, ERL_NIF_TERM* tail)</nametext></name>
297
597
<fsummary>Get head and tail from a list</fsummary>
298
598
<desc><p>Set <c>*head</c> and <c>*tail</c> from
299
<c>list</c> or return false if <c>list</c> is not a non-empty
302
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_binary(ErlNifEnv* env, ErlNifBinary* bin)</nametext></name>
303
<fsummary>Make a binary term.</fsummary>
304
<desc><p>Make a binary term from <c>bin</c>. Will also release
305
the binary.</p></desc>
599
<c>list</c> and return true, or return false if <c>list</c> is not a
600
non-empty list.</p></desc>
602
<func><name><ret>int</ret><nametext>enif_get_list_length(ErlNifEnv* env, ERL_NIF_TERM term, unsigned* len)</nametext></name>
603
<fsummary>Get the length of list <c>term</c>.</fsummary>
604
<desc><p>Set <c>*len</c> to the length of list <c>term</c> and return true,
605
or return false if <c>term</c> is not a list.</p></desc>
607
<func><name><ret>int</ret><nametext>enif_get_long(ErlNifEnv* env, ERL_NIF_TERM term, long int* ip)</nametext></name>
608
<fsummary>Read an long integer term.</fsummary>
609
<desc><p>Set <c>*ip</c> to the long integer value of <c>term</c> and
610
return true, or return false if <c>term</c> is not an integer or is
611
outside the bounds of type <c>long int</c>.</p></desc>
613
<func><name><ret>int</ret><nametext>enif_get_resource(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifResourceType* type, void** objp)</nametext></name>
614
<fsummary>Get the pointer to a resource object</fsummary>
615
<desc><p>Set <c>*objp</c> to point to the resource object referred to by <c>term</c>.</p>
616
<p>Return true on success or false if <c>term</c> is not a handle to a resource object
617
of type <c>type</c>.</p></desc>
619
<func><name><ret>int</ret><nametext>enif_get_string(ErlNifEnv* env,
620
ERL_NIF_TERM list, char* buf, unsigned size,
621
ErlNifCharEncoding encode)</nametext></name>
622
<fsummary>Get a C-string from a list.</fsummary>
623
<desc><p>Write a null-terminated string, in the buffer pointed to by
624
<c>buf</c> with size <c>size</c>, consisting of the characters
625
in the string <c>list</c>. The characters are written using encoding
626
<seealso marker="#ErlNifCharEncoding">encode</seealso>.
627
Return the number of bytes written (including terminating null
628
character), or <c>-size</c> if the string was truncated due to
629
buffer space, or 0 if <c>list</c> is not a string that can be
630
encoded with <c>encode</c> or if <c>size</c> was less than 1.
631
The written string is always null-terminated unless buffer
632
<c>size</c> is less than 1.</p></desc>
634
<func><name><ret>int</ret><nametext>enif_get_tuple(ErlNifEnv* env, ERL_NIF_TERM term, int* arity, const ERL_NIF_TERM** array)</nametext></name>
635
<fsummary>Inspect the elements of a tuple.</fsummary>
636
<desc><p>If <c>term</c> is a tuple, set <c>*array</c> to point
637
to an array containing the elements of the tuple and set
638
<c>*arity</c> to the number of elements. Note that the array
639
is read-only and <c>(*array)[N-1]</c> will be the Nth element of
640
the tuple. <c>*array</c> is undefined if the arity of the tuple
641
is zero.</p><p>Return true on success or false if <c>term</c> is not a
644
<func><name><ret>int</ret><nametext>enif_get_uint(ErlNifEnv* env, ERL_NIF_TERM term, unsigned int* ip)</nametext></name>
645
<fsummary>Read an unsigned integer term.</fsummary>
646
<desc><p>Set <c>*ip</c> to the unsigned integer value of <c>term</c> and
647
return true, or return false if <c>term</c> is not an unsigned integer or
648
is outside the bounds of type <c>unsigned int</c>.</p></desc>
650
<func><name><ret>int</ret><nametext>enif_get_uint64(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifUInt64* ip)</nametext></name>
651
<fsummary>Read an unsigned 64-bit integer term.</fsummary>
652
<desc><p>Set <c>*ip</c> to the unsigned integer value of <c>term</c> and
653
return true, or return false if <c>term</c> is not an unsigned integer or
654
is outside the bounds of an unsigned 64-bit integer.</p></desc>
656
<func><name><ret>int</ret><nametext>enif_get_ulong(ErlNifEnv* env, ERL_NIF_TERM term, unsigned long* ip)</nametext></name>
657
<fsummary>Read an unsigned integer term.</fsummary>
658
<desc><p>Set <c>*ip</c> to the unsigned long integer value of <c>term</c>
659
and return true, or return false if <c>term</c> is not an unsigned integer or is
660
outside the bounds of type <c>unsigned long</c>.</p></desc>
662
<func><name><ret>int</ret><nametext>enif_inspect_binary(ErlNifEnv* env, ERL_NIF_TERM bin_term, ErlNifBinary* bin)</nametext></name>
663
<fsummary>Inspect the content of a binary</fsummary>
664
<desc><p>Initialize the structure pointed to by <c>bin</c> with
665
information about the binary term
666
<c>bin_term</c>. Return true on success or false if <c>bin_term</c> is not a binary.</p></desc>
668
<func><name><ret>int</ret><nametext>enif_inspect_iolist_as_binary(ErlNifEnv*
669
env, ERL_NIF_TERM term, ErlNifBinary* bin)
671
<fsummary>Inspect the content of an iolist</fsummary>
672
<desc><p>Initialize the structure pointed to by <c>bin</c> with one
673
continuous buffer with the same byte content as <c>iolist</c>. As with
674
inspect_binary, the data pointed to by <c>bin</c> is transient and does
675
not need to be released. Return true on success or false if <c>iolist</c> is not an
679
<func><name><ret>int</ret><nametext>enif_is_atom(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name>
680
<fsummary>Determine if a term is an atom</fsummary>
681
<desc><p>Return true if <c>term</c> is an atom.</p></desc>
683
<func><name><ret>int</ret><nametext>enif_is_binary(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name>
684
<fsummary>Determine if a term is a binary</fsummary>
685
<desc><p>Return true if <c>term</c> is a binary</p></desc>
687
<func><name><ret>int</ret><nametext>enif_is_empty_list(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name>
688
<fsummary>Determine if a term is an empty list</fsummary>
689
<desc><p>Return true if <c>term</c> is an empty list.</p></desc>
691
<func><name><ret>int</ret><nametext>enif_is_fun(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name>
692
<fsummary>Determine if a term is a fun</fsummary>
693
<desc><p>Return true if <c>term</c> is a fun.</p></desc>
695
<func><name><ret>int</ret><nametext>enif_is_identical(ERL_NIF_TERM lhs, ERL_NIF_TERM rhs)</nametext></name>
696
<fsummary>Erlang operator =:=</fsummary>
697
<desc><p>Return true if the two terms are identical. Corresponds to the
698
Erlang operators <c>=:=</c> and
699
<c>=/=</c>.</p></desc>
701
<func><name><ret>int</ret><nametext>enif_is_pid(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name>
702
<fsummary>Determine if a term is a pid</fsummary>
703
<desc><p>Return true if <c>term</c> is a pid.</p></desc>
705
<func><name><ret>int</ret><nametext>enif_is_port(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name>
706
<fsummary>Determine if a term is a port</fsummary>
707
<desc><p>Return true if <c>term</c> is a port.</p></desc>
709
<func><name><ret>int</ret><nametext>enif_is_ref(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name>
710
<fsummary>Determine if a term is a reference</fsummary>
711
<desc><p>Return true if <c>term</c> is a reference.</p></desc>
713
<func><name><ret>int</ret><nametext>enif_is_tuple(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name>
714
<fsummary>Determine if a term is a tuple</fsummary>
715
<desc><p>Return true if <c>term</c> is a tuple.</p></desc>
717
<func><name><ret>int</ret><nametext>enif_is_list(ErlNifEnv* env, ERL_NIF_TERM term)</nametext></name>
718
<fsummary>Determine if a term is a list</fsummary>
719
<desc><p>Return true if <c>term</c> is a list.</p></desc>
721
<func><name><ret>int</ret><nametext>enif_keep_resource(void* obj)</nametext></name>
722
<fsummary>Add a reference to a resource object</fsummary>
723
<desc><p>Add a reference to resource object <c>obj</c> obtained from
724
<seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>.
725
Each call to <c>enif_keep_resource</c> for an object must be balanced by
726
a call to <seealso marker="#enif_release_resource">enif_release_resource</seealso>
727
before the object will be destructed.</p></desc>
729
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_atom(ErlNifEnv* env, const char* name)</nametext></name>
730
<fsummary>Create an atom term</fsummary>
731
<desc><p>Create an atom term from the null-terminated C-string <c>name</c>
732
with iso-latin-1 encoding.</p></desc>
734
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_atom_len(ErlNifEnv* env, const char* name, size_t len)</nametext></name>
735
<fsummary>Create an atom term</fsummary>
736
<desc><p>Create an atom term from the string <c>name</c> with length <c>len</c>.
737
Null-characters are treated as any other characters.</p></desc>
307
739
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_badarg(ErlNifEnv* env)</nametext></name>
308
740
<fsummary>Make a badarg exception.</fsummary>
309
741
<desc><p>Make a badarg exception to be returned from a NIF.</p></desc>
743
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_binary(ErlNifEnv* env, ErlNifBinary* bin)</nametext></name>
744
<fsummary>Make a binary term.</fsummary>
745
<desc><p>Make a binary term from <c>bin</c>. Any ownership of
746
the binary data will be transferred to the created term and
747
<c>bin</c> should be considered read-only for the rest of the NIF
748
call and then as released.</p></desc>
750
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_copy(ErlNifEnv* dst_env, ERL_NIF_TERM src_term)</nametext></name>
751
<fsummary>Make a copy of a term.</fsummary>
752
<desc><p>Make a copy of term <c>src_term</c>. The copy will be created in
753
environment <c>dst_env</c>. The source term may be located in any
754
environment.</p></desc>
756
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_double(ErlNifEnv* env, double d)</nametext></name>
757
<fsummary>Create a floating-point term</fsummary>
758
<desc><p>Create a floating-point term from a <c>double</c>.</p></desc>
760
<func><name><ret>int</ret><nametext>enif_make_existing_atom(ErlNifEnv* env, const char* name, ERL_NIF_TERM* atom, ErlNifCharEncoding encode)</nametext></name>
761
<fsummary>Create an existing atom term</fsummary>
762
<desc><p>Try to create the term of an already existing atom from
763
the null-terminated C-string <c>name</c> with encoding
764
<seealso marker="#ErlNifCharEncoding">encode</seealso>. If the atom
765
already exists store the term in <c>*atom</c> and return true, otherwise
766
return false.</p></desc>
768
<func><name><ret>int</ret><nametext>enif_make_existing_atom_len(ErlNifEnv* env, const char* name, size_t len, ERL_NIF_TERM* atom, ErlNifCharEncoding encoding)</nametext></name>
769
<fsummary>Create an existing atom term</fsummary>
770
<desc><p>Try to create the term of an already existing atom from the
771
string <c>name</c> with length <c>len</c> and encoding
772
<seealso marker="#ErlNifCharEncoding">encode</seealso>. Null-characters
773
are treated as any other characters. If the atom already exists store the term
774
in <c>*atom</c> and return true, otherwise return false.</p></desc>
311
776
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_int(ErlNifEnv* env, int i)</nametext></name>
312
777
<fsummary>Create an integer term</fsummary>
313
778
<desc><p>Create an integer term.</p></desc>
315
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_ulong(ErlNifEnv* env, unsigned long i)</nametext></name>
316
<fsummary>Create an integer term from an unsigned long int</fsummary>
317
<desc><p>Create an integer term from an <c>unsigned long int</c>.</p></desc>
319
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_atom(ErlNifEnv* env, const char* name)</nametext></name>
320
<fsummary>Create an atom term</fsummary>
321
<desc><p>Create an atom term from the C-string <c>name</c>. Atom
322
terms may be saved and used between NIF calls.</p></desc>
324
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple(ErlNifEnv* env, unsigned cnt, ...)</nametext></name>
325
<fsummary>Create a tuple term.</fsummary>
326
<desc><p>Create a tuple term of arity <c>cnt</c>. Expects
327
<c>cnt</c> number of arguments (after <c>cnt</c>) of type ERL_NIF_TERM as the
328
elements of the tuple.</p></desc>
780
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_int64(ErlNifEnv* env, ErlNifSInt64 i)</nametext></name>
781
<fsummary>Create an integer term</fsummary>
782
<desc><p>Create an integer term from a signed 64-bit integer.</p></desc>
330
784
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list(ErlNifEnv* env, unsigned cnt, ...)</nametext></name>
331
785
<fsummary>Create a list term.</fsummary>
333
787
<c>cnt</c> number of arguments (after <c>cnt</c>) of type ERL_NIF_TERM as the
334
788
elements of the list. An empty list is returned if <c>cnt</c> is 0.</p></desc>
790
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list1(ErlNifEnv* env, ERL_NIF_TERM e1)</nametext></name>
791
<name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list2(ErlNifEnv* env, ERL_NIF_TERM e1, ERL_NIF_TERM e2)</nametext></name>
792
<name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list3(ErlNifEnv* env, ERL_NIF_TERM e1, ERL_NIF_TERM e2, ERL_NIF_TERM e3)</nametext></name>
793
<name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list4(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e4)</nametext></name>
794
<name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list5(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e5)</nametext></name>
795
<name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list6(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e6)</nametext></name>
796
<name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list7(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e7)</nametext></name>
797
<name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list8(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e8)</nametext></name>
798
<name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list9(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e9)</nametext></name>
799
<fsummary>Create a list term.</fsummary>
800
<desc><p>Create an ordinary list term with length indicated by the
801
function name. Prefer these functions (macros) over the variadic
802
<c>enif_make_list</c> to get a compile time error if the number of
803
arguments does not match.</p></desc>
336
805
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list_cell(ErlNifEnv* env, ERL_NIF_TERM head, ERL_NIF_TERM tail)</nametext></name>
337
806
<fsummary>Create a list cell.</fsummary>
338
807
<desc><p>Create a list cell <c>[head | tail]</c>.</p></desc>
340
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_string(ErlNifEnv* env, const char* string)</nametext></name>
341
<fsummary>Create a string.</fsummary>
342
<desc><p>Creates a list containing the characters of the
343
C-string <c>string</c>.</p></desc>
809
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_list_from_array(ErlNifEnv* env, const ERL_NIF_TERM arr[], unsigned cnt)</nametext></name>
810
<fsummary>Create a list term from an array.</fsummary>
811
<desc><p>Create an ordinary list containing the elements of array <c>arr</c>
812
of length <c>cnt</c>. An empty list is returned if <c>cnt</c> is 0.</p></desc>
814
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_long(ErlNifEnv* env, long int i)</nametext></name>
815
<fsummary>Create an integer term from a long int</fsummary>
816
<desc><p>Create an integer term from a <c>long int</c>.</p></desc>
818
<func><name><ret>unsigned char*</ret><nametext>enif_make_new_binary(ErlNifEnv* env, size_t size, ERL_NIF_TERM* termp)</nametext></name>
819
<fsummary>Allocate and create a new binary term</fsummary>
820
<desc><p>Allocate a binary of size <c>size</c> bytes and create an owning
821
term. The binary data is mutable until the calling NIF returns. This is a
822
quick way to create a new binary without having to use
823
<seealso marker="#ErlNifBinary">ErlNifBinary</seealso>. The drawbacks are
824
that the binary can not be kept between NIF calls and it can not be
825
reallocated.</p><p>Return a pointer to the raw binary data and set
826
<c>*termp</c> to the binary term.</p></desc>
828
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_pid(ErlNifEnv* env, const ErlNifPid* pid)</nametext></name>
829
<fsummary>Make a pid term</fsummary>
830
<desc><p>Make a pid term from <c>*pid</c>.</p></desc>
832
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_ref(ErlNifEnv* env)</nametext></name>
833
<fsummary>Create a reference.</fsummary>
834
<desc><p>Create a reference like <seealso marker="erlang#make_ref-0">erlang:make_ref/0</seealso>.</p></desc>
836
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_resource(ErlNifEnv* env, void* obj)</nametext></name>
837
<fsummary>Create an opaque handle to a resource object</fsummary>
838
<desc><p>Create an opaque handle to a memory managed resource object
839
obtained by <seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>.
840
No ownership transfer is done, as the resource object still needs to be released by
841
<seealso marker="#enif_release_resource">enif_release_resource</seealso>,
842
but note that the call to <c>enif_release_resource</c> can occur
843
immediately after obtaining the term from <c>enif_make_resource</c>,
844
in which case the resource object will be deallocated when the
845
term is garbage collected. See the
846
<seealso marker="#enif_resource_example">example of creating and
847
returning a resource object</seealso> for more details.</p>
848
<p>Note that the only defined behaviour of using a resource term in
849
an Erlang program is to store it and send it between processes on the
850
same node. Other operations such as matching or <c>term_to_binary</c>
851
will have unpredictable (but harmless) results.</p></desc>
853
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_resource_binary(ErlNifEnv* env, void* obj, const void* data, size_t size)</nametext></name>
854
<fsummary>Create a custom binary term</fsummary>
855
<desc><p>Create a binary term that is memory managed by a resource object
856
<c>obj</c> obtained by <seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>.
857
The returned binary term will consist of <c>size</c> bytes pointed to
858
by <c>data</c>. This raw binary data must be kept readable and unchanged
859
until the destructor of the resource is called. The binary data may be
860
stored external to the resource object in which case it is the responsibility
861
of the destructor to release the data.</p>
862
<p>Several binary terms may be managed by the same resource object. The
863
destructor will not be called until the last binary is garbage collected.
864
This can be useful as a way to return different parts of a larger binary
866
<p>As with <seealso marker="#enif_make_resource">enif_make_resource</seealso>,
867
no ownership transfer is done. The resource still needs to be released with
868
<seealso marker="#enif_release_resource">enif_release_resource</seealso>.</p>
871
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_string(ErlNifEnv* env, const char* string, ErlNifCharEncoding encoding)</nametext></name>
872
<fsummary>Create a string.</fsummary>
873
<desc><p>Create a list containing the characters of the
874
null-terminated string <c>string</c> with encoding <seealso marker="#ErlNifCharEncoding">encoding</seealso>.</p></desc>
876
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_string_len(ErlNifEnv* env, const char* string, size_t len, ErlNifCharEncoding encoding)</nametext></name>
877
<fsummary>Create a string.</fsummary>
878
<desc><p>Create a list containing the characters of the string <c>string</c> with
879
length <c>len</c> and encoding <seealso marker="#ErlNifCharEncoding">encoding</seealso>.
880
Null-characters are treated as any other characters.</p></desc>
882
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_sub_binary(ErlNifEnv*
883
env, ERL_NIF_TERM bin_term, size_t pos, size_t size)</nametext></name>
884
<fsummary>Make a subbinary term.</fsummary>
885
<desc><p>Make a subbinary of binary <c>bin_term</c>, starting at
886
zero-based position <c>pos</c> with a length of <c>size</c> bytes.
887
<c>bin_term</c> must be a binary or bitstring and
888
<c>pos+size</c> must be less or equal to the number of whole
889
bytes in <c>bin_term</c>.</p></desc>
891
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple(ErlNifEnv* env, unsigned cnt, ...)</nametext></name>
892
<fsummary>Create a tuple term.</fsummary>
893
<desc><p>Create a tuple term of arity <c>cnt</c>. Expects
894
<c>cnt</c> number of arguments (after <c>cnt</c>) of type ERL_NIF_TERM as the
895
elements of the tuple.</p></desc>
897
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple1(ErlNifEnv* env, ERL_NIF_TERM e1)</nametext></name>
898
<name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple2(ErlNifEnv* env, ERL_NIF_TERM e1, ERL_NIF_TERM e2)</nametext></name>
899
<name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple3(ErlNifEnv* env, ERL_NIF_TERM e1, ERL_NIF_TERM e2, ERL_NIF_TERM e3)</nametext></name>
900
<name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple4(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e4)</nametext></name>
901
<name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple5(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e5)</nametext></name>
902
<name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple6(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e6)</nametext></name>
903
<name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple7(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e7)</nametext></name>
904
<name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple8(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e8)</nametext></name>
905
<name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple9(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e9)</nametext></name>
906
<fsummary>Create a tuple term.</fsummary>
907
<desc><p>Create a tuple term with length indicated by the
908
function name. Prefer these functions (macros) over the variadic
909
<c>enif_make_tuple</c> to get a compile time error if the number of
910
arguments does not match.</p></desc>
912
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_tuple_from_array(ErlNifEnv* env, const ERL_NIF_TERM arr[], unsigned cnt)</nametext></name>
913
<fsummary>Create a tuple term from an array.</fsummary>
914
<desc><p>Create a tuple containing the elements of array <c>arr</c>
915
of length <c>cnt</c>.</p></desc>
917
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_uint(ErlNifEnv* env, unsigned int i)</nametext></name>
918
<fsummary>Create an unsigned integer term</fsummary>
919
<desc><p>Create an integer term from an <c>unsigned int</c>.</p></desc>
921
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_uint64(ErlNifEnv* env, ErlNifUInt64 i)</nametext></name>
922
<fsummary>Create an unsigned integer term</fsummary>
923
<desc><p>Create an integer term from an unsigned 64-bit integer.</p></desc>
925
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_ulong(ErlNifEnv* env, unsigned long i)</nametext></name>
926
<fsummary>Create an integer term from an unsigned long int</fsummary>
927
<desc><p>Create an integer term from an <c>unsigned long int</c>.</p></desc>
929
<func><name><ret>ErlNifMutex*</ret><nametext>enif_mutex_create(char *name)</nametext></name>
930
<fsummary></fsummary>
931
<desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_create">erl_drv_mutex_create</seealso>.
934
<func><name><ret>void</ret><nametext>enif_mutex_destroy(ErlNifMutex *mtx)</nametext></name>
935
<fsummary></fsummary>
936
<desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_destroy">erl_drv_mutex_destroy</seealso>.
939
<func><name><ret>void</ret><nametext>enif_mutex_lock(ErlNifMutex *mtx)</nametext></name>
940
<fsummary></fsummary>
941
<desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_lock">erl_drv_mutex_lock</seealso>.
944
<func><name><ret>int</ret><nametext>enif_mutex_trylock(ErlNifMutex *mtx)</nametext></name>
945
<fsummary></fsummary>
946
<desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_trylock">erl_drv_mutex_trylock</seealso>.
949
<func><name><ret>void</ret><nametext>enif_mutex_unlock(ErlNifMutex *mtx)</nametext></name>
950
<fsummary></fsummary>
951
<desc><p>Same as <seealso marker="erl_driver#erl_drv_mutex_unlock">erl_drv_mutex_unlock</seealso>.
954
<func><name><ret>ErlNifResourceType*</ret><nametext>enif_open_resource_type(ErlNifEnv* env,
955
const char* module_str, const char* name,
956
ErlNifResourceDtor* dtor, ErlNifResourceFlags flags, ErlNifResourceFlags* tried)</nametext></name>
957
<fsummary>Create or takeover a resource type</fsummary>
958
<desc><p>Create or takeover a resource type identified by the string
959
<c>name</c> and give it the destructor function pointed to by <seealso marker="#ErlNifResourceDtor">dtor</seealso>.
960
Argument <c>flags</c> can have the following values:</p>
962
<tag><c>ERL_NIF_RT_CREATE</c></tag>
963
<item>Create a new resource type that does not already exist.</item>
964
<tag><c>ERL_NIF_RT_TAKEOVER</c></tag>
965
<item>Open an existing resource type and take over ownership of all its instances.
966
The supplied destructor <c>dtor</c> will be called both for existing instances
967
as well as new instances not yet created by the calling NIF library.</item>
969
<p>The two flag values can be combined with bitwise-or. The name of the
970
resource type is local to the calling module. Argument <c>module_str</c>
971
is not (yet) used and must be NULL. The <c>dtor</c> may be <c>NULL</c>
972
in case no destructor is needed.</p>
973
<p>On success, return a pointer to the resource type and <c>*tried</c>
974
will be set to either <c>ERL_NIF_RT_CREATE</c> or
975
<c>ERL_NIF_RT_TAKEOVER</c> to indicate what was actually done.
976
On failure, return <c>NULL</c> and set <c>*tried</c> to <c>flags</c>.
977
It is allowed to set <c>tried</c> to <c>NULL</c>.</p>
978
<p>Note that <c>enif_open_resource_type</c> is only allowed to be called in the three callbacks
979
<seealso marker="#load">load</seealso>, <seealso marker="#reload">reload</seealso>
980
and <seealso marker="#upgrade">upgrade</seealso>.</p>
983
<func><name><ret>void*</ret><nametext>enif_priv_data(ErlNifEnv* env)</nametext></name>
984
<fsummary>Get the private data of a NIF library</fsummary>
985
<desc><p>Return the pointer to the private data that was set by <c>load</c>,
986
<c>reload</c> or <c>upgrade</c>.</p>
987
<p>Was previously named <c>enif_get_data</c>.</p></desc>
989
<func><name><ret>int</ret><nametext>enif_realloc_binary(ErlNifBinary* bin, size_t size)</nametext></name>
990
<fsummary>Change the size of a binary.</fsummary>
991
<desc><p>Change the size of a binary <c>bin</c>. The source binary
992
may be read-only, in which case it will be left untouched and
993
a mutable copy is allocated and assigned to <c>*bin</c>. Return true on success,
994
false if memory allocation failed.</p></desc>
996
<func><name><ret>void</ret><nametext>enif_release_binary(ErlNifBinary* bin)</nametext></name>
997
<fsummary>Release a binary.</fsummary>
998
<desc><p>Release a binary obtained from <c>enif_alloc_binary</c>.</p></desc>
1000
<func><name><ret>void</ret><nametext>enif_release_resource(void* obj)</nametext></name>
1001
<fsummary>Release a resource object.</fsummary>
1002
<desc><p>Remove a reference to resource object <c>obj</c>obtained from
1003
<seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>.
1004
The resource object will be destructed when the last reference is removed.
1005
Each call to <c>enif_release_resource</c> must correspond to a previous
1006
call to <c>enif_alloc_resource</c> or
1007
<seealso marker="#enif_keep_resource">enif_keep_resource</seealso>.
1008
References made by <seealso marker="#enif_make_resource">enif_make_resource</seealso>
1009
can only be removed by the garbage collector.</p></desc>
1011
<func><name><ret>ErlNifRWLock*</ret><nametext>enif_rwlock_create(char *name)</nametext></name>
1012
<fsummary></fsummary>
1013
<desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_create">erl_drv_rwlock_create</seealso>.
1016
<func><name><ret>void</ret><nametext>enif_rwlock_destroy(ErlNifRWLock *rwlck)</nametext></name>
1017
<fsummary></fsummary>
1018
<desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_destroy">erl_drv_rwlock_destroy</seealso>.
1021
<func><name><ret>void</ret><nametext>enif_rwlock_rlock(ErlNifRWLock *rwlck)</nametext></name>
1022
<fsummary></fsummary>
1023
<desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_rlock">erl_drv_rwlock_rlock</seealso>.
1026
<func><name><ret>void</ret><nametext>enif_rwlock_runlock(ErlNifRWLock *rwlck)</nametext></name>
1027
<fsummary></fsummary>
1028
<desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_runlock">erl_drv_rwlock_runlock</seealso>.
1031
<func><name><ret>void</ret><nametext>enif_rwlock_rwlock(ErlNifRWLock *rwlck)</nametext></name>
1032
<fsummary></fsummary>
1033
<desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_rwlock">erl_drv_rwlock_rwlock</seealso>.
1036
<func><name><ret>void</ret><nametext>enif_rwlock_rwunlock(ErlNifRWLock *rwlck)</nametext></name>
1037
<fsummary></fsummary>
1038
<desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_rwunlock">erl_drv_rwlock_rwunlock</seealso>.
1041
<func><name><ret>int</ret><nametext>enif_rwlock_tryrlock(ErlNifRWLock *rwlck)</nametext></name>
1042
<fsummary></fsummary>
1043
<desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_tryrlock">erl_drv_rwlock_tryrlock</seealso>.
1046
<func><name><ret>int</ret><nametext>enif_rwlock_tryrwlock(ErlNifRWLock *rwlck)</nametext></name>
1047
<fsummary></fsummary>
1048
<desc><p>Same as <seealso marker="erl_driver#erl_drv_rwlock_tryrwlock">erl_drv_rwlock_tryrwlock</seealso>.
1051
<func><name><ret>ErlNifPid*</ret><nametext>enif_self(ErlNifEnv* caller_env, ErlNifPid* pid)</nametext></name>
1052
<fsummary>Get the pid of the calling process.</fsummary>
1053
<desc><p>Initialize the pid variable <c>*pid</c> to represent the
1054
calling process. Return <c>pid</c>.</p></desc>
1056
<func><name><ret>int</ret><nametext>enif_send(ErlNifEnv* env, ErlNifPid* to_pid, ErlNifEnv* msg_env, ERL_NIF_TERM msg)</nametext></name>
1057
<fsummary>Send a message to a process.</fsummary>
1058
<desc><p>Send a message to a process.</p>
1060
<tag><c>env</c></tag>
1061
<item>The environment of the calling process. Must be NULL if and
1062
only if calling from a created thread.</item>
1063
<tag><c>*to_pid</c></tag>
1064
<item>The pid of the receiving process. The pid should refer to a process on the local node.</item>
1065
<tag><c>msg_env</c></tag>
1066
<item>The environment of the message term. Must be a process
1067
independent environment allocated with
1068
<seealso marker="#enif_alloc_env">enif_alloc_env</seealso>.</item>
1069
<tag><c>msg</c></tag>
1070
<item>The message term to send.</item>
1072
<p>Return true on success, or false if <c>*to_pid</c> does not refer to an alive local process.</p>
1073
<p>The message environment <c>msg_env</c> with all its terms (including
1074
<c>msg</c>) will be invalidated by a successful call to <c>enif_send</c>. The environment
1075
should either be freed with <seealso marker="#enif_free_env">enif_free_env</seealso>
1076
of cleared for reuse with <seealso marker="#enif_clear_env">enif_clear_env</seealso>.</p>
1077
<p>This function is only thread-safe when the emulator with SMP support is used.
1078
It can only be used in a non-SMP emulator from a NIF-calling thread.</p>
1081
<func><name><ret>unsigned</ret><nametext>enif_sizeof_resource(void* obj)</nametext></name>
1082
<fsummary>Get the byte size of a resource object</fsummary>
1083
<desc><p>Get the byte size of a resource object <c>obj</c> obtained by
1084
<seealso marker="#enif_alloc_resource">enif_alloc_resource</seealso>.</p></desc>
1087
<name><ret>void</ret><nametext>enif_system_info(ErlNifSysInfo *sys_info_ptr, size_t size)</nametext></name>
1088
<fsummary>Get information about the Erlang runtime system</fsummary>
1089
<desc><p>Same as <seealso marker="erl_driver#driver_system_info">driver_system_info</seealso>.
1092
<func><name><ret>int</ret><nametext>enif_thread_create(char *name,ErlNifTid *tid,void * (*func)(void *),void *args,ErlNifThreadOpts *opts)</nametext></name>
1093
<fsummary></fsummary>
1094
<desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_create">erl_drv_thread_create</seealso>.
1097
<func><name><ret>void</ret><nametext>enif_thread_exit(void *resp)</nametext></name>
1098
<fsummary></fsummary>
1099
<desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_exit">erl_drv_thread_exit</seealso>.
1102
<func><name><ret>int</ret><nametext>enif_thread_join(ErlNifTid, void **respp)</nametext></name>
1103
<fsummary></fsummary>
1104
<desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_join">erl_drv_thread_join </seealso>.
1107
<func><name><ret>ErlNifThreadOpts*</ret><nametext>enif_thread_opts_create(char *name)</nametext></name>
1108
<fsummary></fsummary>
1109
<desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_opts_create">erl_drv_thread_opts_create</seealso>.
1112
<func><name><ret>void</ret><nametext>enif_thread_opts_destroy(ErlNifThreadOpts *opts)</nametext></name>
1113
<fsummary></fsummary>
1114
<desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_opts_destroy">erl_drv_thread_opts_destroy</seealso>.
1117
<func><name><ret>ErlNifTid</ret><nametext>enif_thread_self(void)</nametext></name>
1118
<fsummary></fsummary>
1119
<desc><p>Same as <seealso marker="erl_driver#erl_drv_thread_self">erl_drv_thread_self</seealso>.
1122
<func><name><ret>int</ret><nametext>enif_tsd_key_create(char *name, ErlNifTSDKey *key)</nametext></name>
1123
<fsummary></fsummary>
1124
<desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_key_create">erl_drv_tsd_key_create</seealso>.
1127
<func><name><ret>void</ret><nametext>enif_tsd_key_destroy(ErlNifTSDKey key)</nametext></name>
1128
<fsummary></fsummary>
1129
<desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_key_destroy">erl_drv_tsd_key_destroy</seealso>.
1132
<func><name><ret>void*</ret><nametext>enif_tsd_get(ErlNifTSDKey key)</nametext></name>
1133
<fsummary></fsummary>
1134
<desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_get">erl_drv_tsd_get</seealso>.
1137
<func><name><ret>void</ret><nametext>enif_tsd_set(ErlNifTSDKey key, void *data)</nametext></name>
1138
<fsummary></fsummary>
1139
<desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_set">erl_drv_tsd_set</seealso>.
347
1144
<title>SEE ALSO</title>
348
<p><seealso marker="erlang#erlang:load_nif-2">load_nif(3)</seealso></p>
1145
<p><seealso marker="erlang#load_nif-2">erlang:load_nif/2</seealso></p>
added
removed
erts/doc/src/erl_nif.xml
