# erl_driver

### MODULE

erl_driver

### MODULE SUMMARY

API functions for an erlang driver

### DESCRIPTION

As of erts version 5.5.3 the driver interface has been extended (see extended marker). The extended interface introduce version management, the possibility to pass capability flags (see driver flags) to the runtime system at driver initialization, and some new driver API functions.

| Old drivers (compiled with an `erl_driver.h` from an earlier erts version than 5.5.3) have to be recompiled (but does not have to use the extended interface).

The driver calls back to the emulator, using the API functions declared in `erl_driver.h`. They are used for outputting data from the driver, using timers, etc.

A driver is a library with a set of function that the emulator calls, in response to erlang functions and message sending. There may be multiple instances of a driver, each instance is connected to an erlang port. Every port has a port owner process. Communication with the port is normally done through the port owner process.

Most of the functions takes the `port` handle as an argument. This identifies the driver instance. Note that this port handle must be stored by the driver, it is not given when the driver is called from the emulator (see driver_entry).

Some of the functions takes a parameter of type `ErlDrvBinary`, a driver binary. It should be both allocated and freed by the caller. Using a binary directly avoid one extra copying of data.

Many of the output functions has a "header buffer", with `hbuf` and `hlen` parameters. This buffer is sent as a list before the binary (or list, depending on port mode) that is sent. This is convenient when matching on messages received from the port. (Although in the latest versions of erlang, there is the binary syntax, that enables you to match on the beginning of a binary.)

In the runtime system with SMP support, drivers are locked either on driver level or port level (driver instance level). By default driver level locking will be used, i.e., only one emulator thread will execute code in the driver at a time. If port level locking is used, multiple emulator threads may execute code in the driver at the same time. There will only be one thread at a time calling driver call-backs corresponding to the same port, though. In order to enable port level locking set the `ERL_DRV_FLAG_USE_PORT_LOCKING` driver flag in the driver_entry used by the driver. When port level locking is used it is the responsibility of the driver writer to synchronize all accesses to data shared by the ports (driver instances).

Most drivers written before the runtime system with SMP support existed will be able to run in the runtime system with SMP support without being rewritten if driver level locking is used.

| It is assumed that drivers does not access other drivers. If drivers should access each other they have to provide their own mechanism for thread safe synchronization. Such "inter driver communication" is strongly discouraged.

Previously, in the runtime system without SMP support, specific driver call-backs were always called from the same thread. This is not the case in the runtime system with SMP support. Regardless of locking scheme used, calls to driver call-backs may be made from different threads, e.g., two consecutive calls to exactly the same call-back for exactly the same port may be made from two different threads. This will for most drivers not be a problem, but it might. Drivers that depend on all call-backs being called in the same thread, have to be rewritten before being used in the runtime system with SMP support.

| Regardless of locking scheme used, calls to driver call-backs may be made from different threads.

Most functions in this API are not thread-safe, i.e., they may not be called from an arbitrary thread. Function that are not documented as thread-safe may only be called from driver call-backs or function calls descending from a driver call-back call. Note that driver call-backs may be called from different threads. This, however, is not a problem for any functions in this API, since the emulator have control over these threads.

| Functions not explicitly documented as thread-safe are not thread-safe. Also note that some functions are only thread safe when used in a runtime system with SMP support.

### Functionality

All functions that a driver needs to do with erlang are performed through driver API functions. There are functions for the following functionality:

Timer functions
  Timer functions are used to control the timer that a driver may use. The timer will have the emulator call the timeout entry function after a specified time. Only one timer is available for each driver instance.
Queue handling
  Every driver instance has an associated queue. This queue is a `SysIOVec` that works as a buffer. It's mostly used for the driver to buffer data that should be written to a device, it is a byte stream. If the port owner process closes the driver, and the queue is not empty, the driver will not be closed. This enables the driver to flush its buffers before closing.
  The queue can be manipulated from arbitrary threads if a port data lock is used. See documentation of the ErlDrvPDL type for more information.
Output functions
  With the output functions, the driver sends data back the emulator. They will be received as messages by the port owner process, see `open_port/2`. The vector function and the function taking a driver binary is faster, because thet avoid copying the data buffer. There is also a fast way of sending terms from the driver, without going through the binary term format.
Failure
  The driver can exit and signal errors up to erlang. This is only for severe errors, when the driver can't possibly keep open.
Asynchronous calls
  The latest erlang versions (R7B and later) has provision for asynchonous function calls, using a thread pool provided by erlang. There is also a select call, that can be used for asynchronous drivers.
Adding / remove drivers
  A driver can add and later remove drivers.
