5.1 Dynamic Linking

If SCM has been compiled with dynl.c then the additional properties of load and ([SLIB]) require specified here are supported. The require form is preferred.

Function: require feature ¶

If the symbol feature has not already been given as an argument to require, then the object and library files associated with feature will be dynamically-linked, and an unspecified value returned. If feature is not found in *catalog*, then an error is signaled.

Function: usr:lib lib ¶

Returns the pathname of the C library named lib. For example: (usr:lib "m") returns "/usr/lib/libm.a", the path of the C math library.

Function: x:lib lib ¶

Returns the pathname of the X library named lib. For example: (x:lib "X11") returns "/usr/X11/lib/libX11.sa", the path of the X11 library.

Function: load filename lib1 … ¶

In addition to the [R5RS] requirement of loading Scheme expressions if filename is a Scheme source file, load will also dynamically load/link object files (produced by compile-file, for instance). The object-suffix need not be given to load. For example,

(load (in-vicinity (implementation-vicinity) "sc2"))
or (load (in-vicinity (implementation-vicinity) "sc2.o"))
or (require 'rev2-procedures)
or (require 'rev3-procedures)

will load/link sc2.o if it exists.

The lib1 … pathnames specify additional libraries which may be needed for object files not produced by the Hobbit compiler. For instance, crs is linked on GNU/Linux by

(load (in-vicinity (implementation-vicinity) "crs.o")
      (usr:lib "ncurses") (usr:lib "c"))
or (require 'curses)

Turtlegr graphics library is linked by:

(load (in-vicinity (implementation-vicinity) "turtlegr")
      (usr:lib "X11") (usr:lib "c") (usr:lib "m"))
or (require 'turtle-graphics)

And the string regular expression (see Regular Expression Pattern Matching) package is linked by:

(load (in-vicinity (implementation-vicinity) "rgx") (usr:lib "c"))

or

(require 'regex)

The following functions comprise the low-level Scheme interface to dynamic linking. See the file Link.scm in the SCM distribution for an example of their use.

Function: dyn:link filename ¶

filename should be a string naming an object or archive file, the result of C-compiling. The dyn:link procedure links and loads filename into the current SCM session. If successfull, dyn:link returns a link-token suitable for passing as the second argument to dyn:call. If not successful, #f is returned.

Function: dyn:call name link-token ¶

link-token should be the value returned by a call to dyn:link. name should be the name of C function of no arguments defined in the file named filename which was succesfully dyn:linked in the current SCM session. The dyn:call procedure calls the C function corresponding to name. If successful, dyn:call returns #t; If not successful, #f is returned.

dyn:call is used to call the init_… function after loading SCM object files. The init_… function then makes the identifiers defined in the file accessible as Scheme procedures.

Function: dyn:main-call name link-token arg1 … ¶

link-token should be the value returned by a call to dyn:link. name should be the name of C function of 2 arguments, (int argc, const char **argv), defined in the file named filename which was succesfully dyn:linked in the current SCM session. The dyn:main-call procedure calls the C function corresponding to name with argv style arguments, such as are given to C main functions. If successful, dyn:main-call returns the integer returned from the call to name.

dyn:main-call can be used to call a main procedure from SCM. For example, I link in and dyn:main-call a large C program, the low level routines of which callback (see Callbacks) into SCM (which emulates PCI hardware).

Function: dyn:unlink link-token ¶

link-token should be the value returned by a call to dyn:link. The dyn:unlink procedure removes the previously loaded file from the current SCM session. If successful, dyn:unlink returns #t; If not successful, #f is returned.