1driver_entry(3)               C Library Functions              driver_entry(3)
2
3
4

NAME

6       driver_entry - The driver-entry structure used by Erlang drivers.
7

DESCRIPTION

9   Warning:
10       Use this functionality with extreme care.
11
12       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
18         * A driver callback that crash will crash the whole VM.
19
20         * 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
25         * A driver callback doing lengthy work before returning degrades  re‐
26           sponsiveness  of the VM, and can cause miscellaneous strange behav‐
27           iors. Such strange behaviors include, but are not limited  to,  ex‐
28           treme  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
32       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
36   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
41
42       The  driver_entry  structure  is a C struct that all Erlang drivers de‐
43       fine. It contains entry points for the Erlang driver, which are  called
44       by the Erlang emulator when Erlang code accesses the driver.
45
46       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
54       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
59       The driver structure contains the driver  name  and  some  15  function
60       pointers, which are called at different times by the emulator.
61
62       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
68       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
72       extern "C" DRIVER_INIT(drivername);
73
74       When  the  driver has passed the driver_entry over to the emulator, the
75       driver is not allowed to modify the driver_entry.
76
77       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
81   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
87

DATA TYPES

89       ErlDrvEntry
90
91       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
153         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
159         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
164           ERL_DRV_ERROR_GENERAL:
165             General error, no error code
166
167           ERL_DRV_ERROR_ERRNO:
168             Error with error code in errno
169
170           ERL_DRV_ERROR_BADARG:
171             Error, badarg
172
173           If an error code is returned, the port is not started.
174
175         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
181         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
189         void (*ready_input)(ErlDrvData drv_data, ErlDrvEvent event):
190
191
192         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
197           On Unix the event is a pipe or socket handle (or something that the
198           select system call understands).
199
200           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
205           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
210           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
215         char *driver_name:
216           The driver name. It  must  correspond  to  the  atom  used  in  er‐
217           lang:open_port/2,  and the name of the driver library file (without
218           the extension).
219
220         void (*finish)(void):
221           Called by the erl_ddll driver when the driver is unloaded.  (It  is
222           only called in dynamic drivers.)
223
224           The  driver  is  only  unloaded as a result of calling erl_ddll:un‐
225           load_driver/1, or when the emulator halts.
226
227         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 driver_en‐
230           try is not declared const.
231
232         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
239           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
244           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
250           If  the  flag  is  set to PORT_CONTROL_FLAG_BINARY, a binary is re‐
251           turned. Small binaries can be returned by writing the raw data into
252           the  default buffer. A binary can also be returned by setting *rbuf
253           to point to a binary allocated with erl_driver:driver_alloc_binary.
254           This  binary is freed automatically after control has returned. The
255           driver  can  retain  the  binary  for   read   only   access   with
256           erl_driver:driver_binary_inc_refc    to   be   freed   later   with
257           erl_driver:driver_free_binary. It is never allowed  to  change  the
258           binary  after  control  has  returned.  If *rbuf is set to NULL, an
259           empty list is returned.
260
261           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
266           Using binaries is faster if more than a few bytes are returned.
267
268           The return value is the number of bytes returned in *rbuf.
269
270         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
276         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
282           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
288         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
296         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
300         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
306           command is an integer, obtained from the call from Erlang (the sec‐
307           ond argument to erlang:port_call/3).
308
309           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
312           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
319           The  return  value  is  the  number  of bytes returned in *rbuf. If
320           ERL_DRV_ERROR_GENERAL is returned (or in fact, anything <  0),  er‐
321           lang:port_call/3 throws a BAD_ARG.
322
323         void (*event)(ErlDrvData drv_data, ErlDrvEvent event, ErlDrvEventData
324         event_data):
325           Intentionally left undocumented.
326
327         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
333         int major_version:
334           This  field is to equal ERL_DRV_EXTENDED_MAJOR_VERSION if field ex‐
335           tended_marker equals ERL_DRV_EXTENDED_MARKER.
336
337         int minor_version:
338           This field is to equal ERL_DRV_EXTENDED_MINOR_VERSION if field  ex‐
339           tended_marker equals ERL_DRV_EXTENDED_MARKER.
340
341         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  ERL_DRV_EX‐
344           TENDED_MARKER,  it is to contain 0 or driver flags (ERL_DRV_FLAG_*)
345           OR'ed bitwise. The following driver flags exist:
346
347           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. For more informa‐
350             tion, see erl_driver.
351
352           ERL_DRV_FLAG_SOFT_BUSY:
353             Marks that driver instances can handle being called in the output
354             and/or  outputv  callbacks  although a driver instance has marked
355             itself as busy (see erl_driver:set_busy_port). As from ERTS 5.7.4
356             this flag is required for drivers used by the Erlang distribution
357             (the behavior has always been required by  drivers  used  by  the
358             distribution).
359
360           ERL_DRV_FLAG_NO_BUSY_MSGQ:
361             Disables busy port message queue functionality. For more informa‐
362             tion, see erl_driver:erl_drv_busy_msgq_limits.
363
364           ERL_DRV_FLAG_USE_INIT_ACK:
365             When this flag is specified, the linked-in driver  must  manually
366             acknowledge  that  the  port  has been successfully started using
367             erl_driver:erl_drv_init_ack(). This  allows  the  implementor  to
368             make  the  erlang:open_port  exit  with badarg after some initial
369             asynchronous initialization has been done.
370
371         void *handle2:
372           This field is reserved for the emulator's internal use. The  emula‐
373           tor  modifies  this field, so it is important that the driver_entry
374           is not declared const.
375
376         void (*process_exit)(ErlDrvData drv_data, ErlDrvMonitor *monitor):
377           Called when a monitored process exits. The drv_data is the data as‐
378           sociated  with  the  port for which the process is monitored (using
379           erl_driver:driver_monitor_process) and the monitor  corresponds  to
380           the  ErlDrvMonitor  structure  filled in when creating the monitor.
381           The   driver   interface    function    erl_driver:driver_get_moni‐
382           tored_process can be used to retrieve the process ID of the exiting
383           process as an ErlDrvTermData.
384
385         void (*stop_select)(ErlDrvEvent event, void* reserved):
386           Called on behalf of erl_driver:driver_select when  it  is  safe  to
387           close an event object.
388
389           A typical implementation on Unix is to do close((int)event).
390
391           Argument reserved is intended for future use and is to be ignored.
392
393           In contrast to most of the other callback functions, stop_select is
394           called independent of any port. No ErlDrvData argument is passed to
395           the function. No driver lock or port lock is guaranteed to be held.
396           The port that called driver_select can even be closed at  the  time
397           stop_select is called. But it can also be the case that stop_select
398           is called directly by erl_driver:driver_select.
399
400           It is not allowed to call any functions  in  the  driver  API  from
401           stop_select. This strict limitation is because the volatile context
402           that stop_select can be called.
403

SEE ALSO

405       erl_driver(3), erlang(3), erl_ddll(3)
406
407
408
409Ericsson AB                       erts 13.1.4                  driver_entry(3)
Impressum