[ Reference Manual | Alphabetic Index ]

# library(foreign)

Simple foreign interface like SICStus or Quintus [more]

## Predicates

> declare_externals(?)
>   No description available
> declare_externals(?, ?)
>   No description available
> load_foreign_files(?, ?)
>   No description available
> make_simple_interface
>   No description available
> make_simple_interface(?)
>   No description available
> tr_foreign(?, ?, ?)
>   No description available

## Other Exports

> export macro(foreign / 3, tr_foreign / 3, [clause])

## Description

    Simple foreign interface like SICStus or Quintus(TM). For every C function
    an interface C function is generated which converts the arguments
    from and to the Sepia ones. Note that this is faster (and uses more
    C code) than one generic interface procedure which dispatches all
    external calls like in the above systems. Use it as follows:

    1) load this file with lib(foreign)
    2) compile (Sepia) the file with the foreign/3 clauses
    3) call make_simple_interface/0 or /1; this will generate the file
       e_interface.c
    4) compile (cc) e_interface.c and the other C source files
          On a SVR4 system (e.g. Solaris 2.x) produce one .so file
          from all the .o files that should be loaded, including
          the file e_interface.o. On Solaris this can be done with
          something like
    	cc -I$ECLIPSEDIR/include -G -o myfile.so file1.c file2.c 		... e_interface.c
    5) call load_foreign_files/2. This assumes that the foreign/3 clauses
       are still available.

    This means that a file which contains both foreign/3 facts and
    a goal :- load_foreign_files(...) must be split so that
    make_simple_interface/0 can be called before the goal.
    However, once the file e_interface.c is created, this file can be used
    in the original form.

    The main purpose of the interface is to port foreign files from
    SICStus or Quintus to Sepia, or to automate interfacing of
    other existing C functions. When writing new external functions,
    it is more efficient to use the Sepia external interface directly.

    User-defined types and conversion can also be specified.
    If some additional declarations and function calls are necessary
    before or after calling the C function, the type can be specified
    as a user type:
    	[+-]user(Type)

    When such a type is encountered, this library will call the predicate

    foreign_user_type(+Type, +I, -CType, -Local, -TypeCheck, -InConv,
    	-Call, -OutConv, -Unif)

    which is supposed to yield the data to be inserted into the
    source of the interface file. The arguments are as follows:
    Type	- the name of the user type with + or -, e.g. +mystring
    I	- the argument position; used to make distinction
    	  among several args of the same type
    CType	- the corresponding C type
    Local	- declaration of local variables for this type
    TypeCheck - type testing of the predicate arguments
    InConv	- calls to be made before calling the foreign function
    Call	- the actual argument passed to the foreign function
    OutConv	- calls to be made after the foreign call and before
    	  the unification of output arguments
    Unif	- unification of the output argument

    The source of the generated interface for a declaration
    foreign(funct, c, funct(+integer, +user(ut)))
    looks as follows:

    p_funct(val1, tag1, val2, tag2)
    value	val1, val2;
    type	tag1, tag2;
    {
    	LOCAL

    	Check_Integer(tag1);
    	TYPECHECK
    	INCONV
    	funct(val1.nint, CALL)
    	OUTCONV
    	Return_UNIF
    }
    where the capitalized ids are substituted by the user definition.

## About

- Author: Micha Meier, ECRC Munich
- Copyright © Cisco Systems, Inc
- Date: $Date: 2009/07/16 09:11:24 $

Generated from foreign.eci on 2020-02-26 22:26