Merge tag 'OTP-20.0' into sverker/20/binary_to_atom-utf8-crash/ERL-474/OTP-14590

1 files changed, 350 insertions, 291 deletions

diff --git a/erts/doc/src/driver_entry.xml b/erts/doc/src/driver_entry.xml
index ae7f264d0c..2421e0a8d9 100644
--- a/erts/doc/src/driver_entry.xml
+++ b/erts/doc/src/driver_entry.xml
@@ -4,7 +4,7 @@
 <cref>
   <header>
     <copyright>
-      <year>2001</year><year>2015</year>
+      <year>2001</year><year>2016</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -33,55 +33,64 @@
     <file>driver_entry.xml</file>
   </header>
   <lib>driver_entry</lib>
-  <libsummary>The driver-entry structure used by erlang drivers.</libsummary>
+  <libsummary>The driver-entry structure used by Erlang drivers.</libsummary>
   <description>
     <marker id="WARNING"/>
-      <warning><p><em>Use this functionality with extreme care!</em></p>
+    <warning>
+      <p><em>Use this functionality with extreme care.</em></p>
       <p>A driver callback is executed as a direct extension of the
-      native code of the VM. Execution is not made in a safe environment.
-      The VM can <em>not</em> provide the same services as provided when
-      executing Erlang code, such as preemptive scheduling or memory
-      protection. If the driver callback function doesn't behave well,
-      the whole VM will misbehave.</p>
-      <list>
-	<item><p>A driver callback that crash will crash the whole VM.</p></item>
-	<item><p>An erroneously implemented driver callback might cause
-	a VM internal state inconsistency which may cause a crash of the VM,
-	or miscellaneous misbehaviors of the VM at any point after the call
-	to the driver callback.</p></item>
-	<item><p>A driver callback that do
-	<seealso marker="erl_driver#lengthy_work">lengthy work</seealso>
-	before returning will degrade responsiveness of the VM,
-	and may cause miscellaneous strange behaviors. Such strange behaviors
-	include, but are not limited to, extreme memory usage, and bad load
-	balancing between schedulers. Strange behaviors that might occur due
-	to lengthy work may also vary between OTP releases.</p></item>
+        native code of the VM. Execution is not made in a safe environment.
+        The VM <em>cannot</em> provide the same services as provided when
+        executing Erlang code, such as pre-emptive scheduling or memory
+        protection. If the driver callback function does not behave well,
+        the whole VM will misbehave.</p>
+      <list type="bulleted">
+        <item>
+          <p>A driver callback that crash will crash the whole VM.</p>
+        </item>
+        <item>
+          <p>An erroneously implemented driver callback can cause a VM
+            internal state inconsistency, which can cause a crash of the VM,
+            or miscellaneous misbehaviors of the VM at any point after the
+            call to the driver callback.</p>
+        </item>
+        <item>
+          <p>A driver callback doing
+            <seealso marker="erl_driver#lengthy_work">lengthy work</seealso>
+            before returning degrades responsiveness of the VM, and can cause
+            miscellaneous strange behaviors. Such strange behaviors
+            include, but are not limited to, extreme memory usage, and bad
+            load balancing between schedulers. Strange behaviors that can
+            occur because of lengthy work can also vary between Erlang/OTP
+            releases.</p>
+        </item>
       </list>
-      </warning>
-    <p>
-      As of erts version 5.9 (OTP release R15B) the driver interface
+    </warning>
+
+    <p>As from ERTS 5.9 (Erlang/OTP R15B) the driver interface
       has been changed with larger types for the callbacks
-      <seealso marker="#output">output</seealso>,
-      <seealso marker="#control">control</seealso> and
-      <seealso marker="#call">call</seealso>.
+      <seealso marker="#output"><c>output</c></seealso>,
+      <seealso marker="#control"><c>control</c></seealso>, and
+      <seealso marker="#call"><c>call</c></seealso>.
       See driver <seealso marker="erl_driver#version_management">
       version management</seealso> in
-      <seealso marker="erl_driver">erl_driver</seealso>.
-    </p>
+      <seealso marker="erl_driver"><c>erl_driver</c></seealso>.</p>
+
     <note>
       <p>Old drivers (compiled with an <c>erl_driver.h</c> from an
-      earlier erts version than 5.9) have to be updated and have
-      to use the extended interface (with
-      <seealso marker="erl_driver#version_management">version management
-      </seealso>).</p>
+        ERTS version earlier than 5.9) must be updated and have
+        to use the extended interface (with
+        <seealso marker="erl_driver#version_management">version management
+        </seealso>).</p>
     </note>
-    <p>The <c>driver_entry</c> structure is a C struct that all erlang
-      drivers define. It contains entry points for the erlang driver
-      that are called by the erlang emulator when erlang code accesses
+
+    <p>The <c>driver_entry</c> structure is a C struct that all Erlang
+      drivers define. It contains entry points for the Erlang driver,
+      which are called by the Erlang emulator when Erlang code accesses
       the driver.</p>
-    <p>      
-      <marker id="emulator"></marker>
-      The <seealso marker="erl_driver">erl_driver</seealso> driver
+
+    <p><marker id="emulator"></marker>
+      The <seealso marker="erl_driver"><c>erl_driver</c></seealso> driver
       API functions need a port handle
       that identifies the driver instance (and the port in the
       emulator). This is only passed to the <c>start</c> function, but
@@ -90,416 +99,466 @@
       common practice is to have the <c>start</c> function allocate
       some application-defined structure and stash the <c>port</c>
       handle in it, to use it later with the driver API functions.</p>
