DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

(libtool14.info.gz) Libltdl interface

Info Catalog (libtool14.info.gz) Using libltdl (libtool14.info.gz) Modules for libltdl
 
 10.1 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  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'.
 
Info Catalog (libtool14.info.gz) Using libltdl (libtool14.info.gz) Modules for libltdl
automatically generated byinfo2html