ig

MODULE

MODULE SUMMARY

The Interface Generator

DESCRIPTION

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.

EXPORTS

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}]).

The Grammar of the .h file

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- and struct statements.

TYPEDEF_STMT ::= typedef struct OPT_TAG '{' MEMBER_LIST '}' 
                   STD_TYPEDEFNAME ';' |

                 typedef STD_TYPE_SPEC STD_TYPEDEFNAME ';'

STRUCT_STMT  ::= struct IDENTIFIER '{' MEMBER_LIST '}' ';'

Variable statements.

VAR_STMT  ::= 'IG_var' DECLARATION STD_IDENTIFIER ';' |

              'IG_var' OPT_STORAGE_CLASS STRUCT IDENTIFIER 
                 STD_IDENTIFIER ';' |

              'IG_var' IDENTIFIER STD_IDENTIFIER ';'

Preprocessor directives.

HDEF_STMT ::= 'IG_define' IDENTIFIER [HDEF_CONST]? ';' |

              ['IG_ifdef'|'IG_ifndef'] IDENTIFIER ';' |

              ['IG_else'|'IG_endif'] ';'

Function prototypes.

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 ')' ';'

The rest of the syntax.

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"

ig

MODULE

MODULE SUMMARY

DESCRIPTION

EXPORTS

The Grammar of the .h file

See Also

AUTHORS