1DLOPEN(3) Linux Programmer's Manual DLOPEN(3)
2
6 dlclose, dlopen, dlmopen - open and close a shared object
7
9 #include <dlfcn.h>
10 void *dlopen(const char *filename, int flags);
12 int dlclose(void *handle);
14 #define _GNU_SOURCE
16 #include <dlfcn.h>
17 void *dlmopen(Lmid_t lmid, const char *filename, int flags);
19 Link with -ldl.
21
23 dlopen()
24 The function dlopen() loads the dynamic shared object (shared library)
25 file named by the null-terminated string filename and returns an opaque
26 "handle" for the loaded object. This handle is employed with other
27 functions in the dlopen API, such as dlsym(3), dladdr(3), dlinfo(3),
28 and dlclose().
29 If filename is NULL, then the returned handle is for the main program.
31 If filename contains a slash ("/"), then it is interpreted as a (rela‐
32 tive or absolute) pathname. Otherwise, the dynamic linker searches for
33 the object as follows (see ld.so(8) for further details):
34 o (ELF only) If the calling object (i.e., the shared library or exe‐
36 cutable from which dlopen() is called) contains a DT_RPATH tag, and
37 does not contain a DT_RUNPATH tag, then the directories listed in
38 the DT_RPATH tag are searched.
39 o If, at the time that the program was started, the environment vari‐
41 able LD_LIBRARY_PATH was defined to contain a colon-separated list
42 of directories, then these are searched. (As a security measure,
43 this variable is ignored for set-user-ID and set-group-ID pro‐
44 grams.)
45 o (ELF only) If the calling object contains a DT_RUNPATH tag, then
47 the directories listed in that tag are searched.
48 o The cache file /etc/ld.so.cache (maintained by ldconfig(8)) is
50 checked to see whether it contains an entry for filename.
51 o The directories /lib and /usr/lib are searched (in that order).
53 If the object specified by filename has dependencies on other shared
55 objects, then these are also automatically loaded by the dynamic linker
56 using the same rules. (This process may occur recursively, if those
57 objects in turn have dependencies, and so on.)
58 One of the following two values must be included in flags:
60 RTLD_LAZY
62 Perform lazy binding. Resolve symbols only as the code that
63 references them is executed. If the symbol is never referenced,
64 then it is never resolved. (Lazy binding is performed only for
65 function references; references to variables are always immedi‐
66 ately bound when the shared object is loaded.) Since glibc
67 2.1.1, this flag is overridden by the effect of the LD_BIND_NOW
68 environment variable.
69 RTLD_NOW
71 If this value is specified, or the environment variable
72 LD_BIND_NOW is set to a nonempty string, all undefined symbols
73 in the shared object are resolved before dlopen() returns. If
74 this cannot be done, an error is returned.
75 Zero or more of the following values may also be ORed in flags:
77 RTLD_GLOBAL
79 The symbols defined by this shared object will be made available
80 for symbol resolution of subsequently loaded shared objects.
81 RTLD_LOCAL
83 This is the converse of RTLD_GLOBAL, and the default if neither
84 flag is specified. Symbols defined in this shared object are
85 not made available to resolve references in subsequently loaded
86 shared objects.
87 RTLD_NODELETE (since glibc 2.2)
89 Do not unload the shared object during dlclose(). Consequently,
90 the object's static and global variables are not reinitialized
91 if the object is reloaded with dlopen() at a later time.
92 RTLD_NOLOAD (since glibc 2.2)
94 Don't load the shared object. This can be used to test if the
95 object is already resident (dlopen() returns NULL if it is not,
96 or the object's handle if it is resident). This flag can also
97 be used to promote the flags on a shared object that is already
98 loaded. For example, a shared object that was previously loaded
99 with RTLD_LOCAL can be reopened with RTLD_NOLOAD | RTLD_GLOBAL.
100 RTLD_DEEPBIND (since glibc 2.3.4)
102 Place the lookup scope of the symbols in this shared object
103 ahead of the global scope. This means that a self-contained ob‐
104 ject will use its own symbols in preference to global symbols
105 with the same name contained in objects that have already been
106 loaded.
107 If filename is NULL, then the returned handle is for the main program.
109 When given to dlsym(3), this handle causes a search for a symbol in the
110 main program, followed by all shared objects loaded at program startup,
111 and then all shared objects loaded by dlopen() with the flag
112 RTLD_GLOBAL.
113 Symbol references in the shared object are resolved using (in order):
115 symbols in the link map of objects loaded for the main program and its
116 dependencies; symbols in shared objects (and their dependencies) that
117 were previously opened with dlopen() using the RTLD_GLOBAL flag; and
118 definitions in the shared object itself (and any dependencies that were
119 loaded for that object).
120 Any global symbols in the executable that were placed into its dynamic
122 symbol table by ld(1) can also be used to resolve references in a dy‐
123 namically loaded shared object. Symbols may be placed in the dynamic
124 symbol table either because the executable was linked with the flag
125 "-rdynamic" (or, synonymously, "--export-dynamic"), which causes all of
126 the executable's global symbols to be placed in the dynamic symbol ta‐
127 ble, or because ld(1) noted a dependency on a symbol in another object
128 during static linking.
129 If the same shared object is opened again with dlopen(), the same ob‐
131 ject handle is returned. The dynamic linker maintains reference counts
132 for object handles, so a dynamically loaded shared object is not de‐
133 allocated until dlclose() has been called on it as many times as
134 dlopen() has succeeded on it. Constructors (see below) are called only
135 when the object is actually loaded into memory (i.e., when the refer‐
136 ence count increases to 1).
137 A subsequent dlopen() call that loads the same shared object with
139 RTLD_NOW may force symbol resolution for a shared object earlier loaded
140 with RTLD_LAZY. Similarly, an object that was previously opened with
141 RTLD_LOCAL can be promoted to RTLD_GLOBAL in a subsequent dlopen().
142 If dlopen() fails for any reason, it returns NULL.
144 dlmopen()
146 This function performs the same task as dlopen()—the filename and flags
147 arguments, as well as the return value, are the same, except for the
148 differences noted below.
149 The dlmopen() function differs from dlopen() primarily in that it ac‐
151 cepts an additional argument, lmid, that specifies the link-map list
152 (also referred to as a namespace) in which the shared object should be
153 loaded. (By comparison, dlopen() adds the dynamically loaded shared
154 object to the same namespace as the shared object from which the
155 dlopen() call is made.) The Lmid_t type is an opaque handle that
156 refers to a namespace.
157 The lmid argument is either the ID of an existing namespace (which can
159 be obtained using the dlinfo(3) RTLD_DI_LMID request) or one of the
160 following special values:
161 LM_ID_BASE
163 Load the shared object in the initial namespace (i.e., the ap‐
164 plication's namespace).
165 LM_ID_NEWLM
167 Create a new namespace and load the shared object in that name‐
168 space. The object must have been correctly linked to reference
169 all of the other shared objects that it requires, since the new
170 namespace is initially empty.
171 If filename is NULL, then the only permitted value for lmid is
173 LM_ID_BASE.
174 dlclose()
176 The function dlclose() decrements the reference count on the dynami‐
177 cally loaded shared object referred to by handle.
178 If the object's reference count drops to zero and no symbols in this
180 object are required by other objects, then the object is unloaded after
181 first calling any destructors defined for the object. (Symbols in this
182 object might be required in another object because this object was
183 opened with the RTLD_GLOBAL flag and one of its symbols satisfied a re‐
184 location in another object.)
185 All shared objects that were automatically loaded when dlopen() was in‐
187 voked on the object referred to by handle are recursively closed in the
188 same manner.
189 A successful return from dlclose() does not guarantee that the symbols
191 associated with handle are removed from the caller's address space. In
192 addition to references resulting from explicit dlopen() calls, a shared
193 object may have been implicitly loaded (and reference counted) because
194 of dependencies in other shared objects. Only when all references have
195 been released can the shared object be removed from the address space.
196
198 On success, dlopen() and dlmopen() return a non-NULL handle for the
199 loaded object. On error (file could not be found, was not readable,
200 had the wrong format, or caused errors during loading), these functions
201 return NULL.
202 On success, dlclose() returns 0; on error, it returns a nonzero value.
204 Errors from these functions can be diagnosed using dlerror(3).
206
208 dlopen() and dlclose() are present in glibc 2.0 and later. dlmopen()
209 first appeared in glibc 2.3.4.
210
212 For an explanation of the terms used in this section, see at‐
213 tributes(7).
214 ┌───────────────────────────────┬───────────────┬─────────┐
216 │Interface │ Attribute │ Value │
217 ├───────────────────────────────┼───────────────┼─────────┤
218 │dlopen(), dlmopen(), dlclose() │ Thread safety │ MT-Safe │
219 └───────────────────────────────┴───────────────┴─────────┘
221 POSIX.1-2001 describes dlclose() and dlopen(). The dlmopen() function
222 is a GNU extension.
223 The RTLD_NOLOAD, RTLD_NODELETE, and RTLD_DEEPBIND flags are GNU exten‐
225 sions; the first two of these flags are also present on Solaris.
226
228 dlmopen() and namespaces
229 A link-map list defines an isolated namespace for the resolution of
230 symbols by the dynamic linker. Within a namespace, dependent shared
231 objects are implicitly loaded according to the usual rules, and symbol
232 references are likewise resolved according to the usual rules, but such
233 resolution is confined to the definitions provided by the objects that
234 have been (explicitly and implicitly) loaded into the namespace.
235 The dlmopen() function permits object-load isolation—the ability to
237 load a shared object in a new namespace without exposing the rest of
238 the application to the symbols made available by the new object. Note
239 that the use of the RTLD_LOCAL flag is not sufficient for this purpose,
240 since it prevents a shared object's symbols from being available to any
241 other shared object. In some cases, we may want to make the symbols
242 provided by a dynamically loaded shared object available to (a subset
243 of) other shared objects without exposing those symbols to the entire
244 application. This can be achieved by using a separate namespace and
245 the RTLD_GLOBAL flag.
246 The dlmopen() function also can be used to provide better isolation
248 than the RTLD_LOCAL flag. In particular, shared objects loaded with
249 RTLD_LOCAL may be promoted to RTLD_GLOBAL if they are dependencies of
250 another shared object loaded with RTLD_GLOBAL. Thus, RTLD_LOCAL is in‐
251 sufficient to isolate a loaded shared object except in the (uncommon)
252 case where one has explicit control over all shared object dependen‐
253 cies.
254 Possible uses of dlmopen() are plugins where the author of the plugin-
256 loading framework can't trust the plugin authors and does not wish any
257 undefined symbols from the plugin framework to be resolved to plugin
258 symbols. Another use is to load the same object more than once. With‐
259 out the use of dlmopen(), this would require the creation of distinct
260 copies of the shared object file. Using dlmopen(), this can be
261 achieved by loading the same shared object file into different name‐
262 spaces.
263 The glibc implementation supports a maximum of 16 namespaces.
265 Initialization and finalization functions
267 Shared objects may export functions using the __attribute__((construc‐
268 tor)) and __attribute__((destructor)) function attributes. Constructor
269 functions are executed before dlopen() returns, and destructor func‐
270 tions are executed before dlclose() returns. A shared object may ex‐
271 port multiple constructors and destructors, and priorities can be asso‐
272 ciated with each function to determine the order in which they are exe‐
273 cuted. See the gcc info pages (under "Function attributes") for fur‐
274 ther information.
275 An older method of (partially) achieving the same result is via the use
277 of two special symbols recognized by the linker: _init and _fini. If a
278 dynamically loaded shared object exports a routine named _init(), then
279 that code is executed after loading a shared object, before dlopen()
280 returns. If the shared object exports a routine named _fini(), then
281 that routine is called just before the object is unloaded. In this
282 case, one must avoid linking against the system startup files, which
283 contain default versions of these files; this can be done by using the
284 gcc(1) -nostartfiles command-line option.
285 Use of _init and _fini is now deprecated in favor of the aforementioned
287 constructors and destructors, which among other advantages, permit mul‐
288 tiple initialization and finalization functions to be defined.
289 Since glibc 2.2.3, atexit(3) can be used to register an exit handler
291 that is automatically called when a shared object is unloaded.
292 History
294 These functions are part of the dlopen API, derived from SunOS.
295
297 As at glibc 2.24, specifying the RTLD_GLOBAL flag when calling dl‐
298 mopen() generates an error. Furthermore, specifying RTLD_GLOBAL when
299 calling dlopen() results in a program crash (SIGSEGV) if the call is
300 made from any object loaded in a namespace other than the initial name‐
301 space.
302
304 The program below loads the (glibc) math library, looks up the address
305 of the cos(3) function, and prints the cosine of 2.0. The following is
306 an example of building and running the program:
307 $ cc dlopen_demo.c -ldl
309 $ ./a.out
310 -0.416147
311 Program source
313 #include <stdio.h>
315 #include <stdlib.h>
316 #include <dlfcn.h>
317 #include <gnu/lib-names.h> /* Defines LIBM_SO (which will be a
318 string such as "libm.so.6") */
319 int
320 main(void)
321 {
322 void *handle;
323 double (*cosine)(double);
324 char *error;
325 handle = dlopen(LIBM_SO, RTLD_LAZY);
327 if (!handle) {
328 fprintf(stderr, "%s\n", dlerror());
329 exit(EXIT_FAILURE);
330 }
331 dlerror(); /* Clear any existing error */
333 cosine = (double (*)(double)) dlsym(handle, "cos");
335 /* According to the ISO C standard, casting between function
337 pointers and 'void *', as done above, produces undefined results.
338 POSIX.1-2001 and POSIX.1-2008 accepted this state of affairs and
339 proposed the following workaround:
340 *(void **) (&cosine) = dlsym(handle, "cos");
342 This (clumsy) cast conforms with the ISO C standard and will
344 avoid any compiler warnings.
345 The 2013 Technical Corrigendum 1 to POSIX.1-2008 improved matters
347 by requiring that conforming implementations support casting
348 'void *' to a function pointer. Nevertheless, some compilers
349 (e.g., gcc with the '-pedantic' option) may complain about the
350 cast used in this program. */
351 error = dlerror();
353 if (error != NULL) {
354 fprintf(stderr, "%s\n", error);
355 exit(EXIT_FAILURE);
356 }
357 printf("%f\n", (*cosine)(2.0));
359 dlclose(handle);
360 exit(EXIT_SUCCESS);
361 }
362
364 ld(1), ldd(1), pldd(1), dl_iterate_phdr(3), dladdr(3), dlerror(3),
365 dlinfo(3), dlsym(3), rtld-audit(7), ld.so(8), ldconfig(8)
366 gcc info pages, ld info pages
368
370 This page is part of release 5.10 of the Linux man-pages project. A
371 description of the project, information about reporting bugs, and the
372 latest version of this page, can be found at
373 https://www.kernel.org/doc/man-pages/.
374Linux 2020-11-01 DLOPEN(3)