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 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 2014-01-08 "Linux" "Linux Programmer's Manual"
  36 .SH NAME
  37 dladdr, dlclose, dlerror, dlopen, dlsym, dlvsym \- programming interface to
  38 dynamic linking loader
  39 .SH SYNOPSIS
  40 .B #include <dlfcn.h>
  41 .sp
  42 .BI "void *dlopen(const char *" filename ", int " flag );
  43 .sp
  44 .B "char *dlerror(void);"
  45 .sp
  46 .BI "void *dlsym(void *" handle ", const char *" symbol );
  47 .sp
  48 .BI "int dlclose(void *" handle );
  49 .sp
  50 Link with \fI\-ldl\fP.
  51 .SH DESCRIPTION
  52 The four functions
  53 .BR dlopen (),
  54 .BR dlsym (),
  55 .BR dlclose (),
  56 .BR dlerror ()
  57 implement the interface to the dynamic linking loader.
  58 .SS dlerror()
  59 The function
  60 .BR dlerror ()
  61 returns a human-readable string describing the most recent error
  62 that occurred from
  63 .BR dlopen (),
  64 .BR dlsym ()
  65 or
  66 .BR dlclose ()
  67 since the last call to
  68 .BR dlerror ().
  69 It returns NULL if no errors have occurred since initialization or since
  70 it was last called.
  71 .SS dlopen()
  72 The function
  73 .BR dlopen ()
  74 loads the dynamic library file named by the null-terminated
  75 string
  76 .I filename
  77 and returns an opaque "handle" for the dynamic library.
  78 If
  79 .I filename
  80 is NULL, then the returned handle is for the main program.
  81 If
  82 .I filename
  83 contains a slash ("/"), then it is interpreted as a (relative
  84 or absolute) pathname.
  85 Otherwise, the dynamic linker searches for the library as follows
  86 (see
  87 .BR ld.so (8)
  88 for further details):
  89 .IP o 4
  90 (ELF only) If the executable file for the calling program
  91 contains a DT_RPATH tag, and does not contain a DT_RUNPATH tag,
  92 then the directories listed in the DT_RPATH tag are searched.
  93 .IP o
  94 If, at the time that the program was started, the environment variable
  95 .B LD_LIBRARY_PATH
  96 was defined to contain a colon-separated list of directories,
  97 then these are searched.
  98 (As a security measure this variable is ignored for set-user-ID and
  99 set-group-ID programs.)
 100 .IP o
 101 (ELF only) If the executable file for the calling program
 102 contains a DT_RUNPATH tag, then the directories listed in that tag
 103 are searched.
 104 .IP o
 105 The cache file
 106 .I /etc/ld.so.cache
 107 (maintained by
 108 .BR ldconfig (8))
 109 is checked to see whether it contains an entry for
 110 .IR filename .
 111 .IP o
 112 The directories
 113 .I /lib
 114 and
 115 .I /usr/lib
 116 are searched (in that order).
 117 .PP
 118 If the library has dependencies on other shared libraries,
 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 libraries in turn have dependencies, and so on.)
 123 .PP
 124 One of the following two values must be included in
 125 .IR flag :
 126 .TP
 127 .B RTLD_LAZY
 128 Perform lazy binding.
 129 Only resolve symbols 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 library is loaded.)
 134 .TP
 135 .B RTLD_NOW
 136 If this value is specified, or the environment variable
 137 .B LD_BIND_NOW
 138 is set to a nonempty string,
 139 all undefined symbols in the library are resolved before
 140 .BR dlopen ()
 141 returns.
 142 If this cannot be done, an error is returned.
 143 .PP
 144 Zero or more of the following values may also be ORed in
 145 .IR flag :
 146 .TP
 147 .B RTLD_GLOBAL
 148 The symbols defined by this library will be
 149 made available for symbol resolution of subsequently loaded libraries.
 150 .TP
 151 .B RTLD_LOCAL
 152 This is the converse of
 153 .BR RTLD_GLOBAL ,
 154 and the default if neither flag is specified.
 155 Symbols defined in this library are not made available to resolve
 156 references in subsequently loaded libraries.
 157 .TP
 158 .BR RTLD_NODELETE " (since glibc 2.2)"
 159 Do not unload the library during
 160 .BR dlclose ().
 161 Consequently, the library's static variables are not reinitialized
 162 if the library is reloaded with
 163 .BR dlopen ()
 164 at a later time.
 165 This flag is not specified in POSIX.1-2001.
 166 .\" (But it is present on Solaris.)
 167 .TP
 168 .BR RTLD_NOLOAD " (since glibc 2.2)"
 169 Don't load the library.
 170 This can be used to test if the library is already resident
 171 .RB ( dlopen ()
 172 returns NULL if it is not, or the library's handle if it is resident).
 173 This flag can also be used to promote the flags on a library
 174 that is already loaded.
 175 For example, a library that was previously loaded with
 176 .B RTLD_LOCAL
 177 can be reopened with
 178 .BR RTLD_NOLOAD\ |\ RTLD_GLOBAL .
 179 This flag is not specified in POSIX.1-2001.
 180 .\" (But it is present on Solaris.)
 181 .\"
 182 .TP
 183 .BR RTLD_DEEPBIND " (since glibc 2.3.4)"
 184 .\" Inimitably described by UD in
 185 .\" http://sources.redhat.com/ml/libc-hacker/2004-09/msg00083.html.
 186 Place the lookup scope of the symbols in this
 187 library ahead of the global scope.
 188 This means that a self-contained library will use
 189 its own symbols in preference to global symbols with the same name
 190 contained in libraries that have already been loaded.
 191 This flag is not specified in POSIX.1-2001.
 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 libraries loaded at program startup,
 200 and then all shared libraries loaded by
 201 .BR dlopen ()
 202 with the flag
 203 .BR RTLD_GLOBAL .
 204 .PP
 205 External references in the library are resolved using the libraries
 206 in that library's dependency list and any other libraries previously
 207 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 library.
 214 .PP
 215 If the same library is loaded again with
 216 .BR dlopen (),
 217 the same library handle is returned.
 218 The dl library maintains reference
 219 counts for library handles, so a dynamic library 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 The
 226 .BR _init ()
 227 routine, if present, is called only once.
 228 But a subsequent call with
 229 .B RTLD_NOW
 230 may force symbol resolution for a library earlier loaded with
 231 .BR RTLD_LAZY .
 232 .PP
 233 If
 234 .BR dlopen ()
 235 fails for any reason, it returns NULL.
 236 .SS dlsym()
 237 The function
 238 .BR dlsym ()
 239 takes a "handle" of a dynamic library returned by
 240 .BR dlopen ()
 241 and the
 242 null-terminated symbol name, returning the address where that symbol is
 243 loaded into memory.
 244 If the symbol is not found, in the specified
 245 library or any of the libraries that were automatically loaded by
 246 .BR dlopen ()
 247 when that library was loaded,
 248 .BR dlsym ()
 249 returns NULL.
 250 (The search performed by
 251 .BR dlsym ()
 252 is breadth first through the dependency tree of these libraries.)
 253 Since the value of the symbol could actually be NULL (so that a
 254 NULL return from
 255 .BR dlsym ()
 256 need not indicate an error), the correct way to test for an error
 257 is to call
 258 .BR dlerror ()
 259 to clear any old error conditions, then call
 260 .BR dlsym (),
 261 and then call
 262 .BR dlerror ()
 263 again, saving its return value into a variable, and check whether
 264 this saved value is not NULL.
 265 .PP
 266 There are two special pseudo-handles,
 267 .B RTLD_DEFAULT
 268 and
 269 .BR RTLD_NEXT .
 270 The former will find the first occurrence of the desired symbol
 271 using the default library search order.
 272 The latter
 273 will find the next occurrence of a function in the search order
 274 after the current library.
 275 This allows one to provide a wrapper
 276 around a function in another shared library.
 277 .SS dlclose()
 278 The function
 279 .BR dlclose ()
 280 decrements the reference count on the dynamic library handle
 281 .IR handle .
 282 If the reference count drops to zero and no other loaded libraries use
 283 symbols in it, then the dynamic library is unloaded.
 284 .LP
 285 The function
 286 .BR dlclose ()
 287 returns 0 on success, and nonzero on error.
 288 .SS The obsolete symbols _init() and _fini()
 289 The linker recognizes special symbols
 290 .B _init
 291 and
 292 .BR _fini .
 293 If a dynamic library exports a routine named
 294 .BR _init (),
 295 then that code is executed after the loading, before
 296 .BR dlopen ()
 297 returns.
 298 If the dynamic library exports a routine named
 299 .BR _fini (),
 300 then that routine is called just before the library is unloaded.
 301 In case you need to avoid linking against the system startup files,
 302 this can be done by using the
 303 .BR gcc (1)
 304 .I \-nostartfiles
 305 command-line option.
 306 .LP
 307 Using these routines, or the gcc
 308 .B \-nostartfiles
 309 or
 310 .B \-nostdlib
 311 options, is not recommended.
 312 Their use may result in undesired behavior,
 313 since the constructor/destructor routines will not be executed
 314 (unless special measures are taken).
 315 .\" void _init(void) __attribute__((constructor));
 316 .\" void _fini(void) __attribute__((destructor));
 317 .LP
 318 Instead, libraries should export routines using the
 319 .B __attribute__((constructor))
 320 and
 321 .B __attribute__((destructor))
 322 function attributes.
 323 See the gcc info pages for information on these.
 324 Constructor routines are executed before
 325 .BR dlopen ()
 326 returns, and destructor routines are executed before
 327 .BR dlclose ()
 328 returns.
 329 .SS Glibc extensions: dladdr() and dlvsym()
 330 Glibc adds two functions not described by POSIX, with prototypes
 331 .sp
 332 .nf
 333 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
 334 .B #include <dlfcn.h>
 335 .sp
 336 .BI "int dladdr(void *" addr ", Dl_info *" info );
 337 .sp
 338 .BI "void *dlvsym(void *" handle ", char *" symbol ", char *" version );
 339 .fi
 340 .PP
 341 The function
 342 .BR dladdr ()
 343 takes a function pointer and tries to resolve name
 344 and file where it is located.
 345 Information is stored in the
 346 .I Dl_info
 347 structure:
 348 .sp
 349 .in +4n
 350 .nf
 351 typedef struct {
 352     const char *dli_fname;  /* Pathname of shared object that
 353                                contains address */
 354     void       *dli_fbase;  /* Address at which shared object
 355                                is loaded */
 356     const char *dli_sname;  /* Name of symbol whose definition
 357                                overlaps \fIaddr\fP */
 358     void       *dli_saddr;  /* Exact address of symbol named
 359                                in \fIdli_sname\fP */
 360 } Dl_info;
 361 .fi
 362 .in
 363 .PP
 364 If no symbol matching
 365 .I addr
 366 could be found, then
 367 .I dli_sname
 368 and
 369 .I dli_saddr
 370 are set to NULL.
 371 .PP
 372 .BR dladdr ()
 373 returns 0 on error, and nonzero on success.
 374 .PP
 375 The function
 376 .BR dlvsym (),
 377 provided by glibc since version 2.1,
 378 does the same as
 379 .BR dlsym ()
 380 but takes a version string as an additional argument.
 381 .SH CONFORMING TO
 382 POSIX.1-2001 describes
 383 .BR dlclose (),
 384 .BR dlerror (),
 385 .BR dlopen (),
 386 and
 387 .BR dlsym ().
 388 .SH NOTES
 389 The symbols
 390 .B RTLD_DEFAULT
 391 and
 392 .B RTLD_NEXT
 393 are defined by
 394 .I <dlfcn.h>
 395 only when
 396 .B _GNU_SOURCE
 397 was defined before including it.
 398 .\" .LP
 399 .\" The string returned by
 400 .\" .BR dlerror ()
 401 .\" should not be modified.
 402 .\" Some systems give the prototype as
 403 .\" .sp
 404 .\" .in +5
 405 .\" .B "const char *dlerror(void);"
 406 .\" .in
 407
 408 Since glibc 2.2.3,
 409 .BR atexit (3)
 410 can be used to register an exit handler that is automatically
 411 called when a library is unloaded.
 412 .SS History
 413 The dlopen interface standard comes from SunOS.
 414 That system also has
 415 .BR dladdr (),
 416 but not
 417 .BR dlvsym ().
 418 .SH BUGS
 419 Sometimes, the function pointers you pass to
 420 .BR dladdr ()
 421 may surprise you.
 422 On some architectures (notably i386 and x86_64),
 423 .I dli_fname
 424 and
 425 .I dli_fbase
 426 may end up pointing back at the object from which you called
 427 .BR dladdr (),
 428 even if the function used as an argument should come from
 429 a dynamically linked library.
 430 .PP
 431 The problem is that the function pointer will still be resolved
 432 at compile time, but merely point to the
 433 .I plt
 434 (Procedure Linkage Table)
 435 section of the original object (which dispatches the call after
 436 asking the dynamic linker to resolve the symbol).
 437 To work around this,
 438 you can try to compile the code to be position-independent:
 439 then, the compiler cannot prepare the pointer
 440 at compile time anymore and today's
 441 .BR gcc (1)
 442 will generate code that just loads the final symbol address from the
 443 .I got
 444 (Global Offset Table) at run time before passing it to
 445 .BR dladdr ().
 446 .SH EXAMPLE
 447 Load the math library, and print the cosine of 2.0:
 448 .nf
 449
 450 #include <stdio.h>
 451 #include <stdlib.h>
 452 #include <dlfcn.h>
 453
 454 int
 455 main(int argc, char **argv)
 456 {
 457     void *handle;
 458     double (*cosine)(double);
 459     char *error;
 460
 461     handle = dlopen("libm.so", RTLD_LAZY);
 462     if (!handle) {
 463         fprintf(stderr, "%s\en", dlerror());
 464         exit(EXIT_FAILURE);
 465     }
 466
 467     dlerror();    /* Clear any existing error */
 468
 469     cosine = (double (*)(double)) dlsym(handle, "cos");
 470
 471     /* According to the ISO C standard, casting between function
 472        pointers and 'void *', as done above, produces undefined results.
 473        POSIX.1-2003 and POSIX.1-2008 accepted this state of affairs and
 474        proposed the following workaround:
 475
 476            *(void **) (&cosine) = dlsym(handle, "cos");
 477
 478        This (clumsy) cast conforms with the ISO C standard and will
 479        avoid any compiler warnings.
 480
 481        The 2013 Technical Corrigendum to POSIX.1-2008 (a.k.a.
 482        POSIX.1-2013) improved matters by requiring that conforming
 483        implementations support casting 'void *' to a function pointer.
 484        Nevertheless, some compilers (e.g., gcc with the '-pedantic'
 485        option) may complain about the cast used in this program. */
 486 .\" http://pubs.opengroup.org/onlinepubs/009695399/functions/dlsym.html#tag_03_112_08
 487 .\" http://pubs.opengroup.org/onlinepubs/9699919799/functions/dlsym.html#tag_16_96_07
 488 .\" http://austingroupbugs.net/view.php?id=74
 489
 490     error = dlerror();
 491     if (error != NULL) {
 492         fprintf(stderr, "%s\en", error);
 493         exit(EXIT_FAILURE);
 494     }
 495
 496     printf("%f\en", (*cosine)(2.0));
 497     dlclose(handle);
 498     exit(EXIT_SUCCESS);
 499 }
 500 .fi
 501 .PP
 502 If this program were in a file named "foo.c", you would build the program
 503 with the following command:
 504 .in +4n
 505 .LP
 506     gcc \-rdynamic \-o foo foo.c \-ldl
 507 .in
 508 .PP
 509 Libraries exporting
 510 .BR _init ()
 511 and
 512 .BR _fini ()
 513 will want to be compiled as
 514 follows, using
 515 .I bar.c
 516 as the example name:
 517 .in +4n
 518 .LP
 519     gcc \-shared \-nostartfiles \-o bar bar.c
 520 .in
 521 .SH SEE ALSO
 522 .BR ld (1),
 523 .BR ldd (1),
 524 .BR dl_iterate_phdr (3),
 525 .BR rtld-audit (7),
 526 .BR ld.so (8),
 527 .BR ldconfig (8)
 528
 529 ld.so info pages, gcc info pages, ld info pages