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

1 files changed, 218 insertions, 0 deletions

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 .