]>
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 |
1e321034 MK |
59 | that occurred from |
60 | .BR dlopen (), | |
61 | .BR dlsym () | |
62 | or | |
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. | |
880f5b4b MK |
95 | (As a security measure this variable is ignored for set-user-ID and |
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 | |
d355f1ed | 110 | .I /lib |
fea681da | 111 | and |
d355f1ed | 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 | |
117 | using the same rules. (This process may occur recursively, | |
118 | if those libraries in turn have dependencies, and so on.) | |
119 | .PP | |
336e88f0 MK |
120 | One of the following two values must be included in |
121 | .IR flag : | |
122 | .TP | |
fea681da | 123 | .B RTLD_LAZY |
336e88f0 | 124 | Perform lazy binding. |
a3a11667 | 125 | Only resolve symbols as the code that references them is executed. |
336e88f0 MK |
126 | If the symbol is never referenced, then it is never resolved. |
127 | (Lazy binding is only performed for function references; | |
128 | references to variables are always immediately bound when | |
129 | the library is loaded.) | |
130 | .TP | |
fea681da | 131 | .B RTLD_NOW |
336e88f0 | 132 | If this value is specified, or the environment variable |
fea681da MK |
133 | .B LD_BIND_NOW |
134 | is set to a non-empty string, | |
135 | all undefined symbols in the library are resolved before | |
d355f1ed | 136 | .BR dlopen () |
fea681da | 137 | returns. If this cannot be done, an error is returned. |
fea681da | 138 | .PP |
336e88f0 MK |
139 | Zero of more of the following values may also be ORed in |
140 | .IR flag : | |
141 | .TP | |
fea681da | 142 | .B RTLD_GLOBAL |
a3a11667 | 143 | The symbols defined by this library will be |
fea681da | 144 | made available for symbol resolution of subsequently loaded libraries. |
336e88f0 MK |
145 | .TP |
146 | .B RTLD_LOCAL | |
147 | This is the converse of | |
148 | .BR RTLD_GLOBAL , | |
149 | and the default if neither flag is specified. | |
150 | Symbols defined in this library are not made available to resolve | |
151 | references in subsequently loaded libraries. | |
152 | .TP | |
c10859eb | 153 | .BR RTLD_NODELETE " (since glibc 2.2)" |
336e88f0 MK |
154 | Do not unload the library during |
155 | .BR dlclose (). | |
156 | Consequently, the library's static variables are not reinitialised | |
157 | if the library is reloaded with | |
158 | .BR dlopen () | |
159 | at a later time. | |
160 | This flag is not specified in POSIX.1-2001. | |
161 | .\" (But it is present on Solaris.) | |
162 | .TP | |
c10859eb | 163 | .BR RTLD_NOLOAD " (since glibc 2.2)" |
336e88f0 MK |
164 | Don't load the library. |
165 | This can be used to test if the library is already resident | |
166 | .RB ( dlopen () | |
167 | returns NULL if it is not, or the library's handle if it is resident). | |
168 | This flag can also be used to promote the flags on a library | |
169 | that is already loaded. | |
170 | For example, a library that was previously loaded with | |
171 | .B RTLD_LOCAL | |
172 | can be re-opened with | |
173 | .BR RTLD_NOLOAD\ |\ RTLD_GLOBAL . | |
174 | This flag is not specified in POSIX.1-2001. | |
175 | .\" (But it is present on Solaris.) | |
176 | .\" | |
bba06189 MK |
177 | .TP |
178 | .BR RTLD_DEEPBIND " (since glibc 2.3.4)" | |
a3a11667 MK |
179 | .\" Inimitably described by UD in |
180 | .\" http://sources.redhat.com/ml/libc-hacker/2004-09/msg00083.html. | |
bba06189 MK |
181 | Place the lookup scope of the symbols in this |
182 | library ahead of the global scope. | |
183 | This means that a self-contained library will use | |
184 | its own symbols in preference to global symbols with the same name | |
185 | contained in libraries that have already been loaded. | |
186 | This flag is not specified in POSIX.1-2001. | |
fea681da MK |
187 | .PP |
188 | If | |
189 | .I filename | |
190 | is a NULL pointer, then the returned handle is for the main program. | |
191 | When given to | |
d355f1ed | 192 | .BR dlsym (), |
fea681da MK |
193 | this handle causes a search for a symbol in the main program, |
194 | followed by all shared libraries loaded at program startup, | |
195 | and then all shared libraries loaded by | |
d355f1ed | 196 | .BR dlopen () |
fea681da | 197 | with the flag |
a5e0a0e4 | 198 | .BR RTLD_GLOBAL . |
fea681da MK |
199 | .PP |
200 | External references in the library are resolved using the libraries | |
201 | in that library's dependency list and any other libraries previously | |
202 | opened with the | |
203 | .B RTLD_GLOBAL | |
204 | flag. | |
2bc2f479 MK |
205 | If the executable was linked with the flag "\-rdynamic" |
206 | (or, synonymously, "\-\-export\-dynamic"), | |
fea681da MK |
207 | then the global symbols in the executable will also be used |
208 | to resolve references in a dynamically loaded library. | |
209 | .PP | |
210 | If the same library is loaded again with | |
d355f1ed | 211 | .BR dlopen (), |
fea681da MK |
212 | the same file handle is returned. The dl library maintains reference |
213 | counts for library handles, so a dynamic library is not | |
214 | deallocated until | |
d355f1ed | 215 | .BR dlclose () |
fea681da | 216 | has been called on it as many times as |
d355f1ed | 217 | .BR dlopen () |
fea681da MK |
218 | has succeeded on it. The |
219 | .B _init | |
220 | routine, if present, is only called once. But a subsequent call with | |
221 | .B RTLD_NOW | |
222 | may force symbol resolution for a library earlier loaded with | |
223 | .BR RTLD_LAZY . | |
224 | .PP | |
225 | If | |
d355f1ed | 226 | .BR dlopen () |
fea681da MK |
227 | fails for any reason, it returns NULL. |
228 | .SS "dlsym" | |
229 | The function | |
d355f1ed | 230 | .BR dlsym () |
28d88c17 MK |
231 | takes a "handle" of a dynamic library returned by |
232 | .BR dlopen () | |
233 | and the | |
234 | null-terminated symbol name, returning the address where that symbol is | |
fea681da MK |
235 | loaded into memory. If the symbol is not found, in the specified |
236 | library or any of the libraries that were automatically loaded by | |
d355f1ed | 237 | .BR dlopen () |
fea681da | 238 | when that library was loaded, |
d355f1ed | 239 | .BR dlsym () |
fea681da MK |
240 | returns NULL. |
241 | (The search performed by | |
d355f1ed | 242 | .BR dlsym () |
fea681da MK |
243 | is breadth first through the dependency tree of these libraries.) |
244 | Since the value of the symbol could actually be NULL (so that a | |
245 | NULL return from | |
d355f1ed | 246 | .BR dlsym () |
fea681da MK |
247 | need not indicate an error), the correct way to test for an error |
248 | is to call | |
d355f1ed | 249 | .BR dlerror () |
fea681da | 250 | to clear any old error conditions, then call |
d355f1ed | 251 | .BR dlsym (), |
fea681da | 252 | and then call |
d355f1ed | 253 | .BR dlerror () |
fea681da MK |
254 | again, saving its return value into a variable, and check whether |
255 | this saved value is not NULL. | |
256 | .PP | |
257 | There are two special pseudo-handles, | |
258 | .B RTLD_DEFAULT | |
259 | and | |
260 | .BR RTLD_NEXT . | |
261 | The former will find the first occurrence of the desired symbol | |
262 | using the default library search order. The latter | |
263 | will find the next occurrence of a function in the search order | |
264 | after the current library. This allows one to provide a wrapper | |
265 | around a function in another shared library. | |
266 | .SS "dlclose" | |
267 | The function | |
d355f1ed | 268 | .BR dlclose () |
fea681da MK |
269 | decrements the reference count on the dynamic library handle |
270 | .IR handle . | |
271 | If the reference count drops to zero and no other loaded libraries use | |
272 | symbols in it, then the dynamic library is unloaded. | |
273 | .LP | |
274 | The function | |
d355f1ed | 275 | .BR dlclose () |
fea681da MK |
276 | returns 0 on success, and non-zero on error. |
277 | .SS "The obsolete symbols _init and _fini" | |
278 | The linker recognizes special symbols | |
279 | .B _init | |
280 | and | |
281 | .BR _fini . | |
282 | If a dynamic library exports a routine named | |
283 | .BR _init , | |
284 | then that code is executed after the loading, before | |
d355f1ed | 285 | .BR dlopen () |
fea681da MK |
286 | returns. If the dynamic library exports a routine named |
287 | .BR _fini , | |
288 | then that routine is called just before the library is unloaded. | |
289 | In case you need to avoid linking against the system startup files, | |
2bc2f479 | 290 | this can be done by giving gcc the "\-nostartfiles" parameter on |
fea681da MK |
291 | the command line. |
292 | .LP | |
293 | Using these routines, or the gcc | |
f242322f | 294 | .B \-nostartfiles |
fea681da MK |
295 | or |
296 | .B \-nostdlib | |
297 | options, is not recommended. Their use may result in undesired behavior, | |
298 | since the constructor/destructor routines will not be executed | |
299 | (unless special measures are taken). | |
300 | .\" void _init(void) __attribute__((constructor)); | |
301 | .\" void _fini(void) __attribute__((destructor)); | |
302 | .LP | |
303 | Instead, libraries should export routines using the | |
304 | .BR __attribute__((constructor)) | |
305 | and | |
306 | .BR __attribute__((destructor)) | |
307 | function attributes. See the gcc info pages for information on these. | |
308 | Constructor routines are executed before | |
e511ffb6 | 309 | .BR dlopen () |
fea681da | 310 | returns, and destructor routines are executed before |
e511ffb6 | 311 | .BR dlclose () |
fea681da MK |
312 | returns. |
313 | .SH "GNU EXTENSIONS" | |
314 | Glibc adds two functions not described by POSIX, with prototypes | |
315 | .sp | |
316 | .nf | |
bf93c935 | 317 | .B #define _GNU_SOURCE |
fea681da MK |
318 | .B #include <dlfcn.h> |
319 | .sp | |
320 | .BI "int dladdr(void *" addr ", Dl_info *" info ); | |
321 | .sp | |
322 | .BI "void *dlvsym(void *" handle ", char *" symbol ", char *" version ); | |
323 | .fi | |
324 | .PP | |
325 | The function | |
d355f1ed | 326 | .BR dladdr () |
fea681da MK |
327 | takes a function pointer and tries to resolve name |
328 | and file where it is located. Information is stored in the | |
329 | Dl_info structure: | |
330 | .sp | |
331 | .nf | |
332 | typedef struct { | |
2c5f1089 | 333 | const char *dli_fname;/* Filename of defining object */ |
fea681da MK |
334 | void *dli_fbase; /* Load address of that object */ |
335 | const char *dli_sname;/* Name of nearest lower symbol */ | |
336 | void *dli_saddr; /* Exact value of nearest symbol */ | |
337 | } Dl_info; | |
338 | .fi | |
339 | .sp | |
d355f1ed | 340 | .BR dladdr () |
fea681da MK |
341 | returns 0 on error, and non-zero on success. |
342 | .PP | |
343 | The function | |
d355f1ed | 344 | .BR dlvsym () |
fea681da | 345 | does the same as |
d355f1ed MK |
346 | .BR dlsym () |
347 | but takes a version string as an additional argument. | |
fea681da | 348 | .SH EXAMPLE |
9ff08aad | 349 | Load the math library, and print the cosine of 2.0: |
fea681da MK |
350 | .RS |
351 | .nf | |
352 | .if t .ft CW | |
9ff08aad | 353 | |
fea681da | 354 | #include <stdio.h> |
b28f7a67 | 355 | #include <stdlib.h> |
fea681da MK |
356 | #include <dlfcn.h> |
357 | ||
cf0a9ace MK |
358 | int |
359 | main(int argc, char **argv) | |
360 | { | |
fea681da MK |
361 | void *handle; |
362 | double (*cosine)(double); | |
363 | char *error; | |
364 | ||
cf0a9ace | 365 | handle = dlopen("libm.so", RTLD_LAZY); |
fea681da | 366 | if (!handle) { |
cf0a9ace | 367 | fprintf(stderr, "%s\en", dlerror()); |
fea681da MK |
368 | exit(1); |
369 | } | |
370 | ||
371 | dlerror(); /* Clear any existing error */ | |
68e1685c | 372 | .\" This is the (somewhat ugly) POSIX.1-2003 (TC1) fix for |
bba06189 | 373 | .\" the dlsym() casting problem |
fea681da MK |
374 | *(void **) (&cosine) = dlsym(handle, "cos"); |
375 | if ((error = dlerror()) != NULL) { | |
cf0a9ace | 376 | fprintf(stderr, "%s\en", error); |
fea681da MK |
377 | exit(1); |
378 | } | |
379 | ||
cf0a9ace | 380 | printf("%f\en", (*cosine)(2.0)); |
fea681da MK |
381 | dlclose(handle); |
382 | return 0; | |
383 | } | |
384 | .if t .ft P | |
385 | .fi | |
386 | .RE | |
387 | .PP | |
388 | If this program were in a file named "foo.c", you would build the program | |
389 | with the following command: | |
390 | .RS | |
391 | .LP | |
4d9b6984 | 392 | gcc \-rdynamic \-o foo foo.c \-ldl |
fea681da MK |
393 | .RE |
394 | .PP | |
395 | Libraries exporting _init() and _fini() will want to be compiled as | |
396 | follows, using bar.c as the example name: | |
397 | .RS | |
398 | .LP | |
4d9b6984 | 399 | gcc \-shared \-nostartfiles \-o bar bar.c |
fea681da MK |
400 | .RE |
401 | .SH NOTES | |
402 | The symbols RTLD_DEFAULT and RTLD_NEXT are defined by | |
403 | .I <dlfcn.h> | |
404 | only when _GNU_SOURCE was defined before including it. | |
405 | .\" .LP | |
406 | .\" The string returned by | |
4d52e8f8 | 407 | .\" .BR dlerror () |
fea681da MK |
408 | .\" should not be modified. Some systems give the prototype as |
409 | .\" .sp | |
410 | .\" .in +5 | |
411 | .\" .B "const char *dlerror(void);" | |
412 | .\" .in | |
0ed29c54 MK |
413 | |
414 | Since glibc 2.2.3, | |
415 | .BR atexit (3) | |
416 | can be used to register an exit handler that is automatically | |
417 | called when a library is unloaded. | |
fea681da MK |
418 | .SH HISTORY |
419 | The dlopen interface standard comes from SunOS. That system also has | |
d355f1ed MK |
420 | .BR dladdr (), |
421 | but not | |
422 | .BR dlvsym (). | |
fea681da | 423 | .SH "CONFORMING TO" |
68e1685c | 424 | POSIX.1-2001 describes |
d355f1ed MK |
425 | .BR dlclose (), |
426 | .BR dlerror (), | |
427 | .BR dlopen (), | |
428 | and | |
429 | .BR dlsym (). | |
fea681da MK |
430 | .SH "SEE ALSO" |
431 | .BR ld (1), | |
432 | .BR ldd (1), | |
433 | .BR dl_iterate_phdr (3), | |
0a90178c | 434 | .BR feature_test_macros (7) |
fea681da MK |
435 | .BR ld.so (8), |
436 | .BR ldconfig (8), | |
437 | ld.so info pages, gcc info pages, ld info pages |