A symbol or string specifying the Lisp name the module will be registered under.
A keyword determining when the connection to the dynamic library is made. One of
:automatic
,
:manual
or
:immediate
. The default value is
:automatic
.
A keyword specifying the lifetime of the connection. One of
:indefinite
or
:session
. The default value is
:indefinite.
Overrides the name for identifying the actual dynamic library to connect to.
The function
register-module
explicitly informs LispWorks of the presence of a DLL or shared object file, referred to here as a dynamic library. Functions such as make-pointer and define-foreign-function have a
module
keyword which can be used to specify which module the function refers to.
The main use of modules is to overcome ambiguities that can arise when two different dynamic libraries have functions with the same name.
name
is used for explicit look up from the
:module
keyword of functions such as define-foreign-function. If
real-name
is not specified then
name
is taken to be the actual name of the module to connect to.
The naming convention for the module name can contain the full pathname for the dynamic library. For example, a pathname such as
#p"C:/MYPRODUCT/LIBS/MYLIBRARY.DLL"
"C:\\MYPRODUCT\\LIBS\\MYLIBRARY.DLL"
On Windows, if the module is declared without an extension, "
.DLL
" is automatically appended to the name. To declare a name without an extension it must end with the period character ("
.
"). On other platforms, you should provide the extension, since there is more than one library format. Typical would be
.so
on Linux and
.dylib
on Macintosh.
If a full pathname is not specified for the module, then it is searched for.
On Windows the following directories (in the given order) are searched:
GetSystemDirectory
). For Windows NT/2000/XP the 16-bit system directory (
SYSTEM
) is also searched.
GetWindowsDirectory
)
PATH
variable.On Linux, the search is conducted in this order:
LD_LIBRARY
path environment variable.
/etc/ld.so.cache
.
/usr/lib
, followed by
/lib
.
If
connection-style
is
:automatic
then the system automatically connects to a dynamic library when it needs to resolve currently undefined foreign symbols.
If
connection-style
is
:manual
then the system only connects to the dynamic library if the symbol to resolve is explicitly marked as coming from this module via the
:module
keyword of functions such as define-foreign-function.
Note: on LispWorks for UNIX only (not LispWorks for Linux or LispWorks for Macintosh) this value
:manual
for
connection-style
is not supported.
If
connection-style
is
:immediate
then the connection to the dynamic library is made immediately. This checks that the library can actually be loaded before its symbols are actually needed: an error is signalled if loading fails.
If
lifetime
is
:session
then the module is disconnected when Lisp starts up. The only supported value of
lifetime
in LispWorks for UNIX is
:indefinite
.
Note: In LispWorks for UNIX the loader function
link-load:read-foreign-modules
is now deprecated in favor of
register-module
.
Note: static libraries are not supported except on UNIX. For example, on Linux evaluating this form:
(fli:register-module "libc.a"
:real-name "/usr/lib/libc.a"
:connection-style :immediate)
Could not register handle for external module "libc"
/usr/lib/libc.a : invalid ELF header
The problem is that
libc.a
is a static library. Instead, do:
(fli:register-module "libc.so"
:real-name "libc.so.6"
:connection-style :immediate)
Note that
:real-name
is given a relative path in this case, because
libc
is a standard library on Linux and it is best to let the operating system locate it
Note: when developing with foreign code in LispWorks, the utilities provided in the Editor are useful - see Compiling and Loading Foreign Code with the Editor
In the following example on Windows, the
user32
DLL is registered, and then a foreign function called
set-cursor-pos
is defined to explicitly reference the
SetCursorPos
function in the
user32
DLL.
(fli:register-module :user-dll :real-name "user32")
(fli:define-foreign-function (set-cursor-pos
"SetCursorPos")
((x :long)
(y :long))
:module :user-dll)
This example on Linux loads the shared library even though its symbols are not yet needed. An error is signalled if loading fails:
(fli:register-module "libX11.so"
:connection-style :immediate)
connected-module-pathname
define-foreign-function
make-pointer
module-unresolved-symbols
print-foreign-modules