Home
Contents
Index
Summary
Previous
Next
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 6 connects a Windows
message-box using a foreign function. This example was tested using
Windows NT and Microsoft Visual C++ 2.0.
<![CDATA[
#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);
}
]]>
Figure 6 : MessageBox() example in Windows NT
Below is an outline of the files structure required for statically
linking SWI-Prolog with foreign extensions. ... /pl refers
to the SWI-Prolog home directory (see feature/2). <arch>
refers to the architecture identifier that may be obtained using feature/2.
... /pl/runtime/<arch>/libpl.a | SWI-Library |
... /pl/include/SWI-Prolog.h | Include
file |
... /pl/include/SWI-Stream.h | Stream
I/O include file |
... /pl/include/SWI-Exports | Export
declarations (AIX only) |
... /pl/include/stub.c | Extension
stub |
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 ... /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:
<![CDATA[
/* 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 PL_extensions [] =
{
/*{ "name", arity, function, PL_FA_<flags> },*/
{ "lowercase", 2 pl_lowercase, 0 },
{ NULL, 0, NULL, 0 } /* terminating line */
};
int
main(int argc, char **argv, char **env)
{ if ( !PL_initialise(argc, argv, env) )
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.
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.