Foreign predicates must always appear in modules, which can contain only foreign predicates. The main difference between a normal module and a foreign module is the very natural one: the source file of the module implementation, which is in C, must appear in a *.c file rather than a *.P file. This *.c file cannot contain a main() function. Furthermore, a *.P file with the same name must not be present or else the *.c file is ignored and the module is compiled as a regular Prolog module. The interface part of a foreign module, which has the same syntax as that of a normal module, is written in Prolog and hence must appear in a *.H file. This *.H file contains export declarations for each and every one of the foreign predicates that are to be used by other modules. Here is an example of a .H file for a foreign module:
:- export minus_one/2, my_sqrt/2, change_char/4.
:- ldoption('-lm'). % link together with the math library
Directives such as index, hilog, table, auto_table or even import make no sense in the case of a foreign module and thus are ignored by the compiler. However, another directive, namely ldoption, is recognized in a foreign module and is used to instruct the dynamic loading and linking of the module. The syntax of the ldoption directive is simply:
The foreign language interface of XSB uses the Unix command ld that combines object programs to create an executable file or another object program suitable for further ld processing. Version 2.2 of XSB assumes that the ld command resides in the file /usr/bin/ld.
C functions that implement foreign predicates must return values of type int. If a non-zero is returned, the foreign predicate succeeds; a zero return value means failure.
A well-designed foreign predicate must check that its arguments are of the correct types and modes. However, such checks can also be done using Prolog-side wrappers that invoke a foreign predicate.
At the C level, the procedure that implements the foreign predicate must have the same name as the predicate (that is declared in the *.H file), and it must be parameterless. The Prolog level arguments are converted to C data structures through several predefined functions rather than through direct parameter passing.
In the current implementation, the Prolog procedures that are attached to foreign predicates are deterministic, in the sense that they succeed at most once for a given call and are not re-entered on backtracking. Note that this requirement imposes no serious limitation, since it is always possible to divide a foreign predicate into the part to be done on the first call and the part to be redone on backtracking. Backtracking can then take place at the Prolog level where it is more naturally expressed.
A foreign module can be compiled or consulted just like a normal Prolog module. Currently, predicates consult/[1,2] recompile both the *.c and the *.H files of a foreign module when at least one of them has been changed from the time the corresponding object files have been created (see the section Compiling and Consulting in Volume 1. The C compiler used to compile the *.c files can be set as a compilation option or defaults to that used for the configuration of XSB (refer to the section Getting Started with XSB in Volume 1. Moreover, the user can control the compiler options that can be passed to the C compiler. To give an example, the following command will compile file file.c using the Gnu C Compiler with optimization and by including /usr/local/X11/R6/include to the directories that will be searched for header files.
-c file.c where is the name of the C compiler
used to install XSB.
Any Prolog compiler options are ignored when compiling a foreign module.