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