The Interface Generator (IG) is used to make C functions accessible from Erlang, and vice versa.
The input specification to IG consists of a .h
ANSI C
header file, in which the function prototypes and relevant data
types are specified. When the code is generated, two or three
files with stub code are created: one Erlang file, one C
file, and an optional Erlang header file.
The actual communication between Erlang and the C program is handled by the open_port/2
mechanism, or by using sockets. The method used is decided at application start-up by choosing either the generated start/1
function, or one of the client/1
or server/2
functions.
The generated Erlang code has functions which correspond to the C functions to be accessed. The generated C stub code must be linked to an executable. It can either be linked with user provided code, or with the standard modules included with IG. Depending on what was specified in the input file to IG, the stub code contains routines for calling C and/or Erlang functions.
ig:gen(FileName [ , Options ] ) -> Result
Result = ok | {error,Reason}
Filename = Module | "Module" | "Module.h"
Options = {cback_mod,CbackMod} | nouse_stdio | {file,IncFile}
CbackMod = Module (location of the Erlang call-back functions)
nouse_stdio = File descriptor 3 and 4 will be used in the open_port/2 command
IncFile = Module (additional include file to be used)
Module = Atomic module name
If no CbackMod is specified, it is assumed that the call-back functions are located in a module: <Filename>_cb.erl
Example:
ig:gen(xemtP, [nouse_stdio, {file, xmainwindow}, {file, unix}]).
Pre-process directives and comments are ignored by IG. This
means, for example, that any declarations you may have in other
include
files will be ignored. This is also true for conditional
pre-processor directives, such as #ifdef
, which might still
be very useful in order to avoid type conflicts.
The actual syntax of the C subset which IG accepts is described below in a BNF like form.
TYPEDEF_STMT ::= typedef struct OPT_TAG '{' MEMBER_LIST '}' STD_TYPEDEFNAME ';' | typedef STD_TYPE_SPEC STD_TYPEDEFNAME ';' STRUCT_STMT ::= struct IDENTIFIER '{' MEMBER_LIST '}' ';'
VAR_STMT ::= 'IG_var' DECLARATION STD_IDENTIFIER ';' | 'IG_var' OPT_STORAGE_CLASS STRUCT IDENTIFIER STD_IDENTIFIER ';' | 'IG_var' IDENTIFIER STD_IDENTIFIER ';'
HDEF_STMT ::= 'IG_define' IDENTIFIER [HDEF_CONST]? ';' | ['IG_ifdef'|'IG_ifndef'] IDENTIFIER ';' | ['IG_else'|'IG_endif'] ';'
PROTOTYPE_STMT ::= IG_KEYWORD DECLARATION STD_IDENTIFIER '(' PARAM_DECLARATIONS ')' ';' | IG_KEYWORD struct IDENTIFIER STD_IDENTIFIER '(' PARAM_DECLARATIONS ')' ';' | IG_KEYWORD 'IG_binaryPtr' IDENTIFIER '(' PARAM_DECLARATIONS ')' ';' | IG_KEYWORD IDENTIFIER STD_IDENTIFIER '(' PARAM_DECLARATIONS ')' ';'
MEMBER_LIST ::= MEMBER_DECLARATION | MEMBER_LIST MEMBER_DECLARATION MEMBER_DECLARATION ::= STD_TYPE_SPEC MEMBER_NAME | 'IG_binaryPtr' STD_IDENTIFIER ';' MEMBER_NAME ::= STD_IDENTIFIER ';' | STD_IDENTIFIER '[' CONSTANT_EXPRESSION ']' ';' PARAM_DECLARATIONS ::= PARAM_DECL | PARAM_DECLARATIONS ',' PARAM_DECL PARAM_DECL ::= STD_TYPE_SPEC STD_OPT_IDENTIFIER | IDENTIFIER STD_OPT_IDENTIFIER | 'IG_binaryPtr' STD_OPT_IDENTIFIER | struct IDENTIFIER STD_OPT_IDENTIFIER STD_TYPEDEFNAME ::= ['*'|TYPE_QUALIFIERS]? TYPEDEFNAME STD_IDENTIFIER ::= ['*'|TYPE_QUALIFIERS]? IDENTIFIER HDEF_CONST ::= INTEGERCONSTANT | FLOATINGCONSTANT | CHARACTERCONSTANT | OCTALCONSTANT | HEXCONSTANT | STRING | IDENTIFIER CONSTANT_EXPRESSION ::= "An arithmetic expression which can be evaluated at compile time. For example: 2*(64+2) ." DECLARATION ::= "Basically, a non-aggregate, ANSI C variable declaration." IDENTIFIER ::= "An identifier is a sequence of letters, digits, and underscores. An identifier must not begin with a digit, and it must not have the same spelling as a reserved word." TYPEDEFNAME ::= "An identifier which is currently in scope as a typedef name"
For more detailed information see the IG User's Guide.