]>
Commit | Line | Data |
---|---|---|
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 | .\" and Copyright 2003 Michael Kerrisk (mtk.manpages@gmail.com). | |
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 | |
31 | .\" Modified by Michael Kerrisk <mtk.manpages@gmail.com> 2003-05-16. | |
32 | .\" Modified by Walter Harms: dladdr, dlvsym | |
33 | .\" Modified by Petr Baudis <pasky@suse.cz>, 2008-12-04: dladdr caveat | |
34 | .\" | |
35 | .TH DLOPEN 3 2008-12-06 "Linux" "Linux Programmer's Manual" | |
36 | .SH NAME | |
37 | dladdr, dlclose, dlerror, dlopen, dlsym, dlvsym \- programming interface to | |
38 | dynamic linking loader | |
39 | .SH SYNOPSIS | |
40 | .B #include <dlfcn.h> | |
41 | .sp | |
42 | .BI "void *dlopen(const char *" filename ", int " flag ); | |
43 | .sp | |
44 | .B "char *dlerror(void);" | |
45 | .sp | |
46 | .BI "void *dlsym(void *" handle ", const char *" symbol ); | |
47 | .sp | |
48 | .BI "int dlclose(void *" handle ); | |
49 | .sp | |
50 | Link with \fI\-ldl\fP. | |
51 | .SH DESCRIPTION | |
52 | The four functions | |
53 | .BR dlopen (), | |
54 | .BR dlsym (), | |
55 | .BR dlclose (), | |
56 | .BR dlerror () | |
57 | implement the interface to the dynamic linking loader. | |
58 | .SS "dlerror()" | |
59 | The function | |
60 | .BR dlerror () | |
61 | returns a human readable string describing the most recent error | |
62 | that occurred from | |
63 | .BR dlopen (), | |
64 | .BR dlsym () | |
65 | or | |
66 | .BR dlclose () | |
67 | since the last call to | |
68 | .BR dlerror (). | |
69 | It returns NULL if no errors have occurred since initialization or since | |
70 | it was last called. | |
71 | .SS "dlopen()" | |
72 | The function | |
73 | .BR dlopen () | |
74 | loads the dynamic library file named by the null-terminated | |
75 | string | |
76 | .I filename | |
77 | and returns an opaque "handle" for the dynamic library. | |
78 | If | |
79 | .I filename | |
80 | is NULL, then the returned handle is for the main program. | |
81 | If | |
82 | .I filename | |
83 | contains a slash ("/"), then it is interpreted as a (relative | |
84 | or absolute) pathname. | |
85 | Otherwise, the dynamic linker searches for the library as follows | |
86 | (see | |
87 | .BR ld.so (8) | |
88 | for further details): | |
89 | .IP o 4 | |
90 | (ELF only) If the executable file for the calling program | |
91 | contains a DT_RPATH tag, and does not contain a DT_RUNPATH tag, | |
92 | then the directories listed in the DT_RPATH tag are searched. | |
93 | .IP o | |
94 | If, at the time that the program was started, the environment variable | |
95 | .B LD_LIBRARY_PATH | |
96 | was defined to contain a colon-separated list of directories, | |
97 | then these are searched. | |
98 | (As a security measure this variable is ignored for set-user-ID and | |
99 | set-group-ID programs.) | |
100 | .IP o | |
101 | (ELF only) If the executable file for the calling program | |
102 | contains a DT_RUNPATH tag, then the directories listed in that tag | |
103 | are searched. | |
104 | .IP o | |
105 | The cache file | |
106 | .I /etc/ld.so.cache | |
107 | (maintained by | |
108 | .BR ldconfig (8)) | |
109 | is checked to see whether it contains an entry for | |
110 | .IR filename . | |
111 | .IP o | |
112 | The directories | |
113 | .I /lib | |
114 | and | |
115 | .I /usr/lib | |
116 | are searched (in that order). | |
117 | .PP | |
118 | If the library has dependencies on other shared libraries, | |
119 | then these are also automatically loaded by the dynamic linker | |
120 | using the same rules. | |
121 | (This process may occur recursively, | |
122 | if those libraries in turn have dependencies, and so on.) | |
123 | .PP | |
124 | One of the following two values must be included in | |
125 | .IR flag : | |
126 | .TP | |
127 | .B RTLD_LAZY | |
128 | Perform lazy binding. | |
129 | Only resolve symbols as the code that references them is executed. | |
130 | If the symbol is never referenced, then it is never resolved. | |
131 | (Lazy binding is only performed for function references; | |
132 | references to variables are always immediately bound when | |
133 | the library is loaded.) | |
134 | .TP | |
135 | .B RTLD_NOW | |
136 | If this value is specified, or the environment variable | |
137 | .B LD_BIND_NOW | |
138 | is set to a nonempty string, | |
139 | all undefined symbols in the library are resolved before | |
140 | .BR dlopen () | |
141 | returns. | |
142 | If this cannot be done, an error is returned. | |
143 | .PP | |
144 | Zero or more of the following values may also be ORed in | |
145 | .IR flag : | |
146 | .TP | |
147 | .B RTLD_GLOBAL | |
148 | The symbols defined by this library will be | |
149 | made available for symbol resolution of subsequently loaded libraries. | |
150 | .TP | |
151 | .B RTLD_LOCAL | |
152 | This is the converse of | |
153 | .BR RTLD_GLOBAL , | |
154 | and the default if neither flag is specified. | |
155 | Symbols defined in this library are not made available to resolve | |
156 | references in subsequently loaded libraries. | |
157 | .TP | |
158 | .BR RTLD_NODELETE " (since glibc 2.2)" | |
159 | Do not unload the library during | |
160 | .BR dlclose (). | |
161 | Consequently, the library's static variables are not reinitialized | |
162 | if the library is reloaded with | |
163 | .BR dlopen () | |
164 | at a later time. | |
165 | This flag is not specified in POSIX.1-2001. | |
166 | .\" (But it is present on Solaris.) | |
167 | .TP | |
168 | .BR RTLD_NOLOAD " (since glibc 2.2)" | |
169 | Don't load the library. | |
170 | This can be used to test if the library is already resident | |
171 | .RB ( dlopen () | |
172 | returns NULL if it is not, or the library's handle if it is resident). | |
173 | This flag can also be used to promote the flags on a library | |
174 | that is already loaded. | |
175 | For example, a library that was previously loaded with | |
176 | .B RTLD_LOCAL | |
177 | can be reopened with | |
178 | .BR RTLD_NOLOAD\ |\ RTLD_GLOBAL . | |
179 | This flag is not specified in POSIX.1-2001. | |
180 | .\" (But it is present on Solaris.) | |
181 | .\" | |
182 | .TP | |
183 | .BR RTLD_DEEPBIND " (since glibc 2.3.4)" | |
184 | .\" Inimitably described by UD in | |
185 | .\" http://sources.redhat.com/ml/libc-hacker/2004-09/msg00083.html. | |
186 | Place the lookup scope of the symbols in this | |
187 | library ahead of the global scope. | |
188 | This means that a self-contained library will use | |
189 | its own symbols in preference to global symbols with the same name | |
190 | contained in libraries that have already been loaded. | |
191 | This flag is not specified in POSIX.1-2001. | |
192 | .PP | |
193 | If | |
194 | .I filename | |
195 | is a NULL pointer, then the returned handle is for the main program. | |
196 | When given to | |
197 | .BR dlsym (), | |
198 | this handle causes a search for a symbol in the main program, | |
199 | followed by all shared libraries loaded at program startup, | |
200 | and then all shared libraries loaded by | |
201 | .BR dlopen () | |
202 | with the flag | |
203 | .BR RTLD_GLOBAL . | |
204 | .PP | |
205 | External references in the library are resolved using the libraries | |
206 | in that library's dependency list and any other libraries previously | |
207 | opened with the | |
208 | .B RTLD_GLOBAL | |
209 | flag. | |
210 | If the executable was linked with the flag "\-rdynamic" | |
211 | (or, synonymously, "\-\-export\-dynamic"), | |
212 | then the global symbols in the executable will also be used | |
213 | to resolve references in a dynamically loaded library. | |
214 | .PP | |
215 | If the same library is loaded again with | |
216 | .BR dlopen (), | |
217 | the same file handle is returned. | |
218 | The dl library maintains reference | |
219 | counts for library handles, so a dynamic library is not | |
220 | deallocated until | |
221 | .BR dlclose () | |
222 | has been called on it as many times as | |
223 | .BR dlopen () | |
224 | has succeeded on it. | |
225 | The | |
226 | .BR _init () | |
227 | routine, if present, is only called once. | |
228 | But a subsequent call with | |
229 | .B RTLD_NOW | |
230 | may force symbol resolution for a library earlier loaded with | |
231 | .BR RTLD_LAZY . | |
232 | .PP | |
233 | If | |
234 | .BR dlopen () | |
235 | fails for any reason, it returns NULL. | |
236 | .SS "dlsym()" | |
237 | The function | |
238 | .BR dlsym () | |
239 | takes a "handle" of a dynamic library returned by | |
240 | .BR dlopen () | |
241 | and the | |
242 | null-terminated symbol name, returning the address where that symbol is | |
243 | loaded into memory. | |
244 | If the symbol is not found, in the specified | |
245 | library or any of the libraries that were automatically loaded by | |
246 | .BR dlopen () | |
247 | when that library was loaded, | |
248 | .BR dlsym () | |
249 | returns NULL. | |
250 | (The search performed by | |
251 | .BR dlsym () | |
252 | is breadth first through the dependency tree of these libraries.) | |
253 | Since the value of the symbol could actually be NULL (so that a | |
254 | NULL return from | |
255 | .BR dlsym () | |
256 | need not indicate an error), the correct way to test for an error | |
257 | is to call | |
258 | .BR dlerror () | |
259 | to clear any old error conditions, then call | |
260 | .BR dlsym (), | |
261 | and then call | |
262 | .BR dlerror () | |
263 | again, saving its return value into a variable, and check whether | |
264 | this saved value is not NULL. | |
265 | .PP | |
266 | There are two special pseudo-handles, | |
267 | .B RTLD_DEFAULT | |
268 | and | |
269 | .BR RTLD_NEXT . | |
270 | The former will find the first occurrence of the desired symbol | |
271 | using the default library search order. | |
272 | The latter | |
273 | will find the next occurrence of a function in the search order | |
274 | after the current library. | |
275 | This allows one to provide a wrapper | |
276 | around a function in another shared library. | |
277 | .SS "dlclose()" | |
278 | The function | |
279 | .BR dlclose () | |
280 | decrements the reference count on the dynamic library handle | |
281 | .IR handle . | |
282 | If the reference count drops to zero and no other loaded libraries use | |
283 | symbols in it, then the dynamic library is unloaded. | |
284 | .LP | |
285 | The function | |
286 | .BR dlclose () | |
287 | returns 0 on success, and nonzero on error. | |
288 | .SS "The obsolete symbols _init() and _fini()" | |
289 | The linker recognizes special symbols | |
290 | .B _init | |
291 | and | |
292 | .BR _fini . | |
293 | If a dynamic library exports a routine named | |
294 | .BR _init (), | |
295 | then that code is executed after the loading, before | |
296 | .BR dlopen () | |
297 | returns. | |
298 | If the dynamic library exports a routine named | |
299 | .BR _fini (), | |
300 | then that routine is called just before the library is unloaded. | |
301 | In case you need to avoid linking against the system startup files, | |
302 | this can be done by using the | |
303 | .BR gcc (1) | |
304 | .I \-nostartfiles | |
305 | command-line option. | |
306 | .LP | |
307 | Using these routines, or the gcc | |
308 | .B \-nostartfiles | |
309 | or | |
310 | .B \-nostdlib | |
311 | options, is not recommended. | |
312 | Their use may result in undesired behavior, | |
313 | since the constructor/destructor routines will not be executed | |
314 | (unless special measures are taken). | |
315 | .\" void _init(void) __attribute__((constructor)); | |
316 | .\" void _fini(void) __attribute__((destructor)); | |
317 | .LP | |
318 | Instead, libraries should export routines using the | |
319 | .B __attribute__((constructor)) | |
320 | and | |
321 | .B __attribute__((destructor)) | |
322 | function attributes. | |
323 | See the gcc info pages for information on these. | |
324 | Constructor routines are executed before | |
325 | .BR dlopen () | |
326 | returns, and destructor routines are executed before | |
327 | .BR dlclose () | |
328 | returns. | |
329 | .SS Glibc extensions: dladdr() and dlvsym() | |
330 | Glibc adds two functions not described by POSIX, with prototypes | |
331 | .sp | |
332 | .nf | |
333 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" | |
334 | .B #include <dlfcn.h> | |
335 | .sp | |
336 | .BI "int dladdr(void *" addr ", Dl_info *" info ); | |
337 | .sp | |
338 | .BI "void *dlvsym(void *" handle ", char *" symbol ", char *" version ); | |
339 | .fi | |
340 | .PP | |
341 | The function | |
342 | .BR dladdr () | |
343 | takes a function pointer and tries to resolve name | |
344 | and file where it is located. | |
345 | Information is stored in the | |
346 | .I Dl_info | |
347 | structure: | |
348 | .sp | |
349 | .in +4n | |
350 | .nf | |
351 | typedef struct { | |
352 | const char *dli_fname; /* Pathname of shared object that | |
353 | contains address */ | |
354 | void *dli_fbase; /* Address at which shared object | |
355 | is loaded */ | |
356 | const char *dli_sname; /* Name of nearest symbol with address | |
357 | lower than \fIaddr\fP */ | |
358 | void *dli_saddr; /* Exact address of symbol named | |
359 | in \fIdli_sname\fP */ | |
360 | } Dl_info; | |
361 | .fi | |
362 | .in | |
363 | .PP | |
364 | If no symbol matching | |
365 | .I addr | |
366 | could be found, then | |
367 | .I dli_sname | |
368 | and | |
369 | .I dli_saddr | |
370 | are set to NULL. | |
371 | .PP | |
372 | .BR dladdr () | |
373 | returns 0 on error, and nonzero on success. | |
374 | .PP | |
375 | The function | |
376 | .BR dlvsym (), | |
377 | provided by glibc since version 2.1, | |
378 | does the same as | |
379 | .BR dlsym () | |
380 | but takes a version string as an additional argument. | |
381 | .SH CONFORMING TO | |
382 | POSIX.1-2001 describes | |
383 | .BR dlclose (), | |
384 | .BR dlerror (), | |
385 | .BR dlopen (), | |
386 | and | |
387 | .BR dlsym (). | |
388 | .SH NOTES | |
389 | The symbols | |
390 | .B RTLD_DEFAULT | |
391 | and | |
392 | .B RTLD_NEXT | |
393 | are defined by | |
394 | .I <dlfcn.h> | |
395 | only when | |
396 | .B _GNU_SOURCE | |
397 | was defined before including it. | |
398 | .\" .LP | |
399 | .\" The string returned by | |
400 | .\" .BR dlerror () | |
401 | .\" should not be modified. | |
402 | .\" Some systems give the prototype as | |
403 | .\" .sp | |
404 | .\" .in +5 | |
405 | .\" .B "const char *dlerror(void);" | |
406 | .\" .in | |
407 | ||
408 | Since glibc 2.2.3, | |
409 | .BR atexit (3) | |
410 | can be used to register an exit handler that is automatically | |
411 | called when a library is unloaded. | |
412 | .SS History | |
413 | The dlopen interface standard comes from SunOS. | |
414 | That system also has | |
415 | .BR dladdr (), | |
416 | but not | |
417 | .BR dlvsym (). | |
418 | .SH BUGS | |
419 | Sometimes, the function pointers you pass to | |
420 | .BR dladdr () | |
421 | may surprise you. | |
422 | On some architectures (notably i386 and x86_64), | |
423 | .I dli_fname | |
424 | and | |
425 | .I dli_fbase | |
426 | may end up pointing back at the object from which you called | |
427 | .BR dladdr (), | |
428 | even if the function used as an argument should come from | |
429 | a dynamically linked library. | |
430 | .PP | |
431 | The problem is that the function pointer will still be resolved | |
432 | at compile time, but merely point to the | |
433 | .I plt | |
434 | (Procedure Linkage Table) | |
435 | section of the original object (which dispatches the call after | |
436 | asking the dynamic linker to resolve the symbol). | |
437 | To work around this, | |
438 | you can try to compile the code to be position-independent: | |
439 | then, the compiler cannot prepare the pointer | |
440 | at compile time anymore and today's | |
441 | .BR gcc (1) | |
442 | will generate code that just loads the final symbol address from the | |
443 | .I got | |
444 | (Global Offset Table) at run time before passing it to | |
445 | .BR dladdr (). | |
446 | .SH EXAMPLE | |
447 | Load the math library, and print the cosine of 2.0: | |
448 | .nf | |
449 | ||
450 | #include <stdio.h> | |
451 | #include <stdlib.h> | |
452 | #include <dlfcn.h> | |
453 | ||
454 | int | |
455 | main(int argc, char **argv) | |
456 | { | |
457 | void *handle; | |
458 | double (*cosine)(double); | |
459 | char *error; | |
460 | ||
461 | handle = dlopen("libm.so", RTLD_LAZY); | |
462 | if (!handle) { | |
463 | fprintf(stderr, "%s\en", dlerror()); | |
464 | exit(EXIT_FAILURE); | |
465 | } | |
466 | ||
467 | dlerror(); /* Clear any existing error */ | |
468 | ||
469 | /* Writing: cosine = (double (*)(double)) dlsym(handle, "cos"); | |
470 | would seem more natural, but the C99 standard leaves | |
471 | casting from "void *" to a function pointer undefined. | |
472 | The assignment used below is the POSIX.1\-2003 (Technical | |
473 | Corrigendum 1) workaround; see the Rationale for the | |
474 | POSIX specification of dlsym(). */ | |
475 | ||
476 | *(void **) (&cosine) = dlsym(handle, "cos"); | |
477 | .\" But in fact "gcc -O2 -Wall" will complain about the preceding cast. | |
478 | ||
479 | if ((error = dlerror()) != NULL) { | |
480 | fprintf(stderr, "%s\en", error); | |
481 | exit(EXIT_FAILURE); | |
482 | } | |
483 | ||
484 | printf("%f\en", (*cosine)(2.0)); | |
485 | dlclose(handle); | |
486 | exit(EXIT_SUCCESS); | |
487 | } | |
488 | .fi | |
489 | .PP | |
490 | If this program were in a file named "foo.c", you would build the program | |
491 | with the following command: | |
492 | .in +4n | |
493 | .LP | |
494 | gcc \-rdynamic \-o foo foo.c \-ldl | |
495 | .in | |
496 | .PP | |
497 | Libraries exporting | |
498 | .BR _init () | |
499 | and | |
500 | .BR _fini () | |
501 | will want to be compiled as | |
502 | follows, using \fIbar.c\fP as the example name: | |
503 | .in +4n | |
504 | .LP | |
505 | gcc \-shared \-nostartfiles \-o bar bar.c | |
506 | .in | |
507 | .SH SEE ALSO | |
508 | .BR ld (1), | |
509 | .BR ldd (1), | |
510 | .BR dl_iterate_phdr (3), | |
511 | .BR rtld-audit (7), | |
512 | .BR ld.so (8), | |
513 | .BR ldconfig (8) | |
514 | ||
515 | ld.so info pages, gcc info pages, ld info pages |