Warning: This is the manual of the legacy Guile 2.2 series. You may want to read the manual of the current stable series instead.

6.21.1 Foreign Libraries

Most modern Unices have something called shared libraries. This ordinarily means that they have the capability to share the executable image of a library between several running programs to save memory and disk space. But generally, shared libraries give a lot of additional flexibility compared to the traditional static libraries. In fact, calling them ‘dynamic’ libraries is as correct as calling them ‘shared’.

Shared libraries really give you a lot of flexibility in addition to the memory and disk space savings. When you link a program against a shared library, that library is not closely incorporated into the final executable. Instead, the executable of your program only contains enough information to find the needed shared libraries when the program is actually run. Only then, when the program is starting, is the final step of the linking process performed. This means that you need not recompile all programs when you install a new, only slightly modified version of a shared library. The programs will pick up the changes automatically the next time they are run.

Now, when all the necessary machinery is there to perform part of the linking at run-time, why not take the next step and allow the programmer to explicitly take advantage of it from within their program? Of course, many operating systems that support shared libraries do just that, and chances are that Guile will allow you to access this feature from within your Scheme programs. As you might have guessed already, this feature is called dynamic linking.¹⁹

We titled this section “foreign libraries” because although the name “foreign” doesn’t leak into the API, the world of C really is foreign to Scheme – and that estrangement extends to components of foreign libraries as well, as we see in future sections.

Scheme Procedure: dynamic-link [library]

C Function: scm_dynamic_link (library)

Find the shared library denoted by library (a string) and link it into the running Guile application. When everything works out, return a Scheme object suitable for representing the linked object file. Otherwise an error is thrown. How object files are searched is system dependent.

Normally, library is just the name of some shared library file that will be searched for in the places where shared libraries usually reside, such as in /usr/lib and /usr/local/lib.

library should not contain an extension such as .so. The correct file name extension for the host operating system is provided automatically, according to libltdl’s rules (see lt_dlopenext in Shared Library Support for GNU).

When library is omitted, a global symbol handle is returned. This handle provides access to the symbols available to the program at run-time, including those exported by the program itself and the shared libraries already loaded.

Note that on hosts that use dynamic-link libraries (DLLs), the global symbol handle may not be able to provide access to symbols from recursively-loaded DLLs. Only exported symbols from those DLLs directly loaded by the program may be available.

Scheme Procedure: dynamic-object? obj

C Function: scm_dynamic_object_p (obj)

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

Scheme Procedure: dynamic-unlink dobj

C Function: scm_dynamic_unlink (dobj)

Unlink the indicated object file from the application. The argument dobj must have been obtained by a call to dynamic-link. After dynamic-unlink has been called on dobj, its content is no longer accessible.

(define libgl-obj (dynamic-link "libGL"))
libgl-obj
⇒ #<dynamic-object "libGL">
(dynamic-unlink libGL-obj)
libGL-obj
⇒ #<dynamic-object "libGL" (unlinked)>

As you can see, after calling dynamic-unlink on a dynamically linked library, it is marked as ‘(unlinked)’ and you are no longer able to use it with dynamic-call, etc. Whether the library is really removed from you program is system-dependent and will generally not happen when some other parts of your program still use it.

When dynamic linking is disabled or not supported on your system, the above functions throw errors, but they are still available.