## 6 How to implement a driver

### 6.1 Introduction

This chapter tells you how to build your own driver for erlang.

A driver in erlang is a library written in C, that is linked to the erlang emulator and called from erlang. Drivers can be used when C is more suitable than erlang, to speed things up, or to provide access to OS resources not directly accessible from erlang.

A driver can be dynamically loaded, as a shared library (DLL), or statically loaded, linked with the emulator when it is compiled and linked. Only dynamically loaded drivers are described here, statically linked drivers are beyond the scope of this chapter.

When a driver is loaded it is executed in the context of the emulator, shares the same memory and the same thread. This means that all operations in the driver must be non-blocking, and that any crash in the driver will bring the whole emulator down. In short: you have to be extremely careful!

### 6.2 Sample driver

...

### 6.3 Compiling and linking a driver

...

### 6.4 Calling a driver as a port in erlang

...

### 6.5 The driver structure

The header file `erl_driver.h` contains all types, macros and prototypes needed for the driver.

The only exported function from the driver is `driver_init`. This function returns the driver_entry structure that points to the other functions in the driver. The driver_init function is declared with a macro `DRIVER_INIT(drivername)`. (This is because different OS's have different names for it.)

The driver structure contains the name of the driver and some 15 function pointers. These pointers are called at different times by the emulator. Here is the declaration of `driver_entry`:

    typedef struct erl_drv_entry {
        int (*init)(void);          /* called at system start up for statically
                                       linked drivers, and after loading for
                                       dynamically loaded drivers */
        ErlDrvData (*start)(ErlDrvPort port, char *command);
                                    /* called when open_port/2 is invoked.
                                       return value -1 means failure. */
        void (*stop)(ErlDrvData drv_data);
                                    /* called when port is closed, and when the
                                       emulator is halted. */
        void (*output)(ErlDrvData drv_data, char *buf, int len);
                                    /* called when we have output from erlang to
                                       the port */
        void (*ready_input)(ErlDrvData drv_data, ErlDrvEvent event);
                                    /* called when we have input from one of
                                       the driver's handles) */
        void (*ready_output)(ErlDrvData drv_data, ErlDrvEvent event);
                                    /* called when output is possible to one of
                                       the driver's handles */
        char *driver_name;          /* name supplied as command
                                       in open_port XXX ? */
        void (*finish)(void);        /* called before unloading the driver -
                                       DYNAMIC DRIVERS ONLY */
        void *handle;               /* not used -- here for backwards compatibility */
        int (*control)(ErlDrvData drv_data, unsigned int command, char *buf,
                       int len, char **rbuf, int rlen);
                                    /* "ioctl" for drivers - invoked by
                                       port_command/3) */
        void (*timeout)(ErlDrvData drv_data);       /* Handling of timeout in driver */
        void (*outputv)(ErlDrvData drv_data, ErlIOVec *ev);
                                    /* called when we have output from erlang
                                       to the port */
        void (*ready_async)(ErlDrvData drv_data, ErlDrvThreadData thred_data);
    } ErlDrvEntry;

### 6.6 Driver callbacks

The erlang emulator has callbacks that the driver uses.

### 6.7 Threads and drivers

...

### 6.8 Drivers on specific platforms

#### 6.8.1 Solaris

...

#### 6.8.2 Windows

...

#### 6.8.3 VxWorks

...

### 6.9 Loading drivers

...

### 6.10 Preloaded drivers

...

### 6.11 Handling the binary term format with ei

#### 6.11.1 Introduction

`ei` is a small set of C routines to encode and decode the erlang binary term format. It is just some small functions that encodes and decodes terms in the binary format. It is generally a lot faster than `erl_interface` and suitable to use in drivers and port programs.

The functions in ei is provided in library, with some header files. Each function is described in the reference manual.

...

Copyright © 1991-2005 Ericsson AB