summaryrefslogtreecommitdiff
path: root/ldso/man/dlopen.3
diff options
context:
space:
mode:
Diffstat (limited to 'ldso/man/dlopen.3')
-rw-r--r--ldso/man/dlopen.3217
1 files changed, 0 insertions, 217 deletions
diff --git a/ldso/man/dlopen.3 b/ldso/man/dlopen.3
deleted file mode 100644
index 0907aed9c..000000000
--- a/ldso/man/dlopen.3
+++ /dev/null
@@ -1,217 +0,0 @@
-.\" -*- 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, see
-.\" <http://www.gnu.org/licenses/>.
-.\"
-.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 .