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).
4 .\" and Copyright 2003, 2015 Michael Kerrisk <mtk.manpages@gmail.com>
6 .\" SPDX-License-Identifier: GPL-2.0-or-later
8 .\" Modified by David A. Wheeler <dwheeler@dwheeler.com> 2000-11-28.
9 .\" Applied patch by Terran Melconian, aeb, 2001-12-14.
10 .\" Modified by Hacksaw <hacksaw@hacksaw.org> 2003-03-13.
11 .\" Modified by Matt Domsch, 2003-04-09: _init and _fini obsolete
12 .\" Modified by Michael Kerrisk <mtk.manpages@gmail.com> 2003-05-16.
13 .\" Modified by Walter Harms: dladdr, dlvsym
14 .\" Modified by Petr Baudis <pasky@suse.cz>, 2008-12-04: dladdr caveat
16 .TH DLOPEN 3 2021-03-22 "Linux" "Linux Programmer's Manual"
18 dlclose, dlopen, dlmopen \-
19 open and close a shared object
21 Dynamic linking library
22 .RI ( libdl ", " \-ldl )
27 .BI "void *dlopen(const char *" filename ", int " flags );
28 .BI "int dlclose(void *" handle );
30 .B #define _GNU_SOURCE
34 .BI "void *dlmopen(Lmid_t " lmid ", const char *" filename ", int " flags );
40 loads the dynamic shared object (shared library)
41 file named by the null-terminated
44 and returns an opaque "handle" for the loaded object.
45 This handle is employed with other functions in the dlopen API, such as
54 .\" FIXME On Solaris, when handle is NULL, we seem to get back
55 .\" a handle for (something like) the root of the namespace.
56 .\" The point here is that if we do a dlmopen(LM_ID_NEWLM), then
57 .\" the filename==NULL case returns a different handle than
58 .\" in the initial namespace. But, on glibc, the same handle is
59 .\" returned. This is probably a bug in glibc.
61 is NULL, then the returned handle is for the main program.
64 contains a slash ("/"), then it is interpreted as a (relative
65 or absolute) pathname.
66 Otherwise, the dynamic linker searches for the object as follows
71 (ELF only) If the calling object
72 (i.e., the shared library or executable from which
75 contains a DT_RPATH tag, and does not contain a DT_RUNPATH tag,
76 then the directories listed in the DT_RPATH tag are searched.
78 If, at the time that the program was started, the environment variable
80 was defined to contain a colon-separated list of directories,
81 then these are searched.
82 (As a security measure, this variable is ignored for set-user-ID and
83 set-group-ID programs.)
85 (ELF only) If the calling object
86 contains a DT_RUNPATH tag, then the directories listed in that tag
93 is checked to see whether it contains an entry for
100 are searched (in that order).
102 If the object specified by
104 has dependencies on other shared objects,
105 then these are also automatically loaded by the dynamic linker
106 using the same rules.
107 (This process may occur recursively,
108 if those objects in turn have dependencies, and so on.)
110 One of the following two values must be included in
114 Perform lazy binding.
115 Resolve symbols only as the code that references them is executed.
116 If the symbol is never referenced, then it is never resolved.
117 (Lazy binding is performed only for function references;
118 references to variables are always immediately bound when
119 the shared object is loaded.)
121 .\" commit 12b5b6b7f78ea111e89bbf638294a5413c791072
122 this flag is overridden by the effect of the
124 environment variable.
127 If this value is specified, or the environment variable
129 is set to a nonempty string,
130 all undefined symbols in the shared object are resolved before
133 If this cannot be done, an error is returned.
135 Zero or more of the following values may also be ORed in
139 The symbols defined by this shared object will be
140 made available for symbol resolution of subsequently loaded shared objects.
143 This is the converse of
145 and the default if neither flag is specified.
146 Symbols defined in this shared object are not made available to resolve
147 references in subsequently loaded shared objects.
149 .BR RTLD_NODELETE " (since glibc 2.2)"
150 Do not unload the shared object during
152 Consequently, the object's static and global variables are not reinitialized
153 if the object is reloaded with
157 .BR RTLD_NOLOAD " (since glibc 2.2)"
158 Don't load the shared object.
159 This can be used to test if the object is already resident
161 returns NULL if it is not, or the object's handle if it is resident).
162 This flag can also be used to promote the flags on a shared object
163 that is already loaded.
164 For example, a shared object that was previously loaded with
167 .BR RTLD_NOLOAD\ |\ RTLD_GLOBAL .
170 .BR RTLD_DEEPBIND " (since glibc 2.3.4)"
171 .\" Inimitably described by UD in
172 .\" http://sources.redhat.com/ml/libc-hacker/2004-09/msg00083.html.
173 Place the lookup scope of the symbols in this
174 shared object ahead of the global scope.
175 This means that a self-contained object will use
176 its own symbols in preference to global symbols with the same name
177 contained in objects that have already been loaded.
181 is NULL, then the returned handle is for the main program.
184 this handle causes a search for a symbol in the main program,
185 followed by all shared objects loaded at program startup,
186 and then all shared objects loaded by
191 Symbol references in the shared object are resolved using (in order):
192 symbols in the link map of objects loaded for the main program and its
194 symbols in shared objects (and their dependencies)
195 that were previously opened with
200 and definitions in the shared object itself
201 (and any dependencies that were loaded for that object).
203 Any global symbols in the executable that were placed into
204 its dynamic symbol table by
206 can also be used to resolve references in a dynamically loaded shared object.
207 Symbols may be placed in the dynamic symbol table
208 either because the executable was linked with the flag "\-rdynamic"
209 (or, synonymously, "\-\-export\-dynamic"), which causes all of
210 the executable's global symbols to be placed in the dynamic symbol table,
213 noted a dependency on a symbol in another object during static linking.
215 If the same shared object is opened again with
217 the same object handle is returned.
218 The dynamic linker maintains reference
219 counts for object handles, so a dynamically loaded shared object is not
222 has been called on it as many times as
225 Constructors (see below) are called only when the object is actually loaded
226 into memory (i.e., when the reference count increases to 1).
230 call that loads the same shared object with
232 may force symbol resolution for a shared object earlier loaded with
234 Similarly, an object that was previously opened with
243 fails for any reason, it returns NULL.
246 This function performs the same task as
251 arguments, as well as the return value, are the same,
252 except for the differences noted below.
256 function differs from
258 primarily in that it accepts an additional argument,
260 that specifies the link-map list (also referred to as a
262 in which the shared object should be loaded.
265 adds the dynamically loaded shared object to the same namespace as
266 the shared object from which the
271 type is an opaque handle that refers to a namespace.
275 argument is either the ID of an existing namespace
276 .\" FIXME: Is using dlinfo() RTLD_DI_LMID the right technique?
277 (which can be obtained using the
280 request) or one of the following special values:
283 Load the shared object in the initial namespace
284 (i.e., the application's namespace).
287 Create a new namespace and load the shared object in that namespace.
288 The object must have been correctly linked
289 to reference all of the other shared objects that it requires,
290 since the new namespace is initially empty.
294 is NULL, then the only permitted value for
301 decrements the reference count on the
302 dynamically loaded shared object referred to by
305 If the object's reference count drops to zero
306 and no symbols in this object are required by other objects,
307 then the object is unloaded
308 after first calling any destructors defined for the object.
309 (Symbols in this object might be required in another object
310 because this object was opened with the
312 flag and one of its symbols satisfied a relocation in another object.)
314 All shared objects that were automatically loaded when
316 was invoked on the object referred to by
318 are recursively closed in the same manner.
320 A successful return from
322 does not guarantee that the symbols associated with
324 are removed from the caller's address space.
325 In addition to references resulting from explicit
327 calls, a shared object may have been implicitly loaded
328 (and reference counted) because of dependencies in other shared objects.
329 Only when all references have been released can the shared object
330 be removed from the address space.
336 return a non-NULL handle for the loaded object.
338 (file could not be found, was not readable, had the wrong format,
339 or caused errors during loading),
340 these functions return NULL.
344 returns 0; on error, it returns a nonzero value.
346 Errors from these functions can be diagnosed using
352 are present in glibc 2.0 and later.
354 first appeared in glibc 2.3.4.
356 For an explanation of the terms used in this section, see
364 Interface Attribute Value
369 T} Thread safety MT-Safe
375 POSIX.1-2001 describes
381 function is a GNU extension.
388 flags are GNU extensions;
389 the first two of these flags are also present on Solaris.
391 .SS dlmopen() and namespaces
392 A link-map list defines an isolated namespace for the
393 resolution of symbols by the dynamic linker.
395 dependent shared objects are implicitly loaded according to the usual rules,
396 and symbol references are likewise resolved according to the usual rules,
397 but such resolution is confined to the definitions provided by the
398 objects that have been (explicitly and implicitly) loaded into the namespace.
402 function permits object-load isolation\(emthe ability
403 to load a shared object in a new namespace without
404 exposing the rest of the application to the symbols
405 made available by the new object.
406 Note that the use of the
408 flag is not sufficient for this purpose,
409 since it prevents a shared object's symbols from being available to
413 we may want to make the symbols provided by a dynamically
414 loaded shared object available to (a subset of) other shared objects
415 without exposing those symbols to the entire application.
416 This can be achieved by using a separate namespace and the
422 function also can be used to provide better isolation than the
425 In particular, shared objects loaded with
429 if they are dependencies of another shared object loaded with
433 is insufficient to isolate a loaded shared object except in the (uncommon)
434 case where one has explicit control over all shared object dependencies.
438 are plugins where the author of the plugin-loading framework
439 can't trust the plugin authors and does not wish
440 any undefined symbols from the plugin framework to be resolved to plugin
442 Another use is to load the same object more than once.
445 this would require the creation of distinct copies of the shared object file.
448 this can be achieved by loading the same shared object file into
449 different namespaces.
451 The glibc implementation supports a maximum of
455 .SS Initialization and finalization functions
456 Shared objects may export functions using the
457 .B __attribute__((constructor))
459 .B __attribute__((destructor))
461 Constructor functions are executed before
463 returns, and destructor functions are executed before
466 A shared object may export multiple constructors and destructors,
467 and priorities can be associated with each function
468 to determine the order in which they are executed.
471 info pages (under "Function attributes")
472 .\" info gcc "C Extensions" "Function attributes"
473 for further information.
475 An older method of (partially) achieving the same result is via the use of
476 two special symbols recognized by the linker:
480 If a dynamically loaded shared object exports a routine named
482 then that code is executed after loading a shared object, before
485 If the shared object exports a routine named
487 then that routine is called just before the object is unloaded.
488 In this case, one must avoid linking against the system startup files,
489 which contain default versions of these files;
490 this can be done by using the
499 is now deprecated in favor of the aforementioned
500 constructors and destructors,
501 which among other advantages,
502 permit multiple initialization and finalization functions to be defined.
504 .\" Using these routines, or the gcc
505 .\" .B \-nostartfiles
508 .\" options, is not recommended.
509 .\" Their use may result in undesired behavior,
510 .\" since the constructor/destructor routines will not be executed
511 .\" (unless special measures are taken).
512 .\" .\" void _init(void) __attribute__((constructor));
513 .\" .\" void _fini(void) __attribute__((destructor));
518 can be used to register an exit handler that is automatically
519 called when a shared object is unloaded.
521 These functions are part of the dlopen API, derived from SunOS.
523 As at glibc 2.24, specifying the
527 .\" dlerror(): "invalid mode"
529 Furthermore, specifying
533 results in a program crash
535 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=18684
536 if the call is made from any object loaded in a
537 namespace other than the initial namespace.
539 The program below loads the (glibc) math library,
540 looks up the address of the
542 function, and prints the cosine of 2.0.
543 The following is an example of building and running the program:
547 $ \fBcc dlopen_demo.c \-ldl\fP
558 #include <gnu/lib\-names.h> /* Defines LIBM_SO (which will be a
559 string such as "libm.so.6") */
564 double (*cosine)(double);
567 handle = dlopen(LIBM_SO, RTLD_LAZY);
569 fprintf(stderr, "%s\en", dlerror());
573 dlerror(); /* Clear any existing error */
575 cosine = (double (*)(double)) dlsym(handle, "cos");
577 /* According to the ISO C standard, casting between function
578 pointers and \(aqvoid *\(aq, as done above, produces undefined results.
579 POSIX.1\-2001 and POSIX.1\-2008 accepted this state of affairs and
580 proposed the following workaround:
582 *(void **) (&cosine) = dlsym(handle, "cos");
584 This (clumsy) cast conforms with the ISO C standard and will
585 avoid any compiler warnings.
587 The 2013 Technical Corrigendum 1 to POSIX.1\-2008 improved matters
588 by requiring that conforming implementations support casting
589 \(aqvoid *\(aq to a function pointer. Nevertheless, some compilers
590 (e.g., gcc with the \(aq\-pedantic\(aq option) may complain about the
591 cast used in this program. */
592 .\" http://pubs.opengroup.org/onlinepubs/009695399/functions/dlsym.html#tag_03_112_08
593 .\" http://pubs.opengroup.org/onlinepubs/9699919799/functions/dlsym.html#tag_16_96_07
594 .\" http://austingroupbugs.net/view.php?id=74
598 fprintf(stderr, "%s\en", error);
602 printf("%f\en", (*cosine)(2.0));
611 .BR dl_iterate_phdr (3),
620 gcc info pages, ld info pages