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