Go to the first, previous, next, last section, table of contents.

How to use libltdl in your programs

The libltdl API is similar to the dlopen interface of Solaris and Linux, which is very simple but powerful.

To use libltdl in your program you have to include the header file `ltdl.h': 

#include <ltdl.h>

The last release of libltdl used some symbols that violated the POSIX namespace conventions. These symbols are now deprecated, and have been replaced by those described here. If you have code that relies on the old deprecated symbol names, defining `LT_NON_POSIX_NAMESPACE' before you include `ltdl.h' provides conversion macros. Whichever set of symbols you use, the new api is not binary compatible with the last, so you will need to recompile your application in order to use this version of libltdl.

Note that libltdl is not threadsafe, i.e. a multithreaded application has to use a mutex for libltdl. It was reported that GNU/Linux's glibc 2.0's dlopen with `RTLD_LAZY' (which libltdl uses by default) is not thread-safe, but this problem is supposed to be fixed in glibc 2.1. On the other hand, `RTLD_NOW' was reported to introduce problems in multi-threaded applications on FreeBSD. Working around these problems is left as an exercise for the reader; contributions are certainly welcome.

The following types are defined in `ltdl.h':

Type: lt_ptr
lt_ptr is a generic pointer.

Type: lt_dlhandle
lt_dlhandle is a module "handle". Every lt_dlopened module has a handle associated with it.

Type: lt_dlsymlist
lt_dlsymlist is a symbol list for dlpreopened modules. This structure is described in see section Dlpreopening.

libltdl provides the following functions:

Function: int lt_dlinit (void)
Initialize libltdl. This function must be called before using libltdl and may be called several times. Return 0 on success, otherwise the number of errors.

Function: int lt_dlexit (void)
Shut down libltdl and close all modules. This function will only then shut down libltdl when it was called as many times as lt_dlinit has been successfully called. Return 0 on success, otherwise the number of errors.

Function: lt_dlhandle lt_dlopen (const char *filename)
Open the module with the file name filename and return a handle for it. lt_dlopen is able to open libtool dynamic modules, preloaded static modules, the program itself and native dynamic libraries.

Unresolved symbols in the module are resolved using its dependency libraries (not implemented yet) and previously dlopened modules. If the executable using this module was linked with the -export-dynamic flag, then the global symbols in the executable will also be used to resolve references in the module.

If filename is NULL and the program was linked with -export-dynamic or -dlopen self, lt_dlopen will return a handle for the program itself, which can be used to access its symbols.

If libltdl cannot find the library and the file name filename does not have a directory component it will additionally search in the following search paths for the module (in the order as follows):

  1. user-defined search path: This search path can be set by the program using the functions lt_dlsetsearchpath and lt_dladdsearchdir.
  2. libltdl's search path: This search path is the value of the environment variable LTDL_LIBRARY_PATH.
  3. system library search path: The system dependent library search path (e.g. on Linux it is LD_LIBRARY_PATH).

Each search path must be a colon-separated list of absolute directories, for example, "/usr/lib/mypkg:/lib/foo".

If the same module is loaded several times, the same handle is returned. If lt_dlopen fails for any reason, it returns NULL.

Function: lt_dlhandle lt_dlopenext (const char *filename)
The same as lt_dlopen, except that it tries to append different file name extensions to the file name. If the file with the file name filename cannot be found libltdl tries to append the following extensions:

  1. the libtool archive extension `.la'
  2. the extension used for native dynamic libraries on the host platform, e.g., `.so', `.sl', etc.

This lookup strategy was designed to allow programs that don't have knowledge about native dynamic libraries naming conventions to be able to dlopen such libraries as well as libtool modules transparently.

Function: int lt_dlclose (lt_dlhandle handle)
Decrement the reference count on the module handle. If it drops to zero and no other module depends on this module, then the module is unloaded. Return 0 on success.

Function: lt_ptr lt_dlsym (lt_dlhandle handle, const char *name)
Return the address in the module handle, where the symbol given by the null-terminated string name is loaded. If the symbol cannot be found, NULL is returned.

Function: {const char *}lt_dlerror (void)
Return a human readable string describing the most recent error that occurred from any of libltdl's functions. Return NULL if no errors have occurred since initialization or since it was last called.

Function: int lt_dlpreload (const lt_dlsymlist *preloaded)
Register the list of preloaded modules preloaded. If preloaded is NULL, then all previously registered symbol lists, except the list set by lt_dlpreload_default, are deleted. Return 0 on success.

Function: int lt_dlpreload_default (const lt_dlsymlist *preloaded)
Set the default list of preloaded modules to preloaded, which won't be deleted by lt_dlpreload. Note that this function does not require libltdl to be initialized using lt_dlinit and can be used in the program to register the default preloaded modules. Instead of calling this function directly, most programs will use the macro LTDL_SET_PRELOADED_SYMBOLS.

Return 0 on success.

Macro: LTDL_SET_PRELOADED_SYMBOLS()
Set the default list of preloaded symbols. Should be used in your program to initialize libltdl's list of preloaded modules. 

#include <ltdl.h>

int main() {
  /* ... */
  LTDL_SET_PRELOADED_SYMBOLS();
  /* ... */
}

Function: int lt_dladdsearchdir (const char *search_dir)
Add the search directory search_dir to the user-defined library search path. Return 0 on success.

Function: int lt_dlsetsearchpath (const char *search_path)
Replace the current user-defined library search path with search_path, which must be a colon-separated list of absolute directories. Return 0 on success.

Function: {const char *}lt_dlgetsearchpath (void)
Return the current user-defined library search path.

Function: int lt_dlmakeresident (lt_dlhandle handle)
Mark a module so that it cannot be `lt_dlclose'd. This can be useful if a module implements some core functionality in your project, which would cause your code to crash if removed. Return 0 on success.

If you use `lt_dlopen (NULL)' to get a handle for the running binary, that handle will always be marked as resident, and consequently cannot be successfully `lt_dlclose'd.

Function: int lt_dlisresident (lt_dlhandle handle)
Check whether a particular module has been marked as resident, returning 1 if it has or 0 otherwise. If there is an error while executing this function, return -1 and set an error message for retrieval with lt_dlerror.

Variable: lt_ptr (*) (size_t size) lt_dlmalloc
Variable: void (*) (lt_ptr ptr) lt_dlfree
These variables are set to malloc and free, by default, but you can set them to any other functions that provides equivalent functionality. However, you must not modify their values after calling any libltdl function other than lt_dlpreopen_default or the macro LTDL_SET_PRELOADED_SYMBOLS.

Go to the first, previous, next, last section, table of contents.