6.21.2 Foreign Functions

The most natural thing to do with a dynamic library is to grovel around in it for a function pointer: a foreign function. dynamic-func exists for that purpose.

Scheme Procedure: dynamic-func name dobj

C Function: scm_dynamic_func (name, dobj)

Return a “handle” for the func name in the shared object referred to by dobj. The handle can be passed to dynamic-call to actually call the function.

Regardless whether your C compiler prepends an underscore ‘_’ to the global names in a program, you should not include this underscore in name since it will be added automatically when necessary.

Guile has static support for calling functions with no arguments, dynamic-call.

Scheme Procedure: dynamic-call func dobj

C Function: scm_dynamic_call (func, dobj)

Call the C function indicated by func and dobj. The function is passed no arguments and its return value is ignored. When function is something returned by dynamic-func, call that function and ignore dobj. When func is a string , look it up in dynobj; this is equivalent to

(dynamic-call (dynamic-func func dobj) #f)

dynamic-call is not very powerful. It is mostly intended to be used for calling specially written initialization functions that will then add new primitives to Guile. For example, we do not expect that you will dynamically link libX11 with dynamic-link and then construct a beautiful graphical user interface just by using dynamic-call. Instead, the usual way would be to write a special Guile-to-X11 glue library that has intimate knowledge about both Guile and X11 and does whatever is necessary to make them inter-operate smoothly. This glue library could then be dynamically linked into a vanilla Guile interpreter and activated by calling its initialization function. That function would add all the new types and primitives to the Guile interpreter that it has to offer.

(There is actually another, better option: simply to create a libX11 wrapper in Scheme via the dynamic FFI. See Dynamic FFI, for more information.)

Given some set of C extensions to Guile, the next logical step is to integrate these glue libraries into the module system of Guile so that you can load new primitives into a running system just as you can load new Scheme code.

Scheme Procedure: load-extension lib init

C Function: scm_load_extension (lib, init)

Load and initialize the extension designated by LIB and INIT. When there is no pre-registered function for LIB/INIT, this is equivalent to

(dynamic-call INIT (dynamic-link LIB))

When there is a pre-registered function, that function is called instead.

Normally, there is no pre-registered function. This option exists only for situations where dynamic linking is unavailable or unwanted. In that case, you would statically link your program with the desired library, and register its init function right after Guile has been initialized.

As for dynamic-link, lib should not contain any suffix such as .so (see dynamic-link). It should also not contain any directory components. Libraries that implement Guile Extensions should be put into the normal locations for shared libraries. We recommend to use the naming convention libguile-bla-blum for a extension related to a module (bla blum).

The normal way for a extension to be used is to write a small Scheme file that defines a module, and to load the extension into this module. When the module is auto-loaded, the extension is loaded as well. For example,

(define-module (bla blum))

(load-extension "libguile-bla-blum" "bla_init_blum")