-    <p>The driver call-back functions are called synchronously from the
-      erlang emulator. If they take too long before completing, they
-      can cause timeouts in the emulator. Use the queue or
-      asynchronous calls if necessary, since the emulator must be
+
+    <p>The driver callback functions are called synchronously from the
+      Erlang emulator. If they take too long before completing, they
+      can cause time-outs in the emulator. Use the queue or
+      asynchronous calls if necessary, as the emulator must be
       responsive.</p>
-    <p>The driver structure contains the name of the driver and some
-      15 function pointers. These pointers are called at different
+
+    <p>The driver structure contains the driver name and some
+      15 function pointers, which are called at different
       times by the emulator.</p>
+
     <p>The only exported function from the driver is
       <c>driver_init</c>. This function returns the <c>driver_entry</c>
       structure that points to the other functions in the driver. The
-      <c>driver_init</c> function is declared with a macro
-      <c>DRIVER_INIT(drivername)</c>. (This is because different OS's
-      have different names for it.)</p>
-    <p>When writing a driver in C++, the driver entry should be of
-      <c>"C"</c> linkage. One way to do this is to put this line
-      somewhere before the driver entry:
-      <c>extern "C" DRIVER_INIT(drivername);</c>.</p>
+      <c>driver_init</c> function is declared with a macro,
+      <c>DRIVER_INIT(drivername)</c>. (This is because different
+      operating systems have different names for it.)</p>
+
+    <p>When writing a driver in C++, the driver entry is to be of
+      <c>"C"</c> linkage. One way to do this is to put the
+      following line somewhere before the driver entry:</p>
+
+    <pre>
+extern "C" DRIVER_INIT(drivername);</pre>
+
     <p>When the driver has passed the <c>driver_entry</c> over to
       the emulator, the driver is <em>not</em> allowed to modify the
       <c>driver_entry</c>.</p>
-    <p>If compiling a driver for static inclusion via --enable-static-drivers you
-    have to define STATIC_ERLANG_DRIVER before the DRIVER_INIT declaration.</p>
+
+    <p>If compiling a driver for static inclusion through
+      <c>--enable-static-drivers</c>, you must define
+      <c>STATIC_ERLANG_DRIVER</c> before the <c>DRIVER_INIT</c> declaration.</p>
+
     <note>
-      <p>Do <em>not</em> declare the <c>driver_entry</c> <c>const</c>. This since the emulator needs to
-        modify the <c>handle</c>, and the <c>handle2</c>
-        fields. A statically allocated, and <c>const</c>
-        declared <c>driver_entry</c> may be located in
-        read only memory which will cause the emulator
-        to crash.</p>
+      <p>Do <em>not</em> declare the <c>driver_entry</c> <c>const</c>.
+        This because the emulator must
+        modify the <c>handle</c> and the <c>handle2</c>
+        fields. A statically allocated, and <c>const</c>-declared
+        <c>driver_entry</c> can be located in
+        read-only memory, which causes the emulator to crash.</p>
     </note>
   </description>
 
   <section>
-    <title>DATA TYPES</title>
-    <taglist>
-    <tag><em>ErlDrvEntry</em></tag>
-    <item>
-    <p/>
+    <title>Data Types</title>
+    <p><c>ErlDrvEntry</c></p>
     <code type="none">
 typedef struct erl_drv_entry {
-    int (*init)(void);          /* called at system start up for statically
+    int (*init)(void);          /* Called at system startup for statically
                                    linked drivers, and after loading for
-                                   dynamically loaded drivers */ 
-
+                                   dynamically loaded drivers */
 #ifndef ERL_SYS_DRV
     ErlDrvData (*start)(ErlDrvPort port, char *command);
-                                /* called when open_port/2 is invoked.
-                                   return value -1 means failure. */
+                                /* Called when open_port/2 is invoked,
+                                   return value -1 means failure */
 #else
     ErlDrvData (*start)(ErlDrvPort port, char *command, SysDriverOpts* opts);
-                                /* special options, only for system driver */
+                                /* Special options, only for system driver */
 #endif
     void (*stop)(ErlDrvData drv_data);
-                                /* called when port is closed, and when the
-                                   emulator is halted. */
+                                /* Called when port is closed, and when the
+                                   emulator is halted */
     void (*output)(ErlDrvData drv_data, char *buf, ErlDrvSizeT len);
-                                /* called when we have output from erlang to 
+                                /* 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 
+                                /* 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 
+                                /* 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;               /* Reserved -- Used by emulator internally */
+    char *driver_name;          /* Name supplied as command in
+                                   erlang:open_port/2 */
+    void (*finish)(void);       /* Called before unloading the driver -
+                                   dynamic drivers only */
+    void *handle;               /* Reserved, used by emulator internally */
     ErlDrvSSizeT (*control)(ErlDrvData drv_data, unsigned int command,
                             char *buf, ErlDrvSizeT len,
 			    char **rbuf, ErlDrvSizeT rlen);
-                                /* "ioctl" for drivers - invoked by 
+                                /* "ioctl" for drivers - invoked by
                                    port_control/3 */
-    void (*timeout)(ErlDrvData drv_data);        /* Handling of timeout in driver */
+    void (*timeout)(ErlDrvData drv_data);
+                                /* Handling of time-out in driver */
     void (*outputv)(ErlDrvData drv_data, ErlIOVec *ev);
-                                /* called when we have output from erlang
+                                /* Called when we have output from Erlang
                                    to the port */
     void (*ready_async)(ErlDrvData drv_data, ErlDrvThreadData thread_data);
     void (*flush)(ErlDrvData drv_data);
-                                /* called when the port is about to be 
-                                   closed, and there is data in the 
-                                   driver queue that needs to be flushed
+                                /* Called when the port is about to be
+                                   closed, and there is data in the
+                                   driver queue that must be flushed
                                    before 'stop' can be called */
     ErlDrvSSizeT (*call)(ErlDrvData drv_data, unsigned int command,
                          char *buf, ErlDrvSizeT len,
 			 char **rbuf, ErlDrvSizeT rlen, unsigned int *flags);
                                 /* Works mostly like 'control', a synchronous
-                                   call into the driver. */
+                                   call into the driver */
     void (*event)(ErlDrvData drv_data, ErlDrvEvent event,
                   ErlDrvEventData event_data);
-                                /* Called when an event selected by 
+                                /* Called when an event selected by
                                    driver_event() has occurred */
     int extended_marker;        /* ERL_DRV_EXTENDED_MARKER */
     int major_version;          /* ERL_DRV_EXTENDED_MAJOR_VERSION */
     int minor_version;          /* ERL_DRV_EXTENDED_MINOR_VERSION */
     int driver_flags;           /* ERL_DRV_FLAGs */
-    void *handle2;              /* Reserved -- Used by emulator internally */
+    void *handle2;              /* Reserved, used by emulator internally */
     void (*process_exit)(ErlDrvData drv_data, ErlDrvMonitor *monitor);
                                 /* Called when a process monitor fires */
     void (*stop_select)(ErlDrvEvent event, void* reserved);
                                 /* Called to close an event object */
- } ErlDrvEntry;
-    </code>
-    <p/>
+ } ErlDrvEntry;</code>
     <taglist>
