]>
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 | .\" |
63121bd4 | 35 | .TH DLOPEN 3 2019-08-02 "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 (). |
d031ca92 | 166 | Consequently, the object's static and global variables are not reinitialized |
43151de3 | 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 |
e3a78ee9 | 197 | .BR dlsym (3), |
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 |
43898de4 MK |
205 | Symbol references in the shared object are resolved using (in order): |
206 | symbols in the link map of objects loaded for the main program and its | |
207 | dependencies; | |
208 | symbols in shared objects (and their dependencies) | |
209 | that were previously opened with | |
210 | .BR dlopen () | |
211 | using the | |
212 | .BR RTLD_GLOBAL | |
213 | flag; | |
214 | and definitions in the shared object itself | |
215 | (and any dependencies that were loaded for that object). | |
216 | .PP | |
58a4ac49 MK |
217 | Any global symbols in the executable that were placed into |
218 | its dynamic symbol table by | |
219 | .BR ld (1) | |
220 | can also be used to resolve references in a dynamically loaded shared object. | |
221 | Symbols may be placed in the dynamic symbol table | |
222 | either because the executable was linked with the flag "\-rdynamic" | |
223 | (or, synonymously, "\-\-export\-dynamic"), which causes all of | |
224 | the executable's global symbols to be placed in the dynamic symbol table, | |
225 | or because | |
226 | .BR ld (1) | |
227 | noted a dependency on a symbol in another object during static linking. | |
fea681da | 228 | .PP |
df77f62b | 229 | If the same shared object is opened again with |
d355f1ed | 230 | .BR dlopen (), |
43151de3 | 231 | the same object handle is returned. |
e83ed17d | 232 | The dynamic linker maintains reference |
43151de3 | 233 | counts for object handles, so a dynamically loaded shared object is not |
fea681da | 234 | deallocated until |
d355f1ed | 235 | .BR dlclose () |
fea681da | 236 | has been called on it as many times as |
d355f1ed | 237 | .BR dlopen () |
c13182ef | 238 | has succeeded on it. |
f642cc55 | 239 | Constructors (see below) are called only when the object is actually loaded |
df77f62b | 240 | into memory (i.e., when the reference count increases to 1). |
da6b9a61 MK |
241 | .PP |
242 | A subsequent | |
b6779d1d MK |
243 | .BR dlopen () |
244 | call that loads the same shared object with | |
fea681da | 245 | .B RTLD_NOW |
9c169754 | 246 | may force symbol resolution for a shared object earlier loaded with |
fea681da | 247 | .BR RTLD_LAZY . |
9bdbaa8a MK |
248 | Similarly, an object that was previously opened with |
249 | .BR RTLD_LOCAL | |
250 | can be promoted to | |
251 | .BR RTLD_GLOBAL | |
252 | in a subsequent | |
253 | .BR dlopen (). | |
fea681da MK |
254 | .PP |
255 | If | |
d355f1ed | 256 | .BR dlopen () |
fea681da | 257 | fails for any reason, it returns NULL. |
9c169754 | 258 | .\" |
efdd68a5 MK |
259 | .SS dlmopen() |
260 | This function performs the same task as | |
261 | .BR dlopen ()\(emthe | |
262 | .I filename | |
263 | and | |
264 | .I flags | |
65175b1d MK |
265 | arguments, as well as the return value, are the same, |
266 | except for the differences noted below. | |
847e0d88 | 267 | .PP |
65175b1d MK |
268 | The |
269 | .BR dlmopen () | |
270 | function differs from | |
271 | .BR dlopen () | |
272 | primarily in that it accepts an additional argument, | |
efdd68a5 | 273 | .IR lmid , |
9c169754 MK |
274 | that specifies the link-map list (also referred to as a |
275 | .IR namespace ) | |
276 | in which the shared object should be loaded. | |
efdd68a5 MK |
277 | (By comparison, |
278 | .BR dlopen () | |
9c169754 | 279 | adds the dynamically loaded shared object to the same namespace as |
efdd68a5 MK |
280 | the shared object from which the |
281 | .BR dlopen () | |
282 | call is made.) | |
9c169754 MK |
283 | The |
284 | .I Lmid_t | |
285 | type is an opaque handle that refers to a namespace. | |
847e0d88 | 286 | .PP |
efdd68a5 MK |
287 | The |
288 | .I lmid | |
9c169754 | 289 | argument is either the ID of an existing namespace |
efdd68a5 MK |
290 | .\" FIXME: Is using dlinfo() RTLD_DI_LMID the right technique? |
291 | (which can be obtained using the | |
292 | .BR dlinfo (3) | |
293 | .B RTLD_DI_LMID | |
294 | request) or one of the following special values: | |
295 | .TP | |
296 | .B LM_ID_BASE | |
9c169754 MK |
297 | Load the shared object in the initial namespace |
298 | (i.e., the application's namespace). | |
efdd68a5 MK |
299 | .TP |
300 | .B LM_ID_NEWLM | |
9c169754 | 301 | Create a new namespace and load the shared object in that namespace. |
982eac0d | 302 | The object must have been correctly linked |
9c169754 MK |
303 | to reference all of the other shared objects that it requires, |
304 | since the new namespace is initially empty. | |
65175b1d | 305 | .PP |
65175b1d | 306 | If |
438168a2 | 307 | .I filename |
65175b1d MK |
308 | is NULL, then the only permitted value for |
309 | .I lmid | |
310 | is | |
311 | .BR LM_ID_BASE . | |
73d8cece | 312 | .SS dlclose() |
fea681da | 313 | The function |
d355f1ed | 314 | .BR dlclose () |
43151de3 MK |
315 | decrements the reference count on the |
316 | dynamically loaded shared object referred to by | |
fea681da | 317 | .IR handle . |
ba20328e MK |
318 | .PP |
319 | If the object's reference count drops to zero | |
320 | and no symbols in this object are required by other objects, | |
cbd8927f MK |
321 | then the object is unloaded |
322 | after first calling any destructors defined for the object. | |
ba20328e MK |
323 | (Symbols in this object might be required in another object |
324 | because this object was opened with the | |
325 | .BR RTLD_GLOBAL | |
326 | flag and one of its symbols satisfied a relocation in another object.) | |
327 | .PP | |
cc2ddf2f MK |
328 | All shared objects that were automatically loaded when |
329 | .BR dlopen () | |
330 | was invoked on the object referred to by | |
331 | .I handle | |
332 | are recursively closed in the same manner. | |
847e0d88 | 333 | .PP |
747b2b0a MK |
334 | A successful return from |
335 | .BR dlclose () | |
336 | does not guarantee that the symbols associated with | |
337 | .I handle | |
338 | are removed from the caller's address space. | |
339 | In addition to references resulting from explicit | |
340 | .BR dlopen () | |
341 | calls, a shared object may have been implicitly loaded | |
342 | (and reference counted) because of dependencies in other shared objects. | |
343 | Only when all references have been released can the shared object | |
344 | be removed from the address space. | |
982eac0d MK |
345 | .SH RETURN VALUE |
346 | On success, | |
347 | .BR dlopen () | |
348 | and | |
349 | .BR dlmopen () | |
f642cc55 | 350 | return a non-NULL handle for the loaded object. |
982eac0d MK |
351 | On error |
352 | (file could not be found, was not readable, had the wrong format, | |
353 | or caused errors during loading), | |
354 | these functions return NULL. | |
847e0d88 | 355 | .PP |
982eac0d | 356 | On success, |
d355f1ed | 357 | .BR dlclose () |
9ebcbe13 | 358 | returns 0; on error, it returns a nonzero value. |
847e0d88 | 359 | .PP |
982eac0d MK |
360 | Errors from these functions can be diagnosed using |
361 | .BR dlerror (3). | |
6445992d | 362 | .SH VERSIONS |
374b34d3 | 363 | .BR dlopen () |
6445992d | 364 | and |
374b34d3 | 365 | .BR dlclose () |
6445992d | 366 | are present in glibc 2.0 and later. |
efdd68a5 MK |
367 | .BR dlmopen () |
368 | first appeared in glibc 2.3.4. | |
b23510e5 MK |
369 | .SH ATTRIBUTES |
370 | For an explanation of the terms used in this section, see | |
371 | .BR attributes (7). | |
372 | .TS | |
373 | allbox; | |
374 | lbw30 lb lb | |
375 | l l l. | |
376 | Interface Attribute Value | |
377 | T{ | |
378 | .BR dlopen (), | |
379 | .BR dlmopen (), | |
380 | .BR dlclose () | |
381 | T} Thread safety MT-Safe | |
382 | .TE | |
47297adb | 383 | .SH CONFORMING TO |
2b2581ee | 384 | POSIX.1-2001 describes |
374b34d3 | 385 | .BR dlclose () |
2b2581ee | 386 | and |
896c71d0 | 387 | .BR dlopen (). |
3f4c09d0 | 388 | The |
efdd68a5 | 389 | .BR dlmopen () |
896c71d0 | 390 | function is a GNU extension. |
847e0d88 | 391 | .PP |
e8a1758c MK |
392 | The |
393 | .BR RTLD_NOLOAD , | |
394 | .BR RTLD_NODELETE , | |
395 | and | |
1a08b97b | 396 | .BR RTLD_DEEPBIND |
e8a1758c MK |
397 | flags are GNU extensions; |
398 | the first two of these flags are also present on Solaris. | |
2b2581ee | 399 | .SH NOTES |
9c169754 MK |
400 | .SS dlmopen() and namespaces |
401 | A link-map list defines an isolated namespace for the | |
402 | resolution of symbols by the dynamic linker. | |
403 | Within a namespace, | |
404 | dependent shared objects are implicitly loaded according to the usual rules, | |
405 | and symbol references are likewise resolved according to the usual rules, | |
406 | but such resolution is confined to the definitions provided by the | |
407 | objects that have been (explicitly and implicitly) loaded into the namespace. | |
847e0d88 | 408 | .PP |
9c169754 MK |
409 | The |
410 | .BR dlmopen () | |
411 | function permits object-load isolation\(emthe ability | |
412 | to load a shared object in a new namespace without | |
413 | exposing the rest of the application to the symbols | |
414 | made available by the new object. | |
415 | Note that the use of the | |
416 | .B RTLD_LOCAL | |
417 | flag is not sufficient for this purpose, | |
418 | since it prevents a shared object's symbols from being available to | |
419 | .I any | |
420 | other shared object. | |
421 | In some cases, | |
422 | we may want to make the symbols provided by a dynamically | |
43151de3 | 423 | loaded shared object available to (a subset of) other shared objects |
9c169754 | 424 | without exposing those symbols to the entire application. |
982eac0d MK |
425 | This can be achieved by using a separate namespace and the |
426 | .B RTLD_GLOBAL | |
427 | flag. | |
847e0d88 | 428 | .PP |
0fdbc114 MK |
429 | The |
430 | .BR dlmopen () | |
431 | function also can be used to provide better isolation than the | |
432 | .BR RTLD_LOCAL | |
433 | flag. | |
8dbd75b8 | 434 | In particular, shared objects loaded with |
0fdbc114 MK |
435 | .BR RTLD_LOCAL |
436 | may be promoted to | |
437 | .BR RTLD_GLOBAL | |
438 | if they are dependencies of another shared object loaded with | |
439 | .BR RTLD_GLOBAL . | |
440 | Thus, | |
441 | .BR RTLD_LOCAL | |
442 | is insufficient to isolate a loaded shared object except in the (uncommon) | |
443 | case where one has explicit control over all shared object dependencies. | |
847e0d88 | 444 | .PP |
9c169754 MK |
445 | Possible uses of |
446 | .BR dlmopen () | |
447 | are plugins where the author of the plugin-loading framework | |
448 | can't trust the plugin authors and does not wish | |
449 | any undefined symbols from the plugin framework to be resolved to plugin | |
450 | symbols. | |
451 | Another use is to load the same object more than once. | |
452 | Without the use of | |
982eac0d | 453 | .BR dlmopen (), |
9c169754 MK |
454 | this would require the creation of distinct copies of the shared object file. |
455 | Using | |
982eac0d | 456 | .BR dlmopen (), |
9c169754 MK |
457 | this can be achieved by loading the same shared object file into |
458 | different namespaces. | |
847e0d88 | 459 | .PP |
982eac0d MK |
460 | The glibc implementation supports a maximum of |
461 | .\" DL_NNS | |
462 | 16 namespaces. | |
9c169754 | 463 | .\" |
c7c01315 MK |
464 | .SS Initialization and finalization functions |
465 | Shared objects may export functions using the | |
466 | .B __attribute__((constructor)) | |
467 | and | |
468 | .B __attribute__((destructor)) | |
469 | function attributes. | |
470 | Constructor functions are executed before | |
471 | .BR dlopen () | |
472 | returns, and destructor functions are executed before | |
473 | .BR dlclose () | |
474 | returns. | |
475 | A shared object may export multiple constructors and destructors, | |
476 | and priorities can be associated with each function | |
477 | to determine the order in which they are executed. | |
478 | See the | |
479 | .BR gcc | |
480 | info pages (under "Function attributes") | |
481 | .\" info gcc "C Extensions" "Function attributes" | |
482 | for further information. | |
847e0d88 | 483 | .PP |
c7c01315 MK |
484 | An older method of (partially) achieving the same result is via the use of |
485 | two special symbols recognized by the linker: | |
e8290357 MK |
486 | .B _init |
487 | and | |
488 | .BR _fini . | |
489 | If a dynamically loaded shared object exports a routine named | |
490 | .BR _init (), | |
c7c01315 | 491 | then that code is executed after loading a shared object, before |
e8290357 MK |
492 | .BR dlopen () |
493 | returns. | |
494 | If the shared object exports a routine named | |
495 | .BR _fini (), | |
496 | then that routine is called just before the object is unloaded. | |
c7c01315 MK |
497 | In this case, one must avoid linking against the system startup files, |
498 | which contain default versions of these files; | |
e8290357 MK |
499 | this can be done by using the |
500 | .BR gcc (1) | |
501 | .I \-nostartfiles | |
502 | command-line option. | |
dd3568a1 | 503 | .PP |
c7c01315 MK |
504 | Use of |
505 | .B _init | |
e8290357 | 506 | and |
c7c01315 MK |
507 | .BR _fini |
508 | is now deprecated in favor of the aforementioned | |
509 | constructors and destructors, | |
510 | which among other advantages, | |
511 | permit multiple initialization and finalization functions to be defined. | |
512 | .\" | |
513 | .\" Using these routines, or the gcc | |
514 | .\" .B \-nostartfiles | |
515 | .\" or | |
516 | .\" .B \-nostdlib | |
517 | .\" options, is not recommended. | |
518 | .\" Their use may result in undesired behavior, | |
519 | .\" since the constructor/destructor routines will not be executed | |
520 | .\" (unless special measures are taken). | |
521 | .\" .\" void _init(void) __attribute__((constructor)); | |
522 | .\" .\" void _fini(void) __attribute__((destructor)); | |
e8290357 | 523 | .\" |
847e0d88 | 524 | .PP |
b198e0ae MK |
525 | Since glibc 2.2.3, |
526 | .BR atexit (3) | |
527 | can be used to register an exit handler that is automatically | |
528 | called when a shared object is unloaded. | |
2b2581ee | 529 | .SS History |
896c71d0 | 530 | These functions are part of the dlopen API, derived from SunOS. |
82bd66b8 | 531 | .SH BUGS |
348348b1 | 532 | As at glibc 2.24, specifying the |
82bd66b8 MK |
533 | .BR RTLD_GLOBAL |
534 | flag when calling | |
535 | .BR dlmopen () | |
536 | .\" dlerror(): "invalid mode" | |
537 | generates an error. | |
538 | Furthermore, specifying | |
539 | .BR RTLD_GLOBAL | |
540 | when calling | |
541 | .BR dlopen () | |
542 | results in a program crash | |
543 | .RB ( SIGSEGV ) | |
0f553887 | 544 | .\" https://sourceware.org/bugzilla/show_bug.cgi?id=18684 |
82bd66b8 MK |
545 | if the call is made from any object loaded in a |
546 | namespace other than the initial namespace. | |
fea681da | 547 | .SH EXAMPLE |
2e056718 MK |
548 | The program below loads the (glibc) math library, |
549 | looks up the address of the | |
550 | .BR cos (3) | |
551 | function, and prints the cosine of 2.0. | |
552 | The following is an example of building and running the program: | |
847e0d88 | 553 | .PP |
2e056718 | 554 | .in +4n |
b8302363 | 555 | .EX |
2e056718 MK |
556 | $ \fBcc dlopen_demo.c \-ldl\fP |
557 | $ \fB./a.out\fP | |
558 | \-0.416147 | |
b8302363 | 559 | .EE |
2e056718 MK |
560 | .in |
561 | .SS Program source | |
c7885256 | 562 | \& |
e7d0bb47 | 563 | .EX |
fea681da | 564 | #include <stdio.h> |
b28f7a67 | 565 | #include <stdlib.h> |
fea681da | 566 | #include <dlfcn.h> |
b44cf4bc MK |
567 | #include <gnu/lib-names.h> /* Defines LIBM_SO (which will be a |
568 | string such as "libm.so.6") */ | |
c13182ef | 569 | int |
4373ccc0 | 570 | main(void) |
cf0a9ace | 571 | { |
fea681da MK |
572 | void *handle; |
573 | double (*cosine)(double); | |
574 | char *error; | |
575 | ||
b44cf4bc | 576 | handle = dlopen(LIBM_SO, RTLD_LAZY); |
fea681da | 577 | if (!handle) { |
31a6818e | 578 | fprintf(stderr, "%s\en", dlerror()); |
4c44ffe5 | 579 | exit(EXIT_FAILURE); |
fea681da MK |
580 | } |
581 | ||
582 | dlerror(); /* Clear any existing error */ | |
c73d7281 | 583 | |
29965345 | 584 | cosine = (double (*)(double)) dlsym(handle, "cos"); |
c73d7281 | 585 | |
daf28a2b | 586 | /* According to the ISO C standard, casting between function |
4318a7d0 MK |
587 | pointers and 'void *', as done above, produces undefined results. |
588 | POSIX.1-2003 and POSIX.1-2008 accepted this state of affairs and | |
589 | proposed the following workaround: | |
29965345 MK |
590 | |
591 | *(void **) (&cosine) = dlsym(handle, "cos"); | |
592 | ||
4318a7d0 MK |
593 | This (clumsy) cast conforms with the ISO C standard and will |
594 | avoid any compiler warnings. | |
29965345 | 595 | |
daf28a2b MK |
596 | The 2013 Technical Corrigendum to POSIX.1-2008 (a.k.a. |
597 | POSIX.1-2013) improved matters by requiring that conforming | |
598 | implementations support casting 'void *' to a function pointer. | |
599 | Nevertheless, some compilers (e.g., gcc with the '-pedantic' | |
600 | option) may complain about the cast used in this program. */ | |
601 | .\" http://pubs.opengroup.org/onlinepubs/009695399/functions/dlsym.html#tag_03_112_08 | |
602 | .\" http://pubs.opengroup.org/onlinepubs/9699919799/functions/dlsym.html#tag_16_96_07 | |
5e0622ba | 603 | .\" http://austingroupbugs.net/view.php?id=74 |
c73d7281 | 604 | |
aefd6f89 | 605 | error = dlerror(); |
3487d63b | 606 | if (error != NULL) { |
31a6818e | 607 | fprintf(stderr, "%s\en", error); |
4c44ffe5 | 608 | exit(EXIT_FAILURE); |
fea681da MK |
609 | } |
610 | ||
31a6818e | 611 | printf("%f\en", (*cosine)(2.0)); |
fea681da | 612 | dlclose(handle); |
5bc8c34c | 613 | exit(EXIT_SUCCESS); |
fea681da | 614 | } |
e7d0bb47 | 615 | .EE |
47297adb | 616 | .SH SEE ALSO |
fea681da MK |
617 | .BR ld (1), |
618 | .BR ldd (1), | |
5d95b7d8 | 619 | .BR pldd (1), |
fea681da | 620 | .BR dl_iterate_phdr (3), |
6c46d3bc | 621 | .BR dladdr (3), |
374b34d3 | 622 | .BR dlerror (3), |
46db2df1 | 623 | .BR dlinfo (3), |
896c71d0 | 624 | .BR dlsym (3), |
c18ecec9 | 625 | .BR rtld-audit (7), |
fea681da | 626 | .BR ld.so (8), |
173fe7e7 | 627 | .BR ldconfig (8) |
847e0d88 | 628 | .PP |
7e936c29 | 629 | gcc info pages, ld info pages |