From 66f269d2a51dae6a2cb10f1a9ae4aaeba815219b Mon Sep 17 00:00:00 2001 From: Eric Andersen Date: Mon, 23 Apr 2001 17:43:54 +0000 Subject: Initial checkin for ld.so. This is a combination of effort from Manuel Novoa III and me. I've been working on stripping out arch dependant stuff and replacing it with generic stuff whenever possible. -Erik --- ldso/man/Makefile | 11 ++ ldso/man/dlopen.3 | 218 ++++++++++++++++++++++++++++ ldso/man/ld.so.8 | 113 +++++++++++++++ ldso/man/ld.so.texi | 411 ++++++++++++++++++++++++++++++++++++++++++++++++++++ ldso/man/ldconfig.8 | 189 ++++++++++++++++++++++++ ldso/man/ldd.1 | 59 ++++++++ 6 files changed, 1001 insertions(+) create mode 100644 ldso/man/Makefile create mode 100644 ldso/man/dlopen.3 create mode 100644 ldso/man/ld.so.8 create mode 100644 ldso/man/ld.so.texi create mode 100644 ldso/man/ldconfig.8 create mode 100644 ldso/man/ldd.1 (limited to 'ldso/man') diff --git a/ldso/man/Makefile b/ldso/man/Makefile new file mode 100644 index 000000000..a701e1513 --- /dev/null +++ b/ldso/man/Makefile @@ -0,0 +1,11 @@ +include ../Config.mk + +ALL = #ld.so.info + +all: $(ALL) + +ld.so.info: ld.so.texi + makeinfo $< + +clean: + rm -f $(ALL) *~ diff --git a/ldso/man/dlopen.3 b/ldso/man/dlopen.3 new file mode 100644 index 000000000..8d1e09e71 --- /dev/null +++ b/ldso/man/dlopen.3 @@ -0,0 +1,218 @@ +.\" -*- nroff -*- +.\" Copyright 1995 Yggdrasil Computing, Incorporated. +.\" written by Adam J. Richter (adam@yggdrasil.com), +.\" with typesetting help from Daniel Quinlan (quinlan@yggdrasil.com). +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public +.\" License along with this manual; if not, write to the Free +.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, +.\" USA. +.\" +.TH DLOPEN 3 "16 May 1995" "Linux" "Linux Programmer's Manual" +.SH NAME +dlclose, dlerror, dlopen, dlsym \- Programming interface to dynamic linking loader. +.SH SYNOPSIS +.B #include +.sp +.BI "void *dlopen (const char *" "filename" ", int " flag "); +.br +.BI "const char *dlerror(void);" +.br +.BI "void *dlsym(void *"handle ", char *"symbol ");" +.br +.BI "int dladdr(void *"address ", Dl_info *"dlip ");" +.br +.BI "int dlclose (void *"handle "); +.sp +Special symbols: +.BR "_init" ", " "_fini" ". " +.SH DESCRIPTION +.B dlopen +loads a dynamic library from the file named by the null terminated +string +.I filename +and returns an opaque "handle" for the dynamic library. +If +.I filename +is not an absolute path (i.e., it does not begin with a "/"), then the +file is searched for in the following locations: +.RS +.PP +A colon-separated list of directories in the user's +\fBLD_LIBRARY\fP path environment variable. +.PP +The list of libraries specified in \fI/etc/ld.so.cache\fP. +.PP +\fI/usr/lib\fP, followed by \fI/lib\fP. +.RE +.PP +If +.I filename +is a NULL pointer, then the returned handle is for the main program. +.PP +External references in the library are resolved using the libraries +in that library's dependency list and any other libraries previously +opened with the +.B RTLD_GLOBAL +flag. +If the executable was linked +with the flag "-rdynamic", then the global symbols in the executable +will also be used to resolve references in a dynamically loaded +library. +.PP +.I flag +must be either +.BR RTLD_LAZY , +meaning resolve undefined symbols as code from the dynamic library is +executed, or +.BR RTLD_NOW , +meaning resolve all undefined symbols before +.B dlopen +returns, and fail if this cannot be done. +Optionally, +.B RTLD_GLOBAL +may be or'ed with +.IR flag, +in which case the external symbols defined in the library will be +made available to subsequently loaded libraries. +.PP +If the library exports a routine named +.BR _init , +then that code is executed before dlopen returns. +If the same library is loaded twice with +.BR dlopen() , +the same file handle is returned. The dl library maintains link +counts for dynamic file handles, so a dynamic library is not +deallocated until +.B dlclose +has been called on it as many times as +.B dlopen +has succeeded on it. +.PP +If +.B dlopen +fails for any reason, it returns NULL. +A human readable string describing the most recent error that occurred +from any of the dl routines (dlopen, dlsym or dlclose) can be +extracted with +.BR dlerror() . +.B dlerror +returns NULL if no errors have occurred since initialization or since +it was last called. (Calling +.B dlerror() +twice consecutively, will always result in the second call returning +NULL.) + +.B dlsym +takes a "handle" of a dynamic library returned by dlopen and the null +terminated symbol name, returning the address where that symbol is +loaded. If the symbol is not found, +.B dlsym +returns NULL; however, the correct way to test for an error from +.B dlsym +is to save the result of +.B dlerror +into a variable, and then check if saved value is not NULL. +This is because the value of the symbol could actually be NULL. +It is also necessary to save the results of +.B dlerror +into a variable because if +.B dlerror +is called again, it will return NULL. +.PP +.B dladdr +returns information about the shared library containing the memory +location specified by +.IR address . +.B dladdr +returns zero on success and non-zero on error. +.PP +.B dlclose +decrements the reference count on the dynamic library handle +.IR handle . +If the reference count drops to zero and no other loaded libraries use +symbols in it, then the dynamic library is unloaded. If the dynamic +library exports a routine named +.BR _fini , +then that routine is called just before the library is unloaded. +.SH EXAMPLES +.B Load the math library, and print the cosine of 2.0: +.RS +.nf +.if t .ft CW +#include + +int main(int argc, char **argv) { + void *handle = dlopen ("/lib/libm.so", RTLD_LAZY); + double (*cosine)(double) = dlsym(handle, "cos"); + printf ("%f\\n", (*cosine)(2.0)); + dlclose(handle); +} +.if t .ft P +.fi +.PP +If this program were in a file named "foo.c", you would build the program +with the following command: +.RS +.LP +gcc -rdynamic -o foo foo.c -ldl +.RE +.RE +.LP +.B Do the same thing, but check for errors at every step: +.RS +.nf +.if t .ft CW +#include +#include + +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); +} +.if t .ft P +.fi +.RE +.SH ACKNOWLEDGEMENTS +The dlopen interface standard comes from Solaris. +The Linux dlopen implementation was primarily written by +Eric Youngdale with help from Mitch D'Souza, David Engel, +Hongjiu Lu, Andreas Schwab and others. +The manual page was written by Adam Richter. +.SH SEE ALSO +.BR ld(1) , +.BR ld.so(8) , +.BR ldconfig(8) , +.BR ldd(1) , +.BR ld.so.info . diff --git a/ldso/man/ld.so.8 b/ldso/man/ld.so.8 new file mode 100644 index 000000000..59ec8530d --- /dev/null +++ b/ldso/man/ld.so.8 @@ -0,0 +1,113 @@ +.TH ld.so 8 "14 March 1998" +.SH NAME +ld.so/ld-linux.so \- dynamic linker/loader +.SH DESCRIPTION +.B ld.so +loads the shared libraries needed by a program, prepares the program +to run, and then runs it. +Unless explicitly specified via the +.B \-static +option to +.B ld +during compilation, all Linux programs are incomplete and require +further linking at run time. +.PP +The necessary shared libraries needed by the program are searched for +in the following order +.IP o +Using the environment variable +.B LD_LIBRARY_PATH +.RB ( LD_AOUT_LIBRARY_PATH +for a.out programs). +Except if the executable is a setuid/setgid binary, in which case it +is ignored. +.IP o +From the cache file +.BR /etc/ld.so.cache +which contains a compiled list of candidate libraries previously found +in the augmented library path. +.IP o +In the default path +.BR /usr/lib , +and then +.BR /lib . +.SH ENVIRONMENT +.TP +.B LD_LIBRARY_PATH +A colon-separated list of directories in which to search for +ELF libraries at execution-time. +Similar to the +.B PATH +environment variable. +.TP +.B LD_PRELOAD +A whitespace-separated list of additional, user-specified, ELF shared +libraries to be loaded before all others. +This can be used to selectively override functions in other shared libraries. +For setuid/setgid ELF binaries, only libraries in the standard search +directories that are also setgid will be loaded. +.TP +.B LD_TRACE_LOADED_OBJECTS +If present, causes the program to list its dynamic library dependencies, +as if run by ldd, instead of running normally. +.TP +.B LD_BIND_NOW +If present, causes the dynamic linker to resolve all symbols at program +startup instead of when they are first referenced. +.TP +.B LD_AOUT_LIBRARY_PATH +A colon-separated list of directories in which to search for +a.out libraries at execution-time. +Similar to the +.B PATH +environment variable. +.TP +.B LD_AOUT_PRELOAD +The name of an additional, user-specified, a.out shared library to be loaded +after all others. +This can be used to selectively override functions in other shared libraries. +.TP +.B LD_NOWARN +Suppress warnings about a.out libraries with incompatible minor +version numbers. +.TP +.B LD_KEEPDIR +Don't ignore the directory in the names of a.out libraries to be loaded. +Use of this option is strongly discouraged. +.SH FILES +.PD 0 +.TP 20 +.B /lib/ld.so +a.out dynamic linker/loader +.TP 20 +.B /lib/ld-linux.so.* +ELF dynamic linker/loader +.TP +.B /etc/ld.so.cache +File containing a compiled list of directories in which to search for +libraries and an ordered list of candidate libraries. +.TP +.B /etc/ld.so.preload +File containing a whitespace separated list of ELF shared libraries to +be loaded before the program. +libraries and an ordered list of candidate libraries. +.TP +.B lib*.so* +shared libraries +.PD +.SH SEE ALSO +.BR ldd (1), +.BR ldconfig (8). +.SH BUGS +.LP +Currently +.B ld.so +has no means of unloading and searching for compatible or newer version of +libraries. +.PP +.B ld.so +functionality is only available for executables compiled using libc version +4.4.3 or greater. +.SH AUTHORS +David Engel, Eric Youngdale, Peter MacDonald, Hongjiu Lu, Linus +Torvalds, Lars Wirzenius and Mitch D'Souza (not necessarily in that order). diff --git a/ldso/man/ld.so.texi b/ldso/man/ld.so.texi new file mode 100644 index 000000000..4e5fb841b --- /dev/null +++ b/ldso/man/ld.so.texi @@ -0,0 +1,411 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename ld.so.info +@settitle ld.so : Dynamic-Link Library support +@c %**end of header + +@ifinfo +This file documents the dynamic-link support libraries and utilities for the +Linux OS, version 1.8.1. + +Copyright 1996 Michael Deutschmann + +This 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 copyright +and 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) + +@page +Copyright @copyright{} 1996 Michael Deutschmann + +This 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 copyright +and license. +@end titlepage + +@ifinfo +@node Top +@top + +The @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 Introduction + +The @code{ld.so} suite contains special files and utilities needed for linux +to handle @dfn{dynamic libraries}. + +Ordinary static libraries (@file{lib*.a} files) are included into executables +that use their functions. A file that only uses static libraries needs less +intelligence to load, but takes up more space. If many executables use the +same library, there can be much wastage of storage space, since multiple +copies 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 the +libraries. In linux, the executable will first load the special library +@code{ld.so} or @code{ld-linux.so}, which contains the intelligence +to load further dynamic libraries. Since multiple files end up getting +executable data from the same file, dynamic libraries are also known as +shared 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 of +creating 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} can +be compiled to support only @sc{elf}, or to support both formats. (The last +release 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 cases +one can send instructions to it through environment variables. Also, if +something is wrong with your libraries (usually an incorrect version) ld.so +will give error messages. + +Actually @code{ld.so} is the a.out linker. The new @sc{elf} executables are +handled 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.cache +A file created by @code{ldconfig} and used to speed linking. It's structure +is private to the suite. + +@item /etc/ld.so.conf +A simple list of directories to scan for libraries, in addition to +@file{/usr/lib} and @file{/lib}, which are hardwired. It may contain +comments started with a @samp{#}. + +@item /etc/ld.so.preload +A list of libraries to preload. This allows preloading libraries for +setuid/setgid executables securely. It may contain comments. +@end table + +@node environment +@section Environment Variables + +@table @code +@item LD_AOUT_LIBRARY_PATH +@itemx LD_LIBRARY_PATH +These variables supply a library path for finding dynamic libraries, in the +standard 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_PRELOAD +These variables allow an extra library not specified in the executable to be +loaded. 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_NOWARN +If non-empty, errors about incompatible minor revisions are suppressed. + +@item LD_KEEPDIR +If non-empty, allow executables to specify absolute library names. This +option 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. Recompiling +the 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 the +linker 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 path +The 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 or +non-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 an +executable 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 the +linker to print the dependencies. + +@code{ldd} has a few options: + +@table @samp +@item -v +Print the version number of @code{ldd} itself + +@item -V +Print the version number of the dynamic linker + +@item -d +Report missing functions. This is only supported for @sc{elf} executables. + +@item -r +Report 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 up +symbolic 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 -D +Enter debug mode. Implies @samp{-N} and @samp{-X}. + +@item -v +Verbose. Print out links created and directories scanned. + +@item -n +Check directories specified on the commandline @emph{only}. + +@item -N +Do not regenerate the cache. + +@item -X +Do not rebuild symbolic links. + +@item -l +Set up symbolic links for only libraries presented on the command line. + +@item -p +Print out the library pathnames in the cache file (@file{/etc/ld.so.cache}) +@end table + +@node libdl +@chapter User dynamic linking library + +The @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 Overview + +To access this library, add the flag @samp{-ldl} to your compile command when +linking the executable. You also must include the header file +@code{dlfcn.h}. You may also need the flag @samp{-rdynamic}, which enables +resolving 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 provide +access to external libraries. Without @code{libdl}, it would be neccessary +to link the interpreter executable with any and all external libraries +needed 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 deftypefun + +The following flags can be used with @code{dlopen}: + +@deftypevr Macro int RTLD_LAZY +Resolve symbols in the library as they are needed. +@end deftypevr + +@deftypevr Macro int RTLD_NOW +Resolve all symbols in the library before returning, and fail if not all can +be resolved. This is mutually exclusive with @code{RTLD_LAZY}. +@end deftypevr + +@deftypevr Macro int RTLD_GLOBAL +Make symbols in this library available for resolving symbols in other +libraries 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 returns +it in the void pointer. + +If there is an error, a null pointer will be returned. However, it is +possible 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-readable +string describing the last error, or null, meaning no error. + +The function resets the error value each time it is called, so the result +should be copied into a variable. If the function is called more than once +after an error, the second and subsequent calls will return null. + +@end deftypefun + +@node example +@section Example program + +Here is an example program that prints the cosine of two by manually linking +to the math library: + +@example +@c The following was snarfed verbatim from the dlopen.3 man file. +#include +#include + +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 diff --git a/ldso/man/ldconfig.8 b/ldso/man/ldconfig.8 new file mode 100644 index 000000000..82285291f --- /dev/null +++ b/ldso/man/ldconfig.8 @@ -0,0 +1,189 @@ +.TH ldconfig 8 "14 March 1998" +.SH NAME +ldconfig \- determine run-time link bindings +.SH SYNOPSIS +ldconfig +.RB [ \-DvqnNX ] +.RB [ \-f\ conf ] +.RB [ \-C\ cache ] +.RB [ \-r\ root ] +.IR directory \ ... +.PD 0 +.PP +.PD +ldconfig +.B \-l +.RB [ \-Dvq ] +.IR library \ ... +.PD 0 +.PP +.PD +ldconfig +.B \-p +.SH DESCRIPTION +.B ldconfig +creates the necessary links and cache (for use by the run-time linker, +.IR ld.so ) +to the most recent shared libraries found in the directories specified +on the command line, in the file +.IR /etc/ld.so.conf , +and in the trusted directories +.RI ( /usr/lib +and +.IR /lib ). +.B ldconfig +checks the header and file names of the libraries it encounters when +determining which versions should have their links updated. +.B ldconfig +ignores symbolic links when scanning for libraries. +.PP +.B ldconfig +will attempt to deduce the type of ELF libs (ie. libc5 or libc6/glibc) +based on what C libs if any the library was linked against, therefore when +making dynamic libraries, it is wise to explicitly link against libc (use -lc). +.PP +Some existing libs do not contain enough information to allow the deduction of +their type, therefore the +.IR /etc/ld.so.conf +file format allows the specification of an expected type. This is +.B only +used for those ELF libs which we can not work out. The format +is like this "dirname=TYPE", where type can be libc4, libc5 or libc6. +(This syntax also works on the command line). Spaces are +.B not +allowed. Also see the +.B -p +option. +.PP +Directory names containing an +.B = are no longer legal +unless they also have an expected type specifier. +.PP +.B ldconfig +should normally be run by the super-user as it may require write +permission on some root owned directories and files. +It is normally run automatically at bootup, from /etc/rc, or manually +whenever new DLL's are installed. +.SH OPTIONS +.TP +.B \-D +Debug mode. +Implies +.B \-N +and +.BR \-X . +.TP +.B \-v +Verbose mode. +Print current version number, the name of each directory as it +is scanned and any links that are created. +Overrides quiet mode. +.TP +.B \-q +Quiet mode. +Don't print warnings. +.TP +.B \-n +Only process directories specified on the command line. +Don't process the trusted directories +.RI ( /usr/lib +and +.IR /lib ) +nor those specified in +.IR /etc/ld.so.conf . +Implies +.BR \-N . +.TP +.B \-N +Don't rebuild the cache. +Unless +.B \-X +is also specified, links are still updated. +.TP +.B \-X +Don't update links. +Unless +.B \-N +is also specified, the cache is still rebuilt. +.TP +.B \-f conf +Use +.B conf +instead of +.IR /etc/ld.so.conf . +.TP +.B \-C cache +Use +.B cache +instead of +.IR /etc/ld.so.cache . +.TP +.B \-r root +Change to and use +.B root +as the root directory. +.TP +.B \-l +Library mode. +Manually link individual libraries. +Intended for use by experts only. +.TP +.B \-p +Print the lists of directories and candidate libraries stored in +the current cache. +.SH EXAMPLES +In the bootup file +.I /etc/rc +having the line +.RS + +/sbin/ldconfig -v + +.RE +will set up the correct links for the shared binaries and rebuild +the cache. +.TP +On the command line +.RS + +# /sbin/ldconfig -n /lib + +.RE +as root after the installation of a new DLL, will properly update the +shared library symbolic links in /lib. + +.SH FILES +.PD 0 +.TP 20 +.B /lib/ld.so +execution time linker/loader +.TP 20 +.B /etc/ld.so.conf +File containing a list of colon, space, tab, newline, or comma spearated +directories in which to search for libraries. +.TP 20 +.B /etc/ld.so.cache +File containing an ordered list of libraries found in the directories +specified in +.BR /etc/ld.so.conf . +.TP +.B lib*.so.version +shared libraries +.PD +.SH SEE ALSO +.BR ldd (1), +.BR ld.so (8). +.SH BUGS +.LP +.BR ldconfig 's +functionality, in conjunction with +.BR ld.so , +is only available for executables compiled using libc version 4.4.3 or greater. +.PP +.BR ldconfig , +being a user process, must be run manually and has no means of dynamically +determining and relinking shared libraries for use by +.BR ld.so +when a new DLL is installed. +.SH AUTHORS +David Engel and Mitch D'Souza. diff --git a/ldso/man/ldd.1 b/ldso/man/ldd.1 new file mode 100644 index 000000000..20c557847 --- /dev/null +++ b/ldso/man/ldd.1 @@ -0,0 +1,59 @@ +.\" Copyright 1995-2000 David Engel (david@ods.com) +.\" Copyright 1995 Rickard E. Faith (faith@cs.unc.edu) +.\" Most of this was copied from the README file. Do not restrict distribution. +.\" May be distributed under the GNU General Public License +.TH LDD 1 "14 March 1998" +.SH NAME +ldd \- print shared library dependencies +.SH SYNOPSIS +.B ldd +.RB [ \-vVdr ] +program|library ... +.SH DESCRIPTION +.B ldd +prints the shared libraries required by each program or shared library +specified on the command line. +If a shared library name does not contain a '/', +.B ldd +attempts to locate the library in the standard locations. +To run +.B ldd +on a shared library in the current directory, a "./" must be prepended +to its name. +.SH OPTIONS +.TP +.B \-v +Print the version number of +.BR ldd . +.TP +.B \-V +Print the version number of the dynamic linker, +.BR ld.so . +.TP +.B \-d +Perform relocations and report any missing functions (ELF only). +.TP +.B \-r +Perform relocations for both data objects and functions, and +report any missing objects (ELF only). +.SH BUGS +.B ldd +does not work very well on libc.so.5 itself. +.PP +.B ldd +does not work on a.out shared libraries. +.PP +.B ldd +does not work with some extremely old a.out programs which were +built before +.B ldd +support was added to the compiler releases. +If you use +.B ldd +on one of these programs, the program will attempt to run with argc = 0 and +the results will be unpredictable. +.SH AUTHOR +David Engel. +.SH SEE ALSO +.BR ldconfig (8), +.BR ld.so (8). -- cgit v1.2.3