]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1995 Yggdrasil Computing, Incorporated. |
2 | .\" written by Adam J. Richter (adam@yggdrasil.com), | |
3 | .\" with typesetting help from Daniel Quinlan (quinlan@yggdrasil.com). | |
616c2730 | 4 | .\" and Copyright 2003, 2015 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 5 | .\" |
1dd72f9c | 6 | .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
fea681da MK |
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 | |
c715f741 MK |
23 | .\" License along with this manual; if not, see |
24 | .\" <http://www.gnu.org/licenses/>. | |
6a8d8745 | 25 | .\" %%%LICENSE_END |
fea681da MK |
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 | 32 | .\" Modified by Walter Harms: dladdr, dlvsym |
27a61e86 | 33 | .\" Modified by Petr Baudis <pasky@suse.cz>, 2008-12-04: dladdr caveat |
fea681da | 34 | .\" |
4b8c67d9 | 35 | .TH DLOPEN 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
fea681da | 36 | .SH NAME |
374b34d3 MK |
37 | dlclose, dlopen, dlmopen \- |
38 | open and close a shared object | |
fea681da MK |
39 | .SH SYNOPSIS |
40 | .B #include <dlfcn.h> | |
68e4db0a | 41 | .PP |
cf2789f1 | 42 | .BI "void *dlopen(const char *" filename ", int " flags ); |
68e4db0a | 43 | .PP |
fea681da | 44 | .BI "int dlclose(void *" handle ); |
68e4db0a | 45 | .PP |
3f4c09d0 MK |
46 | .B #define _GNU_SOURCE |
47 | .br | |
48 | .B #include <dlfcn.h> | |
68e4db0a | 49 | .PP |
efdd68a5 | 50 | .BI "void *dlmopen (Lmid_t " lmid ", const char *" filename ", int " flags ); |
68e4db0a | 51 | .PP |
3f37321b | 52 | Link with \fI\-ldl\fP. |
fea681da | 53 | .SH DESCRIPTION |
73d8cece | 54 | .SS dlopen() |
fea681da | 55 | The function |
d355f1ed | 56 | .BR dlopen () |
43151de3 MK |
57 | loads the dynamic shared object (shared library) |
58 | file named by the null-terminated | |
fea681da MK |
59 | string |
60 | .I filename | |
43151de3 | 61 | and returns an opaque "handle" for the loaded object. |
6ceba646 MK |
62 | This handle is employed with other functions in the dlopen API, such as |
63 | .BR dlsym (3), | |
64 | .BR dladdr (3), | |
65 | .BR dlinfo (3), | |
66 | and | |
67 | .BR dlclose (). | |
847e0d88 | 68 | .PP |
fea681da MK |
69 | If |
70 | .I filename | |
6962fdf9 MK |
71 | .\" FIXME On Solaris, when handle is NULL, we seem to get back |
72 | .\" a handle for (something like) the root of the namespace. | |
73 | .\" The point here is that if we do a dlmopen(LM_ID_NEWLM), then | |
74 | .\" the filename==NULL case returns a different handle than | |
75 | .\" in the initial namespace. But, on glibc, the same handle is | |
76 | .\" returned. This is probably a bug in glibc. | |
77 | .\" | |
fea681da MK |
78 | is NULL, then the returned handle is for the main program. |
79 | If | |
80 | .I filename | |
81 | contains a slash ("/"), then it is interpreted as a (relative | |
82 | or absolute) pathname. | |
43151de3 | 83 | Otherwise, the dynamic linker searches for the object as follows |
fea681da MK |
84 | (see |
85 | .BR ld.so (8) | |
86 | for further details): | |
86100362 | 87 | .IP o 4 |
fea681da MK |
88 | (ELF only) If the executable file for the calling program |
89 | contains a DT_RPATH tag, and does not contain a DT_RUNPATH tag, | |
90 | then the directories listed in the DT_RPATH tag are searched. | |
91 | .IP o | |
65f6a3ee | 92 | If, at the time that the program was started, the environment variable |
0daa9e92 | 93 | .B LD_LIBRARY_PATH |
65f6a3ee | 94 | was defined to contain a colon-separated list of directories, |
fea681da | 95 | then these are searched. |
8ac45f42 | 96 | (As a security measure, this variable is ignored for set-user-ID and |
880f5b4b | 97 | set-group-ID programs.) |
fea681da MK |
98 | .IP o |
99 | (ELF only) If the executable file for the calling program | |
100 | contains a DT_RUNPATH tag, then the directories listed in that tag | |
101 | are searched. | |
102 | .IP o | |
103 | The cache file | |
0daa9e92 | 104 | .I /etc/ld.so.cache |
fea681da MK |
105 | (maintained by |
106 | .BR ldconfig (8)) | |
107 | is checked to see whether it contains an entry for | |
108 | .IR filename . | |
109 | .IP o | |
110 | The directories | |
c13182ef MK |
111 | .I /lib |
112 | and | |
113 | .I /usr/lib | |
fea681da MK |
114 | are searched (in that order). |
115 | .PP | |
43151de3 MK |
116 | If the object specified by |
117 | .I filename | |
118 | has dependencies on other shared objects, | |
fea681da | 119 | then these are also automatically loaded by the dynamic linker |
c13182ef MK |
120 | using the same rules. |
121 | (This process may occur recursively, | |
43151de3 | 122 | if those objects in turn have dependencies, and so on.) |
fea681da | 123 | .PP |
336e88f0 | 124 | One of the following two values must be included in |
cf2789f1 | 125 | .IR flags : |
336e88f0 | 126 | .TP |
fea681da | 127 | .B RTLD_LAZY |
c13182ef | 128 | Perform lazy binding. |
79039742 | 129 | Resolve symbols only as the code that references them is executed. |
336e88f0 | 130 | If the symbol is never referenced, then it is never resolved. |
33a0ccb2 | 131 | (Lazy binding is performed only for function references; |
336e88f0 | 132 | references to variables are always immediately bound when |
43151de3 | 133 | the shared object is loaded.) |
50008330 MK |
134 | Since glibc 2.1.1, |
135 | .\" commit 12b5b6b7f78ea111e89bbf638294a5413c791072 | |
136 | this flag is overridden by the effect of the | |
137 | .B LD_BIND_NOW | |
138 | environment variable. | |
336e88f0 | 139 | .TP |
fea681da | 140 | .B RTLD_NOW |
336e88f0 | 141 | If this value is specified, or the environment variable |
fea681da | 142 | .B LD_BIND_NOW |
aa796481 | 143 | is set to a nonempty string, |
43151de3 | 144 | all undefined symbols in the shared object are resolved before |
d355f1ed | 145 | .BR dlopen () |
c13182ef MK |
146 | returns. |
147 | If this cannot be done, an error is returned. | |
fea681da | 148 | .PP |
dfacdd0a | 149 | Zero or more of the following values may also be ORed in |
cf2789f1 | 150 | .IR flags : |
336e88f0 | 151 | .TP |
fea681da | 152 | .B RTLD_GLOBAL |
43151de3 | 153 | The symbols defined by this shared object will be |
fe854f15 | 154 | made available for symbol resolution of subsequently loaded shared objects. |
c13182ef | 155 | .TP |
336e88f0 | 156 | .B RTLD_LOCAL |
c13182ef | 157 | This is the converse of |
336e88f0 MK |
158 | .BR RTLD_GLOBAL , |
159 | and the default if neither flag is specified. | |
43151de3 MK |
160 | Symbols defined in this shared object are not made available to resolve |
161 | references in subsequently loaded shared objects. | |
336e88f0 | 162 | .TP |
c10859eb | 163 | .BR RTLD_NODELETE " (since glibc 2.2)" |
43151de3 | 164 | Do not unload the shared object during |
336e88f0 | 165 | .BR dlclose (). |
43151de3 MK |
166 | Consequently, the object's static variables are not reinitialized |
167 | if the object is reloaded with | |
336e88f0 MK |
168 | .BR dlopen () |
169 | at a later time. | |
336e88f0 | 170 | .TP |
c10859eb | 171 | .BR RTLD_NOLOAD " (since glibc 2.2)" |
43151de3 MK |
172 | Don't load the shared object. |
173 | This can be used to test if the object is already resident | |
336e88f0 | 174 | .RB ( dlopen () |
43151de3 MK |
175 | returns NULL if it is not, or the object's handle if it is resident). |
176 | This flag can also be used to promote the flags on a shared object | |
336e88f0 | 177 | that is already loaded. |
43151de3 | 178 | For example, a shared object that was previously loaded with |
336e88f0 | 179 | .B RTLD_LOCAL |
3b777aff | 180 | can be reopened with |
336e88f0 | 181 | .BR RTLD_NOLOAD\ |\ RTLD_GLOBAL . |
336e88f0 | 182 | .\" |
bba06189 MK |
183 | .TP |
184 | .BR RTLD_DEEPBIND " (since glibc 2.3.4)" | |
c13182ef | 185 | .\" Inimitably described by UD in |
a3a11667 | 186 | .\" http://sources.redhat.com/ml/libc-hacker/2004-09/msg00083.html. |
c13182ef | 187 | Place the lookup scope of the symbols in this |
43151de3 MK |
188 | shared object ahead of the global scope. |
189 | This means that a self-contained object will use | |
c13182ef | 190 | its own symbols in preference to global symbols with the same name |
43151de3 | 191 | contained in objects that have already been loaded. |
fea681da MK |
192 | .PP |
193 | If | |
194 | .I filename | |
b437fdd9 | 195 | is NULL, then the returned handle is for the main program. |
fea681da | 196 | When given to |
d355f1ed | 197 | .BR dlsym (), |
fea681da | 198 | this handle causes a search for a symbol in the main program, |
43151de3 MK |
199 | followed by all shared objects loaded at program startup, |
200 | and then all shared objects loaded by | |
d355f1ed | 201 | .BR dlopen () |
fea681da | 202 | with the flag |
a5e0a0e4 | 203 | .BR RTLD_GLOBAL . |
fea681da | 204 | .PP |
43151de3 MK |
205 | External references in the shared object are resolved using the |
206 | shared objects in that object's dependency list and any other | |
207 | objects previously opened with the | |
fea681da MK |
208 | .B RTLD_GLOBAL |
209 | flag. | |
2bc2f479 MK |
210 | If the executable was linked with the flag "\-rdynamic" |
211 | (or, synonymously, "\-\-export\-dynamic"), | |
fea681da | 212 | then the global symbols in the executable will also be used |
43151de3 | 213 | to resolve references in a dynamically loaded shared object. |
fea681da | 214 | .PP |
43151de3 | 215 | If the same shared object is loaded again with |
d355f1ed | 216 | .BR dlopen (), |
43151de3 | 217 | the same object handle is returned. |
e83ed17d | 218 | The dynamic linker maintains reference |
43151de3 | 219 | counts for object handles, so a dynamically loaded shared object is not |
fea681da | 220 | deallocated until |
d355f1ed | 221 | .BR dlclose () |
fea681da | 222 | has been called on it as many times as |
d355f1ed | 223 | .BR dlopen () |
c13182ef | 224 | has succeeded on it. |
c7c01315 | 225 | Any initialization returns (see below) are called just once. |
b6779d1d MK |
226 | However, a subsequent |
227 | .BR dlopen () | |
228 | call that loads the same shared object with | |
fea681da | 229 | .B RTLD_NOW |
9c169754 | 230 | may force symbol resolution for a shared object earlier loaded with |
fea681da MK |
231 | .BR RTLD_LAZY . |
232 | .PP | |
233 | If | |
d355f1ed | 234 | .BR dlopen () |
fea681da | 235 | fails for any reason, it returns NULL. |
9c169754 | 236 | .\" |
efdd68a5 MK |
237 | .SS dlmopen() |
238 | This function performs the same task as | |
239 | .BR dlopen ()\(emthe | |
240 | .I filename | |
241 | and | |
242 | .I flags | |
65175b1d MK |
243 | arguments, as well as the return value, are the same, |
244 | except for the differences noted below. | |
847e0d88 | 245 | .PP |
65175b1d MK |
246 | The |
247 | .BR dlmopen () | |
248 | function differs from | |
249 | .BR dlopen () | |
250 | primarily in that it accepts an additional argument, | |
efdd68a5 | 251 | .IR lmid , |
9c169754 MK |
252 | that specifies the link-map list (also referred to as a |
253 | .IR namespace ) | |
254 | in which the shared object should be loaded. | |
efdd68a5 MK |
255 | (By comparison, |
256 | .BR dlopen () | |
9c169754 | 257 | adds the dynamically loaded shared object to the same namespace as |
efdd68a5 MK |
258 | the shared object from which the |
259 | .BR dlopen () | |
260 | call is made.) | |
9c169754 MK |
261 | The |
262 | .I Lmid_t | |
263 | type is an opaque handle that refers to a namespace. | |
847e0d88 | 264 | .PP |
efdd68a5 MK |
265 | The |
266 | .I lmid | |
9c169754 | 267 | argument is either the ID of an existing namespace |
efdd68a5 MK |
268 | .\" FIXME: Is using dlinfo() RTLD_DI_LMID the right technique? |
269 | (which can be obtained using the | |
270 | .BR dlinfo (3) | |
271 | .B RTLD_DI_LMID | |
272 | request) or one of the following special values: | |
273 | .TP | |
274 | .B LM_ID_BASE | |
9c169754 MK |
275 | Load the shared object in the initial namespace |
276 | (i.e., the application's namespace). | |
efdd68a5 MK |
277 | .TP |
278 | .B LM_ID_NEWLM | |
9c169754 | 279 | Create a new namespace and load the shared object in that namespace. |
982eac0d | 280 | The object must have been correctly linked |
9c169754 MK |
281 | to reference all of the other shared objects that it requires, |
282 | since the new namespace is initially empty. | |
65175b1d | 283 | .PP |
65175b1d | 284 | If |
438168a2 | 285 | .I filename |
65175b1d MK |
286 | is NULL, then the only permitted value for |
287 | .I lmid | |
288 | is | |
289 | .BR LM_ID_BASE . | |
73d8cece | 290 | .SS dlclose() |
fea681da | 291 | The function |
d355f1ed | 292 | .BR dlclose () |
43151de3 MK |
293 | decrements the reference count on the |
294 | dynamically loaded shared object referred to by | |
fea681da | 295 | .IR handle . |
4a1af09b | 296 | If the reference count drops to zero, |
43151de3 | 297 | then the object is unloaded. |
cc2ddf2f MK |
298 | All shared objects that were automatically loaded when |
299 | .BR dlopen () | |
300 | was invoked on the object referred to by | |
301 | .I handle | |
302 | are recursively closed in the same manner. | |
847e0d88 | 303 | .PP |
747b2b0a MK |
304 | A successful return from |
305 | .BR dlclose () | |
306 | does not guarantee that the symbols associated with | |
307 | .I handle | |
308 | are removed from the caller's address space. | |
309 | In addition to references resulting from explicit | |
310 | .BR dlopen () | |
311 | calls, a shared object may have been implicitly loaded | |
312 | (and reference counted) because of dependencies in other shared objects. | |
313 | Only when all references have been released can the shared object | |
314 | be removed from the address space. | |
982eac0d MK |
315 | .SH RETURN VALUE |
316 | On success, | |
317 | .BR dlopen () | |
318 | and | |
319 | .BR dlmopen () | |
320 | return a non-NULL handle for the loaded library. | |
321 | On error | |
322 | (file could not be found, was not readable, had the wrong format, | |
323 | or caused errors during loading), | |
324 | these functions return NULL. | |
847e0d88 | 325 | .PP |
982eac0d | 326 | On success, |
d355f1ed | 327 | .BR dlclose () |
9ebcbe13 | 328 | returns 0; on error, it returns a nonzero value. |
847e0d88 | 329 | .PP |
982eac0d MK |
330 | Errors from these functions can be diagnosed using |
331 | .BR dlerror (3). | |
6445992d | 332 | .SH VERSIONS |
374b34d3 | 333 | .BR dlopen () |
6445992d | 334 | and |
374b34d3 | 335 | .BR dlclose () |
6445992d | 336 | are present in glibc 2.0 and later. |
efdd68a5 MK |
337 | .BR dlmopen () |
338 | first appeared in glibc 2.3.4. | |
b23510e5 MK |
339 | .SH ATTRIBUTES |
340 | For an explanation of the terms used in this section, see | |
341 | .BR attributes (7). | |
342 | .TS | |
343 | allbox; | |
344 | lbw30 lb lb | |
345 | l l l. | |
346 | Interface Attribute Value | |
347 | T{ | |
348 | .BR dlopen (), | |
349 | .BR dlmopen (), | |
350 | .BR dlclose () | |
351 | T} Thread safety MT-Safe | |
352 | .TE | |
47297adb | 353 | .SH CONFORMING TO |
2b2581ee | 354 | POSIX.1-2001 describes |
374b34d3 | 355 | .BR dlclose () |
2b2581ee | 356 | and |
896c71d0 | 357 | .BR dlopen (). |
3f4c09d0 | 358 | The |
efdd68a5 | 359 | .BR dlmopen () |
896c71d0 | 360 | function is a GNU extension. |
847e0d88 | 361 | .PP |
e8a1758c MK |
362 | The |
363 | .BR RTLD_NOLOAD , | |
364 | .BR RTLD_NODELETE , | |
365 | and | |
1a08b97b | 366 | .BR RTLD_DEEPBIND |
e8a1758c MK |
367 | flags are GNU extensions; |
368 | the first two of these flags are also present on Solaris. | |
2b2581ee | 369 | .SH NOTES |
9c169754 MK |
370 | .SS dlmopen() and namespaces |
371 | A link-map list defines an isolated namespace for the | |
372 | resolution of symbols by the dynamic linker. | |
373 | Within a namespace, | |
374 | dependent shared objects are implicitly loaded according to the usual rules, | |
375 | and symbol references are likewise resolved according to the usual rules, | |
376 | but such resolution is confined to the definitions provided by the | |
377 | objects that have been (explicitly and implicitly) loaded into the namespace. | |
847e0d88 | 378 | .PP |
9c169754 MK |
379 | The |
380 | .BR dlmopen () | |
381 | function permits object-load isolation\(emthe ability | |
382 | to load a shared object in a new namespace without | |
383 | exposing the rest of the application to the symbols | |
384 | made available by the new object. | |
385 | Note that the use of the | |
386 | .B RTLD_LOCAL | |
387 | flag is not sufficient for this purpose, | |
388 | since it prevents a shared object's symbols from being available to | |
389 | .I any | |
390 | other shared object. | |
391 | In some cases, | |
392 | we may want to make the symbols provided by a dynamically | |
43151de3 | 393 | loaded shared object available to (a subset of) other shared objects |
9c169754 | 394 | without exposing those symbols to the entire application. |
982eac0d MK |
395 | This can be achieved by using a separate namespace and the |
396 | .B RTLD_GLOBAL | |
397 | flag. | |
847e0d88 | 398 | .PP |
0fdbc114 MK |
399 | The |
400 | .BR dlmopen () | |
401 | function also can be used to provide better isolation than the | |
402 | .BR RTLD_LOCAL | |
403 | flag. | |
8dbd75b8 | 404 | In particular, shared objects loaded with |
0fdbc114 MK |
405 | .BR RTLD_LOCAL |
406 | may be promoted to | |
407 | .BR RTLD_GLOBAL | |
408 | if they are dependencies of another shared object loaded with | |
409 | .BR RTLD_GLOBAL . | |
410 | Thus, | |
411 | .BR RTLD_LOCAL | |
412 | is insufficient to isolate a loaded shared object except in the (uncommon) | |
413 | case where one has explicit control over all shared object dependencies. | |
847e0d88 | 414 | .PP |
9c169754 MK |
415 | Possible uses of |
416 | .BR dlmopen () | |
417 | are plugins where the author of the plugin-loading framework | |
418 | can't trust the plugin authors and does not wish | |
419 | any undefined symbols from the plugin framework to be resolved to plugin | |
420 | symbols. | |
421 | Another use is to load the same object more than once. | |
422 | Without the use of | |
982eac0d | 423 | .BR dlmopen (), |
9c169754 MK |
424 | this would require the creation of distinct copies of the shared object file. |
425 | Using | |
982eac0d | 426 | .BR dlmopen (), |
9c169754 MK |
427 | this can be achieved by loading the same shared object file into |
428 | different namespaces. | |
847e0d88 | 429 | .PP |
982eac0d MK |
430 | The glibc implementation supports a maximum of |
431 | .\" DL_NNS | |
432 | 16 namespaces. | |
9c169754 | 433 | .\" |
c7c01315 MK |
434 | .SS Initialization and finalization functions |
435 | Shared objects may export functions using the | |
436 | .B __attribute__((constructor)) | |
437 | and | |
438 | .B __attribute__((destructor)) | |
439 | function attributes. | |
440 | Constructor functions are executed before | |
441 | .BR dlopen () | |
442 | returns, and destructor functions are executed before | |
443 | .BR dlclose () | |
444 | returns. | |
445 | A shared object may export multiple constructors and destructors, | |
446 | and priorities can be associated with each function | |
447 | to determine the order in which they are executed. | |
448 | See the | |
449 | .BR gcc | |
450 | info pages (under "Function attributes") | |
451 | .\" info gcc "C Extensions" "Function attributes" | |
452 | for further information. | |
847e0d88 | 453 | .PP |
c7c01315 MK |
454 | An older method of (partially) achieving the same result is via the use of |
455 | two special symbols recognized by the linker: | |
e8290357 MK |
456 | .B _init |
457 | and | |
458 | .BR _fini . | |
459 | If a dynamically loaded shared object exports a routine named | |
460 | .BR _init (), | |
c7c01315 | 461 | then that code is executed after loading a shared object, before |
e8290357 MK |
462 | .BR dlopen () |
463 | returns. | |
464 | If the shared object exports a routine named | |
465 | .BR _fini (), | |
466 | then that routine is called just before the object is unloaded. | |
c7c01315 MK |
467 | In this case, one must avoid linking against the system startup files, |
468 | which contain default versions of these files; | |
e8290357 MK |
469 | this can be done by using the |
470 | .BR gcc (1) | |
471 | .I \-nostartfiles | |
472 | command-line option. | |
dd3568a1 | 473 | .PP |
c7c01315 MK |
474 | Use of |
475 | .B _init | |
e8290357 | 476 | and |
c7c01315 MK |
477 | .BR _fini |
478 | is now deprecated in favor of the aforementioned | |
479 | constructors and destructors, | |
480 | which among other advantages, | |
481 | permit multiple initialization and finalization functions to be defined. | |
482 | .\" | |
483 | .\" Using these routines, or the gcc | |
484 | .\" .B \-nostartfiles | |
485 | .\" or | |
486 | .\" .B \-nostdlib | |
487 | .\" options, is not recommended. | |
488 | .\" Their use may result in undesired behavior, | |
489 | .\" since the constructor/destructor routines will not be executed | |
490 | .\" (unless special measures are taken). | |
491 | .\" .\" void _init(void) __attribute__((constructor)); | |
492 | .\" .\" void _fini(void) __attribute__((destructor)); | |
e8290357 | 493 | .\" |
847e0d88 | 494 | .PP |
b198e0ae MK |
495 | Since glibc 2.2.3, |
496 | .BR atexit (3) | |
497 | can be used to register an exit handler that is automatically | |
498 | called when a shared object is unloaded. | |
2b2581ee | 499 | .SS History |
896c71d0 | 500 | These functions are part of the dlopen API, derived from SunOS. |
82bd66b8 | 501 | .SH BUGS |
348348b1 | 502 | As at glibc 2.24, specifying the |
82bd66b8 MK |
503 | .BR RTLD_GLOBAL |
504 | flag when calling | |
505 | .BR dlmopen () | |
506 | .\" dlerror(): "invalid mode" | |
507 | generates an error. | |
508 | Furthermore, specifying | |
509 | .BR RTLD_GLOBAL | |
510 | when calling | |
511 | .BR dlopen () | |
512 | results in a program crash | |
513 | .RB ( SIGSEGV ) | |
514 | if the call is made from any object loaded in a | |
515 | namespace other than the initial namespace. | |
fea681da | 516 | .SH EXAMPLE |
2e056718 MK |
517 | The program below loads the (glibc) math library, |
518 | looks up the address of the | |
519 | .BR cos (3) | |
520 | function, and prints the cosine of 2.0. | |
521 | The following is an example of building and running the program: | |
847e0d88 | 522 | .PP |
2e056718 | 523 | .in +4n |
b8302363 | 524 | .EX |
2e056718 MK |
525 | $ \fBcc dlopen_demo.c \-ldl\fP |
526 | $ \fB./a.out\fP | |
527 | \-0.416147 | |
b8302363 | 528 | .EE |
2e056718 MK |
529 | .in |
530 | .SS Program source | |
c7885256 | 531 | \& |
e7d0bb47 | 532 | .EX |
fea681da | 533 | #include <stdio.h> |
b28f7a67 | 534 | #include <stdlib.h> |
fea681da | 535 | #include <dlfcn.h> |
b44cf4bc MK |
536 | #include <gnu/lib-names.h> /* Defines LIBM_SO (which will be a |
537 | string such as "libm.so.6") */ | |
c13182ef | 538 | int |
4373ccc0 | 539 | main(void) |
cf0a9ace | 540 | { |
fea681da MK |
541 | void *handle; |
542 | double (*cosine)(double); | |
543 | char *error; | |
544 | ||
b44cf4bc | 545 | handle = dlopen(LIBM_SO, RTLD_LAZY); |
fea681da | 546 | if (!handle) { |
31a6818e | 547 | fprintf(stderr, "%s\en", dlerror()); |
4c44ffe5 | 548 | exit(EXIT_FAILURE); |
fea681da MK |
549 | } |
550 | ||
551 | dlerror(); /* Clear any existing error */ | |
c73d7281 | 552 | |
29965345 | 553 | cosine = (double (*)(double)) dlsym(handle, "cos"); |
c73d7281 | 554 | |
daf28a2b | 555 | /* According to the ISO C standard, casting between function |
4318a7d0 MK |
556 | pointers and 'void *', as done above, produces undefined results. |
557 | POSIX.1-2003 and POSIX.1-2008 accepted this state of affairs and | |
558 | proposed the following workaround: | |
29965345 MK |
559 | |
560 | *(void **) (&cosine) = dlsym(handle, "cos"); | |
561 | ||
4318a7d0 MK |
562 | This (clumsy) cast conforms with the ISO C standard and will |
563 | avoid any compiler warnings. | |
29965345 | 564 | |
daf28a2b MK |
565 | The 2013 Technical Corrigendum to POSIX.1-2008 (a.k.a. |
566 | POSIX.1-2013) improved matters by requiring that conforming | |
567 | implementations support casting 'void *' to a function pointer. | |
568 | Nevertheless, some compilers (e.g., gcc with the '-pedantic' | |
569 | option) may complain about the cast used in this program. */ | |
570 | .\" http://pubs.opengroup.org/onlinepubs/009695399/functions/dlsym.html#tag_03_112_08 | |
571 | .\" http://pubs.opengroup.org/onlinepubs/9699919799/functions/dlsym.html#tag_16_96_07 | |
5e0622ba | 572 | .\" http://austingroupbugs.net/view.php?id=74 |
c73d7281 | 573 | |
aefd6f89 | 574 | error = dlerror(); |
3487d63b | 575 | if (error != NULL) { |
31a6818e | 576 | fprintf(stderr, "%s\en", error); |
4c44ffe5 | 577 | exit(EXIT_FAILURE); |
fea681da MK |
578 | } |
579 | ||
31a6818e | 580 | printf("%f\en", (*cosine)(2.0)); |
fea681da | 581 | dlclose(handle); |
5bc8c34c | 582 | exit(EXIT_SUCCESS); |
fea681da | 583 | } |
e7d0bb47 | 584 | .EE |
47297adb | 585 | .SH SEE ALSO |
fea681da MK |
586 | .BR ld (1), |
587 | .BR ldd (1), | |
5d95b7d8 | 588 | .BR pldd (1), |
fea681da | 589 | .BR dl_iterate_phdr (3), |
6c46d3bc | 590 | .BR dladdr (3), |
374b34d3 | 591 | .BR dlerror (3), |
46db2df1 | 592 | .BR dlinfo (3), |
896c71d0 | 593 | .BR dlsym (3), |
c18ecec9 | 594 | .BR rtld-audit (7), |
fea681da | 595 | .BR ld.so (8), |
173fe7e7 | 596 | .BR ldconfig (8) |
847e0d88 | 597 | .PP |
7e936c29 | 598 | gcc info pages, ld info pages |