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
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
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
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
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
217           erlang:open_port/2,  and the name of the driver library file (with‐
218           out 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
225           erl_ddll:unload_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
230           driver_entry 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
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
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),
321           erlang: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
335           extended_marker equals ERL_DRV_EXTENDED_MARKER.
336
337         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
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
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
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 when the driver is
350             run in a runtime system with SMP support. For  more  information,
351             see erl_driver.
352
353           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
361           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
365           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
372         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
377         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
386         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
390           A typical implementation on Unix is to do close((int)event).
391
392           Argument reserved is intended for future use and is to be ignored.
393
394           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
401           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

SEE ALSO

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