GNU Info

(guile.info)Low level dynamic linking

---

Next: Compiled Code Modules Up: Dynamic Linking from Marius

---

Enter node , (file) or (file)node

Low level dynamic linking
-------------------------

When using the low level procedures to do your dynamic linking, you have
complete control over which library is loaded when and what get's done
with it.

 - primitive: 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'.

 - primitive: dynamic-object? val
     Determine whether VAL represents a dynamically linked object file.

 - primitive: dynamic-unlink dynobj
     Unlink the indicated object file from the application.  The
     argument DYNOBJ should be one of the values returned by
     `dynamic-link'.  When `dynamic-unlink' has been called on DYNOBJ,
     it is no longer usable as an argument to the functions below and
     you will get type mismatch errors when you try to.

 - primitive: dynamic-func function dynobj
     Search the C function indicated by FUNCTION (a string or symbol)
     in DYNOBJ and return some Scheme object that can later be used
     with `dynamic-call' to actually call this function.  Right now,
     these Scheme objects are formed by casting the address of the
     function to `long' and converting this number to its Scheme
     representation.

     Regardless whether your C compiler prepends an underscore `_' to
     the global names in a program, you should *not* include this
     underscore in FUNCTION.  Guile knows whether the underscore is
     needed or not and will add it when necessary.

 - primitive: dynamic-call function dynobj
     Call the C function indicated by FUNCTION and DYNOBJ.  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 DYNOBJ.  When FUNCTION is a string (or symbol,
     etc.), look it up in DYNOBJ; this is equivalent to

          (dynamic-call (dynamic-func FUNCTION DYNOBJ #f))

     Interrupts are deferred while the C function is executing (with
     `SCM_DEFER_INTS'/`SCM_ALLOW_INTS').

 - primitive: dynamic-args-call function dynobj args
     Call the C function indicated by FUNCTION and DYNOBJ, just like
     `dynamic-call', but pass it some arguments and return its return
     value.  The C function is expected to take two arguments and
     return an `int', just like `main':

          int c_func (int argc, char **argv);

     The parameter ARGS must be a list of strings and is converted into
     an array of `char *'.  The array is passed in ARGV and its size in
     ARGC.  The return value is converted to a Scheme number and
     returned from the call to `dynamic-args-call'.

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

Here is a small example that works on GNU/Linux:

     (define libc-obj (dynamic-link "libc.so"))
     libc-obj
     => #<dynamic-object "libc.so">
     (dynamic-args-call 'rand libc-obj '())
     => 269167349
     (dynamic-unlink libc-obj)
     libc-obj
     => #<dynamic-object "libc.so" (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.  In the example above,
`libc' is almost certainly not removed from your program because it is
badly needed by almost everything.

The functions to call a function from a dynamically linked library,
`dynamic-call' and `dynamic-args-call', are not very powerful.  They
are 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' and `dynamic-args-call'.
Instead, the usual way would be to write a special Guile<->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.

From this setup 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.

There is, however, another possibility to get a more thorough access to
the functions contained in a dynamically linked library.  Anthony Green
has written `libffi', a library that implements a "foreign function
interface" for a number of different platforms.  With it, you can
extend the Spartan functionality of `dynamic-call' and
`dynamic-args-call' considerably.  There is glue code available in the
Guile contrib archive to make `libffi' accessible from Guile.