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.