libtool: Libltdl interface
1
1 11.1 How to use libltdl in your programs
1 ========================================
1
1 The libltdl API is similar to the POSIX dlopen interface, which is very
1 simple but powerful.
1
1 To use libltdl in your program you have to include the header file
1 'ltdl.h':
1
1 #include <ltdl.h>
1
1 The early releases of libltdl used some symbols that violated the POSIX
1 namespace conventions. These symbols are now deprecated, and have been
1 replaced by those described here. If you have code that relies on the
1 old deprecated symbol names, defining 'LT_NON_POSIX_NAMESPACE' before
1 you include 'ltdl.h' provides conversion macros. Whichever set of
1 symbols you use, the new API is not binary compatible with the last, so
1 you will need to recompile your application to use this version of
1 libltdl.
1
1 Note that libltdl is not well tested in a multithreaded environment,
11 though the intention is that it should work (⇒Using libltdl in a
multi threaded environment Thread Safety in libltdl.). It was reported
1 that GNU/Linux's glibc 2.0's 'dlopen' with 'RTLD_LAZY' (that libltdl
1 uses by default) is not thread-safe, but this problem is supposed to be
1 fixed in glibc 2.1. On the other hand, 'RTLD_NOW' was reported to
1 introduce problems in multi-threaded applications on FreeBSD. Working
1 around these problems is left as an exercise for the reader;
1 contributions are certainly welcome.
1
1 The following macros are defined by including 'ltdl.h':
1
1 -- Macro: LT_PATHSEP_CHAR
1 'LT_PATHSEP_CHAR' is the system-dependent path separator, that is,
1 ';' on Windows and ':' everywhere else.
1
1 -- Macro: LT_DIRSEP_CHAR
1 If 'LT_DIRSEP_CHAR' is defined, it can be used as directory
1 separator in addition to '/'. On Windows, this contains '\'.
1
1 The following types are defined in 'ltdl.h':
1
1 -- Type: lt_dlhandle
1 'lt_dlhandle' is a module "handle". Every lt_dlopened module has a
1 handle associated with it.
1
1 -- Type: lt_dladvise
1 'lt_dladvise' is used to control optional module loading modes. If
1 it is not used, the default mode of the underlying system module
1 loader is used.
1
1 -- Type: lt_dlsymlist
11 'lt_dlsymlist' is a symbol list for dlpreopened modules (⇒
Dlpreopening).
1
1 libltdl provides the following functions:
1
1 -- Function: int lt_dlinit (void)
1 Initialize libltdl. This function must be called before using
1 libltdl and may be called several times. Return 0 on success,
1 otherwise the number of errors.
1
1 -- Function: int lt_dlexit (void)
1 Shut down libltdl and close all modules. This function will only
1 then shut down libltdl when it was called as many times as
1 'lt_dlinit' has been successfully called. Return 0 on success,
1 otherwise the number of errors.
1
1 -- Function: lt_dlhandle lt_dlopen (const char *FILENAME)
1 Open the module with the file name FILENAME and return a handle for
1 it. 'lt_dlopen' is able to open libtool dynamic modules, preloaded
1 static modules, the program itself and native dynamic modules(1).
1
1 Unresolved symbols in the module are resolved using its dependency
1 libraries and previously dlopened modules. If the executable using
1 this module was linked with the '-export-dynamic' flag, then the
1 global symbols in the executable will also be used to resolve
1 references in the module.
1
1 If FILENAME is 'NULL' and the program was linked with
1 '-export-dynamic' or '-dlopen self', 'lt_dlopen' will return a
1 handle for the program itself, which can be used to access its
1 symbols.
1
1 If libltdl cannot find the library and the file name FILENAME does
1 not have a directory component it will additionally look in the
1 following search paths for the module (in the following order):
1
1 1. user-defined search path: This search path can be changed by
1 the program using the functions 'lt_dlsetsearchpath',
1 'lt_dladdsearchdir' and 'lt_dlinsertsearchdir'.
1
1 2. libltdl's search path: This search path is the value of the
1 environment variable 'LTDL_LIBRARY_PATH'.
1
1 3. system library search path: The system dependent library
1 search path (e.g. on GNU/Linux it is 'LD_LIBRARY_PATH').
1
1 Each search path must be a list of absolute directories separated
1 by 'LT_PATHSEP_CHAR', for example, '"/usr/lib/mypkg:/lib/foo"'.
1 The directory names may not contain the path separator.
1
1 If the same module is loaded several times, the same handle is
1 returned. If 'lt_dlopen' fails for any reason, it returns 'NULL'.
1
1 -- Function: lt_dlhandle lt_dlopenext (const char *FILENAME)
1 The same as 'lt_dlopen', except that it tries to append different
1 file name extensions to the file name. If the file with the file
1 name FILENAME cannot be found libltdl tries to append the following
1 extensions:
1
1 1. the libtool archive extension '.la'
1 2. the extension used for native dynamically loadable modules on
1 the host platform, e.g., '.so', '.sl', etc.
1
1 This lookup strategy was designed to allow programs that don't have
1 knowledge about native dynamic libraries naming conventions to be
1 able to 'dlopen' such libraries as well as libtool modules
1 transparently.
1
1 -- Function: lt_dlhandle lt_dlopenadvise (const char *FILENAME,
1 lt_dladvise ADVISE)
1 The same as 'lt_dlopen', except that it also requires an additional
1 argument that may contain additional hints to the underlying system
1 module loader. The ADVISE parameter is opaque and can only be
1 accessed with the functions documented below.
1
1 Note that this function does not change the content of ADVISE, so
1 unlike the other calls in this API takes a direct 'lt_dladvise'
1 type, and not a pointer to the same.
1
1 -- Function: int lt_dladvise_init (lt_dladvise *ADVISE)
1 The ADVISE parameter can be used to pass hints to the module loader
1 when using 'lt_dlopenadvise' to perform the loading. The ADVISE
1 parameter needs to be initialised by this function before it can be
1 used. Any memory used by ADVISE needs to be recycled with
1 'lt_dladvise_destroy' when it is no longer needed.
1
1 On failure, 'lt_dladvise_init' returns non-zero and sets an error
1 message that can be retrieved with 'lt_dlerror'.
1
1 -- Function: int lt_dladvise_destroy (lt_dladvise *ADVISE)
1 Recycle the memory used by ADVISE. For an example, see the
1 documentation for 'lt_dladvise_ext'.
1
1 On failure, 'lt_dladvise_destroy' returns non-zero and sets an
1 error message that can be retrieved with 'lt_dlerror'.
1
1 -- Function: int lt_dladvise_ext (lt_dladvise *ADVISE)
1 Set the 'ext' hint on ADVISE. Passing an ADVISE parameter to
1 'lt_dlopenadvise' with this hint set causes it to try to append
1 different file name extensions like 'lt_dlopenext'.
1
1 The following example is equivalent to calling 'lt_dlopenext
1 (filename)':
1
1 lt_dlhandle
1 my_dlopenext (const char *filename)
1 {
1 lt_dlhandle handle = 0;
1 lt_dladvise advise;
1
1 if (!lt_dladvise_init (&advise) && !lt_dladvise_ext (&advise))
1 handle = lt_dlopenadvise (filename, advise);
1
1 lt_dladvise_destroy (&advise);
1
1 return handle;
1 }
1
1 On failure, 'lt_dladvise_ext' returns non-zero and sets an error
1 message that can be retrieved with 'lt_dlerror'.
1
1 -- Function: int lt_dladvise_global (lt_dladvise *ADVISE)
1 Set the 'symglobal' hint on ADVISE. Passing an ADVISE parameter to
1 'lt_dlopenadvise' with this hint set causes it to try to make the
1 loaded module's symbols globally available for resolving unresolved
1 symbols in subsequently loaded modules.
1
1 If neither the 'symglobal' nor the 'symlocal' hints are set, or if
1 a module is loaded without using the 'lt_dlopenadvise' call in any
1 case, then the visibility of the module's symbols will be as per
1 the default for the underlying module loader and OS. Even if a
1 suitable hint is passed, not all loaders are able to act upon it in
1 which case 'lt_dlgetinfo' will reveal whether the hint was actually
1 followed.
1
1 On failure, 'lt_dladvise_global' returns non-zero and sets an error
1 message that can be retrieved with 'lt_dlerror'.
1
1 -- Function: int lt_dladvise_local (lt_dladvise *ADVISE)
1 Set the 'symlocal' hint on ADVISE. Passing an ADVISE parameter to
1 'lt_dlopenadvise' with this hint set causes it to try to keep the
1 loaded module's symbols hidden so that they are not visible to
1 subsequently loaded modules.
1
1 If neither the 'symglobal' nor the 'symlocal' hints are set, or if
1 a module is loaded without using the 'lt_dlopenadvise' call in any
1 case, then the visibility of the module's symbols will be as per
1 the default for the underlying module loader and OS. Even if a
1 suitable hint is passed, not all loaders are able to act upon it in
1 which case 'lt_dlgetinfo' will reveal whether the hint was actually
1 followed.
1
1 On failure, 'lt_dladvise_local' returns non-zero and sets an error
1 message that can be retrieved with 'lt_dlerror'.
1
1 -- Function: int lt_dladvise_resident (lt_dladvise *ADVISE)
1 Set the 'resident' hint on ADVISE. Passing an ADVISE parameter to
1 'lt_dlopenadvise' with this hint set causes it to try to make the
1 loaded module resident in memory, so that it cannot be unloaded
1 with a later call to 'lt_dlclose'.
1
1 On failure, 'lt_dladvise_resident' returns non-zero and sets an
1 error message that can be retrieved with 'lt_dlerror'.
1
1 -- Function: int lt_dladvise_preload (lt_dladvise *ADVISE)
1 Set the 'preload' hint on ADVISE. Passing an ADVISE parameter to
1 'lt_dlopenadvise' with this hint set causes it to load only
1 preloaded modules, so that if a suitable preloaded module is not
1 found, 'lt_dlopenadvise' will return 'NULL'.
1
1 -- Function: int lt_dlclose (lt_dlhandle HANDLE)
1 Decrement the reference count on the module HANDLE. If it drops to
1 zero and no other module depends on this module, then the module is
1 unloaded. Return 0 on success.
1
1 -- Function: void * lt_dlsym (lt_dlhandle HANDLE, const char *NAME)
1 Return the address in the module HANDLE, where the symbol given by
1 the null-terminated string NAME is loaded. If the symbol cannot be
1 found, 'NULL' is returned.
1
1 -- Function: const char * lt_dlerror (void)
1 Return a human readable string describing the most recent error
1 that occurred from any of libltdl's functions. Return 'NULL' if no
1 errors have occurred since initialization or since it was last
1 called.
1
1 -- Function: int lt_dladdsearchdir (const char *SEARCH_DIR)
1 Append the search directory SEARCH_DIR to the current user-defined
1 library search path. Return 0 on success.
1
1 -- Function: int lt_dlinsertsearchdir (const char *BEFORE,
1 const char *SEARCH_DIR)
1 Insert the search directory SEARCH_DIR into the user-defined
1 library search path, immediately before the element starting at
1 address BEFORE. If BEFORE is 'NULL', then SEARCH_DIR is appending
1 as if 'lt_dladdsearchdir' had been called. Return 0 on success.
1
1 -- Function: int lt_dlsetsearchpath (const char *SEARCH_PATH)
1 Replace the current user-defined library search path with
1 SEARCH_PATH, which must be a list of absolute directories separated
1 by 'LT_PATHSEP_CHAR'. Return 0 on success.
1
1 -- Function: const char * lt_dlgetsearchpath (void)
1 Return the current user-defined library search path.
1
1 -- Function: int lt_dlforeachfile (const char *SEARCH_PATH,
1 int (*FUNC) (const char *FILENAME, void * DATA), void * DATA)
1 In some applications you may not want to load individual modules
1 with known names, but rather find all of the modules in a set of
1 directories and load them all during initialisation. With this
1 function you can have libltdl scan the 'LT_PATHSEP_CHAR'-delimited
1 directory list in SEARCH_PATH for candidates, and pass them, along
1 with DATA to your own callback function, FUNC. If SEARCH_PATH is
1 'NULL', then search all of the standard locations that 'lt_dlopen'
1 would examine. This function will continue to make calls to FUNC
1 for each file that it discovers in SEARCH_PATH until one of these
1 calls returns non-zero, or until the files are exhausted.
1 'lt_dlforeachfile' returns the value returned by the last call made
1 to FUNC.
1
1 For example you could define FUNC to build an ordered "argv"-like
1 vector of files using DATA to hold the address of the start of the
1 vector.
1
1 -- Function: int lt_dlmakeresident (lt_dlhandle HANDLE)
1 Mark a module so that it cannot be 'lt_dlclose'd. This can be
1 useful if a module implements some core functionality in your
1 project that would cause your code to crash if removed. Return 0
1 on success.
1
1 If you use 'lt_dlopen (NULL)' to get a HANDLE for the running
1 binary, that handle will always be marked as resident, and
1 consequently cannot be successfully 'lt_dlclose'd.
1
1 -- Function: int lt_dlisresident (lt_dlhandle HANDLE)
1 Check whether a particular module has been marked as resident,
1 returning 1 if it has or 0 otherwise. If there is an error while
1 executing this function, return -1 and set an error message for
1 retrieval with 'lt_dlerror'.
1
1 ---------- Footnotes ----------
1
1 (1) Some platforms, notably Mac OS X, differentiate between a runtime
1 library that cannot be opened by 'lt_dlopen' and a dynamic module that
1 can. For maximum portability you should try to ensure that you only
1 pass 'lt_dlopen' objects that have been compiled with libtool's
1 '-module' flag.
1