\input texinfo @c -*-texinfo-*-@c %**start of header@setfilename ld.so.info@settitle ld.so : Dynamic-Link Library support@c %**end of header@ifinfoThis file documents the dynamic-link support libraries and utilities for theLinux OS, version 1.8.1.Copyright 1996 Michael DeutschmannThis document is subject to the GNU General Public License as published by the Free Software foundation, version 2 or later (your choice).Note: The software described in this document is under a different copyrightand license.@end ifinfo@titlepage @title ld.so@subtitle Dynamic Link library support for the Linux OS.@author David Engel@author Eric Youngdale@author Peter Macdonald @author Hongjiu Lu @author Mitch D'Souza@author Michael Deutschmann (this documentation)@pageCopyright @copyright{} 1996 Michael DeutschmannThis document is subject to the GNU General Public License as published by the Free Software foundation, version 2 or later (your choice).Note: The software described in this document is under a different copyrightand license.@end titlepage@ifinfo@node Top@topThe @code{ld.so} module provides dynamic linked library support in Linux.This file documents @code{ld.so} and its companion software.@menu* intro::	Introduction* ld.so::	The dynamic linker core program* ldd::		A utility to print out dependencies* ldconfig::	A utility to maintain the cache and symlinks* libdl::	Manual dynamic linking library@end menu@end ifinfo@node intro@unnumbered IntroductionThe @code{ld.so} suite contains special files and utilities needed for linuxto handle @dfn{dynamic libraries}.Ordinary static libraries (@file{lib*.a} files) are included into executablesthat use their functions. A file that only uses static libraries needs lessintelligence to load, but takes up more space. If many executables use thesame library, there can be much wastage of storage space, since multiplecopies of the library functions are scattered across the executables.However, static libraries are easier to make.Dynamic libraries (@file{lib*.so*} files) are not copied into executables ---the executable is written in such a way that it will automatically load thelibraries. In linux, the executable will first load the special library @code{ld.so} or @code{ld-linux.so}, which contains the intelligenceto load further dynamic libraries. Since multiple files end up gettingexecutable data from the same file, dynamic libraries are also known asshared libraries.Linux executables come in two flavors, @sc{elf} and a.out.a.out is the original executable format used by Linux. It has somewhat less overhead than @sc{elf}. However creating shared libraries for a.out is@emph{very} involved, and each a.out shared library must be explicitly registered. @sc{elf} is a more recent format, which supports a much simpler method ofcreating libraries. @sc{elf} libraries may also be linked manually(@pxref{libdl}).Since many library authors prefer @sc{elf} and no longer release shared a.out libraries, a.out is moribund on Linux. This version of the @code{ld.so} canbe compiled to support only @sc{elf}, or to support both formats. (The lastrelease of ld.so to support a.out alone was 1.8.0.)@node ld.so@chapter @code{ld.so}: Dynamic linker core@code{ld.so} works behind the scenes to handle dynamic libraries in Linux.Users will almost never have to deal with it directly, but in special casesone can send instructions to it through environment variables. Also, ifsomething is wrong with your libraries (usually an incorrect version) ld.sowill give error messages.Actually @code{ld.so} is the a.out linker. The new @sc{elf} executables arehandled by a related program @code{ld-linux.so}.@menu* files::	Configuration files used by the suite* environment::	Environment settings that tweak @code{ld.so}* errors::	Complaints @code{ld.so} might make@end menu@node files@section Configuration Files@table @file@item /etc/ld.so.cacheA file created by @code{ldconfig} and used to speed linking. It's structureis private to the suite.@item /etc/ld.so.confA simple list of directories to scan for libraries, in addition to@file{/usr/lib} and @file{/lib}, which are hardwired. It may containcomments started with a @samp{#}.@item /etc/ld.so.preloadA list of libraries to preload. This allows preloading libraries forsetuid/setgid executables securely. It may contain comments. @end table@node environment@section Environment Variables@table @code@item LD_AOUT_LIBRARY_PATH@itemx LD_LIBRARY_PATHThese variables supply a library path for finding dynamic libraries, in thestandard colon seperated format. These variables are ignored when executing setuid/setgid programs, because otherwise they would be a security hazard. @code{ld.so} will use @code{LD_AOUT_LIBRARY_PATH} and @code{ld-linux.so} will use @code{LD_LIBRARY_PATH}.@item LD_AOUT_PRELOAD@itemx LD_PRELOADThese variables allow an extra library not specified in the executable to beloaded. Generally this is only useful if you want to override a function. These are also ignored when running setuid/setgid executables. @code{ld.so} will use @code{LD_AOUT_PRELOAD} and @code{ld-linux.so} will use @code{LD_PRELOAD}.@item LD_NOWARNIf non-empty, errors about incompatible minor revisions are suppressed.@item LD_KEEPDIRIf non-empty, allow executables to specify absolute library names. Thisoption is deprecated.@c FIXME:@c The following are things I noticed in the ld-linux.so source.@c I don't really understand 'em. Could someone help me?@c@c @item LD_BIND_NOW@c This option is used by the @code{ld-linux.so} only. I don't know @c what it does. (I suspect, looking at the code, that it specifies@c "RTLD_NOW" rather than "RTLD_LAZY" mode for the shared libraries.)@c @c @item LD_TRACE_LOADED_OBJECTS@c @itemx LD_WARN@c These seem to have something to do with the communication between the@c @code{ld-linux.so} and @code{ldd}. I don't know more.@end table@node errors@section Errors@table @samp@item Can't find library @var{library}The executable required a dynamically linked library that ld.so cannot find.Your symbolic links may be not set right, or you may have not installed a library needed by the program.@item Can't load library @var{library}The library is corrupt. @item Incompatible library @var{library}@itemx   Require major version @var{x} and found @var{y}Your version of the library is incompatible with the executable. Recompilingthe executable, or upgrading the library will fix the problem.@item using incompatible library @var{library}@itemx   Desire minor version >= @var{x} and found @var{y}.Your version of the library is older than that expected by the executable,but not so old that the library interface has radically changed, so thelinker will attempt to run anyway. There is a chance that it will work, but you should upgrade the library or recompile the software. The environment variable @code{LD_NOWARN} can be used to supress this message.@item too many directories in library pathThe linker only supports up to 32 library directories. You have too many.@item dynamic linker error in @var{blah}The linker is having trouble handling a binary - it is probably corrupt.@item can't map cache file @var{cache-file}@itemx cache file @var{cache-file} @var{blah}The linker cache file (generally @file{/etc/ld.so.cache}) is corrupt ornon-existent. These errors can be ignored, and can be prevented by regenerating the cache file with @code{ldconfig}.@end table@node ldd@chapter @code{ldd}: Dependency scanner@code{ldd} is a utility that prints out the dynamic libraries that anexecutable is linked to. Actually @code{ldd} works by signalling ld.so to print the dependencies. For a.out executables this is done by starting the executable with @code{argc} equal to 0. The linker detects this and prints the dependencies. (This can cause problems with @emph{very} old binaries, which would run as normal only with an inappropriate @code{argc}.)For @sc{elf} executables, special environment variables are used to tell thelinker to print the dependencies.@code{ldd} has a few options:@table @samp@item -vPrint the version number of @code{ldd} itself@item -VPrint the version number of the dynamic linker@item -dReport missing functions. This is only supported for @sc{elf} executables.@item -rReport missing objects. This is also only available for @sc{elf}executables.@end table@node ldconfig@chapter @code{ldconfig}: Setup program This utility is used by the system administrator to automatically set upsymbolic links needed by the libraries, and also to set up the cache file.@code{ldconfig} is run after new dynamic libraries are installed, and if the cache file or links are damaged. It is also run when upgrading the@code{ld.so} suite itself.The @file{/lib} and @file{/usr/lib} directories, and any listed in the file @file{/etc/ld.so.conf} are scanned by default unless @samp{-n} is used.Additional directories may be specified on the command line.It has the following options:@table @samp@item -DEnter debug mode. Implies @samp{-N} and @samp{-X}.@item -vVerbose. Print out links created and directories scanned.@item -n Check directories specified on the commandline @emph{only}.@item -NDo not regenerate the cache.@item -XDo not rebuild symbolic links.@item -lSet up symbolic links for only libraries presented on the command line.@item -pPrint out the library pathnames in the cache file (@file{/etc/ld.so.cache})@end table@node libdl@chapter User dynamic linking libraryThe @code{ld.so} package includes a small library of functions(@code{libdl}) to allow manual dynamic linking. Normally programs are linked so that dynamic functions and objects are automagically available. These functions allow one to manually load and access a symbol from a library. They are only available for @sc{elf} executables.@menu* using libdl::	General points* functions::	How to use the functions* example::	A sample program@end menu@node using libdl@section OverviewTo access this library, add the flag @samp{-ldl} to your compile command whenlinking the executable. You also must include the header file@code{dlfcn.h}. You may also need the flag @samp{-rdynamic}, which enablesresolving references in the loaded libraries against your executable.Generally, you will first use @code{dlopen} to open a library. Then you use@code{dlsym} one or more times to access symbols. Finally you use@code{dlclose} to close the library.These facilities are most useful for language interpreters that provideaccess to external libraries. Without @code{libdl}, it would be neccessaryto link the interpreter executable with any and all external librariesneeded by the programs it runs. With @code{libdl}, the interpreter only needs to be linked with the libraries it uses itself, and can dynamically load in additional ones if programs need it.@node functions@section Functions@deftypefun void *dlopen ( const char @var{filename}, int @var{flags} )This function opens the dynamic library specified by @var{filename}and returns an abstract handle, which can be used in subsequent calls to @code{dlsym}. The function will respect the @code{LD_ELF_LIBRARY_PATH} and@code{LD_LIBRARY_PATH} environment variables.@end deftypefunThe following flags can be used with @code{dlopen}:@deftypevr Macro int RTLD_LAZYResolve symbols in the library as they are needed.@end deftypevr@deftypevr Macro int RTLD_NOWResolve all symbols in the library before returning, and fail if not all canbe resolved. This is mutually exclusive with @code{RTLD_LAZY}.@end deftypevr@deftypevr Macro int RTLD_GLOBALMake symbols in this library available for resolving symbols in otherlibraries loaded with @code{dlopen}.@end deftypevr@deftypefun int dlclose ( void *@var{handle} )This function releases a library handle.Note that if a library opened twice, the handle will be the same. However,a reference count is used, so you should still close the library as many times as you open it.@end deftypefun@deftypefun void *dlsym (void *@var{handle},char *@var{symbol-name})This function looks up the name @var{symbol-name} in the library and returnsit in the void pointer.If there is an error, a null pointer will be returned. However, it ispossible for a valid name in the library to have a null value, so@code{dlerror} should be used to check if there was an error.@end deftypefun@deftypefun {libdl function} {const char} *dlerror( void )This function is used to read the error state. It returns a human-readablestring describing the last error, or null, meaning no error.The function resets the error value each time it is called, so the resultshould be copied into a variable. If the function is called more than onceafter an error, the second and subsequent calls will return null.@end deftypefun@node example@section Example programHere is an example program that prints the cosine of two by manually linkingto the math library: @example@c The following was snarfed verbatim from the dlopen.3 man file.#include <stdio.h>#include <dlfcn.h>int main(int argc, char **argv) @{    void *handle;    double (*cosine)(double);    char *error;    handle = dlopen ("/lib/libm.so", RTLD_LAZY);    if (!handle) @{        fputs (dlerror(), stderr);        exit(1);    @}    cosine = dlsym(handle, "cos");    if ((error = dlerror()) != NULL)  @{        fputs(error, stderr);        exit(1);    @}    printf ("%f\\n", (*cosine)(2.0));    dlclose(handle);@}@end example@contents@bye