File: libtool.info,  Node: Dlpreopening,  Next: Linking with dlopened modules,  Prev: Building modules,  Up: Dlopened modules

10.2 Dlpreopening
=================

Libtool provides special support for dlopening libtool object and
libtool library files, so that their symbols can be resolved _even on
platforms without any ‘dlopen’ and ‘dlsym’ functions_.

   Consider the following alternative ways of loading code into your
program, in order of increasing "laziness":

  1. Linking against object files that become part of the program
     executable, whether or not they are referenced.  If an object file
     cannot be found, then the compile time linker refuses to create the
     executable.

  2. Declaring a static library to the linker, so that it is searched at
     link time to satisfy any undefined references in the above object
     files.  If the static library cannot be found, then the compile
     time linker refuses to create the executable.

  3. Declaring a shared library to the runtime linker, so that it is
     searched at runtime to satisfy any undefined references in the
     above files.  If the shared library cannot be found, then the
     dynamic linker aborts the program before it runs.

  4. Dlopening a module, so that the application can resolve its own,
     dynamically-computed references.  If there is an error opening the
     module, or the module is not found, then the application can
     recover without crashing.

   Libtool emulates ‘-dlopen’ on static platforms by linking objects
into the program at compile time, and creating data structures that
represent the program's symbol table.  In order to use this feature, you
must declare the objects you want your application to dlopen by using
the ‘-dlopen’ or ‘-dlpreopen’ flags when you link your program (*note
Link mode::).

 -- Data Type: lt_dlsymlist typedef struct { const char *name;
          void *address; } lt_dlsymlist
     The ‘name’ attribute is a null-terminated character string of the
     symbol name, such as ‘"fprintf"’.  The ‘address’ attribute is
     generic pointer to the appropriate object, such as ‘&fprintf’.

 -- Variable: const lt_dlsymlist lt_preloaded_symbols[]
     An array of ‘lt_dlsymlist’ structures, representing all the
     preloaded symbols linked into the program proper.  For each module
     ‘-dlpreopen’ed by the Libtool linked program there is an element
     with the ‘name’ of the module and an ‘address’ of ‘0’, followed by
     all symbols exported from this file.  For the executable itself the
     special name ‘@PROGRAM@’ is used.  The last element of all has a
     ‘name’ and ‘address’ of ‘0’.

     To facilitate inclusion of symbol lists into libraries,
     ‘lt_preloaded_symbols’ is ‘#define’d to a suitably unique name in
     ‘ltdl.h’.

     This variable may not be declared ‘const’ on some systems due to
     relocation issues.

   Some compilers may allow identifiers that are not valid in ANSI C,
such as dollar signs.  Libtool only recognizes valid ANSI C symbols (an
initial ASCII letter or underscore, followed by zero or more ASCII
letters, digits, and underscores), so non-ANSI symbols will not appear
in ‘lt_preloaded_symbols’.

 -- 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 

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

 -- Function Type: int lt_dlpreload_callback_func (lt_dlhandle HANDLE)
     Functions of this type can be passed to ‘lt_dlpreload_open’, which
     in turn will call back into a function thus passed for each
     preloaded module that it opens.

 -- Function: int lt_dlpreload_open (const char *ORIGINATOR,
          lt_dlpreload_callback_func *FUNC)
     Load all of the preloaded modules for ORIGINATOR.  For every module
     opened in this way, call FUNC.

     To open all of the modules preloaded into ‘libhell.la’ (presumably
     from within the ‘libhell.a’ initialisation code):

          #define preloaded_symbols lt_libhell_LTX_preloaded_symbols

          static int hell_preload_callback (lt_dlhandle handle);

          int
          hell_init (void)
          {
            ...
            if (lt_dlpreload (&preloaded_symbols) == 0)
              {
                lt_dlpreload_open ("libhell", preload_callback);
              }
            ...
          }

     Note that to prevent clashes between multiple preloaded modules,
     the preloaded symbols are accessed via a mangled symbol name: to
     get the symbols preloaded into ‘libhell’, you must prefix
     ‘preloaded_symbols’ with ‘lt_’; the originator name, ‘libhell’ in
     this case; and ‘_LTX_’.  That is,
     ‘lt_libhell_LTX_preloaded_symbols’ here.