man3/dlopen.3

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