voidadd_driver_entry(ErlDrvEntry
*de)
Adds a driver entry to the list of drivers known by Erlang. The init function of parameter de is
called.
Note:
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 (that is, .so file)
as a normal dynamically loaded driver (loaded with the erl_ddll interface), the caller is to call
driver_lock_driver before adding driver entries.
Useofthisfunctionisgenerallydeprecated.void*driver_alloc(ErlDrvSizeTsize)
Allocates a memory block of the size specified in size, and returns it. This fails only on out of
memory, in which case NULL is returned. (This is most often a wrapper for malloc).
Memory allocated must be explicitly freed with a corresponding call to driver_free (unless
otherwise stated).
This function is thread-safe.
ErlDrvBinary*driver_alloc_binary(ErlDrvSizeTsize)
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 must
not be changed. Every allocated binary is to be freed by a corresponding call to
driver_free_binary (unless otherwise stated).
Notice 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 is sent to the emulator, it can 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.
longdriver_async(ErlDrvPortport,unsigned
int* key, void (*async_invoke)(void*), void* async_data, void
(*async_free)(void*))
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.
The async thread pool size can be set with command-line argument +A in erl(1). If an async thread
pool is unavailable, the call is made synchronously in the thread calling driver_async. The
current number of async threads in the async thread pool can be retrieved through
driver_system_info.
If a thread pool is available, a thread is used. If argument key 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 argument key set, this behavior is changed. The two same values of *key always get the same
thread.
To ensure that a driver instance always uses the same thread, the following call can be used:
unsigned int myKey = driver_async_port_key(myPort);
r = driver_async(myPort, &myKey, myData, myFunc);
It is enough to initialize myKey once for each driver instance.
If a thread is already working, the calls are queued up and executed in order. Using the same
thread for each driver instance ensures that the calls are made in sequence.
The async_data is the argument to the functions async_invoke and async_free. It is typically a
pointer to a structure containing a pipe or event that can be used to signal that the async
operation completed. The data is to be freed in async_free.
When the async operation is done, ready_async driver entry function is called. If ready_async is
NULL in the driver entry, the async_free function is called instead.
The return value is -1 if the driver_async call fails.
Note:
As from ERTS 5.5.4.3 the default stack size for threads in the async-thread pool is 16 kilowords,
that is, 64 kilobyte on 32-bit architectures. This small default size has been chosen because the
amount of async-threads can be quite large. The default stack size is enough for drivers delivered
with Erlang/OTP, but is possibly not sufficiently large for other dynamically linked-in drivers
that use the driver_async functionality. A suggested stack size for threads in the async-thread
pool can be configured through command-line argument +a in erl(1).
unsignedintdriver_async_port_key(ErlDrvPort
port)
Calculates a key for later use in driver_async. The keys are evenly distributed so that a fair
mapping between port IDs and async thread IDs is achieved.
Note:
Before Erlang/OTP R16, the port ID could be used as a key with proper casting, but after the
rewrite of the port subsystem, this is no longer the case. With this function, you can achieve the
same distribution based on port IDs as before Erlang/OTP R16.
longdriver_binary_dec_refc(ErlDrvBinary*bin)
Decrements the reference count on bin and returns the reference count reached after the decrement.
This function is thread-safe.
Note:
The reference count of driver binary is normally to be decremented 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.
longdriver_binary_get_refc(ErlDrvBinary*bin)
Returns the current reference count on bin.
This function is thread-safe.
longdriver_binary_inc_refc(ErlDrvBinary*bin)
Increments the reference count on bin and returns the reference count reached after the increment.
This function is thread-safe.
ErlDrvTermDatadriver_caller(ErlDrvPort
port)
Returns the process ID of the process that made the current call to the driver. The process ID can
be used with driver_send_term to send back data to the caller. driver_caller only returns valid
data when currently executing in one of the following driver callbacks:
start:
Called from erlang:open_port/2.
output:
Called from erlang:send/2 and erlang:port_command/2.
outputv:
Called from erlang:send/2 and erlang:port_command/2.
control:
Called from erlang:port_control/3.
call:
Called from erlang:port_call/3.
Notice that this function is not thread-safe.
intdriver_cancel_timer(ErlDrvPortport)
Cancels a timer set with driver_set_timer.
The return value is 0.
intdriver_compare_monitors(constErlDrvMonitor
*monitor1, const ErlDrvMonitor *monitor2)
Compares two ErlDrvMonitors. Can also be used to imply some artificial order on monitors, for
whatever reason.
Returns 0 if monitor1 and monitor2 are equal, < 0 if monitor1 < monitor2, and > 0 if monitor1 >
monitor2.
ErlDrvTermDatadriver_connected(ErlDrvPort
port)
Returns the port owner process.
Notice that this function is not thread-safe.
ErlDrvPortdriver_create_port(ErlDrvPortport,
ErlDrvTermData owner_pid, char* name,
ErlDrvData drv_data)
Creates a new port executing the same driver code as the port creating the new port.
port:
The port handle of the port (driver instance) creating the new port.
owner_pid:
The process ID of the Erlang process to become 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 is passed in later calls to driver callbacks. Notice that the
driver start callback is not called for this new driver instance. The driver-defined handle is
normally created in the driver start callback when a port is created through
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 only
allowed to manipulate the newly created port until the current driver callback, which was called
by the emulator, returns.
intdriver_demonitor_process(ErlDrvPortport,
const ErlDrvMonitor *monitor)
Cancels a monitor created earlier.
Returns 0 if a monitor was removed and > 0 if the monitor no longer exists.
ErlDrvSizeTdriver_deq(ErlDrvPortport,
ErlDrvSizeT size)
Dequeues data by moving the head pointer forward in the driver queue by size bytes. The data in
the queue is deallocated.
Returns the number of bytes remaining in the queue on success, otherwise -1.
This function can be called from any thread if a port data lock associated with the port is locked
by the calling thread during the call.
intdriver_enq(ErlDrvPortport,char*buf,
ErlDrvSizeT len)
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 must wait for slow devices, and so on, and wants to yield back to the
emulator. The driver queue is implemented as an ErlIOVec.
When the queue contains data, the driver does not close until the queue is empty.
The return value is 0.
This function can be called from any thread if a port data lock associated with the port is locked
by the calling thread during the call.
intdriver_enq_bin(ErlDrvPortport,
ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len)
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 no data must
be copied.
This function can be called from any thread if a port data lock associated with the port is locked
by the calling thread during the call.
The return value is 0.
intdriver_enqv(ErlDrvPortport,ErlIOVec*ev,
ErlDrvSizeT skip)
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 no data must be copied.
The return value is 0.
This function can be called from any thread if a port data lock associated with the port is locked
by the calling thread during the call.
intdriver_failure(ErlDrvPortport,int
error)
intdriver_failure_atom(ErlDrvPortport,char
*string)
intdriver_failure_posix(ErlDrvPortport,int
error)
Signals to Erlang that the driver has encountered an error and is to 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 is to fail only when in severe error situations, when the driver cannot possibly keep
open, for example, buffer allocation gets out of memory. For normal errors it is more appropriate
to send error codes with driver_output.
The return value is 0.
intdriver_failure_eof(ErlDrvPort
port)
Signals to Erlang that the driver has encountered an EOF and is to be closed, unless the port was
opened with option eof, in which case eof is sent to the port. Otherwise the port is closed and an
'EXIT' message is sent to the port owner process.
The return value is 0.
voiddriver_free(void*ptr)
Frees the memory pointed to by ptr. The memory is to have been allocated with driver_alloc. All
allocated memory is to be deallocated, only once. There is no garbage collection in drivers.
This function is thread-safe.
voiddriver_free_binary(ErlDrvBinary*bin)
Frees a driver binary bin, allocated previously with driver_alloc_binary. As binaries in Erlang
are reference counted, the binary can still be around.
This function is thread-safe.
ErlDrvTermDatadriver_get_monitored_process(ErlDrvPortport,const
ErlDrvMonitor *monitor)
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.
Returns driver_term_nil if the monitor no longer exists.
intdriver_get_now(ErlDrvNowData*now)Warning:Thisfunctionisdeprecated.Donotuseit. Use erl_drv_monotonic_time (perhaps in combination
with erl_drv_time_offset) instead.
Reads a time stamp into the memory pointed to by parameter now. For information about specific
fields, see ErlDrvNowData.
The return value is 0, unless the now pointer is invalid, in which case it is < 0.
intdriver_lock_driver(ErlDrvPort
port)
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 Erlang's statically linked-in drivers.
ErlDrvTermDatadriver_mk_atom(char*
string)
Returns an atom given a name string. The atom is created and does not change, so the return value
can be saved and reused, which is faster than looking up the atom several times.
Notice that this function is not thread-safe.
ErlDrvTermDatadriver_mk_port(ErlDrvPort
port)
Converts a port handle to the Erlang term format, usable in erl_drv_output_term and
erl_drv_send_term.
Notice that this function is not thread-safe.
intdriver_monitor_process(ErlDrvPortport,
ErlDrvTermData process, ErlDrvMonitor *monitor)
Starts monitoring a process from a driver. When a process is monitored, a process exit results in
a call to the provided process_exit callback in the ErlDrvEntry structure. The ErlDrvMonitor
structure is filled in, for later removal or compare.
Parameter process is to be the return value of an earlier call to driver_caller or
driver_connected call.
Returns 0 on success, < 0 if no callback is provided, and > 0 if the process is no longer alive.
intdriver_output(ErlDrvPortport,char*buf,
ErlDrvSizeT len)
Sends data from the driver up to the emulator. The data is 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. Notice that this does not yield to
the emulator (as the driver and the emulator run in the same thread).
Parameter buf points to the data to send, and len is the number of bytes.
The return value for all output functions is 0 for normal use. If the driver is used for
distribution, it can fail and return -1.
intdriver_output_binary(ErlDrvPortport,char
*hbuf, ErlDrvSizeT hlen, ErlDrvBinary* bin, ErlDrvSizeT offset,
ErlDrvSizeT len)
Sends data to a port owner process from a driver binary. It has a header buffer (hbuf and hlen)
just like driver_output2. Parameter hbuf can be NULL.
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.
For example, if hlen is 2, the port owner process receives [H1,H2|<<T>>].
The return value is 0 for normal use.
Notice 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.
intdriver_output_term(ErlDrvPortport,
ErlDrvTermData* term, int n)
Warning:Thisfunctionisdeprecated. Use erl_drv_output_terminstead.
Parameters term and n work as in erl_drv_output_term.
Notice that this function is not thread-safe.
intdriver_output2(ErlDrvPortport,char*hbuf,
ErlDrvSizeT hlen, char *buf, ErlDrvSizeT len)
First sends hbuf (length in hlen) data as a list, regardless of port settings. Then sends buf as a
binary or list. For example, if hlen is 3, the port owner process receives [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.
intdriver_outputv(ErlDrvPortport,char*hbuf,
ErlDrvSizeT hlen, ErlIOVec *ev, ErlDrvSizeT skip)
Sends data from an I/O vector, ev, to the port owner process. It has a header buffer (hbuf and
hlen), just like driver_output2.
Parameter skip 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 ErlDrvBinary buffers at
once. Often it is faster to use driver_output or .
For example, if hlen is 2 and ev points to an array of three binaries, the port owner process
receives [H1,H2,<<B1>>,<<B2>>|<<B3>>].
The return value is 0 for normal use.
The comment for driver_output_binary also applies for driver_outputv.
ErlDrvPDLdriver_pdl_create(ErlDrvPortport)
Creates a port data lock associated with the port.
Note:
Once a port data lock has been created, it must be locked during all operations on the driver
queue of the port.
Returns a newly created port data lock on success, otherwise NULL. The function fails if port is
invalid or if a port data lock already has been associated with the port.
longdriver_pdl_dec_refc(ErlDrvPDL
pdl)
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.
longdriver_pdl_get_refc(ErlDrvPDLpdl)
Returns the current reference count of the port data lock passed as argument (pdl).
This function is thread-safe.
longdriver_pdl_inc_refc(ErlDrvPDLpdl)
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.
voiddriver_pdl_lock(ErlDrvPDLpdl)
Locks the port data lock passed as argument (pdl).
This function is thread-safe.
voiddriver_pdl_unlock(ErlDrvPDLpdl)
Unlocks the port data lock passed as argument (pdl).
This function is thread-safe.
SysIOVec*driver_peekq(ErlDrvPortport,int
*vlen)
Retrieves the driver queue as a pointer to an array of SysIOVecs. It also returns the number of
elements in vlen. This is one of two ways to get data out of the queue.
Nothing is removed 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 any thread if a port data lock associated with the port is locked
by the calling thread during the call.
ErlDrvSizeTdriver_peekqv(ErlDrvPortport,
ErlIOVec *ev)
Retrieves the driver queue into a supplied ErlIOVecev. It also returns the queue size. This is
one of two ways to get data out of the queue.
If ev is NULL, all ones that is -1 type cast to ErlDrvSizeT are returned.
Nothing is removed from the queue by this function, that must be done with driver_deq.
This function can be called from any thread if a port data lock associated with the port is locked
by the calling thread during the call.
intdriver_pushq(ErlDrvPortport,char*buf,
ErlDrvSizeT len)
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 any thread if a port data lock associated with the port is locked
by the calling thread during the call.
intdriver_pushq_bin(ErlDrvPortport,
ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len)
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 no data must be copied.
This function can be called from any thread if a port data lock associated with the port is locked
by the calling thread during the call.
The return value is 0.
intdriver_pushqv(ErlDrvPortport,ErlIOVec
*ev, ErlDrvSizeT skip)
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 no data must be copied.
The return value is 0.
This function can be called from any thread if a port data lock associated with the port is locked
by the calling thread during the call.
intdriver_read_timer(ErlDrvPortport,unsigned
long *time_left)
Reads the current time of a timer, and places the result in time_left. This is the time in
milliseconds, before the time-out occurs.
The return value is 0.
void*driver_realloc(void*ptr,ErlDrvSizeTsize)
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 often a wrapper for realloc.)
This function is thread-safe.
ErlDrvBinary*driver_realloc_binary(ErlDrvBinary*bin,ErlDrvSizeTsize)
Resizes a driver binary, while keeping the data.
Returns the resized driver binary on success. Returns NULL on failure (out of memory).
This function is thread-safe.
intdriver_select(ErlDrvPortport,ErlDrvEvent
event, int mode, int on)
This function is used by drivers to provide the emulator with events to check for. This enables
the emulator to call the driver when something has occurred asynchronously.
Parameter event identifies an OS-specific event object. On Unix systems, the functions select/poll
are used. The event object must be a socket or pipe (or other object that select/poll can use). On
Windows, the Win32 API function WaitForMultipleObjects is used. This places other restrictions on
the event object; see the Win32 SDK documentation.
Parameter on is to be 1 for setting events and 0 for clearing them.
Parameter mode is a bitwise OR combination of ERL_DRV_READ, ERL_DRV_WRITE, and ERL_DRV_USE. The
first two specify whether to wait for read events and/or write events. A fired read event calls
ready_input and a fired write event calls ready_output.
Note:
Some OS (Windows) do not differentiate between read and write events. The callback for a fired
event then only depends on the value of mode.
ERL_DRV_USE specifies if we are using the event object or if we want to close it. It is not safe
to clear all events and then close the event object after driver_select has returned. Another
thread can still be using the event object internally. To safely close an event object, call
driver_select with ERL_DRV_USE and on==0, which clears all events and then either calls
stop_select or schedules it to be called when it is safe to close the event object. ERL_DRV_USE is
to be set together with the first event for an event object. It is harmless to set ERL_DRV_USE
even if it already has been done. Clearing all events but keeping ERL_DRV_USE set indicates that
we are using the event object and probably will set events for it again.
Note:ERL_DRV_USE was added in Erlang/OTP R13. Old drivers still work as before, but it is recommended
to update them to use ERL_DRV_USE and stop_select to ensure that event objects are closed in a
safe way.
The return value is 0, unless ready_input/ready_output is NULL, in which case it is -1.
intdriver_send_term(ErlDrvPortport,
ErlDrvTermData receiver, ErlDrvTermData* term, int n)
Warning:Thisfunctionisdeprecated. Use erl_drv_send_term instead.
Note:
The parameters of this function cannot be properly checked by the runtime system when executed by
arbitrary threads. This can cause the function not to fail when it should.
Parameters term and n work as in erl_drv_output_term.
This function is thread-safe.
intdriver_set_timer(ErlDrvPortport,unsigned
long time)
Sets a timer on the driver, which will count down and call the driver when it is timed out.
Parameter time is the time in milliseconds before the timer expires.
When the timer reaches 0 and expires, the driver entry function timeout is called.
Notice that only one timer exists on each driver instance; setting a new timer replaces an older
one.
Return value is 0, unless the timeout driver function is NULL, in which case it is -1.
ErlDrvSizeTdriver_sizeq(ErlDrvPortport)
Returns the number of bytes currently in the driver queue.
This function can be called from any thread if a port data lock associated with the port is locked
by the calling thread during the call.
voiddriver_system_info(ErlDrvSysInfo
*sys_info_ptr, size_t size)
Writes information about the Erlang runtime system into the ErlDrvSysInfo structure referred to by
the first argument. The second argument is to be the size of the ErlDrvSysInfo structure, that is,
sizeof(ErlDrvSysInfo).
For information about specific fields, see ErlDrvSysInfo.
ErlDrvSizeTdriver_vec_to_buf(ErlIOVec*ev,
char *buf, ErlDrvSizeT len)
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, that is, if ev contains less than len bytes it
is the difference, and if ev contains len bytes or more, it is 0. This is faster if there is more
than one header byte, as the binary syntax can construct integers directly from the binary.
voiderl_drv_busy_msgq_limits(ErlDrvPortport,
ErlDrvSizeT *low, ErlDrvSizeT *high)
Sets and gets limits that will be used for controlling the busy state of the port message queue.
The port message queue is set into a busy state when the amount of command data queued on the
message queue reaches the high limit. The port message queue is set into a not busy state when the
amount of command data queued on the message queue falls below the low limit. Command data is in
this context data passed to the port using either Port!{Owner,{command,Data}} or
port_command/[2,3]. Notice that these limits only concerns command data that have not yet reached
the port. The busy port feature can be used for data that has reached the port.
Valid limits are values in the range [ERL_DRV_BUSY_MSGQ_LIM_MIN,ERL_DRV_BUSY_MSGQ_LIM_MAX].
Limits are automatically adjusted to be sane. That is, the system adjusts values so that the low
limit used is lower than or equal to the high limit used. By default the high limit is 8 kB and
the low limit is 4 kB.
By passing a pointer to an integer variable containing the value ERL_DRV_BUSY_MSGQ_READ_ONLY, the
currently used limit is read and written back to the integer variable. A new limit can be set by
passing a pointer to an integer variable containing a valid limit. The passed value is written to
the internal limit. The internal limit is then adjusted. After this the adjusted limit is written
back to the integer variable from which the new value was read. Values are in bytes.
The busy message queue feature can be disabled either by setting the ERL_DRV_FLAG_NO_BUSY_MSGQ
driver flag in the driver_entry used by the driver, or by calling this function with
ERL_DRV_BUSY_MSGQ_DISABLED as a limit (either low or high). When this feature has been disabled,
it cannot be enabled again. When reading the limits, both are ERL_DRV_BUSY_MSGQ_DISABLED if this
feature has been disabled.
Processes sending command data to the port are suspended if either the port is busy or if the port
message queue is busy. Suspended processes are resumed when neither the port or the port message
queue is busy.
For information about busy port functionality, see set_busy_port.
voiderl_drv_cond_broadcast(ErlDrvCond
*cnd)
Broadcasts on a condition variable. That is, if other threads are waiting on the condition
variable being broadcast on, all of them are woken.
cnd is a pointer to a condition variable to broadcast on.
This function is thread-safe.
ErlDrvCond*erl_drv_cond_create(char
*name)
Creates a condition variable and returns a pointer to it.
name is a string identifying the created condition variable. It is used to identify the condition
variable in planned future debug functionality.
Returns NULL on failure. The driver creating the condition variable is responsible for destroying
it before the driver is unloaded.
This function is thread-safe.
voiderl_drv_cond_destroy(ErlDrvCond
*cnd)
Destroys a condition variable previously created by erl_drv_cond_create.
cnd is a pointer to a condition variable to destroy.
This function is thread-safe.
char*erl_drv_cond_name(ErlDrvCond
*cnd)
Returns a pointer to the name of the condition.
cnd is a pointer to an initialized condition.
Note:
This function is intended for debugging purposes only.
voiderl_drv_cond_signal(ErlDrvCond
*cnd)
Signals on a condition variable. That is, if other threads are waiting on the condition variable
being signaled, one of them is woken.
cnd is a pointer to a condition variable to signal on.
This function is thread-safe.
voiderl_drv_cond_wait(ErlDrvCond*cnd,
ErlDrvMutex *mtx)
Waits on a condition variable. The calling thread is blocked until another thread wakes it by
signaling or broadcasting on the condition variable. Before the calling thread is blocked, it
unlocks the mutex passed as argument. When the calling thread is woken, it locks the same mutex
before returning. That is, the mutex currently must be locked by the calling thread when calling
this function.
cnd is a pointer to a condition variable to wait on. mtx is a pointer to a mutex to unlock while
waiting.
Note:erl_drv_cond_wait can return even if no one has signaled or broadcast on the condition variable.
Code calling erl_drv_cond_wait is always to be prepared for erl_drv_cond_wait returning even if
the condition that the thread was waiting for has not occurred. That is, when returning from
erl_drv_cond_wait, always check if the condition has occurred, and if not call erl_drv_cond_wait
again.
This function is thread-safe.
interl_drv_consume_timeslice(ErlDrvPortport,
int percent)
Gives the runtime system a hint about how much CPU time the current driver callback call has
consumed since the last hint, or since the the start of the callback if no previous hint has been
given.
port:
Port handle of the executing port.
percent:
Approximate consumed fraction of a full time-slice in percent.
The time is specified as a fraction, in percent, of a full time-slice that a port is allowed to
execute before it is to surrender the CPU to other runnable ports or processes. Valid range is [1,100]. The scheduling time-slice is not an exact entity, but can usually be approximated to about 1
millisecond.
Notice that it is up to the runtime system to determine if and how to use this information.
Implementations on some platforms can use other means to determine the consumed fraction of the
time-slice. Lengthy driver callbacks should, regardless of this, frequently call this function to
determine if it is allowed to continue execution or not.
This function returns a non-zero value if the time-slice has been exhausted, and zero if the
callback is allowed to continue execution. If a non-zero value is returned, the driver callback is
to return as soon as possible in order for the port to be able to yield.
This function is provided to better support co-operative scheduling, improve system
responsiveness, and to make it easier to prevent misbehaviors of the VM because of a port
monopolizing a scheduler thread. It can be used when dividing lengthy work into some repeated
driver callback calls, without the need to use threads.
See also the important warning text at the beginning of this manual page.
ErlDrvTimeerl_drv_convert_time_unit(ErlDrvTime
val, ErlDrvTimeUnit from, ErlDrvTimeUnit to)
Converts the val value of time unit from to the corresponding value of time unit to. The result is
rounded using the floor function.
val:
Value to convert time unit for.
from:
Time unit of val.
to:
Time unit of returned value.
Returns ERL_DRV_TIME_ERROR if called with an invalid time unit argument.
See also ErlDrvTime and ErlDrvTimeUnit.
interl_drv_equal_tids(ErlDrvTidtid1,
ErlDrvTid tid2)
Compares two thread identifiers, tid1 and tid2, for equality.
Returns 0 it they are not equal, and a value not equal to 0 if they are equal.
Note:
A thread identifier can be reused very quickly after a thread has terminated. Therefore, if a
thread corresponding to one of the involved thread identifiers has terminated since the thread
identifier was saved, the result of erl_drv_equal_tids does possibly not give the expected result.
This function is thread-safe.
interl_drv_getenv(constchar*key,char
*value, size_t *value_size)
Retrieves the value of an environment variable.
key:
A NULL-terminated string containing the name of the environment variable.
value:
A pointer to an output buffer.
value_size:
A pointer to an integer. The integer is used both for passing input and output sizes (see
below).
When this function is called, *value_size is to contain the size of the value buffer.
On success, 0 is returned, the value of the environment variable has been written to the value
buffer, and *value_size contains the string length (excluding the terminating NULL character) of
the value written to the value buffer.
On failure, that is, no such environment variable was found, a value < 0 is returned. When the
size of the value buffer is too small, a value > 0 is returned and *value_size has been set to the
buffer size needed.
Warning:
This function reads the emulated environment used by os:getenv/1 and not the environment used by
libc's getenv(3erl) or similar. Drivers that require that these are in sync will need to do so
themselves, but keep in mind that they are segregated for a reason; getenv(3erl) and its friends
are notthread-safe and may cause unrelated code to misbehave or crash the emulator.
This function is thread-safe.
voiderl_drv_init_ack(ErlDrvPortport,
ErlDrvData res)
Acknowledges the start of the port.
port:
The port handle of the port (driver instance) doing the acknowledgment.
res:
The result of the port initialization. Can be the same values as the return value of start,
that is, any of the error codes or the ErlDrvData that is to be used for this port.
When this function is called the initiating erlang:open_port call is returned as if the start
function had just been called. It can only be used when flag ERL_DRV_FLAG_USE_INIT_ACK has been
set on the linked-in driver.
ErlDrvTimeerl_drv_monotonic_time(ErlDrvTimeUnittime_unit)
Returns Erlang monotonic time. Notice that negative values are not uncommon.
time_unit is time unit of returned value.
Returns ERL_DRV_TIME_ERROR if called with an invalid time unit argument, or if called from a
thread that is not a scheduler thread.
See also ErlDrvTime and ErlDrvTimeUnit.
ErlDrvMutex*erl_drv_mutex_create(char
*name)
Creates a mutex and returns a pointer to it.
name is a string identifying the created mutex. It is used to identify the mutex in debug
functionality (see note).
Returns NULL on failure. The driver creating the mutex is responsible for destroying it before the
driver is unloaded.
This function is thread-safe.
Note:
One such debug functionality is the lockchecker, which can detect locking order violations and
thereby potential deadlock bugs. For the lock checker to work the name should be on the format
"App.Type" or "App.Type[Instance]", where App is the name of the application, Type is the name of
the lock type and Instance is optional information about each lock instance. "App.Type" should be
a unique name for the lock checker to detect lock order violations between locks of different
types. The Instance information is currently ignored.
For example, if we have mutexes of types "myapp.xtable" and "myapp.xitem" then the lock checker
will make sure either "myapp.xtable" locks are never locked after "myapp.xitem" locks or vice
versa.
voiderl_drv_mutex_destroy(ErlDrvMutex
*mtx)
Destroys a mutex previously created by erl_drv_mutex_create. The mutex must be in an unlocked
state before it is destroyed.
mtx is a pointer to a mutex to destroy.
This function is thread-safe.
voiderl_drv_mutex_lock(ErlDrvMutex
*mtx)
Locks a mutex. The calling thread is blocked until the mutex has been locked. A thread that has
currently locked the mutex cannot lock the same mutex again.
mtx is a pointer to a mutex to lock.
Warning:
If you leave a mutex locked in an emulator thread when you let the thread out of your control, you
will verylikely deadlock the whole emulator.
This function is thread-safe.
char*erl_drv_mutex_name(ErlDrvMutex
*mtx)
Returns a pointer to the mutex name.
mtx is a pointer to an initialized mutex.
Note:
This function is intended for debugging purposes only.
interl_drv_mutex_trylock(ErlDrvMutex
*mtx)
Tries to lock a mutex. A thread that has currently locked the mutex cannot try to lock the same
mutex again.
mtx is a pointer to a mutex to try to lock.
Returns 0 on success, otherwise EBUSY.
Warning:
If you leave a mutex locked in an emulator thread when you let the thread out of your control, you
will verylikely deadlock the whole emulator.
This function is thread-safe.
voiderl_drv_mutex_unlock(ErlDrvMutex
*mtx)
Unlocks a mutex. The mutex currently must be locked by the calling thread.
mtx is a pointer to a mutex to unlock.
This function is thread-safe.
interl_drv_output_term(ErlDrvTermDataport,
ErlDrvTermData* term, int n)
Sends data in the special driver term format to the port owner process. This is a fast way to
deliver term data from a driver. It needs no binary conversion, so the port owner process receives
data as normal Erlang terms. The erl_drv_send_term functions can be used for sending to any
process on the local node.
Note:
Parameter port is not an ordinary port handle, but a port handle converted using driver_mk_port.
Parameter term points to an array of ErlDrvTermData with n elements. This array contains terms
described in the driver term format. Every term consists of 1-4 elements in the array. The first
term has a term type and then arguments. Parameter port specifies the sending port.
Tuples, maps, and lists (except strings, see below) are built in reverse polish notation, so that
to build a tuple, the elements are specified first, and then the tuple term, with a count.
Likewise for lists and maps.
* A tuple must be specified with the number of elements. (The elements precede the ERL_DRV_TUPLE
term.)
* A map must be specified with the number of key-value pairs N. The key-value pairs must precede
the ERL_DRV_MAP in this order: key1,value1,key2,value2,...,keyN,valueN. Duplicate keys are not
allowed.
* 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 specified
this way is not a list in itself, but the elements are elements of the surrounding list.
Term type Arguments
--------- ---------
ERL_DRV_NIL
ERL_DRV_ATOM ErlDrvTermData atom (from driver_mk_atom(char *string))
ERL_DRV_INT ErlDrvSInt integer
ERL_DRV_UINT ErlDrvUInt integer
ERL_DRV_INT64 ErlDrvSInt64 *integer_ptr
ERL_DRV_UINT64 ErlDrvUInt64 *integer_ptr
ERL_DRV_PORT ErlDrvTermData port (from driver_mk_port(ErlDrvPort port))
ERL_DRV_BINARY ErlDrvBinary *bin, ErlDrvUInt len, ErlDrvUInt offset
ERL_DRV_BUF2BINARY char *buf, ErlDrvUInt len
ERL_DRV_STRING char *str, int len
ERL_DRV_TUPLE int sz
ERL_DRV_LIST int sz
ERL_DRV_PID ErlDrvTermData pid (from driver_connected(ErlDrvPort port)
or driver_caller(ErlDrvPort port))
ERL_DRV_STRING_CONS char *str, int len
ERL_DRV_FLOAT double *dbl
ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
ERL_DRV_MAP int sz
The unsigned integer data type ErlDrvUInt and the signed integer data type ErlDrvSInt are 64 bits
wide on a 64-bit runtime system and 32 bits wide on a 32-bit runtime system. They were introduced
in ERTS 5.6 and replaced some of the int arguments in the list above.
The unsigned integer data type ErlDrvUInt64 and the signed integer data type ErlDrvSInt64 are
always 64 bits wide. They were introduced in ERTS 5.7.4.
To build the tuple {tcp,Port,[100|Binary]}, the following call can be made.
ErlDrvBinary* bin = ...
ErlDrvPort port = ...
ErlDrvTermData spec[] = {
ERL_DRV_ATOM, driver_mk_atom("tcp"),
ERL_DRV_PORT, driver_mk_port(drvport),
ERL_DRV_INT, 100,
ERL_DRV_BINARY, bin, 50, 0,
ERL_DRV_LIST, 2,
ERL_DRV_TUPLE, 3,
};
erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0]));
Here bin is a driver binary of length at least 50 and drvport is a port handle. Notice that
ERL_DRV_LIST comes after the elements of the list, likewise ERL_DRV_TUPLE.
The ERL_DRV_STRING_CONS term 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 specified before
ERL_DRV_STRING_CONS.
ERL_DRV_STRING constructs a string, and ends it. (So it is the same as ERL_DRV_NIL followed by
ERL_DRV_STRING_CONS.)
/* to send [x, "abc", y] to the port: */
ErlDrvTermData spec[] = {
ERL_DRV_ATOM, driver_mk_atom("x"),
ERL_DRV_STRING, (ErlDrvTermData)"abc", 3,
ERL_DRV_ATOM, driver_mk_atom("y"),
ERL_DRV_NIL,
ERL_DRV_LIST, 4
};
erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0]));
/* to send "abc123" to the port: */
ErlDrvTermData spec[] = {
ERL_DRV_NIL, /* with STRING_CONS, the tail comes first */
ERL_DRV_STRING_CONS, (ErlDrvTermData)"123", 3,
ERL_DRV_STRING_CONS, (ErlDrvTermData)"abc", 3,
};
erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0]));
The ERL_DRV_EXT2TERM term type is used for passing a term encoded with the external format, that
is, a term that has been encoded by erlang:term_to_binary, erl_interface:ei(3erl), and so on. For
example, if binp is a pointer to an ErlDrvBinary that contains term {17,4711} encoded with the
external format, and you want to wrap it in a two-tuple with the tag my_tag, that is, {my_tag,{17,4711}}, you can do as follows:
ErlDrvTermData spec[] = {
ERL_DRV_ATOM, driver_mk_atom("my_tag"),
ERL_DRV_EXT2TERM, (ErlDrvTermData) binp->orig_bytes, binp->orig_size
ERL_DRV_TUPLE, 2,
};
erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0]));
To build the map #{key1=>100,key2=>{200,300}}, the following call can be made.
ErlDrvPort port = ...
ErlDrvTermData spec[] = {
ERL_DRV_ATOM, driver_mk_atom("key1"),
ERL_DRV_INT, 100,
ERL_DRV_ATOM, driver_mk_atom("key2"),
ERL_DRV_INT, 200,
ERL_DRV_INT, 300,
ERL_DRV_TUPLE, 2,
ERL_DRV_MAP, 2
};
erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0]));
If you want to pass a binary and do not already have the content of the binary in an ErlDrvBinary,
you can benefit from using ERL_DRV_BUF2BINARY instead of creating an ErlDrvBinary through
driver_alloc_binary and then pass the binary through ERL_DRV_BINARY. The runtime system often
allocates binaries smarter if ERL_DRV_BUF2BINARY is used. However, if the content of the binary to
pass already resides in an ErlDrvBinary, it is normally better to pass the binary using
ERL_DRV_BINARY and the ErlDrvBinary in question.
The ERL_DRV_UINT, ERL_DRV_BUF2BINARY, and ERL_DRV_EXT2TERM term types were introduced in ERTS 5.6.
This function is thread-safe.
interl_drv_putenv(constchar*key,char
*value)
Sets the value of an environment variable.
key is a NULL-terminated string containing the name of the environment variable.
value is a NULL-terminated string containing the new value of the environment variable.
Returns 0 on success, otherwise a value !=0.
Note:
The result of passing the empty string ("") as a value is platform-dependent. On some platforms
the variable value is set to the empty string, on others the environment variable is removed.
Warning:
This function modifies the emulated environment used by os:putenv/2 and not the environment used
by libc's putenv(3erl) or similar. Drivers that require that these are in sync will need to do so
themselves, but keep in mind that they are segregated for a reason; putenv(3erl) and its friends
are notthread-safe and may cause unrelated code to misbehave or crash the emulator.
This function is thread-safe.
ErlDrvRWLock*erl_drv_rwlock_create(char
*name)
Creates an rwlock and returns a pointer to it.
name is a string identifying the created rwlock. It is used to identify the rwlock in debug
functionality (see note about the lock checker).
Returns NULL on failure. The driver creating the rwlock is responsible for destroying it before
the driver is unloaded.
This function is thread-safe.
voiderl_drv_rwlock_destroy(ErlDrvRWLock
*rwlck)
Destroys an rwlock previously created by erl_drv_rwlock_create. The rwlock must be in an unlocked
state before it is destroyed.
rwlck is a pointer to an rwlock to destroy.
This function is thread-safe.
char*erl_drv_rwlock_name(ErlDrvRWLock
*rwlck)
Returns a pointer to the name of the rwlock.
rwlck is a pointer to an initialized rwlock.
Note:
This function is intended for debugging purposes only.
voiderl_drv_rwlock_rlock(ErlDrvRWLock
*rwlck)
Read locks an rwlock. The calling thread is blocked until the rwlock has been read locked. A
thread that currently has read or read/write locked the rwlock cannot lock the same rwlock again.
rwlck is a pointer to the rwlock to read lock.
Warning:
If you leave an rwlock locked in an emulator thread when you let the thread out of your control,
you will verylikely deadlock the whole emulator.
This function is thread-safe.
voiderl_drv_rwlock_runlock(ErlDrvRWLock
*rwlck)
Read unlocks an rwlock. The rwlock currently must be read locked by the calling thread.
rwlck is a pointer to an rwlock to read unlock.
This function is thread-safe.
voiderl_drv_rwlock_rwlock(ErlDrvRWLock
*rwlck)
Read/write locks an rwlock. The calling thread is blocked until the rwlock has been read/write
locked. A thread that currently has read or read/write locked the rwlock cannot lock the same
rwlock again.
rwlck is a pointer to an rwlock to read/write lock.
Warning:
If you leave an rwlock locked in an emulator thread when you let the thread out of your control,
you will verylikely deadlock the whole emulator.
This function is thread-safe.
voiderl_drv_rwlock_rwunlock(ErlDrvRWLock
*rwlck)
Read/write unlocks an rwlock. The rwlock currently must be read/write locked by the calling
thread.
rwlck is a pointer to an rwlock to read/write unlock.
This function is thread-safe.
interl_drv_rwlock_tryrlock(ErlDrvRWLock
*rwlck)
Tries to read lock an rwlock.
rwlck is a pointer to an rwlock to try to read lock.
Returns 0 on success, otherwise EBUSY. A thread that currently has read or read/write locked the
rwlock cannot try to lock the same rwlock again.
Warning:
If you leave an rwlock locked in an emulator thread when you let the thread out of your control,
you will verylikely deadlock the whole emulator.
This function is thread-safe.
interl_drv_rwlock_tryrwlock(ErlDrvRWLock
*rwlck)
Tries to read/write lock an rwlock. A thread that currently has read or read/write locked the
rwlock cannot try to lock the same rwlock again.
rwlckis pointer to an rwlock to try to read/write lock.
Returns 0 on success, otherwise EBUSY.
Warning:
If you leave an rwlock locked in an emulator thread when you let the thread out of your control,
you will verylikely deadlock the whole emulator.
This function is thread-safe.
interl_drv_send_term(ErlDrvTermDataport,
ErlDrvTermData receiver, ErlDrvTermData* term, int n)
This function is the only way for a driver to send data to other processes than the port owner
process. Parameter receiver specifies the process to receive the data.
Note:
Parameter port is not an ordinary port handle, but a port handle converted using driver_mk_port.
Parameters port, term, and n work as in erl_drv_output_term.
This function is thread-safe.
voiderl_drv_set_os_pid(ErlDrvPortport,
ErlDrvSInt pid)
Sets the os_pid seen when doing erlang:port_info/2 on this port.
port is the port handle of the port (driver instance) to set the pid on. pidis the pid to set.
interl_drv_thread_create(char*name,ErlDrvTid
*tid, void * (*func)(void *), void *arg, ErlDrvThreadOpts
*opts)
Creates a new thread.
name:
A string identifying the created thread. It is used to identify the thread in planned future
debug functionality.
tid:
A pointer to a thread identifier variable.
func:
A pointer to a function to execute in the created thread.
arg:
A pointer to argument to the func function.
opts:
A pointer to thread options to use or NULL.
Returns 0 on success, otherwise an errno value is returned to indicate the error. The newly
created thread begins executing in the function pointed to by func, and func is passed arg as
argument. When erl_drv_thread_create returns, the thread identifier of the newly created thread is
available in *tid. opts can be either a NULL pointer, or a pointer to an ErlDrvThreadOpts
structure. If opts is a NULL pointer, default options are used, otherwise the passed options are
used.
Warning:
You are not allowed to allocate the ErlDrvThreadOpts structure by yourself. It must be allocated
and initialized by erl_drv_thread_opts_create.
The created thread terminates either when func returns or if erl_drv_thread_exit is called by the
thread. The exit value of the thread is either returned from func or passed as argument to
erl_drv_thread_exit. The driver creating the thread is responsible for joining the thread, through
erl_drv_thread_join, before the driver is unloaded. "Detached" threads cannot be created, that is,
threads that do not need to be joined.
Warning:
All created threads must be joined by the driver before it is unloaded. If the driver fails to
join all threads created before it is unloaded, the runtime system most likely crashes when the
driver code is unloaded.
This function is thread-safe.
voiderl_drv_thread_exit(void
*exit_value)
Terminates the calling thread with the exit value passed as argument. exit_value is a pointer to
an exit value or NULL.
You are only allowed to terminate threads created with erl_drv_thread_create.
The exit value can later be retrieved by another thread through erl_drv_thread_join.
This function is thread-safe.
interl_drv_thread_join(ErlDrvTidtid,void
**exit_value)
Joins the calling thread with another thread, that is, the calling thread is blocked until the
thread identified by tid has terminated.
tid is the thread identifier of the thread to join. exit_value is a pointer to a pointer to an
exit value, or NULL.
Returns 0 on success, otherwise an errno value is returned to indicate the error.
A thread can only be joined once. The behavior of joining more than once is undefined, an emulator
crash is likely. If exit_value==NULL, the exit value of the terminated thread is ignored,
otherwise the exit value of the terminated thread is stored at *exit_value.
This function is thread-safe.
char*erl_drv_thread_name(ErlDrvTid
tid)
Returns a pointer to the name of the thread.
tid is a thread identifier.
Note:
This function is intended for debugging purposes only.
ErlDrvThreadOpts*erl_drv_thread_opts_create(char*name)
Allocates and initializes a thread option structure.
name is a string identifying the created thread options. It is used to identify the thread options
in planned future debug functionality.
Returns NULL on failure. A thread option structure is used for passing options to
erl_drv_thread_create. If the structure is not modified before it is passed to
erl_drv_thread_create, the default values are used.
Warning:
You are not allowed to allocate the ErlDrvThreadOpts structure by yourself. It must be allocated
and initialized by erl_drv_thread_opts_create.
This function is thread-safe.
voiderl_drv_thread_opts_destroy(ErlDrvThreadOpts*opts)
Destroys thread options previously created by erl_drv_thread_opts_create.
opts is a pointer to thread options to destroy.
This function is thread-safe.
ErlDrvTiderl_drv_thread_self(void)
Returns the thread identifier of the calling thread.
This function is thread-safe.
ErlDrvTimeerl_drv_time_offset(ErlDrvTimeUnit
time_unit)
Returns the current time offset between Erlang monotonic time and Erlang system time converted
into the time_unit passed as argument.
time_unit is time unit of returned value.
Returns ERL_DRV_TIME_ERROR if called with an invalid time unit argument, or if called from a
thread that is not a scheduler thread.
See also ErlDrvTime and ErlDrvTimeUnit.
void*erl_drv_tsd_get(ErlDrvTSDKey
key)
Returns the thread-specific data associated with key for the calling thread.
key is a thread-specific data key.
Returns NULL if no data has been associated with key for the calling thread.
This function is thread-safe.
interl_drv_tsd_key_create(char*name,
ErlDrvTSDKey *key)
Creates a thread-specific data key.
name is a string identifying the created key. It is used to identify the key in planned future
debug functionality.
key is a pointer to a thread-specific data key variable.
Returns 0 on success, otherwise an errno value is returned to indicate the error. The driver
creating the key is responsible for destroying it before the driver is unloaded.
This function is thread-safe.
voiderl_drv_tsd_key_destroy(ErlDrvTSDKey
key)
Destroys a thread-specific data key previously created by erl_drv_tsd_key_create. All thread-
specific data using this key in all threads must be cleared (see erl_drv_tsd_set) before the call
to erl_drv_tsd_key_destroy.
key is a thread-specific data key to destroy.
Warning:
A destroyed key is very likely to be reused soon. Therefore, if you fail to clear the thread-
specific data using this key in a thread before destroying the key, you will verylikely get
unexpected errors in other parts of the system.
This function is thread-safe.
voiderl_drv_tsd_set(ErlDrvTSDKeykey,void
*data)
Sets thread-specific data associated with key for the calling thread. You are only allowed to set
thread-specific data for threads while they are fully under your control. For example, if you set
thread-specific data in a thread calling a driver callback function, it must be cleared, that is,
set to NULL, before returning from the driver callback function.
key is a thread-specific data key.
data is a pointer to data to associate with key in the calling thread.
Warning:
If you fail to clear thread-specific data in an emulator thread before letting it out of your
control, you might never be able to clear this data with later unexpected errors in other parts of
the system as a result.
This function is thread-safe.
char*erl_errno_id(interror)
Returns the atom name of the Erlang error, given the error number in error. The error atoms are
einval, enoent, and so on. It can be used to make error terms from the driver.
intremove_driver_entry(ErlDrvEntry
*de)
Removes a driver entry de previously added with add_driver_entry.
Driver entries added by the erl_ddll Erlang interface cannot be removed by using this interface.
voidset_busy_port(ErlDrvPortport,int
on)
Sets and unsets the busy state of the port. If on is non-zero, the port is set to busy. If it is
zero, the port is set to not busy. You typically want to combine this feature with the busy port
message queue functionality.
Processes sending command data to the port are suspended if either the port or the port message
queue is busy. Suspended processes are resumed when neither the port or the port message queue is
busy. Command data is in this context data passed to the port using either Port!{Owner,{command,Data}} or port_command/[2,3].
If the ERL_DRV_FLAG_SOFT_BUSY has been set in the driver_entry, data can be forced into the
driver through erlang:port_command(Port,Data,[force]) even if the driver has signaled that it is
busy.
For information about busy port message queue functionality, see erl_drv_busy_msgq_limits.
voidset_port_control_flags(ErlDrvPortport,
int flags)
Sets flags for how the control driver entry function will return data to the port owner process.
(The control function is called from erlang:port_control/3.)
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 is returned as a binary from control.
Install Now
PNG Icons
Emojis