characters <SAMP>`_LTX_'</SAMP>.  The module name part of this prefix iscanonicalized by replacing all non-alphanumeric characters with anunderscore.  If that fails, <CODE>lt_dlsym</CODE> resorts to the unadornedsymbol name, which is how <SAMP>`run'</SAMP> was found in<TT>`simple-module.la'</TT> by <TT>`ltdl-loader'</TT> earlier.</P><P>Supporting this feature in your module loading code is a simple matterof initialising the address lookup table, and <TT>`ltdl.h'</TT> defines aconvenient macro to do exactly that:</P><P><A NAME="IDX36"></A><DL><DT><U>Macro:</U> <B>LTDL_SET_PRELOADED_SYMBOLS</B> <I>()</I><DD>Add this macro to the code of your module loading code, before the firstcall to a libltdl function, to ensure that the dlopen addresslookup table is populated.</DL></P><P>Now change the contents of <TT>`ltdl-loader.c'</TT>, and add a call to thismacro, so that it looks like this:</P><P><TABLE width=100%><tr><td>&nbsp;</td><td class=example bgcolor=#6688aa><br><pre>  /* Initialise preloaded symbol lookup table. */  LTDL_SET_PRELOADED_SYMBOLS();  /* Initialise libltdl. */  errors = lt_dlinit ();</pre></td></tr></table></P><P>Libtool will now be able to fall back to using preloaded static modulesif you tell it to, or if the host platform doesn't support native dynamicloading.</P><P><BLOCKQUOTE>If you use <SAMP>`LTDL_SET_PRELOADED_SYMBOLS'</SAMP> in your module loader, you<STRONG>must</STRONG> also specify something to preload to avoid compilationfailure due to undefined <SAMP>`lt_preloaded_symbols'</SAMP>.  You can namemodules on the Libtool link command line using one of <SAMP>`-dlopen'</SAMP>or <SAMP>`-dlpreopen'</SAMP>.  This includes support for accessing the symbolsof the main executable opened with <SAMP>`lt_dlopen(NULL)'</SAMP>---you can askLibtool to fall back to preopening the main modules like this:<P><TABLE width=100%><tr><td>&nbsp;</td><td class=example bgcolor=#6688aa><br><pre>$ libtool gcc -g -o ltdl-loader -dlopen self -rpath /tmp/lib \ltdl-loader.c -lltdlrm -f .libs/ltdl-loader.nm .libs/ltdl-loader.nmS \.libs/ltdl-loader.nmTcreating .libs/ltdl-loaderS.c(cd .libs &#38;&#38; gcc -c -fno-builtin -fno-rtti -fno-exceptions"ltdl-loaderS.c")rm -f .libs/ltdl-loaderS.c .libs/ltdl-loader.nm .libs/ltdl-loader.nmS.libs/ltdl-loader.nmTgcc -o ltdl-loader .libs/ltdl-loaderS.o ltdl-loader.c-Wl,--export-dynamic  /usr/lib/libltdl.so -ldl -Wl,--rpath -Wl,/tmp/librm -f .libs/ltdl-loaderS.o</pre></td></tr></table></P><P>It doesn't make sense to add preloaded module support to a project, whenyou have no modules to preopen, so the compilation failure in that caseis actually a feature of sorts.</BLOCKQUOTE><P>The <SAMP>`LTDL_SET_PRELOADED_SYMBOLS'</SAMP> macro does not interfere with thenormal operation of the code when modules are dynamically loaded,provided you use the <SAMP>`-dlopen'</SAMP> option on the link line.  Theadvantage of referencing the macro by default is that you can recompilethe application with or without preloaded module, and all withoutediting the sources.</P><P>If you have no modules to link in by default, you can force Libtool topopulate the preload symbol table by using the <SAMP>`-dlopen force'</SAMP>option.  This is the option used to preload the symbols of the mainexecutable so that you can subsequently call <SAMP>`lt_dlopen(NULL)'</SAMP>.</P><P>Multiple modules can be preloaded, although at the time of writing onlyLibtool compiled modules can be used.  If there is a demand, Libtool willbe extended to include native library preloading in a future revision.</P><P>To illustrate, I have recompiled the <TT>`simple-module.c'</TT> module with<CODE>libtool</CODE>:</P><P><TABLE width=100%><tr><td>&nbsp;</td><td class=example bgcolor=#6688aa><br><pre>$ libtool --mode=compile gcc -c simple-module.crm -f .libs/simple-module.logcc -c simple-module.c  -fPIC -DPIC -o .libs/simple-module.logcc -c simple-module.c -o simple-module.o &#62;/dev/null 2&#62;&#38;1mv -f .libs/simple-module.lo simple-module.lo$ libtool --mode=link gcc -g -o simple-module.la -rpath `pwd`-no-undefined -module -avoid-version simple-module.lorm -fr .libs/simple-module.la .libs/simple-module.*.libs/simple-module.*gcc -shared  simple-module.lo  -lc  -Wl,-soname \-Wl,simple-module.so -o .libs/simple-module.soar cru .libs/simple-module.a  simple-module.ocreating simple-module.la(cd .libs &#38;&#38; rm -f simple-module.la &#38;&#38; ln -s ../simple-module.la \simple-module.la)</pre></td></tr></table></P><P>The names of the modules that may be subsequently <CODE>lt_dlopen</CODE>ed areadded to the application link line.  I am using the <SAMP>`-static'</SAMP>option to force a static only link, which must use dlpreopened modulesby definition.  I am only specifying this because my host has nativedynamic loading, and Libtool will use that unless I force a static onlylink, like this:</P><P><TABLE width=100%><tr><td>&nbsp;</td><td class=example bgcolor=#6688aa><br><pre>$ libtool --mode=link gcc -static -g -o ltdl-loader ltdl-loader.c \-lltdl -dlopen ltdl-module.la -dlopen simple-module.larm -f .libs/ltdl-loader.nm .libs/ltdl-loader.nmS \.libs/ltdl-loader.nmTcreating .libs/ltdl-loaderS.cextracting global C symbols from ./.libs/ltdl-module.aextracting global C symbols from ./.libs/simple-module.a(cd .libs &#38;&#38; gcc -c -fno-builtin -fno-rtti -fno-exceptions \"ltdl-loaderS.c")rm -f .libs/ltdl-loaderS.c .libs/ltdl-loader.nm \.libs/ltdl-loader.nmS .libs/ltdl-loader.nmTgcc -g -o ltdl-loader ltdl-loader.c .libs/ltdl-loaderS.o \./.libs/ltdl-module.a -lm ./.libs/simple-module.a \/usr/lib/libltdl.a -ldlrm -f .libs/ltdl-loaderS.o$ ./ltdl-loader ltdl-module 345Square root of 345 is 18.574176        =&#62; 0$ ./ltdl-loader simple-module WorldHello, World!        =&#62; 0</pre></td></tr></table></P><P>Note that the current release of Libtool requires that thepseudo-library be present for any libltdl loaded module, evenpreloaded ones.  Once again, if there is sufficient demand, this may befixed in a future release. Until then, if the pseudo-library was deletedor cannot be found, this will happen: </P><P><TABLE width=100%><tr><td>&nbsp;</td><td class=example bgcolor=#6688aa><br><pre>$ rm -f simple-module.la$ ./ltdl-loader simple-module World./ltdl-loader: file not found.</pre></td></tr></table></P><P>A side effect of using the <SAMP>`LTDL_SET_PRELOADED_SYMBOLS'</SAMP> macro isthat if you subsequently link the application without Libtool, you willget an undefined symbol for the Libtool supplied<SAMP>`lt_preloaded_symbols'</SAMP>.  If you need to link in this fashion, youwill need to provide a stub that supplies the missing definition.Conversely, you must be careful not to link the stub file when you<EM>do</EM> link with Libtool, because it will clash with the Libtoolgenerated table it is supposed to replace: </P><P><TABLE width=100%><tr><td>&nbsp;</td><td class=example bgcolor=#6688aa><br><pre>#include &#60;ltdl.h&#62;const lt_dlsymlist lt_preloaded_symbols[] = { { 0, 0 } };</pre></td></tr></table></P><P>Of course, if you use this stub, and link the application without thebenefits of Libtool, you will not be able to use any preloaded modules-- even if you statically link them, since there is no preloaded symbollookup table in this case.</P><P><A NAME="User Module Loaders"></A></TR></TABLE><BR>  <FONT SIZE="-1">This document was generatedby <I>Gary V. Vaughan</I> on <I>September, 12  2004</I>using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html"><I>texi2html</I></A></BODY></HTML>