2.4.1 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 Prolog predicate.

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 ``-''. In addition, 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 function in the .c file. At compile-time a C function with name predname will be generated which will translate arguments from Prolog to C, call funcname, and then translate arguments back from C to Prolog.

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.