l4/pkg/l4re-core/uclibc/lib/contrib/uclibc/ldso/man/dlopen.3

   1 .\" -*- nroff -*-
   2 .\" Copyright 1995 Yggdrasil Computing, Incorporated.
   3 .\" written by Adam J. Richter (adam@yggdrasil.com),
   4 .\" with typesetting help from Daniel Quinlan (quinlan@yggdrasil.com).
   5 .\"
   6 .\" This is free documentation; you can redistribute it and/or
   7 .\" modify it under the terms of the GNU General Public License as
   8 .\" published by the Free Software Foundation; either version 2 of
   9 .\" the License, or (at your option) any later version.
  10 .\"
  11 .\" The GNU General Public License's references to "object code"
  12 .\" and "executables" are to be interpreted as the output of any
  13 .\" document formatting or typesetting system, including
  14 .\" intermediate and printed output.
  15 .\"
  16 .\" This manual is distributed in the hope that it will be useful,
  17 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 .\" GNU General Public License for more details.
  20 .\"
  21 .\" You should have received a copy of the GNU General Public
  22 .\" License along with this manual; if not, see
  23 .\" <http://www.gnu.org/licenses/>.
  24 .\"
  25 .TH DLOPEN 3 "16 May 1995" "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 dlclose, dlerror, dlopen, dlsym \- Programming interface to dynamic linking loader.
  28 .SH SYNOPSIS
  29 .B #include <dlfcn.h>
  30 .sp
  31 .BI "void *dlopen (const char *" "filename" ", int " flag ");
  32 .br
  33 .BI "const char *dlerror(void);"
  34 .br
  35 .BI "void *dlsym(void *"handle ", char *"symbol ");"
  36 .br
  37 .BI "int dladdr(void *"address ", Dl_info *"dlip ");"
  38 .br
  39 .BI "int dlclose (void *"handle ");
  40 .sp
  41 Special symbols:
  42 .BR "_init" ", " "_fini" ". "
  43 .SH DESCRIPTION
  44 .B dlopen
  45 loads a dynamic library from the file named by the null terminated
  46 string
  47 .I filename
  48 and returns an opaque "handle" for the dynamic library.
  49 If
  50 .I filename
  51 is not an absolute path (i.e., it does not begin with a "/"), then the
  52 file is searched for in the following locations:
  53 .RS
  54 .PP
  55 A colon-separated list of directories in the user's
  56 \fBLD_LIBRARY\fP path environment variable.
  57 .PP
  58 The list of libraries specified in \fI/etc/ld.so.cache\fP.
  59 .PP
  60 \fI/usr/lib\fP, followed by \fI/lib\fP.
  61 .RE
  62 .PP
  63 If
  64 .I filename
  65 is a NULL pointer, then the returned handle is for the main program.
  66 .PP
  67 External references in the library are resolved using the libraries
  68 in that library's dependency list and any other libraries previously
  69 opened with the
  70 .B RTLD_GLOBAL
  71 flag.
  72 If the executable was linked
  73 with the flag "-rdynamic", then the global symbols in the executable
  74 will also be used to resolve references in a dynamically loaded
  75 library.
  76 .PP
  77 .I flag
  78 must be either
  79 .BR RTLD_LAZY ,
  80 meaning resolve undefined symbols as code from the dynamic library is
  81 executed, or
  82 .BR RTLD_NOW ,
  83 meaning resolve all undefined symbols before
  84 .B dlopen
  85 returns, and fail if this cannot be done.
  86 Optionally,
  87 .B RTLD_GLOBAL
  88 may be or'ed with
  89 .IR flag,
  90 in which case the external symbols defined in the library will be
  91 made available to subsequently loaded libraries.
  92 .PP
  93 If the library exports a routine named
  94 .BR _init ,
  95 then that code is executed before dlopen returns.
  96 If the same library is loaded twice with
  97 .BR dlopen() ,
  98 the same file handle is returned.  The dl library maintains link
  99 counts for dynamic file handles, so a dynamic library is not
 100 deallocated until
 101 .B dlclose
 102 has been called on it as many times as
 103 .B dlopen
 104 has succeeded on it.
 105 .PP
 106 If
 107 .B dlopen
 108 fails for any reason, it returns NULL.
 109 A human readable string describing the most recent error that occurred
 110 from any of the dl routines (dlopen, dlsym or dlclose) can be
 111 extracted with
 112 .BR dlerror() .
 113 .B dlerror
 114 returns NULL if no errors have occurred since initialization or since
 115 it was last called.  (Calling
 116 .B dlerror()
 117 twice consecutively, will always result in the second call returning
 118 NULL.)
 119
 120 .B dlsym
 121 takes a "handle" of a dynamic library returned by dlopen and the null
 122 terminated symbol name, returning the address where that symbol is
 123 loaded.  If the symbol is not found,
 124 .B dlsym
 125 returns NULL; however, the correct way to test for an error from
 126 .B dlsym
 127 is to save the result of
 128 .B dlerror
 129 into a variable, and then check if saved value is not NULL.
 130 This is because the value of the symbol could actually be NULL.
 131 It is also necessary to save the results of
 132 .B dlerror
 133 into a variable because if
 134 .B dlerror
 135 is called again, it will return NULL.
 136 .PP
 137 .B dladdr
 138 returns information about the shared library containing the memory
 139 location specified by
 140 .IR address .
 141 .B dladdr
 142 returns zero on success and non-zero on error.
 143 .PP
 144 .B dlclose
 145 decrements the reference count on the dynamic library handle
 146 .IR handle .
 147 If the reference count drops to zero and no other loaded libraries use
 148 symbols in it, then the dynamic library is unloaded.  If the dynamic
 149 library exports a routine named
 150 .BR _fini ,
 151 then that routine is called just before the library is unloaded.
 152 .SH EXAMPLES
 153 .B Load the math library, and print the cosine of 2.0:
 154 .RS
 155 .nf
 156 .if t .ft CW
 157 #include <dlfcn.h>
 158
 159 int main(int argc, char **argv) {
 160     void *handle = dlopen ("/lib/libm.so", RTLD_LAZY);
 161     double (*cosine)(double) = dlsym(handle, "cos");
 162     printf ("%f\\n", (*cosine)(2.0));
 163     dlclose(handle);
 164 }
 165 .if t .ft P
 166 .fi
 167 .PP
 168 If this program were in a file named "foo.c", you would build the program
 169 with the following command:
 170 .RS
 171 .LP
 172 gcc -rdynamic -o foo foo.c -ldl
 173 .RE
 174 .RE
 175 .LP
 176 .B Do the same thing, but check for errors at every step:
 177 .RS
 178 .nf
 179 .if t .ft CW
 180 #include <stdio.h>
 181 #include <dlfcn.h>
 182
 183 int main(int argc, char **argv) {
 184     void *handle;
 185     double (*cosine)(double);
 186     char *error;
 187
 188     handle = dlopen ("/lib/libm.so", RTLD_LAZY);
 189     if (!handle) {
 190         fputs (dlerror(), stderr);
 191         exit(1);
 192     }
 193
 194     cosine = dlsym(handle, "cos");
 195     if ((error = dlerror()) != NULL)  {
 196         fputs(error, stderr);
 197         exit(1);
 198     }
 199
 200     printf ("%f\\n", (*cosine)(2.0));
 201     dlclose(handle);
 202 }
 203 .if t .ft P
 204 .fi
 205 .RE
 206 .SH ACKNOWLEDGEMENTS
 207 The dlopen interface standard comes from Solaris.
 208 The Linux dlopen implementation was primarily written by
 209 Eric Youngdale with help from Mitch D'Souza, David Engel,
 210 Hongjiu Lu, Andreas Schwab and others.
 211 The manual page was written by Adam Richter.
 212 .SH SEE ALSO
 213 .BR ld(1) ,
 214 .BR ld.so(8) ,
 215 .BR ldconfig(8) ,
 216 .BR ldd(1) ,
 217 .BR ld.so.info .