Monitoring processes
  A driver can monitor a process that does not own a port.
Version management
  Version management is enabled for drivers that have set the extended_marker field of their driver_entry to `ERL_DRV_EXTENDED_MARKER`. `erl_driver.h` defines `ERL_DRV_EXTENDED_MARKER`, `ERL_DRV_EXTENDED_MAJOR_VERSION`, and `ERL_DRV_EXTENDED_MINOR_VERSION`. `ERL_DRV_EXTENDED_MAJOR_VERSION` will be incremented when driver incompatible changes are made to the Erlang runtime system. Normally it will suffice to recompile drivers when the `ERL_DRV_EXTENDED_MAJOR_VERSION` has changed, but it could, under rare circumstances, mean that drivers have to be slightly modified. If so, this will of course be documented. `ERL_DRV_EXTENDED_MINOR_VERSION` will be incremented when new features are added. The runtime system use the minor version of the driver to determine what features to use. The runtime system will refuse to load driver if the major versions differ, or if the major versions are equal and the minor version used by the driver is greater than the one used by the runtime system.

### EXPORTS

`ErlDrvSysInfo`

Types:

`int driver_major_version`
`int driver_minor_version`
`char *erts_version`
`char *otp_release`
`int thread_support`
`int smp_support`

The `ErlDrvSysInfo` structure is used for storage of information about the Erlang runtime system. driver_system_info() will write the system information when passed a reference to a `ErlDrvSysInfo` structure. A description of the fields in the structure follow:

driver_major_version
  The value of ERL_DRV_EXTENDED_MAJOR_VERSION when the runtime system was compiled. This value is the same as the value of ERL_DRV_EXTENDED_MAJOR_VERSION used when compiling the driver; otherwise, the runtime system would have refused to load the driver.
driver_minor_version
  The value of ERL_DRV_EXTENDED_MINOR_VERSION when the runtime system was compiled. This value might differ from the value of ERL_DRV_EXTENDED_MINOR_VERSION used when compiling the driver.
erts_version
  A string containting the version number of the runtime system (the same as erlang:system_info(version)).
otp_release
  A string containting the OTP release number (the same as erlang:system_info(otp_release)).
thread_support
  A value `!= 0` if the runtime system has thread support; otherwise, `0`.
smp_support
  A value `!= 0` if the runtime system has SMP support; otherwise, `0`.

`ErlDrvBinary`

Types:

`int orig_size`
`char orig_bytes[]`

The `ErlDrvBinary` structure is a binary, as sent between the emulator and the driver. All binaries are reference counted; when `driver_binary_free` is called, the reference count is decremented, when it reaches zero, the binary is deallocated. The `orig_size` is the size of the binary, and `orig_bytes` is the buffer. The `ErlDrvBinary` does not have a fixed size, its size is `orig_size + 2 * sizeof(int)`.

| The `refc` field has been removed. The reference count of an `ErlDrvBinary` is now stored elsewhere. The reference count of an `ErlDrvBinary` can be accessed via driver_binary_get_refc(), driver_binary_inc_refc(), and driver_binary_dec_refc().

Some driver calls, such as `driver_enq_binary`, increments the driver reference count, and others, such as `driver_deq` decrements it.

Using a driver binary instead of a normal buffer, is often faster, since the emulator doesn't need to copy the data, only the pointer is used.

