18.1 Introducing libltdl
Probably the best known and supported Unix run time linking API is
the `dlopen' interface, used by Solaris and GNU/Linux amongst
others, and discussed earlier in 17. Dynamic Loading. libltdl
is based on the `dlopen' API, with a few small differences and
The following libltdl API functions are declared in
- Function: lt_dlhandle lt_dlopen (const char *filename)
- This function brings the code from a named module into the address space
of the running program that calls it, and returns a handle which is used
by the other API functions. If filename is not an absolute
path, libltdl will search for it in directories named in the
`LTDL_LIBRARY_PATH' environment variable, and then in the standard
library directories before giving up. It is safe to call this
function many times, libltdl will keep track of the number of calls
made, but will require the same number of calls to `lt_dlclose'
to actually unload the module.
- Function: lt_ptr_t lt_dlsym (lt_dlhandle handle, const char *name)
- Returns the address of the named symbol in the module which returned
handle when it was
lt_dlopened. You must cast the returned
address to a known type before using it.
- Function: int lt_dlclose (lt_dlhandle handle)
- When you are finished with a particular module, it can be removed from
memory using this function.
- Function: const char * lt_dlerror (void)
- If any of the libltdl API calls fail, this function returns
a string which describes the last error that occurred.
In order to use these functions, you must
#include <ltdl.h> for
the function prototypes, and link with `-lltdl' to provide the
API implementation. Assuming you link your application with
libtool, and that you call the necessary macros from your
`configure.in' (see section 18.2 Using libltdl), then any host specific
dependent libraries (for example, `libdl' on GNU/Linux) will
automatically be added to the final link line by
You don't limit yourself to using only Libtool compiled modules when you
use libltdl. By writing the module loader carefully, it will be able to
load native modules too--although you will not be able to preload
non-Libtool modules (see section 18.4 dlpreopen Loading. The loader in
Module Loader is written in this way. It
is useful to be able to load modules flexibly like this, because you
don't tie your users into using Libtool for any modules they write.
Compare the descriptions of the functions above with the API
described in 17.2 Module Access Functions. You will notice that they
are very similar.
Back-linking is the process of resolving any remaining symbols by
referencing back into the application that loads the library at runtime
-- a mechanism implemented on almost all modern Unices.
For instance, your main application may provide some utility function,
`my_function', which you want a module to have access to. There are
two ways to do that:
You could use Libtool to link your application, using the
`-export-dynamic' option to ensure that the global application
symbols are available to modules. When libltdl loads a module into an
application compiled like this, it will back-link symbols from the
application to resolve any otherwise undefined symbols in a module.
When the module is `ltdlopen'ed, libltdl will arrange for
calls to `my_function' in the module, to execute the
`my_function' implementation in the application.
If you have need of this functionality, relying on back-linking is the
simplest way to achieve it. Unfortunately, this simplicity is at the
expense of portability: some platforms have no support for
back-linking at all, and others will not allow a module to be created
with unresolved symbols. Never-the-less, libltdl allows you to do this
if you want to.
You could split the code that implements the symbols you need to share
with modules into a separate library. This library would then be used
to resolve the symbols you wish to share, by linking it into modules and
application alike. The definition of `my_function' would be
compiled separately into a library, `libmy_function.la'.
References to `my_function' from the application would be resolved
by linking it with `libmy_function.la', and the library would be
installed so that modules which need to call `my_function' would be
able to resolve the symbol by linking with `-lmy_function'.
This method requires support for neither back-linking nor unresolved
link time symbols from the host platform. The disadvantage is that when
you realise you need this functionality, it may be quite complicated to
extract the shared functionality from the application to be compiled in
a stand alone library.
On those platforms which support back-linking, libltdl can
be configured to resolve external symbol references in a dynamic module
with any global symbols already present in the main application.
This has two implications for the libltdl API:
There is no need to pass `RTLD_GLOBAL' (or equivalent) to
lt_dlopen as might be necessary with the native module loading
You should be aware that your application will not work on some
platforms--most notably, Windows and AIX---if you rely on
Similarly, there is no need to specify whether the module should be
integrated into the application core before
lt_dlopen returns, or
else when the symbols it provides are first referenced. libltdl
will use lazy loading if it is supported, since this is a slight
performance enhancement, or else fall back to loading everything
immediately. Between this feature and the support of back-linking,
there is no need to pass flags into
lt_dlopen as there is with
There are a couple of other important API functions which you will
need when using libltdl:
- Function: int lt_dlinit (void)
- You must call this function to initialise libltdl before calling
any of the other libltdl API functions. It is safe to call this
function many times, libltdl will keep track of the number of calls
made, but will require the same number of calls to `lt_dlexit'
to actually recycle the library resources. If you don't call
`lt_dlinit' before any other API call, the other calls,
including `lt_dlerror', will return their respective failure codes
(`NULL' or `1', as appropriate).
- Function: int lt_dlexit (void)
- When you are done with libltdl and all dynamic modules have been
unloaded you can call this function to finalise the library, and recycle
its resources. If you forget to unload any modules, the call to
`lt_dlexit' will `lt_dlclose' them for you.
Another useful departure that the libltdl API makes from a
dlopen implementation is that it also will work correctly
with old K&R C compilers, by virtue of not relying on `void *'
pointers. libltdl uses
lt_dlhandles to pass references to
loaded modules, and this also improves ANSI C compiler's type
checking compared to the untyped addresses typically used by native