-      <tag><marker id="init"/>int (*init)(void)</tag>
-      <item>        
-        <p>This is called directly after the driver has been loaded by
-          <c>erl_ddll:load_driver/2</c>. (Actually when the driver is
-          added to the driver list.) The driver should return 0, or if
-          the driver can't initialize, -1.</p>
+      <tag><marker id="init"/><c>int (*init)(void)</c></tag>
+      <item>       
+        <p>Called directly after the driver has been loaded by
+          <seealso marker="kernel:erl_ddll#load_driver/2">
+          <c>erl_ddll:load_driver/2</c></seealso> (actually when the driver is
+          added to the driver list). The driver is to return <c>0</c>, or, if
+          the driver cannot initialize, <c>-1</c>.</p>
       </item>
-      <tag><marker id="start"/>ErlDrvData (*start)(ErlDrvPort port, char* command)</tag>
+      <tag><marker id="start"/>
+        <c>ErlDrvData (*start)(ErlDrvPort port, char* command)</c></tag>
       <item>
-        <p>This is called when the driver is instantiated, when
-          <c>open_port/2</c> is called. The driver should return a
-          number &gt;= 0 or a pointer, or if the driver can't be started,
-          one of three error codes should be returned:</p>
-        <p>ERL_DRV_ERROR_GENERAL - general error, no error code</p>
-        <p>ERL_DRV_ERROR_ERRNO - error with error code in <c>errno</c></p>
-        <p>ERL_DRV_ERROR_BADARG - error, badarg</p>
-        <p>If an error code is returned, the port isn't started.</p>
+        <p>Called when the driver is instantiated, when
+          <seealso marker="erlang#open_port/2">
+          <c>erlang:open_port/2</c></seealso> is called.
+          The driver is to return a number &gt;= 0 or a pointer, or, if the
+          driver cannot be started, one of three error codes:</p>
+        <taglist>
+          <tag><c>ERL_DRV_ERROR_GENERAL</c></tag>
+          <item>General error, no error code</item>
+          <tag><c>ERL_DRV_ERROR_ERRNO</c></tag>
+          <item>Error with error code in <c>errno</c></item>
+          <tag><c>ERL_DRV_ERROR_BADARG</c></tag>
+          <item>Error, <c>badarg</c></item>
+        </taglist>
+        <p>If an error code is returned, the port is not started.</p>
       </item>
-      <tag><marker id="stop"/>void (*stop)(ErlDrvData drv_data)</tag>
+      <tag><marker id="stop"/><c>void (*stop)(ErlDrvData drv_data)</c></tag>
       <item>
-        <p>This is called when the port is closed, with
-          <c>port_close/1</c> or <c>Port ! {self(), close}</c>. Note
-          that terminating the port owner process also closes the
+        <p>Called when the port is closed, with
+          <seealso marker="erlang#port_close/1">
+          <c>erlang:port_close/1</c></seealso> or <c>Port ! {self(), close}</c>.
+          Notice that terminating the port owner process also closes the
           port. If <c>drv_data</c> is a pointer to memory allocated in
-	  <c>start</c>, then <c>stop</c> is the place to deallocate that
-	  memory.</p>
+          <c>start</c>, then <c>stop</c> is the place to deallocate that
+          memory.</p>
       </item>
-      <tag><marker id="output"/>void (*output)(ErlDrvData drv_data, char *buf, ErlDrvSizeT len)</tag>
+      <tag><marker id="output"/>
+        <c>void (*output)(ErlDrvData drv_data, char *buf, ErlDrvSizeT len)</c>
+      </tag>
       <item>
