Declaration of high level foreign predicates

The basic format of a foreign predicate declaration is:

:- foreign_pred predname([+-]parg1, [+-]parg2,...)
                   from funcname(carg1:type1, carg2:type2, ...):functype.

where:

predname

is the name of the foreign predicate. This is the name of the Prolog predicate that will be created.

parg1, parg2, ...

are the predicate arguments. Each argument is preceded by either '+' or '-', indicating its mode as input or output respectively. The names of the arguments must be the same as those used in the declaration of the corresponding C function. If a C argument is used both for input and output, then the corresponding Prolog argument can appear twice: once with ``+'' and once with ``-''. Also, a special argument retval is used to denote the argument that corresponds to the return value of the C function; it must always have the mode '-'.

funcname

is the name of the C function being wrapped. This is the C function given by the user, which will be exported as a Prolog foreign predicate.

carg1, carg2, ...

is the list of arguments of the C function. The names used for the arguments must match the names used in the Prolog declaration.

type1, type2, ...

are the types associated to the arguments of the C function. This is not the set of C types, but rather a set of descriptive types, as defined in Table 2.4.1.

functype

is the return type of the C function.

Table 2.4.1 provides the correspondence between the types allowed on the C side of a foreign module declaration and the types allowed on the Prolog side of the declaration.

Table 2.1: Allowed combinations of types and modes, and their meanings

Descriptive Type Mode Usage Associated C Type Comments

int + int integer numbers

float + double floating point numbers

atom + unsigned long atom represented as an unsigned long

chars + char * the textual representation of an atom is passed to C as a string

chars(size) + char * the textual representation of an atom is passed to C as a string in a buffer of size size

string + char * a prolog list of characters is passed to C as a string

string(size) + char * a prolog list of characters is passed to C as a string

term + prolog_term the unique representation of a term

intptr + int * the location of a given integer

floatptr + double * the location of a given floating point number

atomptr + unsigned long * the location of the unique representation of a given atom

charsptr + char ** the location of the textual representation of an atom

stringptr + char ** the location of the textual representation of a list of characters

termptr + prolog_term * the location of the unique representation of a term

intptr - int * the integer value returned is passed to Prolog

floatptr - double * the floating point number is passed back to Prolog

charsptr - char ** the string returned is passed to Prolog as an atom

stringptr - char ** the string returned is passed back as a list of characters

atomptr - unsigned long * the number returned is passed back to Prolog as the unique representation of an atom

termptr - prolog_term * the number returned is passed to Prolog as the unique representation of a term

chars(size) +- char * the atom is copied from Prolog to a buffer, passed to C and converted back to Prolog afterwards

string(size) +- char * the list of characters is copied from Prolog to a buffer, passed to C and back to Prolog afterwards

intptr +- int * an integer is passed from Prolog to C and from C back to Prolog

floatptr +- double * a float number is passed from Prolog to C, and back to Prolog

atomptr +- unsigned long * the unique representation of an atom is passed to C, and back to Prolog

charsptr +- char ** the atom is passed to C as a string, and a string is passed to Prolog as an atom

stringptr +- char ** the list of characters is passed to C, and a string passed to Prolog as a list of characters

termptr +- prolog_term * the unique representation of a term is passed to C, and back to Prolog

In all modes and types, checks are performed to ensure the types of the arguments. Also, all arguments of type '-' are checked to be free variables at call time.