ErlDriverTerm, ErlDrvTerm & ErlDrvTermData confusion

[Vance Shipley]

R9C\erts-5.3\doc\html\erl_driver.html

The documentation for the driver functions which create and send
terms specify a type of ErlDriverTerm:

ErlDriverTerm driver_mk_atom(char* string)
ErlDriverTerm driver_mk_port(ErlDrvPort port)
int driver_output_term(ErlDrvPort port, ErlDriverTerm* term, int n)
...

However ErlDriverTerm does not appear in erl_driver.h.

The individual terms are all defined as having type ErlDrvTermData:

#define ERL_DRV_ATOM        ((ErlDrvTermData) 2)  /* driver_mk_atom(string) */
#define ERL_DRV_INT         ((ErlDrvTermData) 3)  /* int */
...
EXTERN ErlDrvTermData driver_mk_atom(char*);
EXTERN ErlDrvTermData driver_mk_port(ErlDrvPort);
...

The example for a completed complex term specifies a type of ErlDrvTerm:

/* ErlDrvTerm is the type to use for casts when building
 * terms that should be sent to connected process,
 * for instance a tuple on the form {tcp, Port, [Tag|Binary]}
 * 
 * ErlDrvTerm spec[] = {
 *    ERL_DRV_ATOM, driver_mk_atom("tcp"),
 *    ERL_DRV_PORT, driver_mk_port(drv->ix),
 *             ERL_DRV_INT, REPLY_TAG,
 *             ERL_DRV_BINARY, (ErlDrvTerm)bin, 50, 0,
 *             ERL_DRV_LIST, 2,
 *    ERL_DRV_TUPLE, 3,
 *  }
 *
 */

I believe the intention was to define ErlDriverTerm like this:

typedef ErlDrvTermData *ErlDriverTerm;

I suggest adding the above to erl_driver.h and changing the documentation
to correct the types used with these functions:

ErlDriverTerm driver_connected(ErlDrvPort port)
ErlDriverTerm driver_caller(ErlDrvPort port)
int driver_output_term(ErlDrvPort port, ErlDriverTerm* term, int n)
ErlDriverTerm driver_mk_atom(char* string)
ErlDriverTerm driver_mk_port(ErlDrvPort port)
int driver_send_term(ErlDrvPort port, ErlDriverTerm receiver, ErlDriverTerm* term, int n)

The correct definitions (as they appear in erl_driver.h now) are:

ErlDriverTermData driver_connected(ErlDrvPort port)
ErlDriverTermData driver_caller(ErlDrvPort port)
int driver_output_term(ErlDrvPort port, ErlDriverTermData* term, int n)
ErlDriverTermData driver_mk_atom(char* string)
ErlDriverTermData driver_mk_port(ErlDrvPort port)
int driver_send_term(ErlDrvPort port, ErlDriverTermData receiver, ErlDriverTermData* term, int n)

Basically all appearances of "ErlDriverTerm" in doc\html\erl_driver.html
can be changed to "ErlDriverTermData".  If however you follow the suggestion 
of adding the definition of ErlDriverTerm as a pointer to ErlDriverTermData
(i.e. an array of ErlDriverTermData, a complete term) then you would 
define like this:

int driver_output_term(ErlDrvPort port, ErlDriverTerm term, int n)
int driver_send_term(ErlDrvPort port, ErlDriverTermData receiver, ErlDriverTerm term, int n)

Finally the example in erl_driver.h should be corrected.

	-Vance