A driver binary allocated in the driver, with `driver_alloc_binary`, should be freed in the driver, with `driver_free_binary`. (Note that this doesn't necessarily deallocate it, if the driver is still referred in the emulator, the ref-count will not go to zero.)

Driver binaries are used in the `driver_output2` and `driver_outputv` calls, and in the queue. Also the driver call-back outputv uses driver binaries.

If the driver of some reason or another, wants to keep a driver binary around, in a static variable for instance, the refernece count should be incremented, and the binary can later be freed in the stop call-back, with `driver_free_binary`.

Note that since a driver binary is shared by the driver and the emulator, a binary received from the emulator or sent to the emulator, shouldn't be changed by the driver.

From erts version 5.5 (OTP release R11B), orig_bytes is guaranteed to be properly aligned for storage of an array of doubles (usually 8-byte aligned).

`ErlDrvData`

The `ErlDrvData` is a handle to driver-specific data, passed to the driver call-backs. It is a pointer, and is most often casted to a specific pointer in the driver.

`SysIOVec`

This is a system I/O vector, as used by `writev` on unix and `WSASend` on Win32. It is used in `ErlIOVec`.

`ErlIOVec`

Types:

`int vsize`
`int size`
`SysIOVec* iov`
`ErlDrvBinary** binv`

The I/O vector used by the emulator and drivers, is a list of binaries, with a `SysIOVec` pointing to the buffers of the binaries. It is used in `driver_outputv` and the outputv driver call-back. Also, the driver queue is an `ErlIOVec`.

`ErlDrvMonitor`

When a driver creates a monitor for a process, a `ErlDrvMonitor` is filled in. This is an opaque datatype which can be assigned to but not compared without using the supplied compare function (i.e. it behaves like a struct).

The driver writer should provide the memory for storing the monitor when calling driver_monitor_process. The address of the data is not stored outside of the driver, so the `ErlDrvMonitor` can be used as any other datum, it can be copied, moved in memory, forgotten etc.

`ErlDrvNowData`

The `ErlDrvNowData` structure holds a timestamp consisting of three values measured from some arbitrary point in the past. The three structure members are:

megasecs
  The number of whole megaseconds elapsed since the arbitrary point in time
secs
  The number of whole seconds elapsed since the arbitrary point in time
microsecs
  The number of whole microseconds elapsed since the arbitrary point in time

`ErlDrvPDL`

If certain port specific data have to be accessed from other threads than those calling the driver call-backs, a port data lock can be used in order to synchronize the operations on the data. Currently, the only port specific data that the the emulator associates with the port data lock is the driver queue.

Normally a driver instance does not have a port data lock. If the driver instance want to use a port data lock, it has to create the port data lock by calling driver_pdl_create(). NOTE: Once the port data lock has been created, every access to data associated with the port data lock have to be done while having the port data lock locked. The port data lock is locked, and unlocked, respectively, by use of driver_pdl_lock(), and driver_pdl_unlock().

A port data lock is reference counted, and when the reference count reach zero, it will be destroyed. The emulator will at least increment the reference count once when the lock is created and decrement it once when the port associated with the lock terminates. The emulator will also increment the reference count when an async job is enqueued and decrement it after an async job has been invoked, or canceled. Besides this, it is the responsibility of the driver to ensure that the reference count does not reach zero before the last use of the lock by the driver has been made. The reference count can be read, incremented, and decremented, respectively, by use of driver_pdl_get_refc(), driver_pdl_inc_refc(), and driver_pdl_dec_refc().

`void driver_system_info(ErlDrvSysInfo *sys_info_ptr, size_t size)`

This function will write information about the Erlang runtime system into the ErlDrvSysInfo structure referred to by the first argument. The second argument should be the size of the ErlDrvSysInfo structure, i.e., `sizeof(ErlDrvSysInfo)`.

See the documentation of the ErlDrvSysInfo structure for information about specific fields.

`int driver_output(ErlDrvPort port, char *buf, int len)`

The `driver_output` function is used to send data from the driver up to the emulator. The data will be received as terms or binary data, depending on how the driver port was opened.

The data is queued in the port owner process' message queue. Note that this does not yield to the emulator. (Since the driver and the emulator runs in the same thread.)

The parameter `buf` points to the data to send, and `len` is the number of bytes.

The return value for all output functions is 0. (Unless the driver is used for distribution, in which case it can fail and return -1. For normal use, the output function always returns 0.)

`int driver_output2(ErlDrvPort port, char *hbuf, int hlen, char *buf, int len)`

The `driver_output2` function first sends `hbuf` (length in `hlen`) data as a list, regardless of port settings. Then `buf` is sent as a binary or list. E.g. if `hlen` is 3 then the port owner process will receive `[H1, H2, H3 | T]`.

The point of sending data as a list header, is to facilitate matching on the data received.

The return value is 0 for normal use.

`int driver_output_binary(ErlDrvPort port, char *hbuf, int hlen, ErlDrvBinary* bin, int offset, int len)`

This function sends data to port owner process from a driver binary, it has a header buffer (`hbuf` and `hlen`) just like `driver_output2`. The `hbuf` parameter can be `NULL`.

The parameter `offset` is an offset into the binary and `len` is the number of bytes to send.

Driver binaries are created with `driver_alloc_binary`.

The data in the header is sent as a list and the binary as an erlang binary in the tail of the list.

E.g. if `hlen` is 2, then the port owner process will receive `[H1, H2 | <<T>>]`.

The return value is 0 for normal use.

Note that, using the binary syntax in erlang, the driver application can match the header directly from the binary, so the header can be put in the binary, and hlen can be set to 0.

`int driver_outputv(ErlDrvPort port, char* hbuf, int hlen, ErlIOVec *ev, int skip)`

This function sends data from an IO vector, `ev`, to the port owner process. It has a header buffer (`hbuf` and `hlen`), just like `driver_output2`.

The `skip` parameter is a number of bytes to skip of the `ev` vector from the head.

You get vectors of `ErlIOVec` type from the driver queue (see below), and the outputv driver entry function. You can also make them yourself, if you want to send several `ErlDriverBinary` buffers at once. Often it is faster to use `driver_output` or `driver_output_binary`.

E.g. if `hlen` is 2 and `ev` points to an array of three binaries, the port owner process will receive `[H1, H2, <<B1>>, <<B2>> | <<B3>>]`.

The return value is 0 for normal use.

The comment for `driver_output_binary` applies for `driver_outputv` too.

`int driver_vec_to_buf(ErlIOVec *ev, char *buf, int len)`

This function collects several segments of data, referenced by `ev`, by copying them in order to the buffer `buf`, of the size `len`.

If the data is to be sent from the driver to the port owner process, it is faster to use `driver_outputv`.

The return value is the space left in the buffer, i.e. if the `ev` contains less than `len` bytes it's the difference, and if `ev` contains `len` bytes or more, it's 0. This is faster if there is more than one header byte, since the binary syntax can construct integers directly from the binary.

`int driver_set_timer(ErlDrvPort port, unsigned long time)`

This function sets a timer on the driver, which will count down and call the driver when it is timed out. The `time` parameter is the time in milliseconds before the timer expires.

When the timer reaches 0 and expires, the driver entry function timeout is called.

Note that there is only one timer on each driver instance; setting a new timer will replace an older one.

Return value i 0 (-1 only when the `timeout` driver function is `NULL`).

`int driver_cancel_timer(ErlDrvPort port)`

This function cancels a timer set with `driver_set_timer`.

The return value is 0.

`int driver_read_timer(ErlDrvPort port, unsigned long *time_left)`

This function reads the current time of a timer, and places the result in `time_left`. This is the time in milliseconds, before the timeout will occur.

The return value is 0.

`int driver_get_now(ErlDrvNowData *now)`

This function reads a timestamp into the memory pointed to by the parameter `now`. See the description of ErlDrvNowData for specification of it's fields.

The return value is 0 unless the `now` pointer is not valid, in which case it is < 0.

`int driver_select(ErlDrvPort port, ErlDrvEvent event, int mode, int on)`

The `driver_select` is used by the driver to provide the emulator with an event to check for. This enables the emulator to call the driver when something has happened asynchronously.

The `event` parameter is used in the emulator cycle in a `select` call. If the event is set then the driver is called. The `mode` parameter can be either `ON_READ` or `ON_WRITE`, and specifies whether ready_output or ready_input will be called when the event is fired. Note that this is just a convention, they don't have to read or write anything.

The `on` parameter should be `1` for adding the event and `0` for removing it.

On unix systems, the function `select` is used. The `event` must be a socket or pipe (or other object that `select` can use).

On windows, the Win32 API function `WaitForMultipleObjects` is used. This places other restriction on the `event`. Refer to the Win32 SDK documentation.

The return value is 0 (Failure, -1, only if the `ready_input`/`ready_output` is `NULL`.

`void *driver_alloc(size_t size)`

This function allocates a memory block of the size specified in `size`, and returns it. This only fails on out of memory, in that case `NULL` is returned. (This is most often a wrapper for `malloc`).

Memory allocated must be explicitly freed. Every `driver_alloc` call must have a corresponding `driver_free`.

This function is thread-safe.

`void *driver_realloc(void *ptr, size_t size)`

This function resizes a memory block, either in place, or by allocating a new block, copying the data and freeing the old block. A pointer is returned to the reallocated memory. On failure (out of memory), `NULL` is returned. (This is most ofthen a wrapper for `realloc`.)

This function is thread-safe.

`void driver_free(void *ptr)`

This function frees the memory pointed to by `ptr`. The memory should have been allocated with `driver_alloc`. All allocated memory should be deallocated, just once. There is no garbage collection in drivers.

This function is thread-safe.

`ErlDrvBinary* driver_alloc_binary(int size)`

This function allocates a driver binary with a memory block of at least `size` bytes, and returns a pointer to it, or NULL on failure (out of memory). When a driver binary has been sent to the emulator, it shouldn't be altered. Every allocated binary should be freed.

Note that a driver binary has an internal reference counter, this means that calling `driver_free_binary` it may not actually dispose of it. If it's sent to the emulator, it may be referenced there.

The driver binary has a field, `orig_bytes`, which marks the start of the data in the binary.

This function is thread-safe.

`ErlDrvBinary* driver_realloc_binary(ErlDrvBinary *bin, int size)`

This function resizes a driver binary, while keeping the data. The resized driver binary is returned. On failure (out of memory), `NULL` is returned.

This function is only thread-safe when the emulator with SMP support is used.

`void driver_free_binary(ErlDrvBinary *bin)`

This function frees a driver binary `bin`, allocated previously with `driver_alloc_binary`. Since binaries in erlang are reference counted, the binary may still be around. Every call to `driver_alloc_binary` should have a matching call to `driver_free_binary`.

This function is only thread-safe when the emulator with SMP support is used.

`long driver_binary_get_refc(ErlDrvBinary *bin)`

Returns current reference count on `bin`.

This function is only thread-safe when the emulator with SMP support is used.

`long driver_binary_inc_refc(ErlDrvBinary *bin)`

Increments the reference count on `bin` and returns the reference count reached after the increment.

This function is only thread-safe when the emulator with SMP support is used.

`long driver_binary_dec_refc(ErlDrvBinary *bin)`

Decrements the reference count on `bin` and returns the reference count reached after the decrement.

This function is only thread-safe when the emulator with SMP support is used.

| You should normally decrement the reference count of a driver binary by calling driver_free_binary(). `driver_binary_dec_refc()` does not free the binary if the reference count reaches zero. Only use `driver_binary_dec_refc()` when you are sure not to reach a reference count of zero.

`int driver_enq(ErlDrvPort port, char* buf, int len)`

This function enqueues data in the driver queue. The data in `buf` is copied (`len` bytes) and placed at the end of the driver queue. The driver queue is normally used in a FIFO way.

The driver queue is available to queue output from the emulator to the driver (data from the driver to the emulator is queued by the emulator in normal erlang message queues). This can be useful if the driver has to wait for slow devices etc, and wants to yield back to the emulator. The driver queue is implemented as an ErlIOVec.

When the queue contains data, the driver won't close, until the queue is empty.

The return value is 0.

This function can be called from an arbitrary thread if a port data lock associated with the `port` is locked by the calling thread during the call.

`int driver_pushq(ErlDrvPort port, char* buf, int len)`

This function puts data at the head of the driver queue. The data in `buf` is copied (`len` bytes) and placed at the beginning of the queue.

The return value is 0.

This function can be called from an arbitrary thread if a port data lock associated with the `port` is locked by the calling thread during the call.

`int driver_deq(ErlDrvPort port, int size)`

This function dequeues data by moving the head pointer forward in the driver queue by `size` bytes. The data in the queue will be dealloced.

The return value is 0.

This function can be called from an arbitrary thread if a port data lock associated with the `port` is locked by the calling thread during the call.

`int driver_sizeq(ErlDrvPort port)`

This function returns the number of bytes currently in the driver queue.

This function can be called from an arbitrary thread if a port data lock associated with the `port` is locked by the calling thread during the call.

`int driver_enq_bin(ErlDrvPort port, ErlDrvBinary *bin, int offset, int len)`

This function enqueues a driver binary in the driver queue. The data in `bin` at `offset` with length `len` is placed at the end of the queue. This function is most often faster than `driver_enq`, because the data doesn't have to be copied.

This function can be called from an arbitrary thread if a port data lock associated with the `port` is locked by the calling thread during the call.

The return value is 0.

`int driver_pushq_bin(ErlDrvPort port, ErlDrvBinary *bin, int offset, int len)`

This function puts data in the binary `bin`, at `offset` with length `len` at the head of the driver queue. It is most often faster than `driver_pushq`, because the data doesn't have to be copied.

This function can be called from an arbitrary thread if a port data lock associated with the `port` is locked by the calling thread during the call.

The return value is 0.

`SysIOVec* driver_peekq(ErlDrvPort port, int *vlen)`

This function retrieves the driver queue as a pointer to an array of `SysIOVec`s. It also returns the number of elements in `vlen`. This is the only way to get data out of the queue.

Nothing is remove from the queue by this function, that must be done with `driver_deq`.

The returned array is suitable to use with the unix system call `writev`.

This function can be called from an arbitrary thread if a port data lock associated with the `port` is locked by the calling thread during the call.

`int driver_enqv(ErlDrvPort port, ErlIOVec *ev, int skip)`

This function enqueues the data in `ev`, skipping the first `skip` bytes of it, at the end of the driver queue. It is faster than `driver_enq`, because the data doesn't have to be copied.

The return value is 0.

This function can be called from an arbitrary thread if a port data lock associated with the `port` is locked by the calling thread during the call.

`int driver_pushqv(ErlDrvPort port, ErlIOVec *ev, int skip)`

This function puts the data in `ev`, skipping the first `skip` bytes of it, at the head of the driver queue. It is faster than `driver_pushq`, because the data doesn't have to be copied.

The return value is 0.

This function can be called from an arbitrary thread if a port data lock associated with the `port` is locked by the calling thread during the call.

`ErlDrvPDL driver_pdl_create(ErlDrvPort port)`

This function creates a port data lock associated with the `port`. NOTE: Once a port data lock has been created, it has to be locked during all operations on the driver queue of the `port`.

On success a newly created port data lock is returned. On failure `NULL` is returned. `driver_pdl_create()` will fail if `port` is invalid or if a port data lock already has been associated with the `port`.

`void driver_pdl_lock(ErlDrvPDL pdl)`

This function locks the port data lock passed as argument (`pdl`).

This function is thread-safe.

`void driver_pdl_unlock(ErlDrvPDL pdl)`

This function unlocks the port data lock passed as argument (`pdl`).

This function is thread-safe.

`long driver_pdl_get_refc(ErlDrvPDL pdl)`

This function returns the current reference count of the port data lock passed as argument (`pdl`).

This function is thread-safe.

`long driver_pdl_inc_refc(ErlDrvPDL pdl)`

This function increments the reference count of the port data lock passed as argument (`pdl`).

The current reference count after the increment has been performed is returned.

This function is thread-safe.

`long driver_pdl_dec_refc(ErlDrvPDL pdl)`

This function decrements the reference count of the port data lock passed as argument (`pdl`).

The current reference count after the decrement has been performed is returned.

This function is thread-safe.

`int driver_monitor_process(ErlDrvPort port, ErlDrvTermData process, ErlDrvMonitor *monitor)`

Start monitoring a process from a driver. When a process is monitored, a process exit will result in a call to the provided process_exit callback in the ErlDrvEntry structure. The `ErlDrvMonitor` structure is filled in, for later removal or compare.

The `process` parameter should be the return value of an earlier call to driver_caller or driver_connected call.

The function returns 0 on success, < 0 if no callback is provided and > 0 if the process is no longer alive.

`int driver_demonitor_process(ErlDrvPort port, const ErlDrvMonitor *monitor)`

This function cancels an monitor created earlier.

The function returns 0 if a monitor was removed and > 0 if the monitor did no longer exist.

`ErlDrvTermData driver_get_monitored_process(ErlDrvPort port, const ErlDrvMonitor *monitor)`

The function returns the process id associated with a living monitor. It can be used in the `process_exit` callback to get the process identification for the exiting process.

The function returns `driver_term_nil` if the monitor no longer exists.

`int driver_compare_monitors(const ErlDrvMonitor *monitor1, const ErlDrvMonitor *monitor2)`

This function is used to compare two `ErlDrvMonitor`s. It can also be used to imply some artificial order on monitors, for whatever reason.

The function returns 0 if `monitor1` and `monitor2` are equal, < 0 if `monitor1` is less than `monitor2` and > 0 if `monitor1` is greater than `monitor2`.

`void add_driver_entry(ErlDrvEntry *de)`

This function adds a driver entry to the list of drivers known by erlang. The init function of the `de` parameter is called.

| To use this function for adding drivers residing in dynamically loaded code is dangerous. If the driver code for the added driver resides in the same dynamically loaded module (i.e. `.so` file) as a normal dynamically loaded driver (loaded with the `erl_ddll` interface), the caller should call driver_lock_driver before adding driver entries. Use of this function is generally deprecated.

`int remove_driver_entry(ErlDrvEntry *de)`

This function removes a driver entry `de` previously added with `add_driver_entry`.

Driver entries added by the `erl_ddll` erlang interface can not be removed by using this interface.

`char* erl_errno_id(int error)`

This function returns the atom name of the erlang error, given the error number in `error`. Error atoms are: `einval`, `enoent`, etc. It can be used to make error terms from the driver.

`void set_busy_port(ErlDrvPort port, int on)`

This function set and resets the busy status of the port. If `on` is 1, the port is set to busy, if it's 0 the port is set to not busy.

When the port is busy, sending to it with `Port ! Data` or `port_command/2`, will block the port owner process, until the port is signaled as not busy.

`void set_port_control_flags(ErlDrvPort port, int flags)`

This function sets flags for how the control driver entry function will return data to the port owner process. (The `control` function is called from `port_control/3` in erlang.)

Currently there are only two meaningful values for `flags`: 0 means that data is returned in a list, and `PORT_CONTROL_FLAG_BINARY` means data return from `control` is sent to the port owner process.

`int driver_failure_eof(ErlDrvPort port)`

This function signals to erlang that the driver has encountered an EOF and should be closed, unless the port was opened with the `eof` option, in that case eof is sent to the port. Otherwise, the port is close and an `'EXIT'` message is sent to the port owner process.

The return value is 0.

`int driver_failure_atom(ErlDrvPort port, char *string)`
`int driver_failure_posix(ErlDrvPort port, int error)`
`int driver_failure(ErlDrvPort port, int error)`

These functions signal to erlang that the driver has encountered an error and should be closed. The port is closed and the tuple `{'EXIT', error, Err}`, is sent to the port owner process, where error is an error atom (`driver_failure_atom` and `driver_failure_posix`), or an integer (`driver_failure`).

The driver should fail only when in severe error situations, when the driver cannot possibly kepp open, for instance buffer allocation gets out of memory. Normal errors is more appropriate to handle with sending error codes with `driver_output`.

The return value is 0.

`ErlDriverTerm driver_connected(ErlDrvPort port)`

This function returns the port owner process.

`ErlDriverTerm driver_caller(ErlDrvPort port)`

This function returns the process that made the current call to the driver. This can be used with `driver_send_term` to send back data to the caller. (This is the process that called one of `erlang:send/2`, `erlang:port_command/2` or `erlang:port_control/3`).

`int driver_output_term(ErlDrvPort port, ErlDriverTerm* term, int n)`

This functions sends data in the special driver term format. This is a fast way to deliver term data to from a driver. It also needs no binary conversion, so the port owner process receives data as normal erlang terms.

The `term` parameter points to an array of `ErlDriverTerm`, with `n` elements. This array contains terms described in the driver term format. Every term consists of one to four elements in the array. The term first has a term type, and then arguments.

Tuple and lists (with the exception of strings, see below), are built in reverse polish notation, so that to build a tuple, the elements are given first, and then the tuple term, with a count. Likewise for lists.

A tuple must be specified with the number of elements. (The elements precedes the `ERL_DRV_TUPLE` term.)

A list must be specified with the number of elements, including the tail, which is the last term preceding `ERL_DRV_LIST`.

The special term `ERL_DRV_STRING_CONS` is used to "splice" in a string in a list, a string given this way is not a list per se, but the elements are elements of the surrounding list.

    Term type            Argument(s)
    ===========================================
    ERL_DRV_NIL          None
    ERL_DRV_ATOM         driver_mk_atom(string)
    ERL_DRV_INT          int
    ERL_DRV_PORT         driver_mk_port(ix)
    ERL_DRV_BINARY       ErlDriverBinary*, int len, int offset
    ERL_DRV_STRING       char*, int len
    ERL_DRV_TUPLE        int size
    ERL_DRV_LIST         int size
    ERL_DRV_PID          driver_connected() or driver_caller()
    ERL_DRV_STRING_CONS  char*, int len
    ERL_DRV_FLOAT        double*

To build the tuple `{tcp, Port, [100 | Binary]}`, the following call could be made.

        ErlDriverBinary* bin = ...
        ErlDriverPort port = ...
        ErlDriverTerm spec[] = {
            ERL_DRV_ATOM, driver_mk_atom("tcp"),
            ERL_DRV_PORT, driver_mk_port(port),
                ERL_DRV_INT, 100,
                ERL_DRV_BINARY, bin, 50, 0,
                ERL_DRV_LIST, 2,
            ERL_DRV_TUPLE, 3,
        };
        driver_output_term(port, spec, sizeof(spec) / sizeof(spec[0]));

Where `bin` is a driver binary of length at least 50 and `port` is a port handle. Note that the `ERL_DRV_LIST` comes after the elements of the list, likewise the `ERL_DRV_TUPLE`.

The term `ERL_DRV_STRING_CONS` is a way to construct strings. It works differently from how `ERL_DRV_STRING` works. `ERL_DRV_STRING_CONS` builds a string list in reverse order, (as opposed to how `ERL_DRV_LIST` works), concatenating the strings added to a list. The tail must be given before `ERL_DRV_STRING_CONS`.

The `ERL_DRV_STRING` constructs a string, and ends it. (So it's the same as `ERL_DRV_NIL` followed by `ERL_DRV_STRING_CONS`.)

        /* to send [x, "abc", y] to the port: */
        ErlDriverTerm spec[] = {
            ERL_DRV_ATOM, driver_mk_atom("x"),
            ERL_DRV_STRING, (ErlDriverTerm)"abc", 3,
            ERL_DRV_ATOM, driver_mk_atom("y"),
            ERL_DRV_NIL,
            ERL_DRV_LIST, 4
        };
        driver_output_term(port, spec, sizeof(spec) / sizeof(spec[0]));

        /* to send "abc123" to the port: */
        ErlDriverTerm spec[] = {
            ERL_DRV_NIL,        /* with STRING_CONS, the tail comes first */
            ERL_DRV_STRING_CONS, (ErlDriverTerm)"123", 3,
            ERL_DRV_STRING_CONS, (ErlDriverTerm)"abc", 3,
        };
        driver_output_term(port, spec, sizeof(spec) / sizeof(spec[0]));

Note that this function is not thread-safe, not even when the emulator with SMP support is used.

`ErlDriverTerm driver_mk_atom(char* string)`

This function returns an atom given a name `string`. The atom is created and won't change, so the return value may be saved and reused, which is faster than looking up the atom several times.

`ErlDriverTerm driver_mk_port(ErlDrvPort port)`

This function converts a port handle to the erlang term format, usable in the `driver_output_send` function.

`int driver_send_term(ErlDrvPort port, ErlDriverTerm receiver, ErlDriverTerm* term, int n)`

This function is the only way for a driver to send data to other processes than the port owner process. The `receiver` parameter specifies the process to receive the data.

The parameters `term` and `n` does the same thing as in driver_output_term.

This function is only thread-safe when the emulator with SMP support is used.

`long driver_async (ErlDrvPort port, unsigned int* key, void (*async_invoke)(void*), void* async_data, void (*async_free)(void*))`

This function performs an asynchronous call. The function `async_invoke` is invoked in a thread separate from the emulator thread. This enables the driver to perform time-consuming, blocking operations without blocking the emulator.

Normally, erlang is started without a thread pool. A start argument to the emulator, specifies how many threads that should be available (e.g. `+A 5`, gives five extra driver threads). If no thread pool is available, the call is made synchronously, in the emulator thread.

If there is a thread pool available, a thread will be used. If the `key` argument is null, the threads from the pool are used in a round-robin way, each call to `driver_async` uses the next thread in the pool. With the `key` argument set, this behaviour is changed. The two same values of `*key` always get the same thread.

To make sure that a driver instance always uses the same thread, the following call can be used:

        r = driver_async(myPort, (unsigned int*)&myPort, myData, myFunc);

If a thread is already working, the calls will be queued up and executed in order. Using the same thread for each driver instance ensures that the calls will be made in sequence.

The `async_data` is the argument to the functions `async_invoke` and `async_free`. It's typically a pointer to a structure that contains a pipe or event that can be used to signal that the async operation completed. The data should be freed in `async_free`, because it's called if `driver_async_cancel` is called.

When the async operation is done, ready_async driver entry function is called. If `async_ready` is null in the driver entry, the `async_free` function is called instead.

The return value is a handle to the asynchronous task, which can be used as argument to `driver_async_cancel`.

`int driver_async_cancel(long id)`

This function cancels an asynchronous operation, by removing it from the queue. Only functions in the queue can be cancelled; if a function is executing, it's too late to cancel it. The `async_free` function is also called.

The return value is 1 if the operation was removed from the queue, otherwise 0.

`int driver_lock_driver(ErlDrvPort port)`

This function locks the driver used by the port `port` in memory for the rest of the emulator process lifetime. After this call, the driver behaves as one of Erlangs statically linked in drivers.

`ErlDrvPort driver_create_port(ErlDrvPort port, ErlDrvTermData owner_pid, char* name, ErlDrvData drv_data)`

This function creates a new port executing the same driver code as the port creating the new port. A short description of the arguments:

`port`
  The port handle of the port (driver instance) creating the new port.
`owner_pid`
  The process id of the Erlang process which will be owner of the new port. This process will be linked to the new port. You usually want to use `driver_caller(port)` as `owner_pid`.
`name`
  The port name of the new port. You usually want to use the same port name as the driver name (driver_name field of the driver_entry).
`drv_data`
  The driver defined handle that will be passed in subsequent calls to driver call-backs. Note, that the driver start call-back will not be called for this new driver instance. The driver defined handle is normally created in the driver start call-back when a port is created via erlang:open_port/2.

The caller of `driver_create_port()` is allowed to manipulate the newly created port when `driver_create_port()` has returned. When port level locking is used, the creating port is, however, only allowed to manipulate the newly created port until the current driver call-back that was called by the emulator returns.

| When port level locking is used, the creating port is only allowed to manipulate the newly created port until the current driver call-back returns.

### See Also

driver_entry(3), erl_ddll(3), erlang(3)

An Alternative Distribution Driver (ERTS User's Guide Ch. 3)

### AUTHORS

Kenneth Lundin - support@erlang.ericsson.se
Jakob Cederlund - support@erlang.ericsson.se
Rickard Green - support@erlang.ericsson.se

erts 5.5.3
Copyright © 1991-2007 Ericsson AB