11.3 System–agnostic shared libraries API

This API to load shared libraries is more system–agnostic with respect to the functions described in ffi dl. The following bindings are exported by (vicare ffi).

Function: open-shared-object

Function: open-shared-object so-name

Load a platform shared library and return a pointer object representing a handler for the library. If the library cannot be loaded: raise a non–continuable exception with condition types &who, &message, &shared-object-opening-error.

When no arguments are present: the returned pointer handler references the current process and it can be used to retrieve pointers to functions already loaded, for example the functions exported by the standard C library.

When given: so-name must be a string representing the name of the library; library names are system–dependent and must include the appropriate suffix (for exapmle *.so on Linux, *.dylib on Darwin and *.dll on Cygwin). so-name may include a full path which identifies the location of the library, or it may just be the name of the library.

For Unix We can find documentation about the search path of shared objects in the manual page of dlopen(). The system will lookup the library name using the LD_LIBRARY_PATH environment variable.

Function: close-shared-object so-handle

Release the resources loaded from the library referenced by the so-handle. If the library cannot be closed: raise a non–continuable exception with condition types &who, &message, &shared-object-closing-error.

Closing a library renders all symbols and static data structures that the library exports invalid and the program may crash or corrupt its memory if such symbols are used after a library is closed.

Function: lookup-shared-object so-handle name

Search the loaded library referenced by the so-handle for an exported symbol whose name is represented by the Scheme string name. If successful return a pointer object, else raise a non–continuable exception with condition types &who, &message, &shared-object-lookup-error.

If the returned value references a function: it can be used as argument to the callout generators built by make-c-callout-maker.

Shared object errors

Condition Type: &shared-object-error

Base condition type for all the exceptions associated to a shared object; it is derived from &error. It has no fields.

Function: make-shared-object-error

Build and return a new instance of &shared-object-error.

Function: shared-object-error? obj

Return #t if obj is an instance of &shared-object-error, else return #f.

Opening shared objects

Condition Type: &shared-object-opening-error

Condition type tagging exceptions associated to opening a shared object; it is derived from &shared-object-error. It has the following fields:

name

Scheme string representing the file name of the shared object.

Function: make-shared-object-opening-error so-name

Build and return a new instance of &shared-object-opening-error.

Function: shared-object-opening-error? obj

Return #t if obj is an instance of &shared-object-opening-error, else return #f.

Function: condition-shared-object-opening-name so-opening

Accessor for the field of &shared-object-opening-error.

Closing shared objects

Condition Type: &shared-object-closing-error

Condition type tagging exceptions associated to closing a shared object; it is derived from &shared-object-error. It has the following fields:

so-handle

Pointer object referencing the shared object; it is the value returned by open-shared-object.

Function: make-shared-object-closing-error so-handle

Build and return a new instance of &shared-object-closing-error.

Function: shared-object-closing-error? obj

Return #t if obj is an instance of &shared-object-closing-error, else return #f.

Function: condition-shared-object-closing-so-handle so-closing

Accessor for the field of &shared-object-closing-error.

Inspecting shared objects

Condition Type: &shared-object-lookup-error

Condition type tagging exceptions associated to looking up a symbol in a shared object; it is derived from &shared-object-error. It has the following fields:

so-handle

Pointer object referencing the shared object; it is the value returned by open-shared-object.

foreign-symbol

Scheme string representing the shared object exported symbol whose address was requested.

Function: make-shared-object-lookup-error so-handle symbol

Build and return a new instance of &shared-object-lookup-error.

Function: shared-object-lookup-error? obj

Return #t if obj is an instance of &shared-object-lookup-error, else return #f.

Function: condition-shared-object-lookup-so-handle so-lookup

Function: condition-shared-object-lookup-foreign-symbol so-lookup

Accessors for the fields of &shared-object-lookup-error.