]>
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). | |
6883b3e7 | 5 | .\" and Copyright 2003 Michael Kerrisk (mtk-manpages@gmx.net). |
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 | |
305a0578 | 31 | .\" Modified by Michael Kerrisk <mtk-manpages@gmx.net> 2003-05-16. |
fea681da MK |
32 | .\" Modified by Walter Harms: dladdr, dlvsym |
33 | .\" | |
34 | .TH DLOPEN 3 2003-11-17 "Linux" "Linux Programmer's Manual" | |
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 | |
43 | .BI "char *dlerror(void);" | |
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 MK |
54 | implement the interface to the dynamic linking loader. |
55 | .SS "dlerror" | |
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. | |
68 | .SS "dlopen" | |
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): | |
86 | .IP o | |
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 | |
92 | .BR LD_LIBRARY_PATH | |
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 | |
d355f1ed | 103 | .IR /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 (). | |
158 | Consequently, the library's static variables are not reinitialised | |
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 | |
fea681da | 223 | .B _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 MK |
232 | fails for any reason, it returns NULL. |
233 | .SS "dlsym" | |
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 MK |
273 | around a function in another shared library. |
274 | .SS "dlclose" | |
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 MK |
284 | returns 0 on success, and non-zero on error. |
285 | .SS "The obsolete symbols _init and _fini" | |
286 | The linker recognizes special symbols | |
287 | .B _init | |
288 | and | |
289 | .BR _fini . | |
290 | If a dynamic library exports a routine named | |
291 | .BR _init , | |
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 | |
fea681da MK |
296 | .BR _fini , |
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, | |
2bc2f479 | 299 | this can be done by giving gcc the "\-nostartfiles" parameter on |
fea681da MK |
300 | the command line. |
301 | .LP | |
302 | Using these routines, or the gcc | |
f242322f | 303 | .B \-nostartfiles |
fea681da MK |
304 | or |
305 | .B \-nostdlib | |
c13182ef MK |
306 | options, is not recommended. |
307 | Their use may result in undesired behavior, | |
fea681da MK |
308 | since the constructor/destructor routines will not be executed |
309 | (unless special measures are taken). | |
310 | .\" void _init(void) __attribute__((constructor)); | |
311 | .\" void _fini(void) __attribute__((destructor)); | |
312 | .LP | |
313 | Instead, libraries should export routines using the | |
314 | .BR __attribute__((constructor)) | |
315 | and | |
316 | .BR __attribute__((destructor)) | |
c13182ef MK |
317 | function attributes. |
318 | See the gcc info pages for information on these. | |
fea681da | 319 | Constructor routines are executed before |
e511ffb6 | 320 | .BR dlopen () |
fea681da | 321 | returns, and destructor routines are executed before |
e511ffb6 | 322 | .BR dlclose () |
fea681da MK |
323 | returns. |
324 | .SH "GNU EXTENSIONS" | |
325 | Glibc adds two functions not described by POSIX, with prototypes | |
326 | .sp | |
327 | .nf | |
bf93c935 | 328 | .B #define _GNU_SOURCE |
fea681da MK |
329 | .B #include <dlfcn.h> |
330 | .sp | |
331 | .BI "int dladdr(void *" addr ", Dl_info *" info ); | |
332 | .sp | |
333 | .BI "void *dlvsym(void *" handle ", char *" symbol ", char *" version ); | |
334 | .fi | |
335 | .PP | |
336 | The function | |
d355f1ed | 337 | .BR dladdr () |
fea681da | 338 | takes a function pointer and tries to resolve name |
c13182ef MK |
339 | and file where it is located. |
340 | Information is stored in the | |
fea681da MK |
341 | Dl_info structure: |
342 | .sp | |
343 | .nf | |
344 | typedef struct { | |
2c5f1089 | 345 | const char *dli_fname;/* Filename of defining object */ |
fea681da MK |
346 | void *dli_fbase; /* Load address of that object */ |
347 | const char *dli_sname;/* Name of nearest lower symbol */ | |
348 | void *dli_saddr; /* Exact value of nearest symbol */ | |
349 | } Dl_info; | |
350 | .fi | |
351 | .sp | |
d355f1ed | 352 | .BR dladdr () |
fea681da MK |
353 | returns 0 on error, and non-zero on success. |
354 | .PP | |
355 | The function | |
d355f1ed | 356 | .BR dlvsym () |
fea681da | 357 | does the same as |
d355f1ed MK |
358 | .BR dlsym () |
359 | but takes a version string as an additional argument. | |
fea681da | 360 | .SH EXAMPLE |
9ff08aad | 361 | Load the math library, and print the cosine of 2.0: |
fea681da MK |
362 | .RS |
363 | .nf | |
364 | .if t .ft CW | |
9ff08aad | 365 | |
fea681da | 366 | #include <stdio.h> |
b28f7a67 | 367 | #include <stdlib.h> |
fea681da MK |
368 | #include <dlfcn.h> |
369 | ||
c13182ef MK |
370 | int |
371 | main(int argc, char **argv) | |
cf0a9ace | 372 | { |
fea681da MK |
373 | void *handle; |
374 | double (*cosine)(double); | |
375 | char *error; | |
376 | ||
cf0a9ace | 377 | handle = dlopen("libm.so", RTLD_LAZY); |
fea681da | 378 | if (!handle) { |
cf0a9ace | 379 | fprintf(stderr, "%s\en", dlerror()); |
fea681da MK |
380 | exit(1); |
381 | } | |
382 | ||
383 | dlerror(); /* Clear any existing error */ | |
68e1685c | 384 | .\" This is the (somewhat ugly) POSIX.1-2003 (TC1) fix for |
bba06189 | 385 | .\" the dlsym() casting problem |
fea681da MK |
386 | *(void **) (&cosine) = dlsym(handle, "cos"); |
387 | if ((error = dlerror()) != NULL) { | |
cf0a9ace | 388 | fprintf(stderr, "%s\en", error); |
fea681da MK |
389 | exit(1); |
390 | } | |
391 | ||
cf0a9ace | 392 | printf("%f\en", (*cosine)(2.0)); |
fea681da MK |
393 | dlclose(handle); |
394 | return 0; | |
395 | } | |
396 | .if t .ft P | |
397 | .fi | |
398 | .RE | |
399 | .PP | |
400 | If this program were in a file named "foo.c", you would build the program | |
401 | with the following command: | |
402 | .RS | |
403 | .LP | |
4d9b6984 | 404 | gcc \-rdynamic \-o foo foo.c \-ldl |
fea681da MK |
405 | .RE |
406 | .PP | |
407 | Libraries exporting _init() and _fini() will want to be compiled as | |
408 | follows, using bar.c as the example name: | |
409 | .RS | |
410 | .LP | |
4d9b6984 | 411 | gcc \-shared \-nostartfiles \-o bar bar.c |
fea681da MK |
412 | .RE |
413 | .SH NOTES | |
414 | The symbols RTLD_DEFAULT and RTLD_NEXT are defined by | |
415 | .I <dlfcn.h> | |
416 | only when _GNU_SOURCE was defined before including it. | |
417 | .\" .LP | |
418 | .\" The string returned by | |
4d52e8f8 | 419 | .\" .BR dlerror () |
c13182ef MK |
420 | .\" should not be modified. |
421 | .\" Some systems give the prototype as | |
fea681da MK |
422 | .\" .sp |
423 | .\" .in +5 | |
424 | .\" .B "const char *dlerror(void);" | |
425 | .\" .in | |
0ed29c54 | 426 | |
c13182ef | 427 | Since glibc 2.2.3, |
0ed29c54 | 428 | .BR atexit (3) |
c13182ef | 429 | can be used to register an exit handler that is automatically |
0ed29c54 | 430 | called when a library is unloaded. |
fea681da | 431 | .SH HISTORY |
c13182ef MK |
432 | The dlopen interface standard comes from SunOS. |
433 | That system also has | |
434 | .BR dladdr (), | |
435 | but not | |
d355f1ed | 436 | .BR dlvsym (). |
fea681da | 437 | .SH "CONFORMING TO" |
c13182ef MK |
438 | POSIX.1-2001 describes |
439 | .BR dlclose (), | |
440 | .BR dlerror (), | |
441 | .BR dlopen (), | |
d355f1ed MK |
442 | and |
443 | .BR dlsym (). | |
fea681da MK |
444 | .SH "SEE ALSO" |
445 | .BR ld (1), | |
446 | .BR ldd (1), | |
447 | .BR dl_iterate_phdr (3), | |
0a90178c | 448 | .BR feature_test_macros (7) |
fea681da MK |
449 | .BR ld.so (8), |
450 | .BR ldconfig (8), | |
451 | ld.so info pages, gcc info pages, ld info pages |