1driver_entry(3) C Library Functions driver_entry(3)
2
6 driver_entry - The driver-entry structure used by Erlang drivers.
7
9 Warning:
10 Use this functionality with extreme care.
11 A driver callback is executed as a direct extension of the native code
13 of the VM. Execution is not made in a safe environment. The VM cannot
14 provide the same services as provided when executing Erlang code, such
15 as pre-emptive scheduling or memory protection. If the driver callback
16 function does not behave well, the whole VM will misbehave.
17 * A driver callback that crash will crash the whole VM.
19 * An erroneously implemented driver callback can cause a VM internal
21 state inconsistency, which can cause a crash of the VM, or miscel‐
22 laneous misbehaviors of the VM at any point after the call to the
23 driver callback.
24 * A driver callback doing lengthy work before returning degrades
26 responsiveness of the VM, and can cause miscellaneous strange
27 behaviors. Such strange behaviors include, but are not limited to,
28 extreme memory usage, and bad load balancing between schedulers.
29 Strange behaviors that can occur because of lengthy work can also
30 vary between Erlang/OTP releases.
31 As from ERTS 5.9 (Erlang/OTP R15B) the driver interface has been
33 changed with larger types for the callbacks output, control, and call.
34 See driver version management in erl_driver.
35 Note:
37 Old drivers (compiled with an erl_driver.h from an ERTS version earlier
38 than 5.9) must be updated and have to use the extended interface (with
39 version management ).
40 The driver_entry structure is a C struct that all Erlang drivers
43 define. It contains entry points for the Erlang driver, which are
44 called by the Erlang emulator when Erlang code accesses the driver.
45 The erl_driver driver API functions need a port handle that identifies
47 the driver instance (and the port in the emulator). This is only passed
48 to the start function, but not to the other functions. The start func‐
49 tion returns a driver-defined handle that is passed to the other func‐
50 tions. A common practice is to have the start function allocate some
51 application-defined structure and stash the port handle in it, to use
52 it later with the driver API functions.
53 The driver callback functions are called synchronously from the Erlang
55 emulator. If they take too long before completing, they can cause time-
56 outs in the emulator. Use the queue or asynchronous calls if necessary,
57 as the emulator must be responsive.
58 The driver structure contains the driver name and some 15 function
60 pointers, which are called at different times by the emulator.
61 The only exported function from the driver is driver_init. This func‐
63 tion returns the driver_entry structure that points to the other func‐
64 tions in the driver. The driver_init function is declared with a macro,
65 DRIVER_INIT(drivername). (This is because different operating systems
66 have different names for it.)
67 When writing a driver in C++, the driver entry is to be of "C" linkage.
69 One way to do this is to put the following line somewhere before the
70 driver entry:
71 extern "C" DRIVER_INIT(drivername);
73 When the driver has passed the driver_entry over to the emulator, the
75 driver is not allowed to modify the driver_entry.
76 If compiling a driver for static inclusion through --enable-static-
78 drivers, you must define STATIC_ERLANG_DRIVER before the DRIVER_INIT
79 declaration.
80 Note:
82 Do not declare the driver_entry const. This because the emulator must
83 modify the handle and the handle2 fields. A statically allocated, and
84 const-declared driver_entry can be located in read-only memory, which
85 causes the emulator to crash.
86
89 ErlDrvEntry
90 typedef struct erl_drv_entry {
92 int (*init)(void); /* Called at system startup for statically
93 linked drivers, and after loading for
94 dynamically loaded drivers */
95 #ifndef ERL_SYS_DRV
96 ErlDrvData (*start)(ErlDrvPort port, char *command);
97 /* Called when open_port/2 is invoked,
98 return value -1 means failure */
99 #else
100 ErlDrvData (*start)(ErlDrvPort port, char *command, SysDriverOpts* opts);
101 /* Special options, only for system driver */
102 #endif
103 void (*stop)(ErlDrvData drv_data);
104 /* Called when port is closed, and when the
105 emulator is halted */
106 void (*output)(ErlDrvData drv_data, char *buf, ErlDrvSizeT len);
107 /* Called when we have output from Erlang to
108 the port */
109 void (*ready_input)(ErlDrvData drv_data, ErlDrvEvent event);
110 /* Called when we have input from one of
111 the driver's handles */
112 void (*ready_output)(ErlDrvData drv_data, ErlDrvEvent event);
113 /* Called when output is possible to one of
114 the driver's handles */
115 char *driver_name; /* Name supplied as command in
116 erlang:open_port/2 */
117 void (*finish)(void); /* Called before unloading the driver -
118 dynamic drivers only */
119 void *handle; /* Reserved, used by emulator internally */
120 ErlDrvSSizeT (*control)(ErlDrvData drv_data, unsigned int command,
121 char *buf, ErlDrvSizeT len,
122 char **rbuf, ErlDrvSizeT rlen);
123 /* "ioctl" for drivers - invoked by
124 port_control/3 */
125 void (*timeout)(ErlDrvData drv_data);
126 /* Handling of time-out in driver */
127 void (*outputv)(ErlDrvData drv_data, ErlIOVec *ev);
128 /* Called when we have output from Erlang
129 to the port */
130 void (*ready_async)(ErlDrvData drv_data, ErlDrvThreadData thread_data);
131 void (*flush)(ErlDrvData drv_data);
132 /* Called when the port is about to be
133 closed, and there is data in the
134 driver queue that must be flushed
135 before 'stop' can be called */
136 ErlDrvSSizeT (*call)(ErlDrvData drv_data, unsigned int command,
137 char *buf, ErlDrvSizeT len,
138 char **rbuf, ErlDrvSizeT rlen, unsigned int *flags);
139 /* Works mostly like 'control', a synchronous
140 call into the driver */
141 void (*event)(ErlDrvData drv_data, ErlDrvEvent event,
142 ErlDrvEventData event_data);
143 /* Called when an event selected by
144 driver_event() has occurred */
145 int extended_marker; /* ERL_DRV_EXTENDED_MARKER */
146 int major_version; /* ERL_DRV_EXTENDED_MAJOR_VERSION */
147 int minor_version; /* ERL_DRV_EXTENDED_MINOR_VERSION */
148 int driver_flags; /* ERL_DRV_FLAGs */
149 void *handle2; /* Reserved, used by emulator internally */
150 void (*process_exit)(ErlDrvData drv_data, ErlDrvMonitor *monitor);
151 /* Called when a process monitor fires */
152 void (*stop_select)(ErlDrvEvent event, void* reserved);
153 /* Called to close an event object */
154 } ErlDrvEntry;
155 int (*init)(void):
157 Called directly after the driver has been loaded by
158 erl_ddll:load_driver/2 (actually when the driver is added to the
159 driver list). The driver is to return 0, or, if the driver cannot
160 initialize, -1.
161 ErlDrvData (*start)(ErlDrvPort port, char* command):
163 Called when the driver is instantiated, when erlang:open_port/2 is
164 called. The driver is to return a number >= 0 or a pointer, or, if
165 the driver cannot be started, one of three error codes:
166 ERL_DRV_ERROR_GENERAL:
168 General error, no error code
169 ERL_DRV_ERROR_ERRNO:
171 Error with error code in errno
172 ERL_DRV_ERROR_BADARG:
174 Error, badarg
175 If an error code is returned, the port is not started.
177 void (*stop)(ErlDrvData drv_data):
179 Called when the port is closed, with erlang:port_close/1 or Port !
180 {self(), close}. Notice that terminating the port owner process
181 also closes the port. If drv_data is a pointer to memory allocated
182 in start, then stop is the place to deallocate that memory.
183 void (*output)(ErlDrvData drv_data, char *buf, ErlDrvSizeT len):
185 Called when an Erlang process has sent data to the port. The data
186 is pointed to by buf, and is len bytes. Data is sent to the port
187 with Port ! {self(), {command, Data}} or with erlang:port_com‐
188 mand/2. Depending on how the port was opened, it is to be either a
189 list of integers 0...255 or a binary. See erlang:open_port/2 and
190 erlang:port_command/2.
191 void (*ready_input)(ErlDrvData drv_data, ErlDrvEvent event):
193 void (*ready_output)(ErlDrvData drv_data, ErlDrvEvent event):
196 Called when a driver event (specified in parameter event) is sig‐
197 naled. This is used to help asynchronous drivers "wake up" when
198 something occurs.
199 On Unix the event is a pipe or socket handle (or something that the
201 select system call understands).
202 On Windows the event is an Event or Semaphore (or something that
204 the WaitForMultipleObjects API function understands). (Some trick‐
205 ery in the emulator allows more than the built-in limit of 64
206 Events to be used.)
207 To use this with threads and asynchronous routines, create a pipe
209 on Unix and an Event on Windows. When the routine completes, write
210 to the pipe (use SetEvent on Windows), this makes the emulator call
211 ready_input or ready_output.
212 False events can occur. That is, calls to ready_input or ready_out‐
214 put although no real events are signaled. In reality, it is rare
215 (and OS-dependant), but a robust driver must nevertheless be able
216 to handle such cases.
217 char *driver_name:
219 The driver name. It must correspond to the atom used in
220 erlang:open_port/2, and the name of the driver library file (with‐
221 out the extension).
222 void (*finish)(void):
224 Called by the erl_ddll driver when the driver is unloaded. (It is
225 only called in dynamic drivers.)
226 The driver is only unloaded as a result of calling
228 erl_ddll:unload_driver/1, or when the emulator halts.
229 void *handle:
231 This field is reserved for the emulator's internal use. The emula‐
232 tor will modify this field, so it is important that the
233 driver_entry is not declared const.
234 ErlDrvSSizeT (*control)(ErlDrvData drv_data, unsigned int command,
236 char *buf, ErlDrvSizeT len, char **rbuf, ErlDrvSizeT rlen):
237 A special routine invoked with erlang:port_control/3. It works a
238 little like an "ioctl" for Erlang drivers. The data specified to
239 port_control/3 arrives in buf and len. The driver can send data
240 back, using *rbuf and rlen.
241 This is the fastest way of calling a driver and get a response. It
243 makes no context switch in the Erlang emulator and requires no mes‐
244 sage passing. It is suitable for calling C function to get faster
245 execution, when Erlang is too slow.
246 If the driver wants to return data, it is to return it in rbuf.
248 When control is called, *rbuf points to a default buffer of rlen
249 bytes, which can be used to return data. Data is returned differ‐
250 ently depending on the port control flags (those that are set with
251 erl_driver:set_port_control_flags).
252 If the flag is set to PORT_CONTROL_FLAG_BINARY, a binary is
254 returned. Small binaries can be returned by writing the raw data
255 into the default buffer. A binary can also be returned by setting
256 *rbuf to point to a binary allocated with
257 erl_driver:driver_alloc_binary. This binary is freed automatically
258 after control has returned. The driver can retain the binary for
259 read only access with erl_driver:driver_binary_inc_refc to be freed
260 later with erl_driver:driver_free_binary. It is never allowed to
261 change the binary after control has returned. If *rbuf is set to
262 NULL, an empty list is returned.
263 If the flag is set to 0, data is returned as a list of integers.
265 Either use the default buffer or set *rbuf to point to a larger
266 buffer allocated with erl_driver:driver_alloc. The buffer is freed
267 automatically after control has returned.
268 Using binaries is faster if more than a few bytes are returned.
270 The return value is the number of bytes returned in *rbuf.
272 void (*timeout)(ErlDrvData drv_data):
274 Called any time after the driver's timer reaches 0. The timer is
275 activated with erl_driver:driver_set_timer. No priorities or order‐
276 ing exist among drivers, so if several drivers time out at the same
277 time, anyone of them is called first.
278 void (*outputv)(ErlDrvData drv_data, ErlIOVec *ev):
280 Called whenever the port is written to. If it is NULL, the output
281 function is called instead. This function is faster than output, as
282 it takes an ErlIOVec directly, which requires no copying of the
283 data. The port is to be in binary mode, see erlang:open_port/2.
284 ErlIOVec contains both a SysIOVec, suitable for writev, and one or
286 more binaries. If these binaries are to be retained when the driver
287 returns from outputv, they can be queued (using, for example,
288 erl_driver:driver_enq_bin) or, if they are kept in a static or
289 global variable, the reference counter can be incremented.
290 void (*ready_async)(ErlDrvData drv_data, ErlDrvThreadData
292 thread_data):
293 Called after an asynchronous call has completed. The asynchronous
294 call is started with erl_driver:driver_async. This function is
295 called from the Erlang emulator thread, as opposed to the asynchro‐
296 nous function, which is called in some thread (if multi-threading
297 is enabled).
298 void (*flush)(ErlDrvData drv_data):
300 Called when the port is about to be closed, and there is data in
301 the driver queue that must be flushed before 'stop' can be called.
302 ErlDrvSSizeT (*call)(ErlDrvData drv_data, unsigned int command, char
304 *buf, ErlDrvSizeT len, char **rbuf, ErlDrvSizeT rlen, unsigned int
305 *flags):
306 Called from erlang:port_call/3. It works a lot like the control
307 callback, but uses the external term format for input and output.
308 command is an integer, obtained from the call from Erlang (the sec‐
310 ond argument to erlang:port_call/3).
311 buf and len provide the arguments to the call (the third argument
313 to erlang:port_call/3). They can be decoded using ei functions.
314 rbuf points to a return buffer, rlen bytes long. The return data is
316 to be a valid Erlang term in the external (binary) format. This is
317 converted to an Erlang term and returned by erlang:port_call/3 to
318 the caller. If more space than rlen bytes is needed to return data,
319 *rbuf can be set to memory allocated with erl_driver:driver_alloc.
320 This memory is freed automatically after call has returned.
321 The return value is the number of bytes returned in *rbuf. If
323 ERL_DRV_ERROR_GENERAL is returned (or in fact, anything < 0),
324 erlang:port_call/3 throws a BAD_ARG.
325 void (*event)(ErlDrvData drv_data, ErlDrvEvent event, ErlDrvEventData
327 event_data):
328 Intentionally left undocumented.
329 int extended_marker:
331 This field is either to be equal to ERL_DRV_EXTENDED_MARKER or 0.
332 An old driver (not aware of the extended driver interface) is to
333 set this field to 0. If this field is 0, all the following fields
334 must also be 0, or NULL if it is a pointer field.
335 int major_version:
337 This field is to equal ERL_DRV_EXTENDED_MAJOR_VERSION if field
338 extended_marker equals ERL_DRV_EXTENDED_MARKER.
339 int minor_version:
341 This field is to equal ERL_DRV_EXTENDED_MINOR_VERSION if field
342 extended_marker equals ERL_DRV_EXTENDED_MARKER.
343 int driver_flags:
345 This field is used to pass driver capability and other information
346 to the runtime system. If field extended_marker equals
347 ERL_DRV_EXTENDED_MARKER, it is to contain 0 or driver flags
348 (ERL_DRV_FLAG_*) OR'ed bitwise. The following driver flags exist:
349 ERL_DRV_FLAG_USE_PORT_LOCKING:
351 The runtime system uses port-level locking on all ports executing
352 this driver instead of driver-level locking when the driver is
353 run in a runtime system with SMP support. For more information,
354 see erl_driver.
355 ERL_DRV_FLAG_SOFT_BUSY:
357 Marks that driver instances can handle being called in the output
358 and/or outputv callbacks although a driver instance has marked
359 itself as busy (see erl_driver:set_busy_port). As from ERTS 5.7.4
360 this flag is required for drivers used by the Erlang distribution
361 (the behavior has always been required by drivers used by the
362 distribution).
363 ERL_DRV_FLAG_NO_BUSY_MSGQ:
365 Disables busy port message queue functionality. For more informa‐
366 tion, see erl_driver:erl_drv_busy_msgq_limits.
367 ERL_DRV_FLAG_USE_INIT_ACK:
369 When this flag is specified, the linked-in driver must manually
370 acknowledge that the port has been successfully started using
371 erl_driver:erl_drv_init_ack(). This allows the implementor to
372 make the erlang:open_port exit with badarg after some initial
373 asynchronous initialization has been done.
374 void *handle2:
376 This field is reserved for the emulator's internal use. The emula‐
377 tor modifies this field, so it is important that the driver_entry
378 is not declared const.
379 void (*process_exit)(ErlDrvData drv_data, ErlDrvMonitor *monitor):
381 Called when a monitored process exits. The drv_data is the data
382 associated with the port for which the process is monitored (using
383 erl_driver:driver_monitor_process) and the monitor corresponds to
384 the ErlDrvMonitor structure filled in when creating the monitor.
385 The driver interface function erl_driver:driver_get_moni‐
386 tored_process can be used to retrieve the process ID of the exiting
387 process as an ErlDrvTermData.
388 void (*stop_select)(ErlDrvEvent event, void* reserved):
390 Called on behalf of erl_driver:driver_select when it is safe to
391 close an event object.
392 A typical implementation on Unix is to do close((int)event).
394 Argument reserved is intended for future use and is to be ignored.
396 In contrast to most of the other callback functions, stop_select is
398 called independent of any port. No ErlDrvData argument is passed to
399 the function. No driver lock or port lock is guaranteed to be held.
400 The port that called driver_select can even be closed at the time
401 stop_select is called. But it can also be the case that stop_select
402 is called directly by erl_driver:driver_select.
403 It is not allowed to call any functions in the driver API from
405 stop_select. This strict limitation is because the volatile context
406 that stop_select can be called.
407
409 erl_driver(3), erlang(3), erl_ddll(3)
410Ericsson AB erts 9.3.3.10 driver_entry(3)