(guile.info.gz) Low level dynamic linking

Info Catalog

(guile.info.gz) Dynamic Libraries

(guile.info.gz) Extensions

 
 31.4.1 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 gets done
 with it.
 
  -- 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'.
 
  -- 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.
 
  -- Scheme Procedure: dynamic-func name dobj
  -- C Function: scm_dynamic_func (name, dobj)
      Search the dynamic object DOBJ for the C function indicated by the
      string NAME and return some Scheme handle that can later be used
      with `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 FUNCTION.  Guile knows whether the underscore is
      needed or not and will add it when necessary.
 
  -- 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)
 
      Interrupts are deferred while the C function is executing (with
      `SCM_DEFER_INTS'/`SCM_ALLOW_INTS').
 
  -- Scheme Procedure: dynamic-args-call func dobj args
  -- C Function: scm_dynamic_args_call (func, dobj, args)
      Call the C function indicated by FUNC and DOBJ, 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.
 

Info Catalog

(guile.info.gz) Dynamic Libraries

(guile.info.gz) Extensions