Dynamic Libraries

Often you will want to extend Guile by linking it with some existing system library. For example, linking Guile with a curses or termcap library would be useful if you want to implement a full-screen user interface for a Guile application. However, if you were to link Guile with these libraries at compile time, it would bloat the interpreter considerably, affecting everyone on the system even if the new libraries are useful only to you. Also, every time a new library is installed, you would have to reconfigure, recompile and relink Guile merely in order to provide a new interface.

Many Unix systems permit you to get around this problem by using dynamic loading. When a new library is linked, it can be made a dynamic library by passing certain switches to the linker. A dynamic library does not need to be linked with an executable image at link time; instead, the executable may choose to load it dynamically at run time. This is a powerful concept that permits an executable to link itself with almost any library without reconfiguration, if it has been written properly.

Guile's dynamic linking functions make it relatively easy to write a module that incorporates code from third-party object code libraries.

primitive: dynamic-link library-file

Open the dynamic library library-file. A library handle representing the opened library is returned; this handle should be used as the lib argument to the following functions.

primitive: dynamic-object? obj

Return #t if obj is a dynamic library handle, or #f otherwise.

primitive: dynamic-unlink lib

Unlink the library represented by library-handle, and remove any imported symbols from the address space.

primitive: dynamic-func func lib

Import the symbol func from lib (a dynamic library handle). A function handle representing the imported function is returned.

primitive: dynamic-call lib-thunk lib

Call lib-thunk, a procedure of no arguments. If lib-thunk is a string, it is assumed to be a symbol found in the dynamic library lib and is fetched with dynamic-func. Otherwise, it should be a function handle returned by a previous call to dynamic-func. The return value is unspecified.

primitive: dynamic-args-call proc lib args

Call proc, a dynamically loaded function, passing it the argument list args (a list of strings). As with dynamic-call, proc should be either a function handle or a string, in which case it is first fetched from lib with dynamic-func.

proc is assumed to return an integer, which is used as the return value from dynamic-args-call.

primitive: c-registered-modules

Return a list of the object code modules that have been imported into the current Guile process. Each element of the list is a pair whose car is the name of the module (as it might be used by use-modules, for instance), and whose cdr is the function handle for that module's initializer function.

primitive: c-clear-registered-modules

Destroy the list of modules registered with the current Guile process. The return value is unspecified. Warning: this function does not actually unlink or deallocate these modules, but only destroys the records of which modules have been loaded. It should therefore be used only by module bookkeeping operations.

[FIXME: provide a brief example here of writing the C hooks for an object code module, and using dynamic-link and dynamic-call to load the module.]

Go to the first, previous, next, last section, table of contents.