]>
Commit | Line | Data |
---|---|---|
fea681da MK |
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). | |
c11b1abf | 5 | .\" and Copyright 2003 Michael Kerrisk (mtk.manpages@gmail.com). |
fea681da MK |
6 | .\" |
7 | .\" This is free documentation; you can redistribute it and/or | |
8 | .\" modify it under the terms of the GNU General Public License as | |
9 | .\" published by the Free Software Foundation; either version 2 of | |
10 | .\" the License, or (at your option) any later version. | |
11 | .\" | |
12 | .\" The GNU General Public License's references to "object code" | |
13 | .\" and "executables" are to be interpreted as the output of any | |
14 | .\" document formatting or typesetting system, including | |
15 | .\" intermediate and printed output. | |
16 | .\" | |
17 | .\" This manual is distributed in the hope that it will be useful, | |
18 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
19 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
20 | .\" GNU General Public License for more details. | |
21 | .\" | |
22 | .\" You should have received a copy of the GNU General Public | |
23 | .\" License along with this manual; if not, write to the Free | |
24 | .\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, | |
25 | .\" USA. | |
26 | .\" | |
27 | .\" Modified by David A. Wheeler <dwheeler@dwheeler.com> 2000-11-28. | |
28 | .\" Applied patch by Terran Melconian, aeb, 2001-12-14. | |
29 | .\" Modified by Hacksaw <hacksaw@hacksaw.org> 2003-03-13. | |
30 | .\" Modified by Matt Domsch, 2003-04-09: _init and _fini obsolete | |
c11b1abf | 31 | .\" Modified by Michael Kerrisk <mtk.manpages@gmail.com> 2003-05-16. |
fea681da MK |
32 | .\" Modified by Walter Harms: dladdr, dlvsym |
33 | .\" | |
c73d7281 | 34 | .TH DLOPEN 3 2007-06-27 "Linux" "Linux Programmer's Manual" |
fea681da MK |
35 | .SH NAME |
36 | dladdr, dlclose, dlerror, dlopen, dlsym, dlvsym \- programming interface to | |
37 | dynamic linking loader | |
38 | .SH SYNOPSIS | |
39 | .B #include <dlfcn.h> | |
40 | .sp | |
41 | .BI "void *dlopen(const char *" filename ", int " flag ); | |
42 | .sp | |
0daa9e92 | 43 | .B "char *dlerror(void);" |
fea681da MK |
44 | .sp |
45 | .BI "void *dlsym(void *" handle ", const char *" symbol ); | |
46 | .sp | |
47 | .BI "int dlclose(void *" handle ); | |
48 | .SH DESCRIPTION | |
49 | The four functions | |
d355f1ed MK |
50 | .BR dlopen (), |
51 | .BR dlsym (), | |
52 | .BR dlclose (), | |
53 | .BR dlerror () | |
fea681da | 54 | implement the interface to the dynamic linking loader. |
86100362 | 55 | .SS "dlerror()" |
fea681da | 56 | The function |
d355f1ed | 57 | .BR dlerror () |
fea681da | 58 | returns a human readable string describing the most recent error |
c13182ef MK |
59 | that occurred from |
60 | .BR dlopen (), | |
61 | .BR dlsym () | |
62 | or | |
1e321034 | 63 | .BR dlclose () |
fea681da | 64 | since the last call to |
d355f1ed | 65 | .BR dlerror () . |
fea681da MK |
66 | It returns NULL if no errors have occurred since initialization or since |
67 | it was last called. | |
86100362 | 68 | .SS "dlopen()" |
fea681da | 69 | The function |
d355f1ed | 70 | .BR dlopen () |
fea681da MK |
71 | loads the dynamic library file named by the null-terminated |
72 | string | |
73 | .I filename | |
74 | and returns an opaque "handle" for the dynamic library. | |
75 | If | |
76 | .I filename | |
77 | is NULL, then the returned handle is for the main program. | |
78 | If | |
79 | .I filename | |
80 | contains a slash ("/"), then it is interpreted as a (relative | |
81 | or absolute) pathname. | |
82 | Otherwise, the dynamic linker searches for the library as follows | |
83 | (see | |
84 | .BR ld.so (8) | |
85 | for further details): | |
86100362 | 86 | .IP o 4 |
fea681da MK |
87 | (ELF only) If the executable file for the calling program |
88 | contains a DT_RPATH tag, and does not contain a DT_RUNPATH tag, | |
89 | then the directories listed in the DT_RPATH tag are searched. | |
90 | .IP o | |
91 | If the environment variable | |
0daa9e92 | 92 | .B LD_LIBRARY_PATH |
fea681da MK |
93 | is defined to contain a colon-separated list of directories, |
94 | then these are searched. | |
c13182ef | 95 | (As a security measure this variable is ignored for set-user-ID and |
880f5b4b | 96 | set-group-ID programs.) |
fea681da MK |
97 | .IP o |
98 | (ELF only) If the executable file for the calling program | |
99 | contains a DT_RUNPATH tag, then the directories listed in that tag | |
100 | are searched. | |
101 | .IP o | |
102 | The cache file | |
0daa9e92 | 103 | .I /etc/ld.so.cache |
fea681da MK |
104 | (maintained by |
105 | .BR ldconfig (8)) | |
106 | is checked to see whether it contains an entry for | |
107 | .IR filename . | |
108 | .IP o | |
109 | The directories | |
c13182ef MK |
110 | .I /lib |
111 | and | |
112 | .I /usr/lib | |
fea681da MK |
113 | are searched (in that order). |
114 | .PP | |
115 | If the library has dependencies on other shared libraries, | |
116 | then these are also automatically loaded by the dynamic linker | |
c13182ef MK |
117 | using the same rules. |
118 | (This process may occur recursively, | |
fea681da MK |
119 | if those libraries in turn have dependencies, and so on.) |
120 | .PP | |
336e88f0 MK |
121 | One of the following two values must be included in |
122 | .IR flag : | |
123 | .TP | |
fea681da | 124 | .B RTLD_LAZY |
c13182ef | 125 | Perform lazy binding. |
a3a11667 | 126 | Only resolve symbols as the code that references them is executed. |
336e88f0 MK |
127 | If the symbol is never referenced, then it is never resolved. |
128 | (Lazy binding is only performed for function references; | |
129 | references to variables are always immediately bound when | |
130 | the library is loaded.) | |
131 | .TP | |
fea681da | 132 | .B RTLD_NOW |
336e88f0 | 133 | If this value is specified, or the environment variable |
fea681da MK |
134 | .B LD_BIND_NOW |
135 | is set to a non-empty string, | |
136 | all undefined symbols in the library are resolved before | |
d355f1ed | 137 | .BR dlopen () |
c13182ef MK |
138 | returns. |
139 | If this cannot be done, an error is returned. | |
fea681da | 140 | .PP |
336e88f0 MK |
141 | Zero of more of the following values may also be ORed in |
142 | .IR flag : | |
143 | .TP | |
fea681da | 144 | .B RTLD_GLOBAL |
a3a11667 | 145 | The symbols defined by this library will be |
fea681da | 146 | made available for symbol resolution of subsequently loaded libraries. |
c13182ef | 147 | .TP |
336e88f0 | 148 | .B RTLD_LOCAL |
c13182ef | 149 | This is the converse of |
336e88f0 MK |
150 | .BR RTLD_GLOBAL , |
151 | and the default if neither flag is specified. | |
152 | Symbols defined in this library are not made available to resolve | |
153 | references in subsequently loaded libraries. | |
154 | .TP | |
c10859eb | 155 | .BR RTLD_NODELETE " (since glibc 2.2)" |
336e88f0 MK |
156 | Do not unload the library during |
157 | .BR dlclose (). | |
d9bfdb9c | 158 | Consequently, the library's static variables are not reinitialized |
c13182ef | 159 | if the library is reloaded with |
336e88f0 MK |
160 | .BR dlopen () |
161 | at a later time. | |
162 | This flag is not specified in POSIX.1-2001. | |
163 | .\" (But it is present on Solaris.) | |
164 | .TP | |
c10859eb | 165 | .BR RTLD_NOLOAD " (since glibc 2.2)" |
336e88f0 MK |
166 | Don't load the library. |
167 | This can be used to test if the library is already resident | |
168 | .RB ( dlopen () | |
169 | returns NULL if it is not, or the library's handle if it is resident). | |
c13182ef | 170 | This flag can also be used to promote the flags on a library |
336e88f0 MK |
171 | that is already loaded. |
172 | For example, a library that was previously loaded with | |
173 | .B RTLD_LOCAL | |
c13182ef | 174 | can be re-opened with |
336e88f0 MK |
175 | .BR RTLD_NOLOAD\ |\ RTLD_GLOBAL . |
176 | This flag is not specified in POSIX.1-2001. | |
177 | .\" (But it is present on Solaris.) | |
178 | .\" | |
bba06189 MK |
179 | .TP |
180 | .BR RTLD_DEEPBIND " (since glibc 2.3.4)" | |
c13182ef | 181 | .\" Inimitably described by UD in |
a3a11667 | 182 | .\" http://sources.redhat.com/ml/libc-hacker/2004-09/msg00083.html. |
c13182ef MK |
183 | Place the lookup scope of the symbols in this |
184 | library ahead of the global scope. | |
185 | This means that a self-contained library will use | |
186 | its own symbols in preference to global symbols with the same name | |
bba06189 MK |
187 | contained in libraries that have already been loaded. |
188 | This flag is not specified in POSIX.1-2001. | |
fea681da MK |
189 | .PP |
190 | If | |
191 | .I filename | |
192 | is a NULL pointer, then the returned handle is for the main program. | |
193 | When given to | |
d355f1ed | 194 | .BR dlsym (), |
fea681da MK |
195 | this handle causes a search for a symbol in the main program, |
196 | followed by all shared libraries loaded at program startup, | |
c13182ef | 197 | and then all shared libraries loaded by |
d355f1ed | 198 | .BR dlopen () |
fea681da | 199 | with the flag |
a5e0a0e4 | 200 | .BR RTLD_GLOBAL . |
fea681da MK |
201 | .PP |
202 | External references in the library are resolved using the libraries | |
203 | in that library's dependency list and any other libraries previously | |
c13182ef | 204 | opened with the |
fea681da MK |
205 | .B RTLD_GLOBAL |
206 | flag. | |
2bc2f479 MK |
207 | If the executable was linked with the flag "\-rdynamic" |
208 | (or, synonymously, "\-\-export\-dynamic"), | |
fea681da MK |
209 | then the global symbols in the executable will also be used |
210 | to resolve references in a dynamically loaded library. | |
211 | .PP | |
212 | If the same library is loaded again with | |
d355f1ed | 213 | .BR dlopen (), |
c13182ef MK |
214 | the same file handle is returned. |
215 | The dl library maintains reference | |
fea681da MK |
216 | counts for library handles, so a dynamic library is not |
217 | deallocated until | |
d355f1ed | 218 | .BR dlclose () |
fea681da | 219 | has been called on it as many times as |
d355f1ed | 220 | .BR dlopen () |
c13182ef MK |
221 | has succeeded on it. |
222 | The | |
86100362 | 223 | .BR _init () |
c13182ef MK |
224 | routine, if present, is only called once. |
225 | But a subsequent call with | |
fea681da MK |
226 | .B RTLD_NOW |
227 | may force symbol resolution for a library earlier loaded with | |
228 | .BR RTLD_LAZY . | |
229 | .PP | |
230 | If | |
d355f1ed | 231 | .BR dlopen () |
fea681da | 232 | fails for any reason, it returns NULL. |
86100362 | 233 | .SS "dlsym()" |
fea681da | 234 | The function |
d355f1ed | 235 | .BR dlsym () |
c13182ef | 236 | takes a "handle" of a dynamic library returned by |
28d88c17 MK |
237 | .BR dlopen () |
238 | and the | |
239 | null-terminated symbol name, returning the address where that symbol is | |
c13182ef MK |
240 | loaded into memory. |
241 | If the symbol is not found, in the specified | |
fea681da | 242 | library or any of the libraries that were automatically loaded by |
d355f1ed | 243 | .BR dlopen () |
fea681da | 244 | when that library was loaded, |
d355f1ed | 245 | .BR dlsym () |
fea681da MK |
246 | returns NULL. |
247 | (The search performed by | |
d355f1ed | 248 | .BR dlsym () |
fea681da MK |
249 | is breadth first through the dependency tree of these libraries.) |
250 | Since the value of the symbol could actually be NULL (so that a | |
251 | NULL return from | |
d355f1ed | 252 | .BR dlsym () |
fea681da MK |
253 | need not indicate an error), the correct way to test for an error |
254 | is to call | |
d355f1ed | 255 | .BR dlerror () |
fea681da | 256 | to clear any old error conditions, then call |
d355f1ed | 257 | .BR dlsym (), |
fea681da | 258 | and then call |
d355f1ed | 259 | .BR dlerror () |
fea681da MK |
260 | again, saving its return value into a variable, and check whether |
261 | this saved value is not NULL. | |
262 | .PP | |
263 | There are two special pseudo-handles, | |
264 | .B RTLD_DEFAULT | |
265 | and | |
266 | .BR RTLD_NEXT . | |
267 | The former will find the first occurrence of the desired symbol | |
c13182ef MK |
268 | using the default library search order. |
269 | The latter | |
fea681da | 270 | will find the next occurrence of a function in the search order |
c13182ef MK |
271 | after the current library. |
272 | This allows one to provide a wrapper | |
fea681da | 273 | around a function in another shared library. |
86100362 | 274 | .SS "dlclose()" |
fea681da | 275 | The function |
d355f1ed | 276 | .BR dlclose () |
fea681da MK |
277 | decrements the reference count on the dynamic library handle |
278 | .IR handle . | |
279 | If the reference count drops to zero and no other loaded libraries use | |
280 | symbols in it, then the dynamic library is unloaded. | |
281 | .LP | |
282 | The function | |
d355f1ed | 283 | .BR dlclose () |
fea681da | 284 | returns 0 on success, and non-zero on error. |
86100362 | 285 | .SS "The obsolete symbols _init() and _fini()" |
fea681da MK |
286 | The linker recognizes special symbols |
287 | .B _init | |
288 | and | |
289 | .BR _fini . | |
290 | If a dynamic library exports a routine named | |
86100362 | 291 | .BR _init (), |
fea681da | 292 | then that code is executed after the loading, before |
d355f1ed | 293 | .BR dlopen () |
c13182ef MK |
294 | returns. |
295 | If the dynamic library exports a routine named | |
86100362 | 296 | .BR _fini (), |
fea681da MK |
297 | then that routine is called just before the library is unloaded. |
298 | In case you need to avoid linking against the system startup files, | |
86100362 MK |
299 | this can be done by using the |
300 | .BR gcc (1) | |
ea5a4ee4 | 301 | .I \-nostartfiles |
86100362 | 302 | command-line option. |
fea681da MK |
303 | .LP |
304 | Using these routines, or the gcc | |
f242322f | 305 | .B \-nostartfiles |
fea681da MK |
306 | or |
307 | .B \-nostdlib | |
c13182ef MK |
308 | options, is not recommended. |
309 | Their use may result in undesired behavior, | |
fea681da MK |
310 | since the constructor/destructor routines will not be executed |
311 | (unless special measures are taken). | |
312 | .\" void _init(void) __attribute__((constructor)); | |
313 | .\" void _fini(void) __attribute__((destructor)); | |
314 | .LP | |
315 | Instead, libraries should export routines using the | |
0daa9e92 | 316 | .B __attribute__((constructor)) |
fea681da | 317 | and |
0daa9e92 | 318 | .B __attribute__((destructor)) |
c13182ef MK |
319 | function attributes. |
320 | See the gcc info pages for information on these. | |
fea681da | 321 | Constructor routines are executed before |
e511ffb6 | 322 | .BR dlopen () |
fea681da | 323 | returns, and destructor routines are executed before |
e511ffb6 | 324 | .BR dlclose () |
fea681da | 325 | returns. |
7b1efcab | 326 | .SS Glibc extensions: dladdr() and dlvsym() |
fea681da MK |
327 | Glibc adds two functions not described by POSIX, with prototypes |
328 | .sp | |
329 | .nf | |
bf93c935 | 330 | .B #define _GNU_SOURCE |
fea681da MK |
331 | .B #include <dlfcn.h> |
332 | .sp | |
333 | .BI "int dladdr(void *" addr ", Dl_info *" info ); | |
334 | .sp | |
335 | .BI "void *dlvsym(void *" handle ", char *" symbol ", char *" version ); | |
336 | .fi | |
337 | .PP | |
338 | The function | |
d355f1ed | 339 | .BR dladdr () |
fea681da | 340 | takes a function pointer and tries to resolve name |
c13182ef MK |
341 | and file where it is located. |
342 | Information is stored in the | |
86100362 MK |
343 | .I Dl_info |
344 | structure: | |
fea681da | 345 | .sp |
86100362 | 346 | .in +0.25i |
fea681da MK |
347 | .nf |
348 | typedef struct { | |
86100362 MK |
349 | const char *dli_fname; /* Filename of defining object */ |
350 | void *dli_fbase; /* Load address of that object */ | |
351 | const char *dli_sname; /* Name of nearest lower symbol */ | |
352 | void *dli_saddr; /* Exact value of nearest symbol */ | |
fea681da MK |
353 | } Dl_info; |
354 | .fi | |
86100362 | 355 | .in |
fea681da | 356 | .sp |
d355f1ed | 357 | .BR dladdr () |
fea681da MK |
358 | returns 0 on error, and non-zero on success. |
359 | .PP | |
360 | The function | |
d355f1ed | 361 | .BR dlvsym () |
fea681da | 362 | does the same as |
d355f1ed MK |
363 | .BR dlsym () |
364 | but takes a version string as an additional argument. | |
2b2581ee MK |
365 | .SH "CONFORMING TO" |
366 | POSIX.1-2001 describes | |
367 | .BR dlclose (), | |
368 | .BR dlerror (), | |
369 | .BR dlopen (), | |
370 | and | |
371 | .BR dlsym (). | |
372 | .SH NOTES | |
097585ed MK |
373 | The symbols |
374 | .B RTLD_DEFAULT | |
375 | and | |
376 | .B RTLD_NEXT | |
377 | are defined by | |
2b2581ee | 378 | .I <dlfcn.h> |
c3dfd2c8 MK |
379 | only when |
380 | .B _GNU_SOURCE | |
381 | was defined before including it. | |
2b2581ee MK |
382 | .\" .LP |
383 | .\" The string returned by | |
384 | .\" .BR dlerror () | |
385 | .\" should not be modified. | |
386 | .\" Some systems give the prototype as | |
387 | .\" .sp | |
388 | .\" .in +5 | |
389 | .\" .B "const char *dlerror(void);" | |
390 | .\" .in | |
391 | ||
392 | Since glibc 2.2.3, | |
393 | .BR atexit (3) | |
394 | can be used to register an exit handler that is automatically | |
395 | called when a library is unloaded. | |
396 | .SS History | |
397 | The dlopen interface standard comes from SunOS. | |
398 | That system also has | |
399 | .BR dladdr (), | |
400 | but not | |
401 | .BR dlvsym (). | |
fea681da | 402 | .SH EXAMPLE |
9ff08aad | 403 | Load the math library, and print the cosine of 2.0: |
fea681da | 404 | .nf |
9ff08aad | 405 | |
fea681da | 406 | #include <stdio.h> |
b28f7a67 | 407 | #include <stdlib.h> |
fea681da MK |
408 | #include <dlfcn.h> |
409 | ||
c13182ef MK |
410 | int |
411 | main(int argc, char **argv) | |
cf0a9ace | 412 | { |
fea681da MK |
413 | void *handle; |
414 | double (*cosine)(double); | |
415 | char *error; | |
416 | ||
cf0a9ace | 417 | handle = dlopen("libm.so", RTLD_LAZY); |
fea681da | 418 | if (!handle) { |
cf0a9ace | 419 | fprintf(stderr, "%s\en", dlerror()); |
4c44ffe5 | 420 | exit(EXIT_FAILURE); |
fea681da MK |
421 | } |
422 | ||
423 | dlerror(); /* Clear any existing error */ | |
c73d7281 MK |
424 | |
425 | /* Writing: cosine = (double (*)(double)) dlsym(handle, "cos"); | |
680415af MK |
426 | would seem more natural, but the C99 standard leaves |
427 | casting from "void *" to a function pointer undefined. | |
29059a65 | 428 | The assignment used below is the POSIX.1\-2003 (Technical |
c73d7281 MK |
429 | Corrigendum 1) workaround; see the Rationale for the |
430 | POSIX specification of dlsym(). */ | |
431 | ||
fea681da | 432 | *(void **) (&cosine) = dlsym(handle, "cos"); |
680415af | 433 | .\" But in fact "gcc -O2 -Wall" will complain about the preceding cast. |
c73d7281 | 434 | |
fea681da | 435 | if ((error = dlerror()) != NULL) { |
cf0a9ace | 436 | fprintf(stderr, "%s\en", error); |
4c44ffe5 | 437 | exit(EXIT_FAILURE); |
fea681da MK |
438 | } |
439 | ||
cf0a9ace | 440 | printf("%f\en", (*cosine)(2.0)); |
fea681da | 441 | dlclose(handle); |
5bc8c34c | 442 | exit(EXIT_SUCCESS); |
fea681da | 443 | } |
fea681da | 444 | .fi |
fea681da MK |
445 | .PP |
446 | If this program were in a file named "foo.c", you would build the program | |
447 | with the following command: | |
448 | .RS | |
449 | .LP | |
4d9b6984 | 450 | gcc \-rdynamic \-o foo foo.c \-ldl |
fea681da MK |
451 | .RE |
452 | .PP | |
86100362 MK |
453 | Libraries exporting |
454 | .BR _init () | |
988db661 | 455 | and |
86100362 MK |
456 | .BR _fini () |
457 | will want to be compiled as | |
458 | follows, using \fIbar.c\fP as the example name: | |
fea681da MK |
459 | .RS |
460 | .LP | |
4d9b6984 | 461 | gcc \-shared \-nostartfiles \-o bar bar.c |
fea681da | 462 | .RE |
fea681da MK |
463 | .SH "SEE ALSO" |
464 | .BR ld (1), | |
465 | .BR ldd (1), | |
466 | .BR dl_iterate_phdr (3), | |
0a90178c | 467 | .BR feature_test_macros (7) |
fea681da MK |
468 | .BR ld.so (8), |
469 | .BR ldconfig (8), | |
470 | ld.so info pages, gcc info pages, ld info pages |