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 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
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.
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.
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.
22 .\" You should have received a copy of the GNU General Public
23 .\" License along with this manual; if not, see
24 .\" <http://www.gnu.org/licenses/>.
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
31 .\" Modified by Michael Kerrisk <mtk.manpages@gmail.com> 2003-05-16.
32 .\" Modified by Walter Harms: dladdr, dlvsym
33 .\" Modified by Petr Baudis <pasky@suse.cz>, 2008-12-04: dladdr caveat
35 .TH DLOPEN 3 2015-08-08 "Linux" "Linux Programmer's Manual"
37 dlclose, dlopen, dlmopen \-
38 open and close a shared object
42 .BI "void *dlopen(const char *" filename ", int " flags );
44 .BI "int dlclose(void *" handle );
46 .B #define _GNU_SOURCE
50 .BI "void *dlmopen (Lmid_t " lmid ", const char *" filename ", int " flags );
52 Link with \fI\-ldl\fP.
57 loads the dynamic shared object (shared library)
58 file named by the null-terminated
61 and returns an opaque "handle" for the loaded object.
62 This handle is employed with other functions in the dlopen API, such as
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.
78 is NULL, then the returned handle is for the main program.
81 contains a slash ("/"), then it is interpreted as a (relative
82 or absolute) pathname.
83 Otherwise, the dynamic linker searches for the object as follows
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.
92 If, at the time that the program was started, the environment variable
94 was defined to contain a colon-separated list of directories,
95 then these are searched.
96 (As a security measure, this variable is ignored for set-user-ID and
97 set-group-ID programs.)
99 (ELF only) If the executable file for the calling program
100 contains a DT_RUNPATH tag, then the directories listed in that tag
107 is checked to see whether it contains an entry for
114 are searched (in that order).
116 If the object specified by
118 has dependencies on other shared objects,
119 then these are also automatically loaded by the dynamic linker
120 using the same rules.
121 (This process may occur recursively,
122 if those objects in turn have dependencies, and so on.)
124 One of the following two values must be included in
128 Perform lazy binding.
129 Only resolve symbols as the code that references them is executed.
130 If the symbol is never referenced, then it is never resolved.
131 (Lazy binding is performed only for function references;
132 references to variables are always immediately bound when
133 the shared object is loaded.)
136 If this value is specified, or the environment variable
138 is set to a nonempty string,
139 all undefined symbols in the shared object are resolved before
142 If this cannot be done, an error is returned.
144 Zero or more of the following values may also be ORed in
148 The symbols defined by this shared object will be
149 made available for symbol resolution of subsequently loaded shared objects.
152 This is the converse of
154 and the default if neither flag is specified.
155 Symbols defined in this shared object are not made available to resolve
156 references in subsequently loaded shared objects.
158 .BR RTLD_NODELETE " (since glibc 2.2)"
159 Do not unload the shared object during
161 Consequently, the object's static variables are not reinitialized
162 if the object is reloaded with
166 .BR RTLD_NOLOAD " (since glibc 2.2)"
167 Don't load the shared object.
168 This can be used to test if the object is already resident
170 returns NULL if it is not, or the object's handle if it is resident).
171 This flag can also be used to promote the flags on a shared object
172 that is already loaded.
173 For example, a shared object that was previously loaded with
176 .BR RTLD_NOLOAD\ |\ RTLD_GLOBAL .
179 .BR RTLD_DEEPBIND " (since glibc 2.3.4)"
180 .\" Inimitably described by UD in
181 .\" http://sources.redhat.com/ml/libc-hacker/2004-09/msg00083.html.
182 Place the lookup scope of the symbols in this
183 shared object ahead of the global scope.
184 This means that a self-contained object will use
185 its own symbols in preference to global symbols with the same name
186 contained in objects that have already been loaded.
190 is NULL, then the returned handle is for the main program.
193 this handle causes a search for a symbol in the main program,
194 followed by all shared objects loaded at program startup,
195 and then all shared objects loaded by
200 External references in the shared object are resolved using the
201 shared objects in that object's dependency list and any other
202 objects previously opened with the
205 If the executable was linked with the flag "\-rdynamic"
206 (or, synonymously, "\-\-export\-dynamic"),
207 then the global symbols in the executable will also be used
208 to resolve references in a dynamically loaded shared object.
210 If the same shared object is loaded again with
212 the same object handle is returned.
213 The dynamic linker maintains reference
214 counts for object handles, so a dynamically loaded shared object is not
217 has been called on it as many times as
220 Any initialization returns (see below) are called just once.
221 However, a subsequent
223 call that loads the same shared object with
225 may force symbol resolution for a shared object earlier loaded with
230 fails for any reason, it returns NULL.
233 This function performs the same task as
238 arguments, as well as the return value, are the same,
239 except for the differences noted below.
243 function differs from
245 primarily in that it accepts an additional argument,
247 that specifies the link-map list (also referred to as a
249 in which the shared object should be loaded.
252 adds the dynamically loaded shared object to the same namespace as
253 the shared object from which the
258 type is an opaque handle that refers to a namespace.
262 argument is either the ID of an existing namespace
263 .\" FIXME: Is using dlinfo() RTLD_DI_LMID the right technique?
264 (which can be obtained using the
267 request) or one of the following special values:
270 Load the shared object in the initial namespace
271 (i.e., the application's namespace).
274 Create a new namespace and load the shared object in that namespace.
275 The object must have been correctly linked
276 to reference all of the other shared objects that it requires,
277 since the new namespace is initially empty.
281 is NULL, then the only permitted value for
288 decrements the reference count on the
289 dynamically loaded shared object referred to by
291 If the reference count drops to zero,
292 then the object is unloaded.
293 All shared objects that were automatically loaded when
295 was invoked on the object referred to by
297 are recursively closed in the same manner.
299 A successful return from
301 does not guarantee that the symbols associated with
303 are removed from the caller's address space.
304 In addition to references resulting from explicit
306 calls, a shared object may have been implicitly loaded
307 (and reference counted) because of dependencies in other shared objects.
308 Only when all references have been released can the shared object
309 be removed from the address space.
315 return a non-NULL handle for the loaded library.
317 (file could not be found, was not readable, had the wrong format,
318 or caused errors during loading),
319 these functions return NULL.
323 returns 0; on error, it returns a nonzero value.
325 Errors from these functions can be diagnosed using
331 are present in glibc 2.0 and later.
333 first appeared in glibc 2.3.4.
335 For an explanation of the terms used in this section, see
341 Interface Attribute Value
346 T} Thread safety MT-Safe
349 POSIX.1-2001 describes
355 function is a GNU extension.
362 flags are GNU extensions;
363 the first two of these flags are also present on Solaris.
365 .SS dlmopen() and namespaces
366 A link-map list defines an isolated namespace for the
367 resolution of symbols by the dynamic linker.
369 dependent shared objects are implicitly loaded according to the usual rules,
370 and symbol references are likewise resolved according to the usual rules,
371 but such resolution is confined to the definitions provided by the
372 objects that have been (explicitly and implicitly) loaded into the namespace.
376 function permits object-load isolation\(emthe ability
377 to load a shared object in a new namespace without
378 exposing the rest of the application to the symbols
379 made available by the new object.
380 Note that the use of the
382 flag is not sufficient for this purpose,
383 since it prevents a shared object's symbols from being available to
387 we may want to make the symbols provided by a dynamically
388 loaded shared object available to (a subset of) other shared objects
389 without exposing those symbols to the entire application.
390 This can be achieved by using a separate namespace and the
396 function also can be used to provide better isolation than the
399 In particular, shared objects laoded with
403 if they are dependencies of another shared object loaded with
407 is insufficient to isolate a loaded shared object except in the (uncommon)
408 case where one has explicit control over all shared object dependencies.
412 are plugins where the author of the plugin-loading framework
413 can't trust the plugin authors and does not wish
414 any undefined symbols from the plugin framework to be resolved to plugin
416 Another use is to load the same object more than once.
419 this would require the creation of distinct copies of the shared object file.
422 this can be achieved by loading the same shared object file into
423 different namespaces.
425 The glibc implementation supports a maximum of
429 .SS Initialization and finalization functions
430 Shared objects may export functions using the
431 .B __attribute__((constructor))
433 .B __attribute__((destructor))
435 Constructor functions are executed before
437 returns, and destructor functions are executed before
440 A shared object may export multiple constructors and destructors,
441 and priorities can be associated with each function
442 to determine the order in which they are executed.
445 info pages (under "Function attributes")
446 .\" info gcc "C Extensions" "Function attributes"
447 for further information.
449 An older method of (partially) achieving the same result is via the use of
450 two special symbols recognized by the linker:
454 If a dynamically loaded shared object exports a routine named
456 then that code is executed after loading a shared object, before
459 If the shared object exports a routine named
461 then that routine is called just before the object is unloaded.
462 In this case, one must avoid linking against the system startup files,
463 which contain default versions of these files;
464 this can be done by using the
473 is now deprecated in favor of the aforementioned
474 constructors and destructors,
475 which among other advantages,
476 permit multiple initialization and finalization functions to be defined.
478 .\" Using these routines, or the gcc
479 .\" .B \-nostartfiles
482 .\" options, is not recommended.
483 .\" Their use may result in undesired behavior,
484 .\" since the constructor/destructor routines will not be executed
485 .\" (unless special measures are taken).
486 .\" .\" void _init(void) __attribute__((constructor));
487 .\" .\" void _fini(void) __attribute__((destructor));
492 can be used to register an exit handler that is automatically
493 called when a shared object is unloaded.
495 These functions are part of the dlopen API, derived from SunOS.
497 Load the math library, and print the cosine of 2.0:
505 main(int argc, char **argv)
508 double (*cosine)(double);
511 handle = dlopen("libm.so", RTLD_LAZY);
513 fprintf(stderr, "%s\en", dlerror());
517 dlerror(); /* Clear any existing error */
519 cosine = (double (*)(double)) dlsym(handle, "cos");
521 /* According to the ISO C standard, casting between function
522 pointers and 'void *', as done above, produces undefined results.
523 POSIX.1-2003 and POSIX.1-2008 accepted this state of affairs and
524 proposed the following workaround:
526 *(void **) (&cosine) = dlsym(handle, "cos");
528 This (clumsy) cast conforms with the ISO C standard and will
529 avoid any compiler warnings.
531 The 2013 Technical Corrigendum to POSIX.1-2008 (a.k.a.
532 POSIX.1-2013) improved matters by requiring that conforming
533 implementations support casting 'void *' to a function pointer.
534 Nevertheless, some compilers (e.g., gcc with the '-pedantic'
535 option) may complain about the cast used in this program. */
536 .\" http://pubs.opengroup.org/onlinepubs/009695399/functions/dlsym.html#tag_03_112_08
537 .\" http://pubs.opengroup.org/onlinepubs/9699919799/functions/dlsym.html#tag_16_96_07
538 .\" http://austingroupbugs.net/view.php?id=74
542 fprintf(stderr, "%s\en", error);
546 printf("%f\en", (*cosine)(2.0));
552 As at glibc 2.21, specifying the
556 .\" dlerror(): "invalid mode"
558 Furthermore, specifying
562 results in a program crash
564 if the call is made from any object loaded in a
565 namespace other than the initial namespace.
570 .BR dl_iterate_phdr (3),
579 gcc info pages, ld info pages