-        <p>This is called when an erlang process has sent data to the
-          port. The data is pointed to by <c>buf</c>, and is
-          <c>len</c> bytes.  Data is sent to the port with <c>Port ! {self(), {command, Data}}</c>, or with
-          <c>port_command/2</c>. Depending on how the port was opened,
-          it should be either a list of integers 0...255 or a
-          binary. See <c>open_port/3</c> and <c>port_command/2</c>.</p>
+        <p>Called when an Erlang process has sent data to the port. The data is
+          pointed to by <c>buf</c>, and is <c>len</c> bytes. Data is sent to
+          the port with <c>Port ! {self(), {command, Data}}</c> or with
+          <c>erlang:port_command/2</c>. Depending on how the port was
+          opened, it is to be either a list of integers <c>0...255</c> or a
+          binary. See <seealso marker="erlang#open_port/2">
+          <c>erlang:open_port/2</c></seealso> and
+          <seealso marker="erlang#port_command/2">
+          <c>erlang:port_command/2</c></seealso>.</p>
       </item>
-
-      <tag><marker id="ready_input"/>void (*ready_input)(ErlDrvData drv_data, ErlDrvEvent event)</tag>
-      <item/>
-      <tag><marker id="ready_output"/>void (*ready_output)(ErlDrvData drv_data, ErlDrvEvent event)</tag>
+      <tag><marker id="ready_input"/>
+        <c>void (*ready_input)(ErlDrvData drv_data, ErlDrvEvent event)</c>
+      </tag>
+      <item></item>
+      <tag><marker id="ready_output"/>
+        <c>void (*ready_output)(ErlDrvData drv_data, ErlDrvEvent event)</c>
+      </tag>
       <item>
-        <p>This is called when a driver event (given in the
-          <c>event</c> parameter) is signaled. This is used to help
-          asynchronous drivers "wake up" when something happens.</p>
-        <p>On unix the <c>event</c> is a pipe or socket handle (or
+        <p>Called when a driver event (specified in parameter
+          <c>event</c>) is signaled. This is used to help
+          asynchronous drivers "wake up" when something occurs.</p>
+        <p>On Unix the <c>event</c> is a pipe or socket handle (or
           something that the <c>select</c> system call understands).</p>
-        <p>On Windows the <c>event</c> is an Event or Semaphore (or
-          something that the <c>WaitForMultipleObjects</c> API
+        <p>On Windows the <c>event</c> is an <c>Event</c> or <c>Semaphore</c>
+          (or something that the <c>WaitForMultipleObjects</c> API
           function understands). (Some trickery in the emulator allows
           more than the built-in limit of 64 <c>Events</c> to be used.)</p>
         <p>To use this with threads and asynchronous routines, create a
-          pipe on unix and an Event on Windows. When the routine
+          pipe on Unix and an <c>Event</c> on Windows. When the routine
           completes, write to the pipe (use <c>SetEvent</c> on
-          Windows), this will make the emulator call
+          Windows), this makes the emulator call
           <c>ready_input</c> or <c>ready_output</c>.</p>
-          <p>Spurious events may happen. That is, calls to <c>ready_input</c>
-          or <c>ready_output</c> even though no real events are signaled. In
-          reality it should be rare (and OS dependant), but a robust driver
+        <p>False events can occur. That is, calls to <c>ready_input</c>
+          or <c>ready_output</c> although no real events are signaled. In
+          reality, it is rare (and OS-dependant), but a robust driver
           must nevertheless be able to handle such cases.</p>
       </item>
-      <tag><marker id="driver_name"/>char *driver_name</tag>
+      <tag><marker id="driver_name"/><c>char *driver_name</c></tag>
       <item>
-        <p>This is the name of the driver, it must correspond to the
-          atom used in <c>open_port</c>, and the name of the driver
+        <p>The driver name. It must correspond to the atom used in
+          <seealso marker="erlang#open_port/2">
+          <c>erlang:open_port/2</c></seealso>, and the name of the driver
           library file (without the extension).</p>
       </item>
-      <tag><marker id="finish"/>void (*finish)(void)</tag>
+      <tag><marker id="finish"/><c>void (*finish)(void)</c></tag>
       <item>
-        <p>This function is called by the <c>erl_ddll</c> driver when the
+        <p>Called by the <c>erl_ddll</c> driver when the
           driver is unloaded. (It is only called in dynamic drivers.)</p>
         <p>The driver is only unloaded as a result of calling
-          <c>unload_driver/1</c>, or when the emulator halts.</p>
+          <seealso marker="kernel:erl_ddll#unload_driver/1">
+          <c>erl_ddll:unload_driver/1</c></seealso>,
+          or when the emulator halts.</p>
       </item>
-      <tag>void *handle</tag>
+      <tag><c>void *handle</c></tag>
       <item>
         <p>This field is reserved for the emulator's internal use. The
-          emulator will modify this field; therefore, it is important
-          that the <c>driver_entry</c> isn't declared <c>const</c>.</p> 
+          emulator will modify this field, so it is important
+          that the <c>driver_entry</c> is not declared <c>const</c>.</p> 
       </item>
-      <tag><marker id="control"></marker>ErlDrvSSizeT (*control)(ErlDrvData drv_data, unsigned int command, char *buf, ErlDrvSizeT len, char **rbuf, ErlDrvSizeT rlen)</tag>
+      <tag><marker id="control"></marker>
+        <c>ErlDrvSSizeT (*control)(ErlDrvData drv_data, unsigned int command,
+        char *buf, ErlDrvSizeT len, char **rbuf, ErlDrvSizeT rlen)</c></tag>
       <item>
-        <p>This is a special routine invoked with the erlang function
-          <c>port_control/3</c>. It works a little like an "ioctl" for
-          erlang drivers. The data given to <c>port_control/3</c>
-          arrives in <c>buf</c> and <c>len</c>. The driver may send
+        <p>A special routine invoked with
+          <seealso marker="erlang#port_control/3">
+          <c>erlang:port_control/3</c></seealso>.
+          It works a little like an "ioctl" for
+          Erlang drivers. The data specified to <c>port_control/3</c>
+          arrives in <c>buf</c> and <c>len</c>. The driver can send
           data back, using <c>*rbuf</c> and <c>rlen</c>.</p>
         <p>This is the fastest way of calling a driver and get a
-          response. It won't make any context switch in the erlang
-          emulator, and requires no message passing. It is suitable
-          for calling C function to get faster execution, when erlang
+          response. It makes no context switch in the Erlang
+          emulator and requires no message passing. It is suitable
+          for calling C function to get faster execution, when Erlang
           is too slow.</p>
-        <p>If the driver wants to return data, it should return it in
+        <p>If the driver wants to return data, it is to return it in
           <c>rbuf</c>. When <c>control</c> is called,
           <c>*rbuf</c> points to a default buffer of <c>rlen</c> bytes, which
-          can be used to return data. Data is returned different depending on
+          can be used to return data. Data is returned differently depending on
           the port control flags (those that are set with
-          <seealso marker="erl_driver#set_port_control_flags">set_port_control_flags</seealso>).
-          </p>
+          <seealso marker="erl_driver#set_port_control_flags">
+          <c>erl_driver:set_port_control_flags</c></seealso>).</p>
         <p>If the flag is set to <c>PORT_CONTROL_FLAG_BINARY</c>,
