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