Debian Codegraph @

upstream/debian-unstable/man3/dlopen.3

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