libtool: Dlpreopening

1 
1 10.2 Dlpreopening
1 =================
1 
1 Libtool provides special support for dlopening libtool object and
1 libtool library files, so that their symbols can be resolved _even on
1 platforms without any 'dlopen' and 'dlsym' functions_.
1 
1    Consider the following alternative ways of loading code into your
1 program, in order of increasing "laziness":
1 
1   1. Linking against object files that become part of the program
1      executable, whether or not they are referenced.  If an object file
1      cannot be found, then the compile time linker refuses to create the
1      executable.
1 
1   2. Declaring a static library to the linker, so that it is searched at
1      link time to satisfy any undefined references in the above object
1      files.  If the static library cannot be found, then the compile
1      time linker refuses to create the executable.
1 
1   3. Declaring a shared library to the runtime linker, so that it is
1      searched at runtime to satisfy any undefined references in the
1      above files.  If the shared library cannot be found, then the
1      dynamic linker aborts the program before it runs.
1 
1   4. Dlopening a module, so that the application can resolve its own,
1      dynamically-computed references.  If there is an error opening the
1      module, or the module is not found, then the application can
1      recover without crashing.
1 
1    Libtool emulates '-dlopen' on static platforms by linking objects
1 into the program at compile time, and creating data structures that
1 represent the program's symbol table.  In order to use this feature, you
1 must declare the objects you want your application to dlopen by using
11 the '-dlopen' or '-dlpreopen' flags when you link your program (⇒
 Link mode).
1 
1  -- Data Type: lt_dlsymlist typedef struct { const char *NAME; void *ADDRESS;
1           } lt_dlsymlist
1      The NAME attribute is a null-terminated character string of the
1      symbol name, such as '"fprintf"'.  The ADDRESS attribute is a
1      generic pointer to the appropriate object, such as '&fprintf'.
1 
1  -- Variable: const lt_dlsymlist lt_preloaded_symbols[]
1      An array of 'lt_dlsymlist' structures, representing all the
1      preloaded symbols linked into the program proper.  For each module
1      '-dlpreopen'ed by the Libtool linked program there is an element
1      with the NAME of the module and an ADDRESS of '0', followed by all
1      symbols exported from this file.  For the executable itself the
1      special name '@PROGRAM@' is used.  The last element of all has a
1      NAME and ADDRESS of '0'.
1 
1      To facilitate inclusion of symbol lists into libraries,
1      'lt_preloaded_symbols' is '#define'd to a suitably unique name in
1      'ltdl.h'.
1 
1      This variable may not be declared 'const' on some systems due to
1      relocation issues.
1 
1    Some compilers may allow identifiers that are not valid in ANSI C,
1 such as dollar signs.  Libtool only recognizes valid ANSI C symbols (an
1 initial ASCII letter or underscore, followed by zero or more ASCII
1 letters, digits, and underscores), so non-ANSI symbols will not appear
1 in 'lt_preloaded_symbols'.
1 
1  -- Function: int lt_dlpreload (const lt_dlsymlist *PRELOADED)
1      Register the list of preloaded modules PRELOADED.  If PRELOADED is
1      'NULL', then all previously registered symbol lists, except the
1      list set by 'lt_dlpreload_default', are deleted.  Return 0 on
1      success.
1 
1  -- Function: int lt_dlpreload_default (const lt_dlsymlist *PRELOADED)
1      Set the default list of preloaded modules to PRELOADED, which won't
1      be deleted by 'lt_dlpreload'.  Note that this function does _not_
1      require libltdl to be initialized using 'lt_dlinit' and can be used
1      in the program to register the default preloaded modules.  Instead
1      of calling this function directly, most programs will use the macro
1      'LTDL_SET_PRELOADED_SYMBOLS'.
1 
1      Return 0 on success.
1 
1  -- Macro: LTDL_SET_PRELOADED_SYMBOLS
1      Set the default list of preloaded symbols.  Should be used in your
1      program to initialize libltdl's list of preloaded modules.
1 
1           #include <ltdl.h>
1 
1           int main() {
1             /* ... */
1             LTDL_SET_PRELOADED_SYMBOLS();
1             /* ... */
1           }
1 
1  -- Function Type: int lt_dlpreload_callback_func (lt_dlhandle HANDLE)
1      Functions of this type can be passed to 'lt_dlpreload_open', which
1      in turn will call back into a function thus passed for each
1      preloaded module that it opens.
1 
1  -- Function: int lt_dlpreload_open (const char *ORIGINATOR, lt_dlpreload_callback_func *FUNC)
1      Load all of the preloaded modules for ORIGINATOR.  For every module
1      opened in this way, call FUNC.
1 
1      To open all of the modules preloaded into 'libhell.la' (presumably
1      from within the 'libhell.a' initialisation code):
1 
1           #define preloaded_symbols lt_libhell_LTX_preloaded_symbols
1 
1           static int hell_preload_callback (lt_dlhandle handle);
1 
1           int
1           hell_init (void)
1           {
1             ...
1             if (lt_dlpreload (&preloaded_symbols) == 0)
1               {
1                 lt_dlpreload_open ("libhell", preload_callback);
1               }
1             ...
1           }
1 
1      Note that to prevent clashes between multiple preloaded modules,
1      the preloaded symbols are accessed via a mangled symbol name: to
1      get the symbols preloaded into 'libhell', you must prefix
1      'preloaded_symbols' with 'lt_'; the originator name, 'libhell' in
1      this case; and '_LTX_'.  That is,
1      'lt_libhell_LTX_preloaded_symbols' here.
1