GNU Info
(libtool.info)Libltdl interface
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 Note: 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'.
automatically generated by info2www version 1.2.2.9