1erl_driver(3) C Library Functions erl_driver(3)
2
6 erl_driver - API functions for an Erlang driver.
7
9 An Erlang driver is a library containing a set of native driver call‐
10 back functions that the Erlang Virtual Machine calls when certain
11 events occur. There can be multiple instances of a driver, each in‐
12 stance is associated with an Erlang port.
13 Warning:
15 Use this functionality with extreme care.
16 A driver callback is executed as a direct extension of the native code
18 of the VM. Execution is not made in a safe environment. The VM cannot
19 provide the same services as provided when executing Erlang code, such
20 as pre-emptive scheduling or memory protection. If the driver callback
21 function does not behave well, the whole VM will misbehave.
22 * A driver callback that crash will crash the whole VM.
24 * An erroneously implemented driver callback can cause a VM internal
26 state inconsistency, which can cause a crash of the VM, or miscel‐
27 laneous misbehaviors of the VM at any point after the call to the
28 driver callback.
29 * A driver callback doing lengthy work before returning degrades re‐
31 sponsiveness of the VM and can cause miscellaneous strange behav‐
32 iors. Such strange behaviors include, but are not limited to, ex‐
33 treme memory usage and bad load balancing between schedulers.
34 Strange behaviors that can occur because of lengthy work can also
35 vary between Erlang/OTP releases.
36 As from ERTS 5.5.3 the driver interface has been extended (see extended
38 marker). The extended interface introduces version management, the pos‐
39 sibility to pass capability flags (see driver_flags) to the runtime
40 system at driver initialization, and some new driver API functions.
41 Note:
43 As from ERTS 5.9 old drivers must be recompiled and use the extended
44 interface. They must also be adjusted to the 64-bit capable driver in‐
45 terface.
46 The driver calls back to the emulator, using the API functions declared
49 in erl_driver.h. They are used for outputting data from the driver, us‐
50 ing timers, and so on.
51 Each driver instance is associated with a port. Every port has a port
53 owner process. Communication with the port is normally done through the
54 port owner process. Most of the functions take the port handle as an
55 argument. This identifies the driver instance. Notice that this port
56 handle must be stored by the driver, it is not given when the driver is
57 called from the emulator (see driver_entry).
58 Some of the functions take a parameter of type ErlDrvBinary, a driver
60 binary. It is to be both allocated and freed by the caller. Using a bi‐
61 nary directly avoids one extra copying of data.
62 Many of the output functions have a "header buffer", with hbuf and hlen
64 parameters. This buffer is sent as a list before the binary (or list,
65 depending on port mode) that is sent. This is convenient when matching
66 on messages received from the port. (Although in the latest Erlang ver‐
67 sions there is the binary syntax, which enables you to match on the be‐
68 ginning of a binary.)
69 Drivers are locked either on driver level or port level (driver in‐
71 stance level). By default driver level locking will be used, that is,
72 only one emulator thread will execute code in the driver at a time. If
73 port level locking is used, multiple emulator threads can execute code
74 in the driver at the same time. Only one thread at a time will call
75 driver callbacks corresponding to the same port, though. To enable port
76 level locking, set the ERL_DRV_FLAG_USE_PORT_LOCKING driver flag in the
77 driver_entry used by the driver. When port level locking is used, the
78 driver writer is responsible for synchronizing all accesses to data
79 shared by the ports (driver instances).
80 Most drivers written before the runtime system with SMP support existed
82 can run in the runtime system with SMP support, without being rewrit‐
83 ten, if driver level locking is used.
84 Note:
86 It is assumed that drivers do not access other drivers. If drivers ac‐
87 cess each other, they must provide their own mechanism for thread-safe
88 synchronization. Such "inter-driver communication" is strongly discour‐
89 aged.
90 Note:
93 Regardless of locking scheme used, calls to driver callbacks can be
94 made from different threads.
95 Most functions in this API are not thread-safe, that is, they cannot be
98 called from arbitrary threads. Functions that are not documented as
99 thread-safe can only be called from driver callbacks or function calls
100 descending from a driver callback call. Notice that driver callbacks
101 can be called from different threads. This, however, is not a problem
102 for any function in this API, as the emulator has control over these
103 threads.
104 Warning:
106 Functions not explicitly documented as thread-safe are not thread safe.
107 A function not explicitly documented as thread-safe can, at some point
109 in time, have a thread-safe implementation in the runtime system. Such
110 an implementation can however change to a thread unsafe implementation
111 at any time without any notice.
112 Only use functions explicitly documented as thread-safe from arbitrary
114 threads.
115 As mentioned in the warning text at the beginning of this section, it
118 is of vital importance that a driver callback returns relatively fast.
119 It is difficult to give an exact maximum amount of time that a driver
120 callback is allowed to work, but usually a well-behaving driver call‐
121 back is to return within 1 millisecond. This can be achieved using dif‐
122 ferent approaches. If you have full control over the code to execute in
123 the driver callback, the best approach is to divide the work into mul‐
124 tiple chunks of work, and trigger multiple calls to the time-out call‐
125 back using zero time-outs. Function erl_drv_consume_timeslice can be
126 useful to determine when to trigger such time-out callback calls. How‐
127 ever, sometimes it cannot be implemented this way, for example when
128 calling third-party libraries. In this case, you typically want to dis‐
129 patch the work to another thread. Information about thread primitives
130 is provided below.
131
133 All functions that a driver needs to do with Erlang are performed
134 through driver API functions. Functions exist for the following func‐
135 tionality:
136 Timer functions:
138 Control the timer that a driver can use. The timer has the emulator
139 call the timeout entry function after a specified time. Only one
140 timer is available for each driver instance.
141 Queue handling:
143 Every driver instance has an associated queue. This queue is a Sys‐
144 IOVec, which works as a buffer. It is mostly used for the driver to
145 buffer data that is to be written to a device, it is a byte stream.
146 If the port owner process closes the driver, and the queue is not
147 empty, the driver is not closed. This enables the driver to flush
148 its buffers before closing.
149 The queue can be manipulated from any threads if a port data lock
151 is used. For more information, see ErlDrvPDL.
152 Output functions:
154 With these functions, the driver sends data back to the emulator.
155 The data is received as messages by the port owner process, see er‐
156 lang:open_port/2. The vector function and the function taking a
157 driver binary are faster, as they avoid copying the data buffer.
158 There is also a fast way of sending terms from the driver, without
159 going through the binary term format.
160 Failure:
162 The driver can exit and signal errors up to Erlang. This is only
163 for severe errors, when the driver cannot possibly keep open.
164 Asynchronous calls:
166 Erlang/OTP R7B and later versions have provision for asynchronous
167 function calls, using a thread pool provided by Erlang. There is
168 also a select call, which can be used for asynchronous drivers.
169 Multi-threading:
171 A POSIX thread like API for multi-threading is provided. The Erlang
172 driver thread API only provides a subset of the functionality pro‐
173 vided by the POSIX thread API. The subset provided is more or less
174 the basic functionality needed for multi-threaded programming:
175 * Threads
177 * Mutexes
179 *
181 Condition variables
182 *
184 Read/write locks
185 *
187 Thread-specific data
188 The Erlang driver thread API can be used in conjunction with the
190 POSIX thread API on UN-ices and with the Windows native thread API
191 on Windows. The Erlang driver thread API has the advantage of being
192 portable, but there can exist situations where you want to use
193 functionality from the POSIX thread API or the Windows native
194 thread API.
195 The Erlang driver thread API only returns error codes when it is
197 reasonable to recover from an error condition. If it is not reason‐
198 able to recover from an error condition, the whole runtime system
199 is terminated. For example, if a create mutex operation fails, an
200 error code is returned, but if a lock operation on a mutex fails,
201 the whole runtime system is terminated.
202 Notice that there is no "condition variable wait with time-out" in
204 the Erlang driver thread API. This because of issues with
205 pthread_cond_timedwait. When the system clock suddenly is changed,
206 it is not always guaranteed that you will wake up from the call as
207 expected. An Erlang runtime system must be able to cope with sudden
208 changes of the system clock. Therefore, we have omitted it from the
209 Erlang driver thread API. In the Erlang driver case, time-outs can
210 and are to be handled with the timer functionality of the Erlang
211 driver API.
212 Notice that many functions in the Erlang driver API are not thread-
214 safe. If a function is not documented as thread-safe, it is not
215 thread-safe.
216 Note:
218 When executing in an emulator thread, it is very important that you
219 unlock all locks you have locked before letting the thread out of
220 your control; otherwise you are very likely to deadlock the whole em‐
221 ulator.
222 If you need to use thread-specific data in an emulator thread, only
224 have the thread-specific data set while the thread is under your con‐
225 trol, and clear the thread-specific data before you let the thread
226 out of your control.
227 In the future, debug functionality will probably be integrated with
230 the Erlang driver thread API. All functions that create entities
231 take a name argument. Currently the name argument is unused, but it
232 will be used when the debug functionality is implemented. If you
233 name all entities created well, the debug functionality will be
234 able to give you better error reports.
235 Adding/removing drivers:
237 A driver can add and later remove drivers.
238 Monitoring processes:
240 A driver can monitor a process that does not own a port.
241 Version management:
243 Version management is enabled for drivers that have set the ex‐
244 tended_marker field of their driver_entry to ERL_DRV_EX‐
245 TENDED_MARKER. erl_driver.h defines:
246 * ERL_DRV_EXTENDED_MARKER
248 * ERL_DRV_EXTENDED_MAJOR_VERSION, which is incremented when driver
250 incompatible changes are made to the Erlang runtime system. Nor‐
251 mally it suffices to recompile drivers when ERL_DRV_EXTENDED_MA‐
252 JOR_VERSION has changed, but it can, under rare circumstances,
253 mean that drivers must be slightly modified. If so, this will of
254 course be documented.
255 * ERL_DRV_EXTENDED_MINOR_VERSION, which is incremented when new
257 features are added. The runtime system uses the minor version of
258 the driver to determine what features to use.
259 The runtime system normally refuses to load a driver if the major
261 versions differ, or if the major versions are equal and the minor
262 version used by the driver is greater than the one used by the run‐
263 time system. Old drivers with lower major versions are however al‐
264 lowed after a bump of the major version during a transition period
265 of two major releases. Such old drivers can, however, fail if dep‐
266 recated features are used.
267 The emulator refuses to load a driver that does not use the ex‐
269 tended driver interface, to allow for 64-bit capable drivers, as
270 incompatible type changes for the callbacks output, control, and
271 call were introduced in Erlang/OTP R15B. A driver written with the
272 old types would compile with warnings and when called return
273 garbage sizes to the emulator, causing it to read random memory and
274 create huge incorrect result blobs.
275 Therefore it is not enough to only recompile drivers written with
277 version management for pre R15B types; the types must be changed in
278 the driver suggesting other rewrites, especially regarding size
279 variables. Investigate all warnings when recompiling.
280 Also, the API driver functions driver_output* and
282 driver_vec_to_buf, driver_alloc/realloc*, and the driver_* queue
283 functions were changed to have larger length arguments and return
284 values. This is a lesser problem, as code that passes smaller types
285 gets them auto-converted in the calls, and as long as the driver
286 does not handle sizes that overflow an int, all will work as be‐
287 fore.
288 Time measurement:
290 Support for time measurement in drivers:
291 * ErlDrvTime
293 * ErlDrvTimeUnit
295 * erl_drv_monotonic_time
297 * erl_drv_time_offset
299 * erl_drv_convert_time_unit
301
303 ERTS 5.9 introduced two new integer types, ErlDrvSizeT and ErlDrvS‐
304 SizeT, which can hold 64-bit sizes if necessary.
305 To not update a driver and only recompile, it probably works when
307 building for a 32-bit machine creating a false sense of security. Hope‐
308 fully that will generate many important warnings. But when recompiling
309 the same driver later on for a 64-bit machine, there will be warnings
310 and almost certainly crashes. So it is a bad idea to postpone updating
311 the driver and not fixing the warnings.
312 When recompiling with gcc, use flag -Wstrict-prototypes to get better
314 warnings. Try to find a similar flag if you use another compiler.
315 The following is a checklist for rewriting a pre ERTS 5.9 driver, most
317 important first:
318 Return types for driver callbacks:
320 Rewrite driver callback control to use return type ErlDrvSSizeT in‐
321 stead of int.
322 Rewrite driver callback call to use return type ErlDrvSSizeT in‐
324 stead of int.
325 Note:
327 These changes are essential not to crash the emulator or worse cause
328 malfunction. Without them a driver can return garbage in the high 32
329 bits to the emulator, causing it to build a huge result from random
330 bytes, either crashing on memory allocation or succeeding with a ran‐
331 dom result from the driver call.
332 Arguments to driver callbacks:
335 Driver callback output now gets ErlDrvSizeT as 3rd argument instead
336 of previously int.
337 Driver callback control now gets ErlDrvSizeT as 4th and 6th argu‐
339 ments instead of previously int.
340 Driver callback call now gets ErlDrvSizeT as 4th and 6th arguments
342 instead of previously int.
343 Sane compiler's calling conventions probably make these changes
345 necessary only for a driver to handle data chunks that require
346 64-bit size fields (mostly larger than 2 GB, as that is what an int
347 of 32 bits can hold). But it is possible to think of non-sane call‐
348 ing conventions that would make the driver callbacks mix up the ar‐
349 guments causing malfunction.
350 Note:
352 The argument type change is from signed to unsigned. This can cause
353 problems for, for example, loop termination conditions or error con‐
354 ditions if you only change the types all over the place.
355 Larger size field in ErlIOVec:
358 The size field in ErlIOVec has been changed to ErlDrvSizeT from
359 int. Check all code that use that field.
360 Automatic type-casting probably makes these changes necessary only
362 for a driver that encounters sizes > 32 bits.
363 Note:
365 The size field changed from signed to unsigned. This can cause prob‐
366 lems for, for example, loop termination conditions or error condi‐
367 tions if you only change the types all over the place.
368 Arguments and return values in the driver API:
371 Many driver API functions have changed argument type and/or return
372 value to ErlDrvSizeT from mostly int. Automatic type-casting proba‐
373 bly makes these changes necessary only for a driver that encounters
374 sizes > 32 bits.
375 driver_output:
377 3rd argument
378 driver_output2:
380 3rd and 5th arguments
381 driver_output_binary:
383 3rd, 5th, and 6th arguments
384 driver_outputv:
386 3rd and 5th arguments
387 driver_vec_to_buf:
389 3rd argument and return value
390 driver_alloc:
392 1st argument
393 driver_realloc:
395 2nd argument
396 driver_alloc_binary:
398 1st argument
399 driver_realloc_binary:
401 2nd argument
402 driver_enq:
404 3rd argument
405 driver_pushq:
407 3rd argument
408 driver_deq:
410 2nd argument and return value
411 driver_sizeq:
413 Return value
414 driver_enq_bin:
416 3rd and 4th arguments
417 driver_pushq_bin:
419 3rd and 4th arguments
420 driver_enqv:
422 3rd argument
423 driver_pushqv:
425 3rd argument
426 driver_peekqv:
428 Return value
429 Note:
431 This is a change from signed to unsigned. This can cause problems
432 for, for example, loop termination conditions and error conditions if
433 you only change the types all over the place.
434
437 ErlDrvSizeT:
438 An unsigned integer type to be used as size_t.
439 ErlDrvSSizeT:
441 A signed integer type, the size of ErlDrvSizeT.
442 ErlDrvSysInfo:
444 typedef struct ErlDrvSysInfo {
447 int driver_major_version;
448 int driver_minor_version;
449 char *erts_version;
450 char *otp_release;
451 int thread_support;
452 int smp_support;
453 int async_threads;
454 int scheduler_threads;
455 int nif_major_version;
456 int nif_minor_version;
457 int dirty_scheduler_support;
458 } ErlDrvSysInfo;
459 The ErlDrvSysInfo structure is used for storage of information
461 about the Erlang runtime system. driver_system_info writes the sys‐
462 tem information when passed a reference to a ErlDrvSysInfo struc‐
463 ture. The fields in the structure are as follows:
464 driver_major_version:
466 The value of ERL_DRV_EXTENDED_MAJOR_VERSION when the runtime sys‐
467 tem was compiled. This value is the same as the value of
468 ERL_DRV_EXTENDED_MAJOR_VERSION used when compiling the driver;
469 otherwise the runtime system would have refused to load the
470 driver.
471 driver_minor_version:
473 The value of ERL_DRV_EXTENDED_MINOR_VERSION when the runtime sys‐
474 tem was compiled. This value can differ from the value of
475 ERL_DRV_EXTENDED_MINOR_VERSION used when compiling the driver.
476 erts_version:
478 A string containing the version number of the runtime system (the
479 same as returned by erlang:system_info(version)).
480 otp_release:
482 A string containing the OTP release number (the same as returned
483 by erlang:system_info(otp_release)).
484 thread_support:
486 A value != 0 if the runtime system has thread support; otherwise
487 0.
488 smp_support:
490 A value != 0 if the runtime system has SMP support; otherwise 0.
491 async_threads:
493 The number of async threads in the async thread pool used by
494 driver_async (the same as returned by erlang:sys‐
495 tem_info(thread_pool_size)).
496 scheduler_threads:
498 The number of scheduler threads used by the runtime system (the
499 same as returned by erlang:system_info(schedulers)).
500 nif_major_version:
502 The value of ERL_NIF_MAJOR_VERSION when the runtime system was
503 compiled.
504 nif_minor_version:
506 The value of ERL_NIF_MINOR_VERSION when the runtime system was
507 compiled.
508 dirty_scheduler_support:
510 A value != 0 if the runtime system has support for dirty sched‐
511 uler threads; otherwise 0.
512 ErlDrvBinary:
514 typedef struct ErlDrvBinary {
517 ErlDrvSint orig_size;
518 char orig_bytes[];
519 } ErlDrvBinary;
520 The ErlDrvBinary structure is a binary, as sent between the emula‐
522 tor and the driver. All binaries are reference counted; when
523 driver_binary_free is called, the reference count is decremented,
524 when it reaches zero, the binary is deallocated. orig_size is the
525 binary size and orig_bytes is the buffer. ErlDrvBinary has not a
526 fixed size, its size is orig_size + 2 * sizeof(int).
527 Note:
529 The refc field has been removed. The reference count of an ErlDrvBi‐
530 nary is now stored elsewhere. The reference count of an ErlDrvBinary
531 can be accessed through driver_binary_get_refc, driver_bi‐
532 nary_inc_refc, and driver_binary_dec_refc.
533 Some driver calls, such as driver_enq_binary, increment the driver
536 reference count, and others, such as driver_deq decrement it.
537 Using a driver binary instead of a normal buffer is often faster,
539 as the emulator needs not to copy the data, only the pointer is
540 used.
541 A driver binary allocated in the driver, with driver_alloc_binary,
543 is to be freed in the driver (unless otherwise stated) with
544 driver_free_binary. (Notice that this does not necessarily deallo‐
545 cate it, if the driver is still referred in the emulator, the ref-
546 count will not go to zero.)
547 Driver binaries are used in the driver_output2 and driver_outputv
549 calls, and in the queue. Also the driver callback outputv uses
550 driver binaries.
551 If the driver for some reason wants to keep a driver binary around,
553 for example in a static variable, the reference count is to be in‐
554 cremented, and the binary can later be freed in the stop callback,
555 with driver_free_binary.
556 Notice that as a driver binary is shared by the driver and the emu‐
558 lator. A binary received from the emulator or sent to the emulator
559 must not be changed by the driver.
560 Since ERTS 5.5 (Erlang/OTP R11B), orig_bytes is guaranteed to be
562 properly aligned for storage of an array of doubles (usually 8-byte
563 aligned).
564 ErlDrvData:
566 A handle to driver-specific data, passed to the driver callbacks.
567 It is a pointer, and is most often type cast to a specific pointer
568 in the driver.
569 SysIOVec:
571 A system I/O vector, as used by writev on Unix and WSASend on
572 Win32. It is used in ErlIOVec.
573 ErlIOVec:
575 typedef struct ErlIOVec {
578 int vsize;
579 ErlDrvSizeT size;
580 SysIOVec* iov;
581 ErlDrvBinary** binv;
582 } ErlIOVec;
583 The I/O vector used by the emulator and drivers is a list of bina‐
585 ries, with a SysIOVec pointing to the buffers of the binaries. It
586 is used in driver_outputv and the outputv driver callback. Also,
587 the driver queue is an ErlIOVec.
588 ErlDrvMonitor:
590 When a driver creates a monitor for a process, a ErlDrvMonitor is
591 filled in. This is an opaque data type that can be assigned to, but
592 not compared without using the supplied compare function (that is,
593 it behaves like a struct).
594 The driver writer is to provide the memory for storing the monitor
596 when calling driver_monitor_process. The address of the data is not
597 stored outside of the driver, so ErlDrvMonitor can be used as any
598 other data, it can be copied, moved in memory, forgotten, and so
599 on.
600 ErlDrvNowData:
602 The ErlDrvNowData structure holds a time stamp consisting of three
603 values measured from some arbitrary point in the past. The three
604 structure members are:
605 megasecs:
607 The number of whole megaseconds elapsed since the arbitrary point
608 in time
609 secs:
611 The number of whole seconds elapsed since the arbitrary point in
612 time
613 microsecs:
615 The number of whole microseconds elapsed since the arbitrary
616 point in time
617 ErlDrvPDL:
619 If certain port-specific data must be accessed from other threads
620 than those calling the driver callbacks, a port data lock can be
621 used to synchronize the operations on the data. Currently, the only
622 port-specific data that the emulator associates with the port data
623 lock is the driver queue.
624 Normally a driver instance has no port data lock. If the driver in‐
626 stance wants to use a port data lock, it must create the port data
627 lock by calling driver_pdl_create.
628 Note:
630 Once the port data lock has been created, every access to data asso‐
631 ciated with the port data lock must be done while the port data lock
632 is locked. The port data lock is locked and unlocked by
633 driver_pdl_lock, and driver_pdl_unlock, respectively.
634 A port data lock is reference counted, and when the reference count
637 reaches zero, it is destroyed. The emulator at least increments the
638 reference count once when the lock is created and decrements it
639 once the port associated with the lock terminates. The emulator
640 also increments the reference count when an async job is enqueued
641 and decrements it when an async job has been invoked. Also, the
642 driver is responsible for ensuring that the reference count does
643 not reach zero before the last use of the lock by the driver has
644 been made. The reference count can be read, incremented, and decre‐
645 mented by driver_pdl_get_refc, driver_pdl_inc_refc, and
646 driver_pdl_dec_refc, respectively.
647 ErlDrvTid:
649 Thread identifier.
650 See also erl_drv_thread_create, erl_drv_thread_exit,
652 erl_drv_thread_join, erl_drv_thread_self, and erl_drv_equal_tids.
653 ErlDrvThreadOpts:
655 int suggested_stack_size;
658 Thread options structure passed to erl_drv_thread_create. The fol‐
660 lowing field exists:
661 suggested_stack_size:
663 A suggestion, in kilowords, on how large a stack to use. A value
664 < 0 means default size.
665 See also erl_drv_thread_opts_create, erl_drv_thread_opts_destroy,
667 and erl_drv_thread_create.
668 ErlDrvMutex:
670 Mutual exclusion lock. Used for synchronizing access to shared
671 data. Only one thread at a time can lock a mutex.
672 See also erl_drv_mutex_create, erl_drv_mutex_destroy, erl_drv_mu‐
674 tex_lock, erl_drv_mutex_trylock, and erl_drv_mutex_unlock.
675 ErlDrvCond:
677 Condition variable. Used when threads must wait for a specific con‐
678 dition to appear before continuing execution. Condition variables
679 must be used with associated mutexes.
680 See also erl_drv_cond_create, erl_drv_cond_destroy,
682 erl_drv_cond_signal, erl_drv_cond_broadcast, and erl_drv_cond_wait.
683 ErlDrvRWLock:
685 Read/write lock. Used to allow multiple threads to read shared data
686 while only allowing one thread to write the same data. Multiple
687 threads can read lock an rwlock at the same time, while only one
688 thread can read/write lock an rwlock at a time.
689 See also erl_drv_rwlock_create, erl_drv_rwlock_destroy,
691 erl_drv_rwlock_rlock, erl_drv_rwlock_tryrlock, erl_drv_rwlock_run‐
692 lock, erl_drv_rwlock_rwlock, erl_drv_rwlock_tryrwlock, and
693 erl_drv_rwlock_rwunlock.
694 ErlDrvTSDKey:
696 Key that thread-specific data can be associated with.
697 See also erl_drv_tsd_key_create, erl_drv_tsd_key_destroy,
699 erl_drv_tsd_set, and erl_drv_tsd_get.
700 ErlDrvTime:
702 A signed 64-bit integer type for time representation.
703 ErlDrvTimeUnit:
705 An enumeration of time units supported by the driver API:
706 ERL_DRV_SEC:
708 Seconds
709 ERL_DRV_MSEC:
711 Milliseconds
712 ERL_DRV_USEC:
714 Microseconds
715 ERL_DRV_NSEC:
717 Nanoseconds
718
720 void add_driver_entry(ErlDrvEntry
721 *de)
722 Adds a driver entry to the list of drivers known by Erlang. The
724 init function of parameter de is called.
725 Note:
727 To use this function for adding drivers residing in dynamically
728 loaded code is dangerous. If the driver code for the added
729 driver resides in the same dynamically loaded module (that is,
730 .so file) as a normal dynamically loaded driver (loaded with the
731 erl_ddll interface), the caller is to call driver_lock_driver
732 before adding driver entries.
733 Use of this function is generally deprecated.
735 void *driver_alloc(ErlDrvSizeT size)
738 Allocates a memory block of the size specified in size, and re‐
740 turns it. This fails only on out of memory, in which case NULL
741 is returned. (This is most often a wrapper for malloc).
742 Memory allocated must be explicitly freed with a corresponding
744 call to driver_free (unless otherwise stated).
745 This function is thread-safe.
747 ErlDrvBinary *driver_alloc_binary(ErlDrvSizeT size)
749 Allocates a driver binary with a memory block of at least size
751 bytes, and returns a pointer to it, or NULL on failure (out of
752 memory). When a driver binary has been sent to the emulator, it
753 must not be changed. Every allocated binary is to be freed by a
754 corresponding call to driver_free_binary (unless otherwise
755 stated).
756 Notice that a driver binary has an internal reference counter.
758 This means that calling driver_free_binary, it may not actually
759 dispose of it. If it is sent to the emulator, it can be refer‐
760 enced there.
761 The driver binary has a field, orig_bytes, which marks the start
763 of the data in the binary.
764 This function is thread-safe.
766 long driver_async(ErlDrvPort port, unsigned
768 int* key, void (*async_invoke)(void*), void* async_data, void
769 (*async_free)(void*))
770 Performs an asynchronous call. The function async_invoke is in‐
772 voked in a thread separate from the emulator thread. This en‐
773 ables the driver to perform time-consuming, blocking operations
774 without blocking the emulator.
775 The async thread pool size can be set with command-line argument
777 +A in erl(1). If an async thread pool is unavailable, the call
778 is made synchronously in the thread calling driver_async. The
779 current number of async threads in the async thread pool can be
780 retrieved through driver_system_info.
781 If a thread pool is available, a thread is used. If argument key
783 is NULL, the threads from the pool are used in a round-robin
784 way, each call to driver_async uses the next thread in the pool.
785 With argument key set, this behavior is changed. The two same
786 values of *key always get the same thread.
787 To ensure that a driver instance always uses the same thread,
789 the following call can be used:
790 unsigned int myKey = driver_async_port_key(myPort);
792 r = driver_async(myPort, &myKey, myData, myFunc);
794 It is enough to initialize myKey once for each driver instance.
796 If a thread is already working, the calls are queued up and exe‐
798 cuted in order. Using the same thread for each driver instance
799 ensures that the calls are made in sequence.
800 The async_data is the argument to the functions async_invoke and
802 async_free. It is typically a pointer to a structure containing
803 a pipe or event that can be used to signal that the async opera‐
804 tion completed. The data is to be freed in async_free.
805 When the async operation is done, ready_async driver entry func‐
807 tion is called. If ready_async is NULL in the driver entry, the
808 async_free function is called instead.
809 The return value is -1 if the driver_async call fails.
811 Note:
813 As from ERTS 5.5.4.3 the default stack size for threads in the
814 async-thread pool is 16 kilowords, that is, 64 kilobyte on
815 32-bit architectures. This small default size has been chosen
816 because the amount of async-threads can be quite large. The de‐
817 fault stack size is enough for drivers delivered with Er‐
818 lang/OTP, but is possibly not sufficiently large for other dy‐
819 namically linked-in drivers that use the driver_async function‐
820 ality. A suggested stack size for threads in the async-thread
821 pool can be configured through command-line argument +a in
822 erl(1).
823 unsigned int driver_async_port_key(ErlDrvPort
826 port)
827 Calculates a key for later use in driver_async. The keys are
829 evenly distributed so that a fair mapping between port IDs and
830 async thread IDs is achieved.
831 Note:
833 Before Erlang/OTP R16, the port ID could be used as a key with
834 proper casting, but after the rewrite of the port subsystem,
835 this is no longer the case. With this function, you can achieve
836 the same distribution based on port IDs as before Erlang/OTP
837 R16.
838 long driver_binary_dec_refc(ErlDrvBinary *bin)
841 Decrements the reference count on bin and returns the reference
843 count reached after the decrement.
844 This function is thread-safe.
846 Note:
848 The reference count of driver binary is normally to be decre‐
849 mented by calling driver_free_binary.
850 driver_binary_dec_refc does not free the binary if the reference
852 count reaches zero. Only use driver_binary_dec_refc when you are
853 sure not to reach a reference count of zero.
854 long driver_binary_get_refc(ErlDrvBinary *bin)
857 Returns the current reference count on bin.
859 This function is thread-safe.
861 long driver_binary_inc_refc(ErlDrvBinary *bin)
863 Increments the reference count on bin and returns the reference
865 count reached after the increment.
866 This function is thread-safe.
868 ErlDrvTermData driver_caller(ErlDrvPort
870 port)
871 Returns the process ID of the process that made the current call
873 to the driver. The process ID can be used with driver_send_term
874 to send back data to the caller. driver_caller only returns
875 valid data when currently executing in one of the following
876 driver callbacks:
877 start:
879 Called from erlang:open_port/2.
880 output:
882 Called from erlang:send/2 and erlang:port_command/2.
883 outputv:
885 Called from erlang:send/2 and erlang:port_command/2.
886 control:
888 Called from erlang:port_control/3.
889 call:
891 Called from erlang:port_call/3.
892 Notice that this function is not thread-safe.
894 int driver_cancel_timer(ErlDrvPort port)
896 Cancels a timer set with driver_set_timer.
898 The return value is 0.
900 int driver_compare_monitors(const ErlDrvMonitor
902 *monitor1, const ErlDrvMonitor *monitor2)
903 Compares two ErlDrvMonitors. Can also be used to imply some ar‐
905 tificial order on monitors, for whatever reason.
906 Returns 0 if monitor1 and monitor2 are equal, < 0 if monitor1 <
908 monitor2, and > 0 if monitor1 > monitor2.
909 ErlDrvTermData driver_connected(ErlDrvPort
911 port)
912 Returns the port owner process.
914 Notice that this function is not thread-safe.
916 ErlDrvPort driver_create_port(ErlDrvPort port,
918 ErlDrvTermData owner_pid, char* name,
919 ErlDrvData drv_data)
920 Creates a new port executing the same driver code as the port
922 creating the new port.
923 port:
925 The port handle of the port (driver instance) creating the
926 new port.
927 owner_pid:
929 The process ID of the Erlang process to become owner of the
930 new port. This process will be linked to the new port. You
931 usually want to use driver_caller(port) as owner_pid.
932 name:
934 The port name of the new port. You usually want to use the
935 same port name as the driver name (driver_name field of the
936 driver_entry).
937 drv_data:
939 The driver-defined handle that is passed in later calls to
940 driver callbacks. Notice that the driver start callback is
941 not called for this new driver instance. The driver-defined
942 handle is normally created in the driver start callback when
943 a port is created through erlang:open_port/2.
944 The caller of driver_create_port is allowed to manipulate the
946 newly created port when driver_create_port has returned. When
947 port level locking is used, the creating port is only allowed to
948 manipulate the newly created port until the current driver call‐
949 back, which was called by the emulator, returns.
950 int driver_demonitor_process(ErlDrvPort port,
952 const ErlDrvMonitor *monitor)
953 Cancels a monitor created earlier.
955 Returns 0 if a monitor was removed and > 0 if the monitor no
957 longer exists.
958 ErlDrvSizeT driver_deq(ErlDrvPort port,
960 ErlDrvSizeT size)
961 Dequeues data by moving the head pointer forward in the driver
963 queue by size bytes. The data in the queue is deallocated.
964 Returns the number of bytes remaining in the queue on success,
966 otherwise -1.
967 This function can be called from any thread if a port data lock
969 associated with the port is locked by the calling thread during
970 the call.
971 int driver_enq(ErlDrvPort port, char* buf,
973 ErlDrvSizeT len)
974 Enqueues data in the driver queue. The data in buf is copied
976 (len bytes) and placed at the end of the driver queue. The
977 driver queue is normally used in a FIFO way.
978 The driver queue is available to queue output from the emulator
980 to the driver (data from the driver to the emulator is queued by
981 the emulator in normal Erlang message queues). This can be use‐
982 ful if the driver must wait for slow devices, and so on, and
983 wants to yield back to the emulator. The driver queue is imple‐
984 mented as an ErlIOVec.
985 When the queue contains data, the driver does not close until
987 the queue is empty.
988 The return value is 0.
990 This function can be called from any thread if a port data lock
992 associated with the port is locked by the calling thread during
993 the call.
994 int driver_enq_bin(ErlDrvPort port,
996 ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len)
997 Enqueues a driver binary in the driver queue. The data in bin at
999 offset with length len is placed at the end of the queue. This
1000 function is most often faster than driver_enq, because no data
1001 must be copied.
1002 This function can be called from any thread if a port data lock
1004 associated with the port is locked by the calling thread during
1005 the call.
1006 The return value is 0.
1008 int driver_enqv(ErlDrvPort port, ErlIOVec *ev,
1010 ErlDrvSizeT skip)
1011 Enqueues the data in ev, skipping the first skip bytes of it, at
1013 the end of the driver queue. It is faster than driver_enq, be‐
1014 cause no data must be copied.
1015 The return value is 0.
1017 This function can be called from any thread if a port data lock
1019 associated with the port is locked by the calling thread during
1020 the call.
1021 int driver_failure(ErlDrvPort port, int
1023 error)
1024 int driver_failure_atom(ErlDrvPort port, char
1025 *string)
1026 int driver_failure_posix(ErlDrvPort port, int
1027 error)
1028 Signals to Erlang that the driver has encountered an error and
1030 is to be closed. The port is closed and the tuple {'EXIT', er‐
1031 ror, Err} is sent to the port owner process, where error is an
1032 error atom (driver_failure_atom and driver_failure_posix) or an
1033 integer (driver_failure).
1034 The driver is to fail only when in severe error situations, when
1036 the driver cannot possibly keep open, for example, buffer allo‐
1037 cation gets out of memory. For normal errors it is more appro‐
1038 priate to send error codes with driver_output.
1039 The return value is 0.
1041 int driver_failure_eof(ErlDrvPort
1043 port)
1044 Signals to Erlang that the driver has encountered an EOF and is
1046 to be closed, unless the port was opened with option eof, in
1047 which case eof is sent to the port. Otherwise the port is closed
1048 and an 'EXIT' message is sent to the port owner process.
1049 The return value is 0.
1051 void driver_free(void *ptr)
1053 Frees the memory pointed to by ptr. The memory is to have been
1055 allocated with driver_alloc. All allocated memory is to be de‐
1056 allocated, only once. There is no garbage collection in drivers.
1057 This function is thread-safe.
1059 void driver_free_binary(ErlDrvBinary *bin)
1061 Frees a driver binary bin, allocated previously with driver_al‐
1063 loc_binary. As binaries in Erlang are reference counted, the bi‐
1064 nary can still be around.
1065 This function is thread-safe.
1067 ErlDrvTermData driver_get_monitored_process(ErlDrvPort port, const
1069 ErlDrvMonitor *monitor)
1070 Returns the process ID associated with a living monitor. It can
1072 be used in the process_exit callback to get the process identi‐
1073 fication for the exiting process.
1074 Returns driver_term_nil if the monitor no longer exists.
1076 int driver_get_now(ErlDrvNowData *now)
1078 Warning:
1080 This function is deprecated. Do not use it. Use erl_drv_mono‐
1081 tonic_time (perhaps in combination with erl_drv_time_offset) in‐
1082 stead.
1083 Reads a time stamp into the memory pointed to by parameter now.
1086 For information about specific fields, see ErlDrvNowData.
1087 The return value is 0, unless the now pointer is invalid, in
1089 which case it is < 0.
1090 int driver_lock_driver(ErlDrvPort
1092 port)
1093 Locks the driver used by the port port in memory for the rest of
1095 the emulator process' lifetime. After this call, the driver be‐
1096 haves as one of Erlang's statically linked-in drivers.
1097 ErlDrvTermData driver_mk_atom(char*
1099 string)
1100 Returns an atom given a name string. The atom is created and
1102 does not change, so the return value can be saved and reused,
1103 which is faster than looking up the atom several times.
1104 Notice that this function is not thread-safe.
1106 ErlDrvTermData driver_mk_port(ErlDrvPort
1108 port)
1109 Converts a port handle to the Erlang term format, usable in
1111 erl_drv_output_term and erl_drv_send_term.
1112 Notice that this function is not thread-safe.
1114 int driver_monitor_process(ErlDrvPort port,
1116 ErlDrvTermData process, ErlDrvMonitor *monitor)
1117 Starts monitoring a process from a driver. When a process is
1119 monitored, a process exit results in a call to the provided
1120 process_exit callback in the ErlDrvEntry structure. The ErlDrv‐
1121 Monitor structure is filled in, for later removal or compare.
1122 Parameter process is to be the return value of an earlier call
1124 to driver_caller or driver_connected call.
1125 Returns 0 on success, < 0 if no callback is provided, and > 0 if
1127 the process is no longer alive.
1128 int driver_output(ErlDrvPort port, char *buf,
1130 ErlDrvSizeT len)
1131 Sends data from the driver up to the emulator. The data is re‐
1133 ceived as terms or binary data, depending on how the driver port
1134 was opened.
1135 The data is queued in the port owner process' message queue. No‐
1137 tice that this does not yield to the emulator (as the driver and
1138 the emulator run in the same thread).
1139 Parameter buf points to the data to send, and len is the number
1141 of bytes.
1142 The return value for all output functions is 0 for normal use.
1144 If the driver is used for distribution, it can fail and return
1145 -1.
1146 int driver_output_binary(ErlDrvPort port, char
1148 *hbuf, ErlDrvSizeT hlen, ErlDrvBinary* bin, ErlDrvSizeT offset,
1149 ErlDrvSizeT len)
1150 Sends data to a port owner process from a driver binary. It has
1152 a header buffer (hbuf and hlen) just like driver_output2. Param‐
1153 eter hbuf can be NULL.
1154 Parameter offset is an offset into the binary and len is the
1156 number of bytes to send.
1157 Driver binaries are created with driver_alloc_binary.
1159 The data in the header is sent as a list and the binary as an
1161 Erlang binary in the tail of the list.
1162 For example, if hlen is 2, the port owner process receives [H1,
1164 H2 | <<T>>].
1165 The return value is 0 for normal use.
1167 Notice that, using the binary syntax in Erlang, the driver ap‐
1169 plication can match the header directly from the binary, so the
1170 header can be put in the binary, and hlen can be set to 0.
1171 int driver_output_term(ErlDrvPort port,
1173 ErlDrvTermData* term, int n)
1174 Warning:
1176 This function is deprecated. Use erl_drv_output_terminstead.
1177 Parameters term and n work as in erl_drv_output_term.
1180 Notice that this function is not thread-safe.
1182 int driver_output2(ErlDrvPort port, char *hbuf,
1184 ErlDrvSizeT hlen, char *buf, ErlDrvSizeT len)
1185 First sends hbuf (length in hlen) data as a list, regardless of
1187 port settings. Then sends buf as a binary or list. For example,
1188 if hlen is 3, the port owner process receives [H1, H2, H3 | T].
1189 The point of sending data as a list header, is to facilitate
1191 matching on the data received.
1192 The return value is 0 for normal use.
1194 int driver_outputv(ErlDrvPort port, char* hbuf,
1196 ErlDrvSizeT hlen, ErlIOVec *ev, ErlDrvSizeT skip)
1197 Sends data from an I/O vector, ev, to the port owner process. It
1199 has a header buffer (hbuf and hlen), just like driver_output2.
1200 Parameter skip is a number of bytes to skip of the ev vector
1202 from the head.
1203 You get vectors of ErlIOVec type from the driver queue (see be‐
1205 low), and the outputv driver entry function. You can also make
1206 them yourself, if you want to send several ErlDrvBinary buffers
1207 at once. Often it is faster to use driver_output or .
1208 For example, if hlen is 2 and ev points to an array of three bi‐
1210 naries, the port owner process receives [H1, H2, <<B1>>, <<B2>>
1211 | <<B3>>].
1212 The return value is 0 for normal use.
1214 The comment for driver_output_binary also applies for
1216 driver_outputv.
1217 ErlDrvPDL driver_pdl_create(ErlDrvPort port)
1219 Creates a port data lock associated with the port.
1221 Note:
1223 Once a port data lock has been created, it must be locked during
1224 all operations on the driver queue of the port.
1225 Returns a newly created port data lock on success, otherwise
1228 NULL. The function fails if port is invalid or if a port data
1229 lock already has been associated with the port.
1230 long driver_pdl_dec_refc(ErlDrvPDL
1232 pdl)
1233 Decrements the reference count of the port data lock passed as
1235 argument (pdl).
1236 The current reference count after the decrement has been per‐
1238 formed is returned.
1239 This function is thread-safe.
1241 long driver_pdl_get_refc(ErlDrvPDL pdl)
1243 Returns the current reference count of the port data lock passed
1245 as argument (pdl).
1246 This function is thread-safe.
1248 long driver_pdl_inc_refc(ErlDrvPDL pdl)
1250 Increments the reference count of the port data lock passed as
1252 argument (pdl).
1253 The current reference count after the increment has been per‐
1255 formed is returned.
1256 This function is thread-safe.
1258 void driver_pdl_lock(ErlDrvPDL pdl)
1260 Locks the port data lock passed as argument (pdl).
1262 This function is thread-safe.
1264 void driver_pdl_unlock(ErlDrvPDL pdl)
1266 Unlocks the port data lock passed as argument (pdl).
1268 This function is thread-safe.
1270 SysIOVec *driver_peekq(ErlDrvPort port, int
1272 *vlen)
1273 Retrieves the driver queue as a pointer to an array of Sys‐
1275 IOVecs. It also returns the number of elements in vlen. This is
1276 one of two ways to get data out of the queue.
1277 Nothing is removed from the queue by this function, that must be
1279 done with driver_deq.
1280 The returned array is suitable to use with the Unix system call
1282 writev.
1283 This function can be called from any thread if a port data lock
1285 associated with the port is locked by the calling thread during
1286 the call.
1287 ErlDrvSizeT driver_peekqv(ErlDrvPort port,
1289 ErlIOVec *ev)
1290 Retrieves the driver queue into a supplied ErlIOVec ev. It also
1292 returns the queue size. This is one of two ways to get data out
1293 of the queue.
1294 If ev is NULL, all ones that is -1 type cast to ErlDrvSizeT are
1296 returned.
1297 Nothing is removed from the queue by this function, that must be
1299 done with driver_deq.
1300 This function can be called from any thread if a port data lock
1302 associated with the port is locked by the calling thread during
1303 the call.
1304 int driver_pushq(ErlDrvPort port, char* buf,
1306 ErlDrvSizeT len)
1307 Puts data at the head of the driver queue. The data in buf is
1309 copied (len bytes) and placed at the beginning of the queue.
1310 The return value is 0.
1312 This function can be called from any thread if a port data lock
1314 associated with the port is locked by the calling thread during
1315 the call.
1316 int driver_pushq_bin(ErlDrvPort port,
1318 ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len)
1319 Puts data in the binary bin, at offset with length len at the
1321 head of the driver queue. It is most often faster than
1322 driver_pushq, because no data must be copied.
1323 This function can be called from any thread if a port data lock
1325 associated with the port is locked by the calling thread during
1326 the call.
1327 The return value is 0.
1329 int driver_pushqv(ErlDrvPort port, ErlIOVec
1331 *ev, ErlDrvSizeT skip)
1332 Puts the data in ev, skipping the first skip bytes of it, at the
1334 head of the driver queue. It is faster than driver_pushq, be‐
1335 cause no data must be copied.
1336 The return value is 0.
1338 This function can be called from any thread if a port data lock
1340 associated with the port is locked by the calling thread during
1341 the call.
1342 int driver_read_timer(ErlDrvPort port, unsigned
1344 long *time_left)
1345 Reads the current time of a timer, and places the result in
1347 time_left. This is the time in milliseconds, before the time-out
1348 occurs.
1349 The return value is 0.
1351 void *driver_realloc(void *ptr, ErlDrvSizeT size)
1353 Resizes a memory block, either in place, or by allocating a new
1355 block, copying the data, and freeing the old block. A pointer is
1356 returned to the reallocated memory. On failure (out of memory),
1357 NULL is returned. (This is most often a wrapper for realloc.)
1358 This function is thread-safe.
1360 ErlDrvBinary *driver_realloc_binary(ErlDrvBinary *bin, ErlDrvSizeT
1362 size)
1363 Resizes a driver binary, while keeping the data.
1366 Returns the resized driver binary on success. Returns NULL on
1368 failure (out of memory).
1369 This function is thread-safe.
1371 int driver_select(ErlDrvPort port, ErlDrvEvent
1373 event, int mode, int on)
1374 This function is used by drivers to provide the emulator with
1376 events to check for. This enables the emulator to call the
1377 driver when something has occurred asynchronously.
1378 Parameter event identifies an OS-specific event object. On Unix
1380 systems, the functions select/poll are used. The event object
1381 must be a socket or pipe (or other object that select/poll can
1382 use). On Windows, the Win32 API function WaitForMultipleObjects
1383 is used. This places other restrictions on the event object; see
1384 the Win32 SDK documentation.
1385 Parameter on is to be 1 for setting events and 0 for clearing
1387 them.
1388 Parameter mode is a bitwise OR combination of ERL_DRV_READ,
1390 ERL_DRV_WRITE, and ERL_DRV_USE. The first two specify whether to
1391 wait for read events and/or write events. A fired read event
1392 calls ready_input and a fired write event calls ready_output.
1393 Note:
1395 Some OS (Windows) do not differentiate between read and write
1396 events. The callback for a fired event then only depends on the
1397 value of mode.
1398 ERL_DRV_USE specifies if we are using the event object or if we
1401 want to close it. It is not safe to clear all events and then
1402 close the event object after driver_select has returned. Another
1403 thread can still be using the event object internally. To safely
1404 close an event object, call driver_select with ERL_DRV_USE and
1405 on==0, which clears all events and then either calls stop_select
1406 or schedules it to be called when it is safe to close the event
1407 object. ERL_DRV_USE is to be set together with the first event
1408 for an event object. It is harmless to set ERL_DRV_USE even if
1409 it already has been done. Clearing all events but keeping
1410 ERL_DRV_USE set indicates that we are using the event object and
1411 probably will set events for it again.
1412 Note:
1414 ERL_DRV_USE was added in Erlang/OTP R13. Old drivers still work
1415 as before, but it is recommended to update them to use
1416 ERL_DRV_USE and stop_select to ensure that event objects are
1417 closed in a safe way.
1418 The return value is 0, unless ready_input/ready_output is NULL,
1421 in which case it is -1.
1422 int driver_send_term(ErlDrvPort port,
1424 ErlDrvTermData receiver, ErlDrvTermData* term, int n)
1425 Warning:
1427 This function is deprecated. Use erl_drv_send_term instead.
1428 Note:
1431 The parameters of this function cannot be properly checked by
1432 the runtime system when executed by arbitrary threads. This can
1433 cause the function not to fail when it should.
1434 Parameters term and n work as in erl_drv_output_term.
1437 This function is thread-safe.
1439 int driver_set_timer(ErlDrvPort port, unsigned
1441 long time)
1442 Sets a timer on the driver, which will count down and call the
1444 driver when it is timed out. Parameter time is the time in mil‐
1445 liseconds before the timer expires.
1446 When the timer reaches 0 and expires, the driver entry function
1448 timeout is called.
1449 Notice that only one timer exists on each driver instance; set‐
1451 ting a new timer replaces an older one.
1452 Return value is 0, unless the timeout driver function is NULL,
1454 in which case it is -1.
1455 ErlDrvSizeT driver_sizeq(ErlDrvPort port)
1457 Returns the number of bytes currently in the driver queue.
1459 This function can be called from any thread if a port data lock
1461 associated with the port is locked by the calling thread during
1462 the call.
1463 void driver_system_info(ErlDrvSysInfo
1465 *sys_info_ptr, size_t size)
1466 Writes information about the Erlang runtime system into the Erl‐
1468 DrvSysInfo structure referred to by the first argument. The sec‐
1469 ond argument is to be the size of the ErlDrvSysInfo structure,
1470 that is, sizeof(ErlDrvSysInfo).
1471 For information about specific fields, see ErlDrvSysInfo.
1473 ErlDrvSizeT driver_vec_to_buf(ErlIOVec *ev,
1475 char *buf, ErlDrvSizeT len)
1476 Collects several segments of data, referenced by ev, by copying
1478 them in order to the buffer buf, of the size len.
1479 If the data is to be sent from the driver to the port owner
1481 process, it is faster to use driver_outputv.
1482 The return value is the space left in the buffer, that is, if ev
1484 contains less than len bytes it is the difference, and if ev
1485 contains len bytes or more, it is 0. This is faster if there is
1486 more than one header byte, as the binary syntax can construct
1487 integers directly from the binary.
1488 void erl_drv_busy_msgq_limits(ErlDrvPort port,
1490 ErlDrvSizeT *low, ErlDrvSizeT *high)
1491 Sets and gets limits that will be used for controlling the busy
1493 state of the port message queue.
1494 The port message queue is set into a busy state when the amount
1496 of command data queued on the message queue reaches the high
1497 limit. The port message queue is set into a not busy state when
1498 the amount of command data queued on the message queue falls be‐
1499 low the low limit. Command data is in this context data passed
1500 to the port using either Port ! {Owner, {command, Data}} or
1501 port_command/[2,3]. Notice that these limits only concerns com‐
1502 mand data that have not yet reached the port. The busy port fea‐
1503 ture can be used for data that has reached the port.
1504 Valid limits are values in the range [ERL_DRV_BUSY_MSGQ_LIM_MIN,
1506 ERL_DRV_BUSY_MSGQ_LIM_MAX]. Limits are automatically adjusted to
1507 be sane. That is, the system adjusts values so that the low
1508 limit used is lower than or equal to the high limit used. By de‐
1509 fault the high limit is 8 kB and the low limit is 4 kB.
1510 By passing a pointer to an integer variable containing the value
1512 ERL_DRV_BUSY_MSGQ_READ_ONLY, the currently used limit is read
1513 and written back to the integer variable. A new limit can be set
1514 by passing a pointer to an integer variable containing a valid
1515 limit. The passed value is written to the internal limit. The
1516 internal limit is then adjusted. After this the adjusted limit
1517 is written back to the integer variable from which the new value
1518 was read. Values are in bytes.
1519 The busy message queue feature can be disabled either by setting
1521 the ERL_DRV_FLAG_NO_BUSY_MSGQ driver flag in the driver_entry
1522 used by the driver, or by calling this function with
1523 ERL_DRV_BUSY_MSGQ_DISABLED as a limit (either low or high). When
1524 this feature has been disabled, it cannot be enabled again. When
1525 reading the limits, both are ERL_DRV_BUSY_MSGQ_DISABLED if this
1526 feature has been disabled.
1527 Processes sending command data to the port are suspended if ei‐
1529 ther the port is busy or if the port message queue is busy. Sus‐
1530 pended processes are resumed when neither the port or the port
1531 message queue is busy.
1532 For information about busy port functionality, see
1534 set_busy_port.
1535 void erl_drv_cond_broadcast(ErlDrvCond
1537 *cnd)
1538 Broadcasts on a condition variable. That is, if other threads
1540 are waiting on the condition variable being broadcast on, all of
1541 them are woken.
1542 cnd is a pointer to a condition variable to broadcast on.
1544 This function is thread-safe.
1546 ErlDrvCond *erl_drv_cond_create(char
1548 *name)
1549 Creates a condition variable and returns a pointer to it.
1551 name is a string identifying the created condition variable. It
1553 is used to identify the condition variable in planned future de‐
1554 bug functionality.
1555 Returns NULL on failure. The driver creating the condition vari‐
1557 able is responsible for destroying it before the driver is un‐
1558 loaded.
1559 This function is thread-safe.
1561 void erl_drv_cond_destroy(ErlDrvCond
1563 *cnd)
1564 Destroys a condition variable previously created by
1566 erl_drv_cond_create.
1567 cnd is a pointer to a condition variable to destroy.
1569 This function is thread-safe.
1571 char *erl_drv_cond_name(ErlDrvCond
1573 *cnd)
1574 Returns a pointer to the name of the condition.
1576 cnd is a pointer to an initialized condition.
1578 Note:
1580 This function is intended for debugging purposes only.
1581 void erl_drv_cond_signal(ErlDrvCond
1584 *cnd)
1585 Signals on a condition variable. That is, if other threads are
1587 waiting on the condition variable being signaled, one of them is
1588 woken.
1589 cnd is a pointer to a condition variable to signal on.
1591 This function is thread-safe.
1593 void erl_drv_cond_wait(ErlDrvCond *cnd,
1595 ErlDrvMutex *mtx)
1596 Waits on a condition variable. The calling thread is blocked un‐
1598 til another thread wakes it by signaling or broadcasting on the
1599 condition variable. Before the calling thread is blocked, it un‐
1600 locks the mutex passed as argument. When the calling thread is
1601 woken, it locks the same mutex before returning. That is, the
1602 mutex currently must be locked by the calling thread when call‐
1603 ing this function.
1604 cnd is a pointer to a condition variable to wait on. mtx is a
1606 pointer to a mutex to unlock while waiting.
1607 Note:
1609 erl_drv_cond_wait can return even if no one has signaled or
1610 broadcast on the condition variable. Code calling
1611 erl_drv_cond_wait is always to be prepared for erl_drv_cond_wait
1612 returning even if the condition that the thread was waiting for
1613 has not occurred. That is, when returning from
1614 erl_drv_cond_wait, always check if the condition has occurred,
1615 and if not call erl_drv_cond_wait again.
1616 This function is thread-safe.
1619 int erl_drv_consume_timeslice(ErlDrvPort port,
1621 int percent)
1622 Gives the runtime system a hint about how much CPU time the cur‐
1624 rent driver callback call has consumed since the last hint, or
1625 since the the start of the callback if no previous hint has been
1626 given.
1627 port:
1629 Port handle of the executing port.
1630 percent:
1632 Approximate consumed fraction of a full time-slice in per‐
1633 cent.
1634 The time is specified as a fraction, in percent, of a full time-
1636 slice that a port is allowed to execute before it is to surren‐
1637 der the CPU to other runnable ports or processes. Valid range is
1638 [1, 100]. The scheduling time-slice is not an exact entity, but
1639 can usually be approximated to about 1 millisecond.
1640 Notice that it is up to the runtime system to determine if and
1642 how to use this information. Implementations on some platforms
1643 can use other means to determine the consumed fraction of the
1644 time-slice. Lengthy driver callbacks should, regardless of this,
1645 frequently call this function to determine if it is allowed to
1646 continue execution or not.
1647 This function returns a non-zero value if the time-slice has
1649 been exhausted, and zero if the callback is allowed to continue
1650 execution. If a non-zero value is returned, the driver callback
1651 is to return as soon as possible in order for the port to be
1652 able to yield.
1653 This function is provided to better support co-operative sched‐
1655 uling, improve system responsiveness, and to make it easier to
1656 prevent misbehaviors of the VM because of a port monopolizing a
1657 scheduler thread. It can be used when dividing lengthy work into
1658 some repeated driver callback calls, without the need to use
1659 threads.
1660 See also the important warning text at the beginning of this
1662 manual page.
1663 ErlDrvTime erl_drv_convert_time_unit(ErlDrvTime
1665 val, ErlDrvTimeUnit from, ErlDrvTimeUnit to)
1666 Converts the val value of time unit from to the corresponding
1668 value of time unit to. The result is rounded using the floor
1669 function.
1670 val:
1672 Value to convert time unit for.
1673 from:
1675 Time unit of val.
1676 to:
1678 Time unit of returned value.
1679 Returns ERL_DRV_TIME_ERROR if called with an invalid time unit
1681 argument.
1682 See also ErlDrvTime and ErlDrvTimeUnit.
1684 int erl_drv_equal_tids(ErlDrvTid tid1,
1686 ErlDrvTid tid2)
1687 Compares two thread identifiers, tid1 and tid2, for equality.
1689 Returns 0 it they are not equal, and a value not equal to 0 if
1691 they are equal.
1692 Note:
1694 A thread identifier can be reused very quickly after a thread
1695 has terminated. Therefore, if a thread corresponding to one of
1696 the involved thread identifiers has terminated since the thread
1697 identifier was saved, the result of erl_drv_equal_tids does pos‐
1698 sibly not give the expected result.
1699 This function is thread-safe.
1702 int erl_drv_getenv(const char *key, char
1704 *value, size_t *value_size)
1705 Retrieves the value of an environment variable.
1707 key:
1709 A NULL-terminated string containing the name of the environ‐
1710 ment variable.
1711 value:
1713 A pointer to an output buffer.
1714 value_size:
1716 A pointer to an integer. The integer is used both for pass‐
1717 ing input and output sizes (see below).
1718 When this function is called, *value_size is to contain the size
1720 of the value buffer.
1721 On success, 0 is returned, the value of the environment variable
1723 has been written to the value buffer, and *value_size contains
1724 the string length (excluding the terminating NULL character) of
1725 the value written to the value buffer.
1726 On failure, that is, no such environment variable was found, a
1728 value < 0 is returned. When the size of the value buffer is too
1729 small, a value > 0 is returned and *value_size has been set to
1730 the buffer size needed.
1731 Warning:
1733 This function reads the emulated environment used by os:getenv/1
1734 and not the environment used by libc's getenv(3) or similar.
1735 Drivers that require that these are in sync will need to do so
1736 themselves, but keep in mind that they are segregated for a rea‐
1737 son; getenv(3) and its friends are not thread-safe and may cause
1738 unrelated code to misbehave or crash the emulator.
1739 This function is thread-safe.
1742 void erl_drv_init_ack(ErlDrvPort port,
1744 ErlDrvData res)
1745 Acknowledges the start of the port.
1747 port:
1749 The port handle of the port (driver instance) doing the ac‐
1750 knowledgment.
1751 res:
1753 The result of the port initialization. Can be the same val‐
1754 ues as the return value of start, that is, any of the error
1755 codes or the ErlDrvData that is to be used for this port.
1756 When this function is called the initiating erlang:open_port
1758 call is returned as if the start function had just been called.
1759 It can only be used when flag ERL_DRV_FLAG_USE_INIT_ACK has been
1760 set on the linked-in driver.
1761 ErlDrvTime erl_drv_monotonic_time(ErlDrvTimeUnit time_unit)
1763 Returns Erlang monotonic time. Notice that negative values are
1765 not uncommon.
1766 time_unit is time unit of returned value.
1768 Returns ERL_DRV_TIME_ERROR if called with an invalid time unit
1770 argument, or if called from a thread that is not a scheduler
1771 thread.
1772 See also ErlDrvTime and ErlDrvTimeUnit.
1774 ErlDrvMutex *erl_drv_mutex_create(char
1776 *name)
1777 Creates a mutex and returns a pointer to it.
1779 name is a string identifying the created mutex. It is used to
1781 identify the mutex in debug functionality (see note).
1782 Returns NULL on failure. The driver creating the mutex is re‐
1784 sponsible for destroying it before the driver is unloaded.
1785 This function is thread-safe.
1787 Note:
1789 One such debug functionality is the lock checker, which can de‐
1790 tect locking order violations and thereby potential deadlock
1791 bugs. For the lock checker to work the name should be on the
1792 format "App.Type" or "App.Type[Instance]", where App is the name
1793 of the application, Type is the name of the lock type and In‐
1794 stance is optional information about each lock instance.
1795 "App.Type" should be a unique name for the lock checker to de‐
1796 tect lock order violations between locks of different types. The
1797 Instance information is currently ignored.
1798 For example, if we have mutexes of types "myapp.xtable" and
1800 "myapp.xitem" then the lock checker will make sure either
1801 "myapp.xtable" locks are never locked after "myapp.xitem" locks
1802 or vice versa.
1803 void erl_drv_mutex_destroy(ErlDrvMutex
1806 *mtx)
1807 Destroys a mutex previously created by erl_drv_mutex_create. The
1809 mutex must be in an unlocked state before it is destroyed.
1810 mtx is a pointer to a mutex to destroy.
1812 This function is thread-safe.
1814 void erl_drv_mutex_lock(ErlDrvMutex
1816 *mtx)
1817 Locks a mutex. The calling thread is blocked until the mutex has
1819 been locked. A thread that has currently locked the mutex cannot
1820 lock the same mutex again.
1821 mtx is a pointer to a mutex to lock.
1823 Warning:
1825 If you leave a mutex locked in an emulator thread when you let
1826 the thread out of your control, you will very likely deadlock
1827 the whole emulator.
1828 This function is thread-safe.
1831 char *erl_drv_mutex_name(ErlDrvMutex
1833 *mtx)
1834 Returns a pointer to the mutex name.
1836 mtx is a pointer to an initialized mutex.
1838 Note:
1840 This function is intended for debugging purposes only.
1841 int erl_drv_mutex_trylock(ErlDrvMutex
1844 *mtx)
1845 Tries to lock a mutex. A thread that has currently locked the
1847 mutex cannot try to lock the same mutex again.
1848 mtx is a pointer to a mutex to try to lock.
1850 Returns 0 on success, otherwise EBUSY.
1852 Warning:
1854 If you leave a mutex locked in an emulator thread when you let
1855 the thread out of your control, you will very likely deadlock
1856 the whole emulator.
1857 This function is thread-safe.
1860 void erl_drv_mutex_unlock(ErlDrvMutex
1862 *mtx)
1863 Unlocks a mutex. The mutex currently must be locked by the call‐
1865 ing thread.
1866 mtx is a pointer to a mutex to unlock.
1868 This function is thread-safe.
1870 int erl_drv_output_term(ErlDrvTermData port,
1872 ErlDrvTermData* term, int n)
1873 Sends data in the special driver term format to the port owner
1875 process. This is a fast way to deliver term data from a driver.
1876 It needs no binary conversion, so the port owner process re‐
1877 ceives data as normal Erlang terms. The erl_drv_send_term func‐
1878 tions can be used for sending to any process on the local node.
1879 Note:
1881 Parameter port is not an ordinary port handle, but a port handle
1882 converted using driver_mk_port.
1883 Parameter term points to an array of ErlDrvTermData with n ele‐
1886 ments. This array contains terms described in the driver term
1887 format. Every term consists of 1-4 elements in the array. The
1888 first term has a term type and then arguments. Parameter port
1889 specifies the sending port.
1890 Tuples, maps, and lists (except strings, see below) are built in
1892 reverse polish notation, so that to build a tuple, the elements
1893 are specified first, and then the tuple term, with a count.
1894 Likewise for lists and maps.
1895 * A tuple must be specified with the number of elements. (The
1897 elements precede the ERL_DRV_TUPLE term.)
1898 * A map must be specified with the number of key-value pairs
1900 N. The key-value pairs must precede the ERL_DRV_MAP in this
1901 order: key1,value1,key2,value2,...,keyN,valueN. Duplicate
1902 keys are not allowed.
1903 * A list must be specified with the number of elements, in‐
1905 cluding the tail, which is the last term preceding
1906 ERL_DRV_LIST.
1907 The special term ERL_DRV_STRING_CONS is used to "splice" in a
1909 string in a list, a string specified this way is not a list in
1910 itself, but the elements are elements of the surrounding list.
1911 Term type Arguments
1913 --------- ---------
1914 ERL_DRV_NIL
1915 ERL_DRV_ATOM ErlDrvTermData atom (from driver_mk_atom(char *string))
1916 ERL_DRV_INT ErlDrvSInt integer
1917 ERL_DRV_UINT ErlDrvUInt integer
1918 ERL_DRV_INT64 ErlDrvSInt64 *integer_ptr
1919 ERL_DRV_UINT64 ErlDrvUInt64 *integer_ptr
1920 ERL_DRV_PORT ErlDrvTermData port (from driver_mk_port(ErlDrvPort port))
1921 ERL_DRV_BINARY ErlDrvBinary *bin, ErlDrvUInt len, ErlDrvUInt offset
1922 ERL_DRV_BUF2BINARY char *buf, ErlDrvUInt len
1923 ERL_DRV_STRING char *str, int len
1924 ERL_DRV_TUPLE int sz
1925 ERL_DRV_LIST int sz
1926 ERL_DRV_PID ErlDrvTermData pid (from driver_connected(ErlDrvPort port)
1927 or driver_caller(ErlDrvPort port))
1928 ERL_DRV_STRING_CONS char *str, int len
1929 ERL_DRV_FLOAT double *dbl
1930 ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
1931 ERL_DRV_MAP int sz
1932 The unsigned integer data type ErlDrvUInt and the signed integer
1934 data type ErlDrvSInt are 64 bits wide on a 64-bit runtime system
1935 and 32 bits wide on a 32-bit runtime system. They were intro‐
1936 duced in ERTS 5.6 and replaced some of the int arguments in the
1937 list above.
1938 The unsigned integer data type ErlDrvUInt64 and the signed inte‐
1940 ger data type ErlDrvSInt64 are always 64 bits wide. They were
1941 introduced in ERTS 5.7.4.
1942 To build the tuple {tcp, Port, [100 | Binary]}, the following
1944 call can be made.
1945 ErlDrvBinary* bin = ...
1947 ErlDrvPort port = ...
1948 ErlDrvTermData spec[] = {
1949 ERL_DRV_ATOM, driver_mk_atom("tcp"),
1950 ERL_DRV_PORT, driver_mk_port(drvport),
1951 ERL_DRV_INT, 100,
1952 ERL_DRV_BINARY, bin, 50, 0,
1953 ERL_DRV_LIST, 2,
1954 ERL_DRV_TUPLE, 3,
1955 };
1956 erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0]));
1957 Here bin is a driver binary of length at least 50 and drvport is
1959 a port handle. Notice that ERL_DRV_LIST comes after the elements
1960 of the list, likewise ERL_DRV_TUPLE.
1961 The ERL_DRV_STRING_CONS term is a way to construct strings. It
1963 works differently from how ERL_DRV_STRING works.
1964 ERL_DRV_STRING_CONS builds a string list in reverse order (as
1965 opposed to how ERL_DRV_LIST works), concatenating the strings
1966 added to a list. The tail must be specified before
1967 ERL_DRV_STRING_CONS.
1968 ERL_DRV_STRING constructs a string, and ends it. (So it is the
1970 same as ERL_DRV_NIL followed by ERL_DRV_STRING_CONS.)
1971 /* to send [x, "abc", y] to the port: */
1973 ErlDrvTermData spec[] = {
1974 ERL_DRV_ATOM, driver_mk_atom("x"),
1975 ERL_DRV_STRING, (ErlDrvTermData)"abc", 3,
1976 ERL_DRV_ATOM, driver_mk_atom("y"),
1977 ERL_DRV_NIL,
1978 ERL_DRV_LIST, 4
1979 };
1980 erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0]));
1981 /* to send "abc123" to the port: */
1983 ErlDrvTermData spec[] = {
1984 ERL_DRV_NIL, /* with STRING_CONS, the tail comes first */
1985 ERL_DRV_STRING_CONS, (ErlDrvTermData)"123", 3,
1986 ERL_DRV_STRING_CONS, (ErlDrvTermData)"abc", 3,
1987 };
1988 erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0]));
1989 The ERL_DRV_EXT2TERM term type is used for passing a term en‐
1991 coded with the external format, that is, a term that has been
1992 encoded by erlang:term_to_binary, erl_interface:ei(3), and so
1993 on. For example, if binp is a pointer to an ErlDrvBinary that
1994 contains term {17, 4711} encoded with the external format, and
1995 you want to wrap it in a two-tuple with the tag my_tag, that is,
1996 {my_tag, {17, 4711}}, you can do as follows:
1997 ErlDrvTermData spec[] = {
1999 ERL_DRV_ATOM, driver_mk_atom("my_tag"),
2000 ERL_DRV_EXT2TERM, (ErlDrvTermData) binp->orig_bytes, binp->orig_size
2001 ERL_DRV_TUPLE, 2,
2002 };
2003 erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0]));
2004 To build the map #{key1 => 100, key2 => {200, 300}}, the follow‐
2006 ing call can be made.
2007 ErlDrvPort port = ...
2009 ErlDrvTermData spec[] = {
2010 ERL_DRV_ATOM, driver_mk_atom("key1"),
2011 ERL_DRV_INT, 100,
2012 ERL_DRV_ATOM, driver_mk_atom("key2"),
2013 ERL_DRV_INT, 200,
2014 ERL_DRV_INT, 300,
2015 ERL_DRV_TUPLE, 2,
2016 ERL_DRV_MAP, 2
2017 };
2018 erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0]));
2019 If you want to pass a binary and do not already have the content
2021 of the binary in an ErlDrvBinary, you can benefit from using
2022 ERL_DRV_BUF2BINARY instead of creating an ErlDrvBinary through
2023 driver_alloc_binary and then pass the binary through ERL_DRV_BI‐
2024 NARY. The runtime system often allocates binaries smarter if
2025 ERL_DRV_BUF2BINARY is used. However, if the content of the bi‐
2026 nary to pass already resides in an ErlDrvBinary, it is normally
2027 better to pass the binary using ERL_DRV_BINARY and the ErlDrvBi‐
2028 nary in question.
2029 The ERL_DRV_UINT, ERL_DRV_BUF2BINARY, and ERL_DRV_EXT2TERM term
2031 types were introduced in ERTS 5.6.
2032 This function is thread-safe.
2034 int erl_drv_putenv(const char *key, char
2036 *value)
2037 Sets the value of an environment variable.
2039 key is a NULL-terminated string containing the name of the envi‐
2041 ronment variable.
2042 value is a NULL-terminated string containing the new value of
2044 the environment variable.
2045 Returns 0 on success, otherwise a value != 0.
2047 Note:
2049 The result of passing the empty string ("") as a value is plat‐
2050 form-dependent. On some platforms the variable value is set to
2051 the empty string, on others the environment variable is removed.
2052 Warning:
2055 This function modifies the emulated environment used by
2056 os:putenv/2 and not the environment used by libc's putenv(3) or
2057 similar. Drivers that require that these are in sync will need
2058 to do so themselves, but keep in mind that they are segregated
2059 for a reason; putenv(3) and its friends are not thread-safe and
2060 may cause unrelated code to misbehave or crash the emulator.
2061 This function is thread-safe.
2064 ErlDrvRWLock *erl_drv_rwlock_create(char
2066 *name)
2067 Creates an rwlock and returns a pointer to it.
2069 name is a string identifying the created rwlock. It is used to
2071 identify the rwlock in debug functionality (see note about the
2072 lock checker).
2073 Returns NULL on failure. The driver creating the rwlock is re‐
2075 sponsible for destroying it before the driver is unloaded.
2076 This function is thread-safe.
2078 void erl_drv_rwlock_destroy(ErlDrvRWLock
2080 *rwlck)
2081 Destroys an rwlock previously created by erl_drv_rwlock_create.
2083 The rwlock must be in an unlocked state before it is destroyed.
2084 rwlck is a pointer to an rwlock to destroy.
2086 This function is thread-safe.
2088 char *erl_drv_rwlock_name(ErlDrvRWLock
2090 *rwlck)
2091 Returns a pointer to the name of the rwlock.
2093 rwlck is a pointer to an initialized rwlock.
2095 Note:
2097 This function is intended for debugging purposes only.
2098 void erl_drv_rwlock_rlock(ErlDrvRWLock
2101 *rwlck)
2102 Read locks an rwlock. The calling thread is blocked until the
2104 rwlock has been read locked. A thread that currently has read or
2105 read/write locked the rwlock cannot lock the same rwlock again.
2106 rwlck is a pointer to the rwlock to read lock.
2108 Warning:
2110 If you leave an rwlock locked in an emulator thread when you let
2111 the thread out of your control, you will very likely deadlock
2112 the whole emulator.
2113 This function is thread-safe.
2116 void erl_drv_rwlock_runlock(ErlDrvRWLock
2118 *rwlck)
2119 Read unlocks an rwlock. The rwlock currently must be read locked
2121 by the calling thread.
2122 rwlck is a pointer to an rwlock to read unlock.
2124 This function is thread-safe.
2126 void erl_drv_rwlock_rwlock(ErlDrvRWLock
2128 *rwlck)
2129 Read/write locks an rwlock. The calling thread is blocked until
2131 the rwlock has been read/write locked. A thread that currently
2132 has read or read/write locked the rwlock cannot lock the same
2133 rwlock again.
2134 rwlck is a pointer to an rwlock to read/write lock.
2136 Warning:
2138 If you leave an rwlock locked in an emulator thread when you let
2139 the thread out of your control, you will very likely deadlock
2140 the whole emulator.
2141 This function is thread-safe.
2144 void erl_drv_rwlock_rwunlock(ErlDrvRWLock
2146 *rwlck)
2147 Read/write unlocks an rwlock. The rwlock currently must be
2149 read/write locked by the calling thread.
2150 rwlck is a pointer to an rwlock to read/write unlock.
2152 This function is thread-safe.
2154 int erl_drv_rwlock_tryrlock(ErlDrvRWLock
2156 *rwlck)
2157 Tries to read lock an rwlock.
2159 rwlck is a pointer to an rwlock to try to read lock.
2161 Returns 0 on success, otherwise EBUSY. A thread that currently
2163 has read or read/write locked the rwlock cannot try to lock the
2164 same rwlock again.
2165 Warning:
2167 If you leave an rwlock locked in an emulator thread when you let
2168 the thread out of your control, you will very likely deadlock
2169 the whole emulator.
2170 This function is thread-safe.
2173 int erl_drv_rwlock_tryrwlock(ErlDrvRWLock
2175 *rwlck)
2176 Tries to read/write lock an rwlock. A thread that currently has
2178 read or read/write locked the rwlock cannot try to lock the same
2179 rwlock again.
2180 rwlckis pointer to an rwlock to try to read/write lock.
2182 Returns 0 on success, otherwise EBUSY.
2184 Warning:
2186 If you leave an rwlock locked in an emulator thread when you let
2187 the thread out of your control, you will very likely deadlock
2188 the whole emulator.
2189 This function is thread-safe.
2192 int erl_drv_send_term(ErlDrvTermData port,
2194 ErlDrvTermData receiver, ErlDrvTermData* term, int n)
2195 This function is the only way for a driver to send data to other
2197 processes than the port owner process. Parameter receiver speci‐
2198 fies the process to receive the data.
2199 Note:
2201 Parameter port is not an ordinary port handle, but a port handle
2202 converted using driver_mk_port.
2203 Parameters port, term, and n work as in erl_drv_output_term.
2206 This function is thread-safe.
2208 void erl_drv_set_os_pid(ErlDrvPort port,
2210 ErlDrvSInt pid)
2211 Sets the os_pid seen when doing erlang:port_info/2 on this port.
2213 port is the port handle of the port (driver instance) to set the
2215 pid on. pidis the pid to set.
2216 int erl_drv_thread_create(char *name, ErlDrvTid
2218 *tid, void * (*func)(void *), void *arg, ErlDrvThreadOpts
2219 *opts)
2220 Creates a new thread.
2222 name:
2224 A string identifying the created thread. It is used to iden‐
2225 tify the thread in planned future debug functionality.
2226 tid:
2228 A pointer to a thread identifier variable.
2229 func:
2231 A pointer to a function to execute in the created thread.
2232 arg:
2234 A pointer to argument to the func function.
2235 opts:
2237 A pointer to thread options to use or NULL.
2238 Returns 0 on success, otherwise an errno value is returned to
2240 indicate the error. The newly created thread begins executing in
2241 the function pointed to by func, and func is passed arg as argu‐
2242 ment. When erl_drv_thread_create returns, the thread identifier
2243 of the newly created thread is available in *tid. opts can be
2244 either a NULL pointer, or a pointer to an ErlDrvThreadOpts
2245 structure. If opts is a NULL pointer, default options are used,
2246 otherwise the passed options are used.
2247 Warning:
2249 You are not allowed to allocate the ErlDrvThreadOpts structure
2250 by yourself. It must be allocated and initialized by
2251 erl_drv_thread_opts_create.
2252 The created thread terminates either when func returns or if
2255 erl_drv_thread_exit is called by the thread. The exit value of
2256 the thread is either returned from func or passed as argument to
2257 erl_drv_thread_exit. The driver creating the thread is responsi‐
2258 ble for joining the thread, through erl_drv_thread_join, before
2259 the driver is unloaded. "Detached" threads cannot be created,
2260 that is, threads that do not need to be joined.
2261 Warning:
2263 All created threads must be joined by the driver before it is
2264 unloaded. If the driver fails to join all threads created before
2265 it is unloaded, the runtime system most likely crashes when the
2266 driver code is unloaded.
2267 This function is thread-safe.
2270 void erl_drv_thread_exit(void
2272 *exit_value)
2273 Terminates the calling thread with the exit value passed as ar‐
2275 gument. exit_value is a pointer to an exit value or NULL.
2276 You are only allowed to terminate threads created with
2278 erl_drv_thread_create.
2279 The exit value can later be retrieved by another thread through
2281 erl_drv_thread_join.
2282 This function is thread-safe.
2284 int erl_drv_thread_join(ErlDrvTid tid, void
2286 **exit_value)
2287 Joins the calling thread with another thread, that is, the call‐
2289 ing thread is blocked until the thread identified by tid has
2290 terminated.
2291 tid is the thread identifier of the thread to join. exit_value
2293 is a pointer to a pointer to an exit value, or NULL.
2294 Returns 0 on success, otherwise an errno value is returned to
2296 indicate the error.
2297 A thread can only be joined once. The behavior of joining more
2299 than once is undefined, an emulator crash is likely. If
2300 exit_value == NULL, the exit value of the terminated thread is
2301 ignored, otherwise the exit value of the terminated thread is
2302 stored at *exit_value.
2303 This function is thread-safe.
2305 char *erl_drv_thread_name(ErlDrvTid
2307 tid)
2308 Returns a pointer to the name of the thread.
2310 tid is a thread identifier.
2312 Note:
2314 This function is intended for debugging purposes only.
2315 ErlDrvThreadOpts *erl_drv_thread_opts_create(char *name)
2318 Allocates and initializes a thread option structure.
2320 name is a string identifying the created thread options. It is
2322 used to identify the thread options in planned future debug
2323 functionality.
2324 Returns NULL on failure. A thread option structure is used for
2326 passing options to erl_drv_thread_create. If the structure is
2327 not modified before it is passed to erl_drv_thread_create, the
2328 default values are used.
2329 Warning:
2331 You are not allowed to allocate the ErlDrvThreadOpts structure
2332 by yourself. It must be allocated and initialized by
2333 erl_drv_thread_opts_create.
2334 This function is thread-safe.
2337 void erl_drv_thread_opts_destroy(ErlDrvThreadOpts *opts)
2339 Destroys thread options previously created by
2341 erl_drv_thread_opts_create.
2342 opts is a pointer to thread options to destroy.
2344 This function is thread-safe.
2346 ErlDrvTid erl_drv_thread_self(void)
2348 Returns the thread identifier of the calling thread.
2350 This function is thread-safe.
2352 ErlDrvTime erl_drv_time_offset(ErlDrvTimeUnit
2354 time_unit)
2355 Returns the current time offset between Erlang monotonic time
2357 and Erlang system time converted into the time_unit passed as
2358 argument.
2359 time_unit is time unit of returned value.
2361 Returns ERL_DRV_TIME_ERROR if called with an invalid time unit
2363 argument, or if called from a thread that is not a scheduler
2364 thread.
2365 See also ErlDrvTime and ErlDrvTimeUnit.
2367 void *erl_drv_tsd_get(ErlDrvTSDKey
2369 key)
2370 Returns the thread-specific data associated with key for the
2372 calling thread.
2373 key is a thread-specific data key.
2375 Returns NULL if no data has been associated with key for the
2377 calling thread.
2378 This function is thread-safe.
2380 int erl_drv_tsd_key_create(char *name,
2382 ErlDrvTSDKey *key)
2383 Creates a thread-specific data key.
2385 name is a string identifying the created key. It is used to
2387 identify the key in planned future debug functionality.
2388 key is a pointer to a thread-specific data key variable.
2390 Returns 0 on success, otherwise an errno value is returned to
2392 indicate the error. The driver creating the key is responsible
2393 for destroying it before the driver is unloaded.
2394 This function is thread-safe.
2396 void erl_drv_tsd_key_destroy(ErlDrvTSDKey
2398 key)
2399 Destroys a thread-specific data key previously created by
2401 erl_drv_tsd_key_create. All thread-specific data using this key
2402 in all threads must be cleared (see erl_drv_tsd_set) before the
2403 call to erl_drv_tsd_key_destroy.
2404 key is a thread-specific data key to destroy.
2406 Warning:
2408 A destroyed key is very likely to be reused soon. Therefore, if
2409 you fail to clear the thread-specific data using this key in a
2410 thread before destroying the key, you will very likely get unex‐
2411 pected errors in other parts of the system.
2412 This function is thread-safe.
2415 void erl_drv_tsd_set(ErlDrvTSDKey key, void
2417 *data)
2418 Sets thread-specific data associated with key for the calling
2420 thread. You are only allowed to set thread-specific data for
2421 threads while they are fully under your control. For example, if
2422 you set thread-specific data in a thread calling a driver call‐
2423 back function, it must be cleared, that is, set to NULL, before
2424 returning from the driver callback function.
2425 key is a thread-specific data key.
2427 data is a pointer to data to associate with key in the calling
2429 thread.
2430 Warning:
2432 If you fail to clear thread-specific data in an emulator thread
2433 before letting it out of your control, you might never be able
2434 to clear this data with later unexpected errors in other parts
2435 of the system as a result.
2436 This function is thread-safe.
2439 char *erl_errno_id(int error)
2441 Returns the atom name of the Erlang error, given the error num‐
2443 ber in error. The error atoms are einval, enoent, and so on. It
2444 can be used to make error terms from the driver.
2445 int remove_driver_entry(ErlDrvEntry
2447 *de)
2448 Removes a driver entry de previously added with add_driver_en‐
2450 try.
2451 Driver entries added by the erl_ddll Erlang interface cannot be
2453 removed by using this interface.
2454 void set_busy_port(ErlDrvPort port, int
2456 on)
2457 Sets and unsets the busy state of the port. If on is non-zero,
2459 the port is set to busy. If it is zero, the port is set to not
2460 busy. You typically want to combine this feature with the busy
2461 port message queue functionality.
2462 Processes sending command data to the port are suspended if ei‐
2464 ther the port or the port message queue is busy. Suspended pro‐
2465 cesses are resumed when neither the port or the port message
2466 queue is busy. Command data is in this context data passed to
2467 the port using either Port ! {Owner, {command, Data}} or
2468 port_command/[2,3].
2469 If the ERL_DRV_FLAG_SOFT_BUSY has been set in the driver_entry,
2471 data can be forced into the driver through erlang:port_com‐
2472 mand(Port, Data, [force]) even if the driver has signaled that
2473 it is busy.
2474 For information about busy port message queue functionality, see
2476 erl_drv_busy_msgq_limits.
2477 void set_port_control_flags(ErlDrvPort port,
2479 int flags)
2480 Sets flags for how the control driver entry function will return
2482 data to the port owner process. (The control function is called
2483 from erlang:port_control/3.)
2484 Currently there are only two meaningful values for flags: 0
2486 means that data is returned in a list, and PORT_CONTROL_FLAG_BI‐
2487 NARY means data is returned as a binary from control.
2488
2490 driver_entry(3), erlang(3), erl_ddll(3), section How to Implement an
2491 Alternative Carrier for the Erlang Distribution in the User's Guide
2492Ericsson AB erts 12.3.2.1 erl_driver(3)