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

6 files changed, 1001 insertions, 0 deletions

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 <dlfcn.h>
+.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 <dlfcn.h>
+
+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 <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);
+}
+.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 <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
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).