11.2 Accessing foreign objects from Scheme

Most system implementations of dynamic loading employ reference counting for dlopen and dlclose in that library resources are not freed until the number of calls to dlclose matches the number of calls to dlopen. The following bindings are exported by (vicare ffi).

Function: dlopen

Function: dlopen library-name

Function: dlopen library-name lazy? global?

Interface to the C function dlopen(), see the manual page dlopen(3). Load a platform shared library and return a pointer object representing a handler for the library, which can be used as argument for dlsym and dlclose. If the library cannot be loaded: return #f and the procedure dlerror can be used to obtain the cause of the failure.

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. The lazy? and global? arguments are meaningless in this case.

When given: library-name must be a string or a bytevector representing the name of the library; if it is a string: it is converted to bytevector using the function referenced by filename->string-func.

Library names are system–dependent and must include the appropriate suffix (for exapmle *.so on Linux, *.dylib on Darwin and *.dll on Cygwin). library-name may include a full path which identifies the location of the library, or it may just be the name of the library in which case the system will lookup the library name using the LD_LIBRARY_PATH environment variable.

The argument lazy? specifies how library dependencies are loaded. If true, dlopen delays the resolution and loading of dependent libraries until they are actually used. If false, all library dependencies are loaded before the call to dlopen returns. lazy? defaults to #f.

The argument global? specifies the scope of the symbols exported from the loaded library. If true, all exported symbols become part of the running image, and subsequent dlsym calls may not need to specify the library from which the symbol is loaded. If false, the exported symbols are not global and the library pointer needs to be specified for dlsym. global? defaults to #f.

Function: dlclose handle

Interface to the C function dlclose(), see the manual page dlclose(3). Release the resources loaded from the library referenced by the pointer handler handle. If successful return #t, else return #f and dlerror can be used to obtain the cause of the 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: dlsym handle name

Interface to the C function dlsym(), see the manual page dlsym(3). Search the loaded library referenced by the pointer handle for an exported symbol whose name is represented by the string name. If successful return a pointer object, else return #f and dlerror can be used to obtain the cause of the error.

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

Function: dlerror

Interface to the C function dlerror(), see the manual page dlerror(3). If any of the dynamic loading operations fails, the cause of the error can be obtained by calling dlerror which returns a string describing the error; return #f if there was no dynamic loading error.