-           a binary will be returned. Small binaries can be returned by writing
-           the raw data into the default buffer. A binary can also be
-           returned by setting <c>*rbuf</c> to point to a binary allocated with
-          <seealso marker="erl_driver#driver_alloc_binary">driver_alloc_binary</seealso>.
-          This binary will be freed automatically after <c>control</c> has returned.
+          a binary is returned. Small binaries can be returned by writing
+          the raw data into the default buffer. A binary can also be
+          returned by setting <c>*rbuf</c> to point to a binary allocated with
+          <seealso marker="erl_driver#driver_alloc_binary">
+          <c>erl_driver:driver_alloc_binary</c></seealso>.
+          This binary is freed automatically after <c>control</c> has returned.
           The driver can retain the binary for <em>read only</em> access with
-          <seealso marker="erl_driver#driver_binary_inc_refc">driver_binary_inc_refc</seealso> to be freed later with
-          <seealso marker="erl_driver#driver_free_binary">driver_free_binary</seealso>.
-          It is never allowed to alter the binary after <c>control</c> has returned.
-          If <c>*rbuf</c> is set to NULL, an empty list will be returned.
-          </p>
+          <seealso marker="erl_driver#driver_binary_inc_refc">
+          <c>erl_driver:driver_binary_inc_refc</c></seealso> to be freed later
+          with <seealso marker="erl_driver#driver_free_binary">
+          <c>erl_driver:driver_free_binary</c></seealso>.
+          It is never allowed to change the binary after <c>control</c> has
+          returned. If <c>*rbuf</c> is set to <c>NULL</c>, an empty list is
+          returned.</p>
         <p>If the flag is set to <c>0</c>, data is returned as a
           list of integers. Either use the default buffer or set
           <c>*rbuf</c> to point to a larger buffer allocated with
-          <seealso marker="erl_driver#driver_alloc">driver_alloc</seealso>.
-          The buffer will be freed automatically after <c>control</c> has returned.</p>
+          <seealso marker="erl_driver#driver_alloc">
+          <c>erl_driver:driver_alloc</c></seealso>. The
+          buffer is freed automatically after <c>control</c> has returned.</p>
         <p>Using binaries is faster if more than a few bytes are returned.</p>
-        <p>The return value is the number of bytes returned in
-          <c>*rbuf</c>.</p>
+        <p>The return value is the number of bytes returned in <c>*rbuf</c>.</p>
       </item>
-
-      <tag><marker id="timeout"/>void (*timeout)(ErlDrvData drv_data)</tag>
+      <tag><marker id="timeout"/><c>void (*timeout)(ErlDrvData drv_data)</c>
+      </tag>
       <item>
-        <p>This function is called any time after the driver's timer
-          reaches 0. The timer is activated with
-          <c>driver_set_timer</c>. There are no priorities or ordering
-          among drivers, so if several drivers time out at the same
-          time, any one of them is called first.</p>
+        <p>Called any time after the driver's timer reaches <c>0</c>.
+          The timer is activated with
+          <seealso marker="erl_driver#driver_set_timer">
+          <c>erl_driver:driver_set_timer</c></seealso>. No priorities or
+          ordering exist among drivers, so if several drivers time out at
+          the same time, anyone of them is called first.</p>
       </item>
-
-      <tag><marker id="outputv"/>void (*outputv)(ErlDrvData drv_data, ErlIOVec *ev)</tag>
+      <tag><marker id="outputv"/>
+        <c>void (*outputv)(ErlDrvData drv_data, ErlIOVec *ev)</c></tag>
       <item>
-        <p>This function is called whenever the port is written to. If
+        <p>Called whenever the port is written to. If
           it is <c>NULL</c>, the <c>output</c> function is called
