GNU Info
(guile.info)Dynamic Libraries
Dynamic Libraries
=================
Often you will want to extend Guile by linking it with some existing
system library. For example, linking Guile with a `curses' or
`termcap' library would be useful if you want to implement a
full-screen user interface for a Guile application. However, if you
were to link Guile with these libraries at compile time, it would bloat
the interpreter considerably, affecting everyone on the system even if
the new libraries are useful only to you. Also, every time a new
library is installed, you would have to reconfigure, recompile and
relink Guile merely in order to provide a new interface.
Many Unix systems permit you to get around this problem by using
"dynamic loading". When a new library is linked, it can be made a
"dynamic library" by passing certain switches to the linker. A dynamic
library does not need to be linked with an executable image at link
time; instead, the executable may choose to load it dynamically at run
time. This is a powerful concept that permits an executable to link
itself with almost any library without reconfiguration, if it has been
written properly.
Guile's dynamic linking functions make it relatively easy to write a
module that incorporates code from third-party object code libraries.
- primitive: dynamic-link fname
Open the dynamic library LIBRARY-FILE. A library handle
representing the opened library is returned; this handle should be
used as the LIB argument to the following functions.
- primitive: dynamic-object? obj
Return `#t' if OBJ is a dynamic library handle, or `#f' otherwise.
- primitive: dynamic-unlink dobj
Unlink the library represented by LIBRARY-HANDLE, and remove any
imported symbols from the address space. GJB:FIXME:DOC: 2nd
version below: Unlink the indicated object file from the
application. The argument DYNOBJ must have been obtained by a
call to `dynamic-link'. After `dynamic-unlink' has been called on
DYNOBJ, its content is no longer accessible.
- primitive: 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.
- primitive: dynamic-call func dobj
Call LIB-THUNK, a procedure of no arguments. If LIB-THUNK is a
string, it is assumed to be a symbol found in the dynamic library
LIB and is fetched with `dynamic-func'. Otherwise, it should be a
function handle returned by a previous call to `dynamic-func'.
The return value is unspecified. GJB:FIXME:DOC 2nd version below
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 func dobj args
Call PROC, a dynamically loaded function, passing it the argument
list ARGS (a list of strings). As with `dynamic-call', PROC
should be either a function handle or a string, in which case it
is first fetched from LIB with `dynamic-func'.
PROC is assumed to return an integer, which is used as the return
value from `dynamic-args-call'.
GJB:FIXME:DOC 2nd version below 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'.
- primitive: c-registered-modules
Return a list of the object code modules that have been imported
into the current Guile process. Each element of the list is a
pair whose car is the name of the module, and whose cdr is the
function handle for that module's initializer function. The name
is the string that has been passed to scm_register_module_xxx.
- primitive: c-clear-registered-modules
Destroy the list of modules registered with the current Guile
process. The return value is unspecified. *Warning:* this
function does not actually unlink or deallocate these modules, but
only destroys the records of which modules have been loaded. It
should therefore be used only by module bookkeeping operations.
[FIXME: provide a brief example here of writing the C hooks for an
object code module, and using dynamic-link and dynamic-call to load the
module.]
automatically generated by info2www version 1.2.2.9