Function

Summary

Informs LispWorks of the presence of a dynamic library.

Signature

register-module name &key connection-style lifetime real-name => name

Arguments

name

A symbol or string specifying the Lisp name the module will be registered under.

connection-style

A keyword determining when the connection to the dynamic library is made. One of :automatic , :manual or :immediate . The default value is :automatic .

lifetime

A keyword specifying the lifetime of the connection. One of :indefinite or :session . The default value is :indefinite.

real-name

Overrides the name for identifying the actual dynamic library to connect to.

Values

name

The name argument.

Description

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"

is specified as

"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:

1. The directory of the executable.
2. The current directory. This step can be switched off on Windows XP.
3. The Windows system directory (as specified by GetSystemDirectory ). For Windows NT/2000/XP the 16-bit system directory ( SYSTEM ) is also searched.
4. The Windows directory (as specified by GetWindowsDirectory )
5. Directories specified by the PATH variable.

On Linux, the search is conducted in this order:

1. Directories on the user's LD_LIBRARY path environment variable.
2. The list of libraries specified in /etc/ld.so.cache .
3. /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. This value is not supported on non-Linux UNIX platforms.

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)

results in an error:

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

Example

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)

See also

connected-module-pathname
define-foreign-function
make-pointer
module-unresolved-symbols
print-foreign-modules