-          instead. This function is faster than <c>output</c>, because
+          instead. This function is faster than <c>output</c>, as
           it takes an <c>ErlIOVec</c> directly, which requires no
-          copying of the data. The port should be in binary mode, see
-          <c>open_port/2</c>.</p>
-        <p>The <c>ErlIOVec</c> contains both a <c>SysIOVec</c>,
+          copying of the data. The port is to be in binary mode, see
+          <seealso marker="erlang#open_port/2">
+          <c>erlang:open_port/2</c></seealso>.</p>
+        <p><c>ErlIOVec</c> contains both a <c>SysIOVec</c>,
           suitable for <c>writev</c>, and one or more binaries. If
-          these binaries should be retained, when the driver returns
-          from <c>outputv</c>, they can be queued (using <seealso marker="erl_driver#driver_enq_bin">driver_enq_bin</seealso>
-          for instance), or if they are kept in a static or global
+          these binaries are to be retained when the driver returns
+          from <c>outputv</c>, they can be queued (using, for example,
+          <seealso marker="erl_driver#driver_enq_bin">
+          <c>erl_driver:driver_enq_bin</c></seealso>)
+          or, if they are kept in a static or global
           variable, the reference counter can be incremented.</p>
       </item>
-      <tag><marker id="ready_async"/>void (*ready_async)(ErlDrvData drv_data, ErlDrvThreadData thread_data)</tag>
+      <tag><marker id="ready_async"/>
+        <c>void (*ready_async)(ErlDrvData drv_data, ErlDrvThreadData
+        thread_data)</c></tag>
       <item>
-        <p>This function is called after an asynchronous call has
-          completed. The asynchronous call is started with <seealso marker="erl_driver#driver_async">driver_async</seealso>.
-          This function is called from the erlang emulator thread, as
+        <p>Called after an asynchronous call has completed.
+          The asynchronous call is started with
+          <seealso marker="erl_driver#driver_async">
+          <c>erl_driver:driver_async</c></seealso>.
+          This function is called from the Erlang emulator thread, as
           opposed to the asynchronous function, which is called in
-          some thread (if multithreading is enabled).</p>
+          some thread (if multi-threading is enabled).</p>
+      </item>
+      <tag><c>void (*flush)(ErlDrvData drv_data)</c></tag>
+      <item>
+        <p>Called when the port is about to be closed,
+          and there is data in the driver queue that must be flushed
+          before 'stop' can be called.</p>
       </item>
-      <tag><marker id="call"/>ErlDrvSSizeT (*call)(ErlDrvData drv_data, unsigned int command, char *buf, ErlDrvSizeT len, char **rbuf, ErlDrvSizeT rlen, unsigned int *flags)</tag>
+      <tag><marker id="call"/><c>ErlDrvSSizeT (*call)(ErlDrvData drv_data,
+        unsigned int command, char *buf, ErlDrvSizeT len, char **rbuf,
+        ErlDrvSizeT rlen, unsigned int *flags)</c></tag>
       <item>
-        <p>This function is called from <c>erlang:port_call/3</c>. It
-          works a lot like the <c>control</c> call-back, but uses the
+        <p>Called from <seealso marker="erlang#port_call/3">
+          <c>erlang:port_call/3</c></seealso>.
+          It works a lot like the <c>control</c> callback, but uses the
           external term format for input and output.</p>
         <p><c>command</c> is an integer, obtained from the call from
-          erlang (the second argument to <c>erlang:port_call/3</c>).</p>
+          Erlang (the second argument to <c>erlang:port_call/3</c>).</p>
         <p><c>buf</c> and <c>len</c> provide the arguments to the call
           (the third argument to <c>erlang:port_call/3</c>). They can
           be decoded using <c>ei</c> functions.</p>
         <p><c>rbuf</c> points to a return buffer, <c>rlen</c> bytes
-          long. The return data should be a valid erlang term in the
-          external (binary) format. This is converted to an erlang
+          long. The return data is to be a valid Erlang term in the
+          external (binary) format. This is converted to an Erlang
           term and returned by <c>erlang:port_call/3</c> to the
-          caller.  If more space than <c>rlen</c> bytes is needed to
+          caller. If more space than <c>rlen</c> bytes is needed to
           return data, <c>*rbuf</c> can be set to memory allocated with
-          <c>driver_alloc</c>. This memory will be freed automatically
-          after <c>call</c> has returned.</p>
+          <seealso marker="erl_driver#driver_alloc">
+          <c>erl_driver:driver_alloc</c></seealso>.
+          This memory is freed automatically after <c>call</c> has returned.</p>
         <p>The return value is the number of bytes returned in
           <c>*rbuf</c>. If <c>ERL_DRV_ERROR_GENERAL</c> is returned
-          (or in fact, anything &lt; 0), <c>erlang:port_call/3</c> will
-          throw a <c>BAD_ARG</c>.</p>
+          (or in fact, anything &lt; 0), <c>erlang:port_call/3</c>
+          throws a <c>BAD_ARG</c>.</p>
       </item>
-      <tag>void (*event)(ErlDrvData drv_data, ErlDrvEvent event, ErlDrvEventData event_data)</tag>
+      <tag><c>void (*event)(ErlDrvData drv_data, ErlDrvEvent event,
+        ErlDrvEventData event_data)</c></tag>
       <item>
         <p>Intentionally left undocumented.</p>
       </item>
