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* unused_event_callback;
142 int extended_marker; /* ERL_DRV_EXTENDED_MARKER */
143 int major_version; /* ERL_DRV_EXTENDED_MAJOR_VERSION */
144 int minor_version; /* ERL_DRV_EXTENDED_MINOR_VERSION */
145 int driver_flags; /* ERL_DRV_FLAGs */
146 void *handle2; /* Reserved, used by emulator internally */
147 void (*process_exit)(ErlDrvData drv_data, ErlDrvMonitor *monitor);
148 /* Called when a process monitor fires */
149 void (*stop_select)(ErlDrvEvent event, void* reserved);
150 /* Called to close an event object */
151 } ErlDrvEntry;
152 int (*init)(void):
154 Called directly after the driver has been loaded by
155 erl_ddll:load_driver/2 (actually when the driver is added to the
156 driver list). The driver is to return 0, or, if the driver cannot
157 initialize, -1.
158 ErlDrvData (*start)(ErlDrvPort port, char* command):
160 Called when the driver is instantiated, when erlang:open_port/2 is
161 called. The driver is to return a number >= 0 or a pointer, or, if
162 the driver cannot be started, one of three error codes:
163 ERL_DRV_ERROR_GENERAL:
165 General error, no error code
166 ERL_DRV_ERROR_ERRNO:
168 Error with error code in errno
169 ERL_DRV_ERROR_BADARG:
171 Error, badarg
172 If an error code is returned, the port is not started.
174 void (*stop)(ErlDrvData drv_data):
176 Called when the port is closed, with erlang:port_close/1 or Port !
177 {self(), close}. Notice that terminating the port owner process
178 also closes the port. If drv_data is a pointer to memory allocated
179 in start, then stop is the place to deallocate that memory.
180 void (*output)(ErlDrvData drv_data, char *buf, ErlDrvSizeT len):
182 Called when an Erlang process has sent data to the port. The data
183 is pointed to by buf, and is len bytes. Data is sent to the port
184 with Port ! {self(), {command, Data}} or with erlang:port_com‐
185 mand/2. Depending on how the port was opened, it is to be either a
186 list of integers 0...255 or a binary. See erlang:open_port/2 and
187 erlang:port_command/2.
188 void (*ready_input)(ErlDrvData drv_data, ErlDrvEvent event):
190 void (*ready_output)(ErlDrvData drv_data, ErlDrvEvent event):
193 Called when a driver event (specified in parameter event) is sig‐
194 naled. This is used to help asynchronous drivers "wake up" when
195 something occurs.
196 On Unix the event is a pipe or socket handle (or something that the
198 select system call understands).
199 On Windows the event is an Event or Semaphore (or something that
201 the WaitForMultipleObjects API function understands). (Some trick‐
202 ery in the emulator allows more than the built-in limit of 64
203 Events to be used.)
204 To use this with threads and asynchronous routines, create a pipe
206 on Unix and an Event on Windows. When the routine completes, write
207 to the pipe (use SetEvent on Windows), this makes the emulator call
208 ready_input or ready_output.
209 False events can occur. That is, calls to ready_input or ready_out‐
211 put although no real events are signaled. In reality, it is rare
212 (and OS-dependant), but a robust driver must nevertheless be able
213 to handle such cases.
214 char *driver_name:
216 The driver name. It must correspond to the atom used in
217 erlang:open_port/2, and the name of the driver library file (with‐
218 out the extension).
219 void (*finish)(void):
221 Called by the erl_ddll driver when the driver is unloaded. (It is
222 only called in dynamic drivers.)
223 The driver is only unloaded as a result of calling
225 erl_ddll:unload_driver/1, or when the emulator halts.
226 void *handle:
228 This field is reserved for the emulator's internal use. The emula‐
229 tor will modify this field, so it is important that the
230 driver_entry is not declared const.
231 ErlDrvSSizeT (*control)(ErlDrvData drv_data, unsigned int command,
233 char *buf, ErlDrvSizeT len, char **rbuf, ErlDrvSizeT rlen):
234 A special routine invoked with erlang:port_control/3. It works a
235 little like an "ioctl" for Erlang drivers. The data specified to
236 port_control/3 arrives in buf and len. The driver can send data
237 back, using *rbuf and rlen.
238 This is the fastest way of calling a driver and get a response. It
240 makes no context switch in the Erlang emulator and requires no mes‐
241 sage passing. It is suitable for calling C function to get faster
242 execution, when Erlang is too slow.
243 If the driver wants to return data, it is to return it in rbuf.
245 When control is called, *rbuf points to a default buffer of rlen
246 bytes, which can be used to return data. Data is returned differ‐
247 ently depending on the port control flags (those that are set with
248 erl_driver:set_port_control_flags).
249 If the flag is set to PORT_CONTROL_FLAG_BINARY, a binary is
251 returned. Small binaries can be returned by writing the raw data
252 into the default buffer. A binary can also be returned by setting
253 *rbuf to point to a binary allocated with
254 erl_driver:driver_alloc_binary. This binary is freed automatically
255 after control has returned. The driver can retain the binary for
256 read only access with erl_driver:driver_binary_inc_refc to be freed
257 later with erl_driver:driver_free_binary. It is never allowed to
258 change the binary after control has returned. If *rbuf is set to
259 NULL, an empty list is returned.
260 If the flag is set to 0, data is returned as a list of integers.
262 Either use the default buffer or set *rbuf to point to a larger
263 buffer allocated with erl_driver:driver_alloc. The buffer is freed
264 automatically after control has returned.
265 Using binaries is faster if more than a few bytes are returned.
267 The return value is the number of bytes returned in *rbuf.
269 void (*timeout)(ErlDrvData drv_data):
271 Called any time after the driver's timer reaches 0. The timer is
272 activated with erl_driver:driver_set_timer. No priorities or order‐
273 ing exist among drivers, so if several drivers time out at the same
274 time, anyone of them is called first.
275 void (*outputv)(ErlDrvData drv_data, ErlIOVec *ev):
277 Called whenever the port is written to. If it is NULL, the output
278 function is called instead. This function is faster than output, as
279 it takes an ErlIOVec directly, which requires no copying of the
280 data. The port is to be in binary mode, see erlang:open_port/2.
281 ErlIOVec contains both a SysIOVec, suitable for writev, and one or
283 more binaries. If these binaries are to be retained when the driver
284 returns from outputv, they can be queued (using, for example,
285 erl_driver:driver_enq_bin) or, if they are kept in a static or
286 global variable, the reference counter can be incremented.
287 void (*ready_async)(ErlDrvData drv_data, ErlDrvThreadData
289 thread_data):
290 Called after an asynchronous call has completed. The asynchronous
291 call is started with erl_driver:driver_async. This function is
292 called from the Erlang emulator thread, as opposed to the asynchro‐
293 nous function, which is called in some thread (if multi-threading
294 is enabled).
295 void (*flush)(ErlDrvData drv_data):
297 Called when the port is about to be closed, and there is data in
298 the driver queue that must be flushed before 'stop' can be called.
299 ErlDrvSSizeT (*call)(ErlDrvData drv_data, unsigned int command, char
301 *buf, ErlDrvSizeT len, char **rbuf, ErlDrvSizeT rlen, unsigned int
302 *flags):
303 Called from erlang:port_call/3. It works a lot like the control
304 callback, but uses the external term format for input and output.
305 command is an integer, obtained from the call from Erlang (the sec‐
307 ond argument to erlang:port_call/3).
308 buf and len provide the arguments to the call (the third argument
310 to erlang:port_call/3). They can be decoded using ei functions.
311 rbuf points to a return buffer, rlen bytes long. The return data is
313 to be a valid Erlang term in the external (binary) format. This is
314 converted to an Erlang term and returned by erlang:port_call/3 to
315 the caller. If more space than rlen bytes is needed to return data,
316 *rbuf can be set to memory allocated with erl_driver:driver_alloc.
317 This memory is freed automatically after call has returned.
318 The return value is the number of bytes returned in *rbuf. If
320 ERL_DRV_ERROR_GENERAL is returned (or in fact, anything < 0),
321 erlang:port_call/3 throws a BAD_ARG.
322 void (*event)(ErlDrvData drv_data, ErlDrvEvent event, ErlDrvEventData
324 event_data):
325 Intentionally left undocumented.
326 int extended_marker:
328 This field is either to be equal to ERL_DRV_EXTENDED_MARKER or 0.
329 An old driver (not aware of the extended driver interface) is to
330 set this field to 0. If this field is 0, all the following fields
331 must also be 0, or NULL if it is a pointer field.
332 int major_version:
334 This field is to equal ERL_DRV_EXTENDED_MAJOR_VERSION if field
335 extended_marker equals ERL_DRV_EXTENDED_MARKER.
336 int minor_version:
338 This field is to equal ERL_DRV_EXTENDED_MINOR_VERSION if field
339 extended_marker equals ERL_DRV_EXTENDED_MARKER.
340 int driver_flags:
342 This field is used to pass driver capability and other information
343 to the runtime system. If field extended_marker equals
344 ERL_DRV_EXTENDED_MARKER, it is to contain 0 or driver flags
345 (ERL_DRV_FLAG_*) OR'ed bitwise. The following driver flags exist:
346 ERL_DRV_FLAG_USE_PORT_LOCKING:
348 The runtime system uses port-level locking on all ports executing
349 this driver instead of driver-level locking when the driver is
350 run in a runtime system with SMP support. For more information,
351 see erl_driver.
352 ERL_DRV_FLAG_SOFT_BUSY:
354 Marks that driver instances can handle being called in the output
355 and/or outputv callbacks although a driver instance has marked
356 itself as busy (see erl_driver:set_busy_port). As from ERTS 5.7.4
357 this flag is required for drivers used by the Erlang distribution
358 (the behavior has always been required by drivers used by the
359 distribution).
360 ERL_DRV_FLAG_NO_BUSY_MSGQ:
362 Disables busy port message queue functionality. For more informa‐
363 tion, see erl_driver:erl_drv_busy_msgq_limits.
364 ERL_DRV_FLAG_USE_INIT_ACK:
366 When this flag is specified, the linked-in driver must manually
367 acknowledge that the port has been successfully started using
368 erl_driver:erl_drv_init_ack(). This allows the implementor to
369 make the erlang:open_port exit with badarg after some initial
370 asynchronous initialization has been done.
371 void *handle2:
373 This field is reserved for the emulator's internal use. The emula‐
374 tor modifies this field, so it is important that the driver_entry
375 is not declared const.
376 void (*process_exit)(ErlDrvData drv_data, ErlDrvMonitor *monitor):
378 Called when a monitored process exits. The drv_data is the data
379 associated with the port for which the process is monitored (using
380 erl_driver:driver_monitor_process) and the monitor corresponds to
381 the ErlDrvMonitor structure filled in when creating the monitor.
382 The driver interface function erl_driver:driver_get_moni‐
383 tored_process can be used to retrieve the process ID of the exiting
384 process as an ErlDrvTermData.
385 void (*stop_select)(ErlDrvEvent event, void* reserved):
387 Called on behalf of erl_driver:driver_select when it is safe to
388 close an event object.
389 A typical implementation on Unix is to do close((int)event).
391 Argument reserved is intended for future use and is to be ignored.
393 In contrast to most of the other callback functions, stop_select is
395 called independent of any port. No ErlDrvData argument is passed to
396 the function. No driver lock or port lock is guaranteed to be held.
397 The port that called driver_select can even be closed at the time
398 stop_select is called. But it can also be the case that stop_select
399 is called directly by erl_driver:driver_select.
400 It is not allowed to call any functions in the driver API from
402 stop_select. This strict limitation is because the volatile context
403 that stop_select can be called.
404
406 erl_driver(3), erlang(3), erl_ddll(3)
407Ericsson AB erts 11.2 driver_entry(3)