5.4 Using the library shlib for .DLL and .so files

This section discusses the functionality of the (autoload) library shlib.pl, providing an interface to shared libraries. Currently it supports MS-Windows DLL (.DLL) libraries and Unix .so (shared object) files.

load_foreign_library(+Lib)

Equivalent to load_foreign_library(Lib, install).

load_foreign_library(+Lib, +Entry)

Search for the given foreign library and link it to the current SWI-Prolog instance. The library may be specified with or without the extension. First, absolute_file_name/3 is used to locate the file. If this succeeds, the full path is passed to the low-level function to open the library. Otherwise, the plain library name is passed, exploiting the operating-system defined search mechanism for the shared library. The file_search_path/2 alias mechanism defines the alias foreign, which refers to the directories <plhome>/lib/<arch> and <plhome>/lib, in this order.

If the library can be loaded, the function called Entry will be called without arguments. The return value of the function is ignored.

The Entry function will normally call PL_register_foreign() to declare functions in the library as foreign predicates.

unload_foreign_library(+Lib)

If the foreign library defines the function uninstall(), this function will be called without arguments and its return value is ignored. Next, abolish/2 is used to remove all known foreign predicates defined in the library. Finally the library itself is detached from the process.

current_foreign_library(-Lib, -Predicates)

Query the currently loaded foreign libraries and their predicates. Predicates is a list with elements of the form Module:Head, indicating the predicates installed with PL_register_foreign() when the entry-point of the library was called.

Figure 5 connects a Windows message-box using a foreign function. This example was tested using Windows NT and Microsoft Visual C++ 2.0.

#include <windows.h> #include <SWI-Prolog.h> static foreign_t pl_say_hello(term_t to) { char *a; if ( PL_get_atom_chars(to, &a) ) { MessageBox(NULL, a, "DLL test", MB_OK|MB_TASKMODAL); PL_succeed; } PL_fail; } install_t install() { PL_register_foreign("say_hello", 1, pl_say_hello, 0); }

5.4.1 Static Linking

Below is an outline of the files structure required for statically linking SWI-Prolog with foreign extensions. \ldots/pl refers to the SWI-Prolog home directory (see feature/2). <arch> refers to the architecture identifier that may be obtained using feature/2.

The definition of the foreign predicates is the same as for dynamic linking. Unlike with dynamic linking however, there is no initialisation function. Instead, the file \ldots/pl/include/stub.c may be copied to your project and modified to define the foreign extensions. Below is stub.c, modified to link the lowercase example described later in this chapter:

/* Copyright (c) 1991 Jan Wielemaker. All rights reserved. jan@swi.psy.uva.nl Purpose: Skeleton for extensions */ #include <stdio.h> #include <SWI-Prolog.h> extern foreign_t pl_lowercase(term, term); PL_extension predicates[] = { /*{ "name", arity, function, PL_FA_<flags> },*/ { "lowercase", 2 pl_lowercase, 0 }, { NULL, 0, NULL, 0 } /* terminating line */ }; int main(int argc, char **argv) { PL_register_extensions(predicates); if ( !PL_initialise(argc, argv) ) PL_halt(1); PL_install_readline(); /* delete if not required */ PL_halt(PL_toplevel() ? 0 : 1); }

Now, a new executable may be created by compiling this file and linking it to libpl.a from the runtime directory and the libraries required by both the extensions and the SWI-Prolog kernel. This may be done by hand, or using the plld utility described in secrefplld.

5.4.2 Dynamic Linking based on load_foreign/[2,5]

The predicates below are considered obsolete. They are briefly described here for compatibility purposes. New code should use the predicates from the library(shlib).

load_foreign(+File, +Entry)

Load a foreign file or list of files specified by File. The files are searched for similar to consult/1. Except that the `.o' extension is used rather than `.pl'.

Entry defines the entry point of the resulting executable. The entry point will be called by Prolog to install the foreign predicates.

load_foreign(+File, +Entry, +Options, +Libraries, +Size)

The first two arguments are identical to those of load_foreign/2. Options is (a list of) additional option to be given to the loader. The options are inserted just before the files. Libraries is (a list of) libraries to be passed to the loader. They are inserted just after the files. If Size is specified Prolog first assumes that the resulting executable will fit in Size bytes and do the loading in one pass.

foreign_file(?File)

Is true if File is the absolute path name of a file loaded as foreign file.