-      <tag><marker id="extended_marker"/>int extended_marker</tag>
+      <tag><marker id="extended_marker"/><c>int extended_marker</c></tag>
       <item>
-        <p>
-          This field should either be equal to <c>ERL_DRV_EXTENDED_MARKER</c>
+        <p>This field is either to be equal to <c>ERL_DRV_EXTENDED_MARKER</c>
           or <c>0</c>. An old driver (not aware of the extended driver
-          interface) should set this field to <c>0</c>. If this field is
-          equal to <c>0</c>, all the fields following this field also
-          <em>have</em> to be <c>0</c>, or <c>NULL</c> in case it is a
-          pointer field.
-        </p>
+          interface) is to set this field to <c>0</c>. If this field is
+          <c>0</c>, all the following fields <em>must</em> also be <c>0</c>,
+          or <c>NULL</c> if it is a pointer field.</p>
       </item>
-      <tag>int major_version</tag>
+      <tag><c>int major_version</c></tag>
       <item>
-        <p>This field should equal <c>ERL_DRV_EXTENDED_MAJOR_VERSION</c> if
-          the <c>extended_marker</c> field equals
+        <p>This field is to equal <c>ERL_DRV_EXTENDED_MAJOR_VERSION</c> if
+          field <c>extended_marker</c> equals
           <c>ERL_DRV_EXTENDED_MARKER</c>.</p> 
       </item>
-      <tag>int minor_version</tag>
+      <tag><c>int minor_version</c></tag>
       <item>
-        <p>
-          This field should equal <c>ERL_DRV_EXTENDED_MINOR_VERSION</c> if
-          the <c>extended_marker</c> field equals
-          <c>ERL_DRV_EXTENDED_MARKER</c>.
-        </p>
+        <p>This field is to equal <c>ERL_DRV_EXTENDED_MINOR_VERSION</c> if
+          field <c>extended_marker</c> equals
+          <c>ERL_DRV_EXTENDED_MARKER</c>.</p>
       </item>
-
-      <tag><marker id="driver_flags"/>int driver_flags</tag>
+      <tag><marker id="driver_flags"/><c>int driver_flags</c></tag>
       <item>
         <p>This field is used to pass driver capability and other
-	  information to the runtime system. If the
-	  <c>extended_marker</c> field equals <c>ERL_DRV_EXTENDED_MARKER</c>,
-	  it should contain <c>0</c> or  driver flags (<c>ERL_DRV_FLAG_*</c>)
-	  ored bitwise. Currently the following driver flags exist:
-        </p>
+          information to the runtime system. If
+          field <c>extended_marker</c> equals <c>ERL_DRV_EXTENDED_MARKER</c>,
+          it is to contain <c>0</c> or driver flags (<c>ERL_DRV_FLAG_*</c>)
+          OR'ed bitwise. The following driver flags exist:</p>
         <taglist>
           <tag><c>ERL_DRV_FLAG_USE_PORT_LOCKING</c></tag>
           <item>
-            The runtime system will use port level locking on
-            all ports executing this driver instead of driver
-            level locking when the driver is run in a runtime
-            system with SMP support. For more information see the
-            <seealso marker="erl_driver#smp_support">erl_driver</seealso> 
-            documentation.
-          </item> 
+            <p>The runtime system uses port-level locking on
+              all ports executing this driver instead of driver-level
+              locking when the driver is run in a runtime
+              system with SMP support. For more information, see
+              <seealso marker="erl_driver#smp_support">
+              <c>erl_driver</c></seealso>.</p>
+          </item>
           <tag><c>ERL_DRV_FLAG_SOFT_BUSY</c></tag>
           <item>
-            Marks that driver instances can handle being called
-	    in the <seealso marker="#output">output</seealso> and/or
-	    <seealso marker="#outputv">outputv</seealso> callbacks even
-	    though a driver instance has marked itself as busy (see
-            <seealso marker="erl_driver#set_busy_port">set_busy_port()</seealso>).
-	    Since erts version 5.7.4 this flag is required for drivers used
-	    by the Erlang distribution (the behaviour has always been
-	    required by drivers used by the distribution).
+            <p>Marks that driver instances can handle being called
+              in the <seealso marker="#output"><c>output</c></seealso> and/or
+              <seealso marker="#outputv"><c>outputv</c></seealso> callbacks
+              although a driver instance has marked itself as busy (see
+              <seealso marker="erl_driver#set_busy_port">
+              <c>erl_driver:set_busy_port</c></seealso>).
+              As from ERTS 5.7.4 this flag is required for drivers used
+              by the Erlang distribution (the behavior has always been
+              required by drivers used by the distribution).</p>
           </item>
           <tag><c>ERL_DRV_FLAG_NO_BUSY_MSGQ</c></tag>
-          <item>Disable busy port message queue functionality. For
-	  more information, see the documentation of the
-	  <seealso marker="erl_driver#erl_drv_busy_msgq_limits">erl_drv_busy_msgq_limits()</seealso>
-	  function.
+          <item>
+            <p>Disables busy port message queue functionality. For
+              more information, see
+              <seealso marker="erl_driver#erl_drv_busy_msgq_limits">
+              <c>erl_driver:erl_drv_busy_msgq_limits</c></seealso>.</p>
           </item>
           <tag><c>ERL_DRV_FLAG_USE_INIT_ACK</c></tag>
