1 \input texinfo @c -*-texinfo-*-
3 @setfilename ld.so.info
4 @settitle ld.so : Dynamic-Link Library support
8 This file documents the dynamic-link support libraries and utilities for the
9 Linux OS, version 1.8.1.
11 Copyright 1996 Michael Deutschmann
13 This document is subject to the GNU General Public License as published by
14 the Free Software foundation, version 2 or later (your choice).
16 Note: The software described in this document is under a different copyright
23 @subtitle Dynamic Link library support for the Linux OS.
25 @author Eric Youngdale
26 @author Peter Macdonald
29 @author Michael Deutschmann (this documentation)
32 Copyright @copyright{} 1996 Michael Deutschmann
34 This document is subject to the GNU General Public License as published by
35 the Free Software foundation, version 2 or later (your choice).
37 Note: The software described in this document is under a different copyright
45 The @code{ld.so} module provides dynamic linked library support in Linux.
46 This file documents @code{ld.so} and its companion software.
49 * intro:: Introduction
51 * ld.so:: The dynamic linker core program
52 * ldd:: A utility to print out dependencies
53 * ldconfig:: A utility to maintain the cache and symlinks
54 * libdl:: Manual dynamic linking library
60 @unnumbered Introduction
62 The @code{ld.so} suite contains special files and utilities needed for linux
63 to handle @dfn{dynamic libraries}.
65 Ordinary static libraries (@file{lib*.a} files) are included into executables
66 that use their functions. A file that only uses static libraries needs less
67 intelligence to load, but takes up more space. If many executables use the
68 same library, there can be much wastage of storage space, since multiple
69 copies of the library functions are scattered across the executables.
70 However, static libraries are easier to make.
72 Dynamic libraries (@file{lib*.so*} files) are not copied into executables ---
73 the executable is written in such a way that it will automatically load the
74 libraries. In linux, the executable will first load the special library
75 @code{ld.so} or @code{ld-linux.so}, which contains the intelligence
76 to load further dynamic libraries. Since multiple files end up getting
77 executable data from the same file, dynamic libraries are also known as
80 Linux executables come in two flavors, @sc{elf} and a.out.
82 a.out is the original executable format used by Linux. It has somewhat less
83 overhead than @sc{elf}. However creating shared libraries for a.out is
84 @emph{very} involved, and each a.out shared library must be explicitly
87 @sc{elf} is a more recent format, which supports a much simpler method of
88 creating libraries. @sc{elf} libraries may also be linked manually
91 Since many library authors prefer @sc{elf} and no longer release shared a.out
92 libraries, a.out is moribund on Linux. This version of the @code{ld.so} can
93 be compiled to support only @sc{elf}, or to support both formats. (The last
94 release of ld.so to support a.out alone was 1.8.0.)
97 @chapter @code{ld.so}: Dynamic linker core
99 @code{ld.so} works behind the scenes to handle dynamic libraries in Linux.
100 Users will almost never have to deal with it directly, but in special cases
101 one can send instructions to it through environment variables. Also, if
102 something is wrong with your libraries (usually an incorrect version) ld.so
103 will give error messages.
105 Actually @code{ld.so} is the a.out linker. The new @sc{elf} executables are
106 handled by a related program @code{ld-linux.so}.
109 * files:: Configuration files used by the suite
110 * environment:: Environment settings that tweak @code{ld.so}
111 * errors:: Complaints @code{ld.so} might make
115 @section Configuration Files
118 @item /etc/ld.so.cache
119 A file created by @code{ldconfig} and used to speed linking. It's structure
120 is private to the suite.
122 @item /etc/ld.so.conf
123 A simple list of directories to scan for libraries, in addition to
124 @file{/usr/lib} and @file{/lib}, which are hardwired. It may contain
125 comments started with a @samp{#}.
127 @item /etc/ld.so.preload
128 A list of libraries to preload. This allows preloading libraries for
129 setuid/setgid executables securely. It may contain comments.
133 @section Environment Variables
136 @item LD_AOUT_LIBRARY_PATH
137 @itemx LD_LIBRARY_PATH
138 These variables supply a library path for finding dynamic libraries, in the
139 standard colon seperated format. These variables are ignored when executing
140 setuid/setgid programs, because otherwise they would be a security hazard.
141 @code{ld.so} will use @code{LD_AOUT_LIBRARY_PATH} and @code{ld-linux.so} will
142 use @code{LD_LIBRARY_PATH}.
144 @item LD_AOUT_PRELOAD
146 These variables allow an extra library not specified in the executable to be
147 loaded. Generally this is only useful if you want to override a function.
148 These are also ignored when running setuid/setgid executables. @code{ld.so}
149 will use @code{LD_AOUT_PRELOAD} and @code{ld-linux.so} will use
153 If non-empty, errors about incompatible minor revisions are suppressed.
156 If non-empty, allow executables to specify absolute library names. This
157 option is deprecated.
159 @c The following are things I noticed in the ld-linux.so source.
160 @c I don't really understand 'em. Could someone help me?
163 @c This option is used by the @code{ld-linux.so} only. I don't know
164 @c what it does. (I suspect, looking at the code, that it specifies
165 @c "RTLD_NOW" rather than "RTLD_LAZY" mode for the shared libraries.)
167 @c @item LD_TRACE_LOADED_OBJECTS
169 @c These seem to have something to do with the communication between the
170 @c @code{ld-linux.so} and @code{ldd}. I don't know more.
177 @item Can't find library @var{library}
178 The executable required a dynamically linked library that ld.so cannot find.
179 Your symbolic links may be not set right, or you may have not installed a
180 library needed by the program.
182 @item Can't load library @var{library}
183 The library is corrupt.
185 @item Incompatible library @var{library}
186 @itemx Require major version @var{x} and found @var{y}
187 Your version of the library is incompatible with the executable. Recompiling
188 the executable, or upgrading the library will fix the problem.
190 @item using incompatible library @var{library}
191 @itemx Desire minor version >= @var{x} and found @var{y}.
192 Your version of the library is older than that expected by the executable,
193 but not so old that the library interface has radically changed, so the
194 linker will attempt to run anyway. There is a chance that it will work, but
195 you should upgrade the library or recompile the software. The environment
196 variable @code{LD_NOWARN} can be used to supress this message.
198 @item too many directories in library path
199 The linker only supports up to 32 library directories. You have too many.
201 @item dynamic linker error in @var{blah}
202 The linker is having trouble handling a binary - it is probably corrupt.
204 @item can't map cache file @var{cache-file}
205 @itemx cache file @var{cache-file} @var{blah}
206 The linker cache file (generally @file{/etc/ld.so.cache}) is corrupt or
207 non-existent. These errors can be ignored, and can be prevented by
208 regenerating the cache file with @code{ldconfig}.
212 @chapter @code{ldd}: Dependency scanner
214 @code{ldd} is a utility that prints out the dynamic libraries that an
215 executable is linked to.
217 Actually @code{ldd} works by signalling ld.so to print the dependencies.
218 For a.out executables this is done by starting the executable with
219 @code{argc} equal to 0. The linker detects this and prints the dependencies.
220 (This can cause problems with @emph{very} old binaries, which would run as
221 normal only with an inappropriate @code{argc}.)
223 For @sc{elf} executables, special environment variables are used to tell the
224 linker to print the dependencies.
226 @code{ldd} has a few options:
230 Print the version number of @code{ldd} itself
233 Print the version number of the dynamic linker
236 Report missing functions. This is only supported for @sc{elf} executables.
239 Report missing objects. This is also only available for @sc{elf}
244 @chapter @code{ldconfig}: Setup program
246 This utility is used by the system administrator to automatically set up
247 symbolic links needed by the libraries, and also to set up the cache file.
249 @code{ldconfig} is run after new dynamic libraries are installed, and if the
250 cache file or links are damaged. It is also run when upgrading the
251 @code{ld.so} suite itself.
253 The @file{/lib} and @file{/usr/lib} directories, and any listed in the file
254 @file{/etc/ld.so.conf} are scanned by default unless @samp{-n} is used.
255 Additional directories may be specified on the command line.
257 It has the following options:
261 Enter debug mode. Implies @samp{-N} and @samp{-X}.
264 Verbose. Print out links created and directories scanned.
267 Check directories specified on the commandline @emph{only}.
270 Do not regenerate the cache.
273 Do not rebuild symbolic links.
276 Set up symbolic links for only libraries presented on the command line.
279 Print out the library pathnames in the cache file (@file{/etc/ld.so.cache})
283 @chapter User dynamic linking library
285 The @code{ld.so} package includes a small library of functions
286 (@code{libdl}) to allow manual dynamic linking. Normally programs are linked
287 so that dynamic functions and objects are automagically available. These
288 functions allow one to manually load and access a symbol from a library.
289 They are only available for @sc{elf} executables.
292 * using libdl:: General points
293 * functions:: How to use the functions
294 * example:: A sample program
300 To access this library, add the flag @samp{-ldl} to your compile command when
301 linking the executable. You also must include the header file
302 @code{dlfcn.h}. You may also need the flag @samp{-rdynamic}, which enables
303 resolving references in the loaded libraries against your executable.
305 Generally, you will first use @code{dlopen} to open a library. Then you use
306 @code{dlsym} one or more times to access symbols. Finally you use
307 @code{dlclose} to close the library.
309 These facilities are most useful for language interpreters that provide
310 access to external libraries. Without @code{libdl}, it would be neccessary
311 to link the interpreter executable with any and all external libraries
312 needed by the programs it runs. With @code{libdl}, the interpreter only
313 needs to be linked with the libraries it uses itself, and can dynamically
314 load in additional ones if programs need it.
319 @deftypefun void *dlopen ( const char @var{filename}, int @var{flags} )
321 This function opens the dynamic library specified by @var{filename}
322 and returns an abstract handle, which can be used in subsequent calls to
323 @code{dlsym}. The function will respect the @code{LD_ELF_LIBRARY_PATH} and
324 @code{LD_LIBRARY_PATH} environment variables.
328 The following flags can be used with @code{dlopen}:
330 @deftypevr Macro int RTLD_LAZY
331 Resolve symbols in the library as they are needed.
334 @deftypevr Macro int RTLD_NOW
335 Resolve all symbols in the library before returning, and fail if not all can
336 be resolved. This is mutually exclusive with @code{RTLD_LAZY}.
339 @deftypevr Macro int RTLD_GLOBAL
340 Make symbols in this library available for resolving symbols in other
341 libraries loaded with @code{dlopen}.
344 @deftypefun int dlclose ( void *@var{handle} )
346 This function releases a library handle.
348 Note that if a library opened twice, the handle will be the same. However,
349 a reference count is used, so you should still close the library as many
350 times as you open it.
354 @deftypefun void *dlsym (void *@var{handle},char *@var{symbol-name})
356 This function looks up the name @var{symbol-name} in the library and returns
357 it in the void pointer.
359 If there is an error, a null pointer will be returned. However, it is
360 possible for a valid name in the library to have a null value, so
361 @code{dlerror} should be used to check if there was an error.
365 @deftypefun {libdl function} {const char} *dlerror( void )
367 This function is used to read the error state. It returns a human-readable
368 string describing the last error, or null, meaning no error.
370 The function resets the error value each time it is called, so the result
371 should be copied into a variable. If the function is called more than once
372 after an error, the second and subsequent calls will return null.
377 @section Example program
379 Here is an example program that prints the cosine of two by manually linking
383 @c The following was snarfed verbatim from the dlopen.3 man file.
387 int main(int argc, char **argv) @{
389 double (*cosine)(double);
392 handle = dlopen ("/lib/libm.so", RTLD_LAZY);
394 fputs (dlerror(), stderr);
398 cosine = dlsym(handle, "cos");
399 if ((error = dlerror()) != NULL) @{
400 fputs(error, stderr);
404 printf ("%f\\n", (*cosine)(2.0));