9. Dlopened modules

It can sometimes be confusing to discuss dynamic linking, because the term is used to refer to two different concepts:

1. Compiling and linking a program against a shared library, which is resolved automatically at run time by the dynamic linker. In this process, dynamic linking is transparent to the application.

2. The application calling functions such as dlopen,(7) which load arbitrary, user-specified modules at runtime. This type of dynamic linking is explicitly controlled by the application.

To mitigate confusion, this manual refers to the second type of dynamic linking as dlopening a module.

The main benefit to dlopening object modules is the ability to access compiled object code to extend your program, rather than using an interpreted language. In fact, dlopen calls are frequently used in language interpreters to provide an efficient way to extend the language.

As of version 1.4.2, libtool provides support for dlopened modules. However, you should indicate that your package is willing to use such support, by using the macro `AC_LIBTOOL_DLOPEN' in `configure.in'. If this macro is not used (or it is used after `AC_PROG_LIBTOOL'), libtool will assume no dlopening mechanism is available, and will try to simulate it.

This chapter discusses how you as a dlopen application developer might use libtool to generate dlopen-accessible modules.

9.1 Building modules to dlopen		Creating dlopenable objects and libraries.
9.2 Dlpreopening		Dlopening that works on static platforms.
9.3 Finding the correct name to dlopen		Choosing the right file to dlopen.
9.4 Unresolved dlopen issues		Unresolved problems that need your attention.

9.1 Building modules to dlopen

On some operating systems, a program symbol must be specially declared in order to be dynamically resolved with the dlsym (or equivalent) function.

Libtool provides the `-export-dynamic' and `-module' link flags (see section 4.2 Link mode), which do this declaration. You need to use these flags if you are linking an application program that dlopens other modules or a libtool library that will also be dlopened.

For example, if we wanted to build a shared library, `libhello', that would later be dlopened by an application, we would add `-module' to the other link flags:

burger$ libtool gcc -module -o libhello.la foo.lo \ hello.lo -rpath /usr/local/lib -lm burger$

If symbols from your executable are needed to satisfy unresolved references in a library you want to dlopen you will have to use the flag `-export-dynamic'. You should use `-export-dynamic' while linking the executable that calls dlopen:

burger$ libtool gcc -export-dynamic -o hell-dlopener main.o burger$

9.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 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 linker refuses to link 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 section 4.2 Link mode).

Structure: struct lt_dlsymlist { const char *name; lt_ptr 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.

Variable: const lt_dlsymlist * lt_preloaded_symbols

An array of lt_symbol structures, representing all the preloaded symbols linked into the program. For each `-dlpreloaded' file there is an element with the name of the file 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 has a name and address of 0.

Some compilers may allow identifiers which 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.

9.3 Finding the correct name to dlopen

After a library has been linked with `-module', it can be dlopened. Unfortunately, because of the variation in library names, your package needs to determine the correct file to dlopen.

The most straightforward and flexible implementation is to determine the name at runtime, by finding the installed `.la' file, and searching it for the following lines:

# The name that we can dlopen. dlname='dlname'

If dlname is empty, then the library cannot be dlopened. Otherwise, it gives the dlname of the library. So, if the library was installed as `/usr/local/lib/libhello.la', and the dlname was `libhello.so.3', then `/usr/local/lib/libhello.so.3' should be dlopened.

If your program uses this approach, then it should search the directories listed in the LD_LIBRARY_PATH(8) environment variable, as well as the directory where libraries will eventually be installed. Searching this variable (or equivalent) will guarantee that your program can find its dlopened modules, even before installation, provided you have linked them using libtool.

9.4 Unresolved dlopen issues

The following problems are not solved by using libtool's dlopen support:

• Dlopen functions are generally only available on shared library platforms. If you want your package to be portable to static platforms, you have to use either libltdl (see section 10. Using libltdl) or develop your own alternatives to dlopening dynamic code. Most reasonable solutions involve writing wrapper functions for the dlopen family, which do package-specific tricks when dlopening is unsupported or not available on a given platform.

• There are major differences in implementations of the dlopen family of functions. Some platforms do not even use the same function names (notably HP-UX, with its shl_load family).

• The application developer must write a custom search function in order to discover the correct module filename to supply to dlopen.