-          <item>When this flag is given the linked-in driver has to manually
-          acknowledge that the port has been successfully started using 
-	  <seealso marker="erl_driver#erl_drv_init_ack">erl_drv_init_ack()</seealso>.
-          This allows the implementor to make the erlang:open_port exit with
-          badarg after some initial asynchronous initialization has been done.
+          <item>
+            <p>When this flag is specified, the linked-in driver must manually
+              acknowledge that the port has been successfully started using
+              <seealso marker="erl_driver#erl_drv_init_ack">
+              <c>erl_driver:erl_drv_init_ack()</c></seealso>.
+              This allows the implementor to make the
+              <c>erlang:open_port</c> exit with <c>badarg</c> after some
+              initial asynchronous initialization has been done.</p>
           </item>
         </taglist>
       </item>
-      <tag>void *handle2</tag>
+      <tag><c>void *handle2</c></tag>
       <item>
-        <p>
-          This field is reserved for the emulator's internal use. The
-          emulator will modify this field; therefore, it is important
-          that the <c>driver_entry</c> isn't declared <c>const</c>.
-        </p>
+        <p>This field is reserved for the emulator's internal use. The
+          emulator modifies this field, so it is important
+          that the <c>driver_entry</c> is not declared <c>const</c>.</p>
       </item>
-      <tag><marker id="process_exit"/>void (*process_exit)(ErlDrvData drv_data, ErlDrvMonitor *monitor)</tag>
+      <tag><marker id="process_exit"/>
+        <c>void (*process_exit)(ErlDrvData drv_data, ErlDrvMonitor *monitor)</c>
+      </tag>
       <item>
-        <p>This callback is called when a monitored process exits. The
+        <p>Called when a monitored process exits. The
           <c>drv_data</c> is the data associated with the port for which
-          the process is monitored (using <seealso marker="erl_driver#driver_monitor_process">driver_monitor_process</seealso>)
-          and the <c>monitor</c> corresponds to the <c>ErlDrvMonitor</c> 
+          the process is monitored (using
+          <seealso marker="erl_driver#driver_monitor_process">
+          <c>erl_driver:driver_monitor_process</c></seealso>)
+          and the <c>monitor</c> corresponds to the <c>ErlDrvMonitor</c>
           structure filled
           in when creating the monitor. The driver interface function
-          <seealso marker="erl_driver#driver_get_monitored_process">driver_get_monitored_process</seealso>
-          can be used to retrieve the process id of the exiting process as
+          <seealso marker="erl_driver#driver_get_monitored_process">
+          <c>erl_driver:driver_get_monitored_process</c></seealso>
+          can be used to retrieve the process ID of the exiting process as
           an <c>ErlDrvTermData</c>.</p>
       </item>
-      <tag><marker id="stop_select"/>void (*stop_select)(ErlDrvEvent event, void* reserved)</tag>
+      <tag><marker id="stop_select"/>
+        <c>void (*stop_select)(ErlDrvEvent event, void* reserved)</c></tag>
       <item>
-        <p>This function is called on behalf of
-           <seealso marker="erl_driver#driver_select">driver_select</seealso>
-           when it is safe to close an event object.</p>
+        <p>Called on behalf of
+          <seealso marker="erl_driver#driver_select">
+          <c>erl_driver:driver_select</c></seealso>
+          when it is safe to close an event object.</p>
         <p>A typical implementation on Unix is to do
-           <c>close((int)event)</c>.</p>
-        <p>Argument <c>reserved</c> is intended for future use and should be ignored.</p>
-        <p>In contrast to most of the other call-back functions,
-           <c>stop_select</c> is called independent of any port. No
-           <c>ErlDrvData</c> argument is passed to the function. No
-           driver lock or port lock is guaranteed to be held. The port that
-           called <c>driver_select</c> might even be closed at the
-           time <c>stop_select</c> is called. But it could also be
-           the case that <c>stop_select</c> is called directly by
-           <c>driver_select</c>.</p>
+          <c>close((int)event)</c>.</p>
+        <p>Argument <c>reserved</c> is intended for future use and is to be
+          ignored.</p>
+        <p>In contrast to most of the other callback functions,
+          <c>stop_select</c> is called independent of any port. No
+          <c>ErlDrvData</c> argument is passed to the function. No
+          driver lock or port lock is guaranteed to be held. The port that
+          called <c>driver_select</c> can even be closed at the
+          time <c>stop_select</c> is called. But it can also be
+          the case that <c>stop_select</c> is called directly by
+          <c>erl_driver:driver_select</c>.</p>
         <p>It is not allowed to call any functions in the
-           <seealso marker="erl_driver">driver API</seealso> from
-           <c>stop_select</c>. This strict limitation is due to the
-           volatile context that <c>stop_select</c> may be called.</p>
+          <seealso marker="erl_driver">driver API</seealso> from
+          <c>stop_select</c>. This strict limitation is because the
+          volatile context that <c>stop_select</c> can be called.</p>
       </item>
-
-    </taglist>
-    </item>
-
     </taglist>
   </section>
 
   <section>
-    <title>SEE ALSO</title>
-    <p><seealso marker="erl_driver">erl_driver(3)</seealso>, 
-      <seealso marker="kernel:erl_ddll">erl_ddll(3)</seealso>,
-      <seealso marker="erlang">erlang(3)</seealso>,
-      kernel(3)</p>
+    <title>See Also</title>
+    <p><seealso marker="erl_driver"><c>erl_driver(3)</c></seealso>,
+      <seealso marker="erlang"><c>erlang(3)</c></seealso>,
+      <seealso marker="kernel:erl_ddll"><c>erl_ddll(3)</c></seealso></p>
   </section>
 </cref>