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