Next: , Previous: 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 in order 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 in order 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 (see Link mode).

— Structure: struct lt_dlsymbol { const char *name; void *address; }

The name attribute is a null-terminated character string of the symbol name, such as "fprintf". The address attribute is a generic pointer to the appropriate object, such as &fprintf.

— Structure: struct lt_dlsymlist { const char *originator; const lt_dlsymbol symbols[]; }

The originator attribute is a null-terminated character string, naming the compilation unit that symbols were preloaded on behalf of. This is usually the basename of a library, libltdl.la has a corresponding originator value of ‘libltdl’; if the symbols are for the benefit of the application proper, then originator is ‘@PROGRAM@’, though Libtool takes care of that detail if you use ‘LTDL_SET_PRELOADED_SYMBOLS’.

— Variable: const lt_dlsymlist * lt_preloaded_symbols

An array of lt_symbol structures, representing all the preloaded symbols linked into the program proper. For each module -dlpreopened by the Libtool linked program there is an element with the name of the module and a 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.

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 <ltdl.h>
          
          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.