Debian Codegraph @

upstream/debian-trixie/man3/dlopen.3

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