original/man8/ld.so.8

   1 .\" %%%LICENSE_START(PUBLIC_DOMAIN)
   2 .\" This is in the public domain
   3 .\" %%%LICENSE_END
   4 .\"
   5 .TH LD.SO 8 2014-12-31 "GNU" "Linux Programmer's Manual"
   6 .SH NAME
   7 ld.so, ld-linux.so* \- dynamic linker/loader
   8 .SH SYNOPSIS
   9 The dynamic linker can be run either indirectly by running some
  10 dynamically linked program or library (in which case no command-line options
  11 to the dynamic linker can be passed and, in the ELF case, the dynamic linker
  12 which is stored in the
  13 .B .interp
  14 section of the program is executed) or directly by running:
  15 .P
  16 .I /lib/ld-linux.so.*
  17 [OPTIONS] [PROGRAM [ARGUMENTS]]
  18 .SH DESCRIPTION
  19 The programs
  20 .B ld.so
  21 and
  22 .B ld-linux.so*
  23 find and load the shared libraries needed by a program, prepare
  24 the program to run, and then run it.
  25 .LP
  26 Linux binaries require dynamic linking (linking at run time)
  27 unless the
  28 .B \-static
  29 option was given to
  30 .BR ld (1)
  31 during compilation.
  32 .LP
  33 The program
  34 .B ld.so
  35 handles a.out binaries, a format used long ago;
  36 .B ld-linux.so*
  37 handles ELF (\fI/lib/ld-linux.so.1\fP for libc5, \fI/lib/ld-linux.so.2\fP
  38 for glibc2), which everybody has been using for years now.
  39 Otherwise, both have the same behavior, and use the same
  40 support files and programs
  41 .BR ldd (1),
  42 .BR ldconfig (8),
  43 and
  44 .IR /etc/ld.so.conf .
  45 .LP
  46 When resolving library dependencies,
  47 the dynamic linker first inspects each dependency
  48 string to see if it contains a slash (this can occur if
  49 a library pathname containing slashes was specified at link time).
  50 If a slash is found, then the dependency string is interpreted as
  51 a (relative or absolute) pathname,
  52 and the library is loaded using that pathname.
  53 .LP
  54 If a library dependency does not contain a slash,
  55 then it is searched for in the following order:
  56 .IP o 3
  57 (ELF only) Using the directories specified in the
  58 DT_RPATH dynamic section attribute
  59 of the binary if present and DT_RUNPATH attribute does not exist.
  60 Use of DT_RPATH is deprecated.
  61 .IP o
  62 Using the environment variable
  63 .BR LD_LIBRARY_PATH .
  64 Except if the executable is a set-user-ID/set-group-ID binary,
  65 in which case it is ignored.
  66 .IP o
  67 (ELF only) Using the directories specified in the
  68 DT_RUNPATH dynamic section attribute
  69 of the binary if present.
  70 .IP o
  71 From the cache file
  72 .IR /etc/ld.so.cache ,
  73 which contains a compiled list of candidate libraries previously found
  74 in the augmented library path.
  75 If, however, the binary was linked with the
  76 .B \-z nodeflib
  77 linker option, libraries in the default library paths are skipped.
  78 Libraries installed in hardware capability directories (see below)
  79 are preferred to other libraries.
  80 .IP o
  81 In the default path
  82 .IR /lib ,
  83 and then
  84 .IR /usr/lib .
  85 If the binary was linked with the
  86 .B \-z nodeflib
  87 linker option, this step is skipped.
  88 .SS Rpath token expansion
  89 .PP
  90 .B ld.so
  91 understands certain strings in an rpath specification (DT_RPATH or DT_RUNPATH); those strings are substituted as follows
  92 .TP
  93 .IR $ORIGIN " (or equivalently " ${ORIGIN} )
  94 This expands to
  95 the directory containing the program or shared library.
  96 Thus, an application located in
  97 .I somedir/app
  98 could be compiled with
  99
 100     gcc \-Wl,\-rpath,\(aq$ORIGIN/../lib\(aq
 101
 102 so that it finds an associated shared library in
 103 .I somedir/lib
 104 no matter where
 105 .I somedir
 106 is located in the directory hierarchy.
 107 This facilitates the creation of "turn-key" applications that
 108 do not need to be installed into special directories,
 109 but can instead be unpacked into any directory
 110 and still find their own shared libraries.
 111 .TP
 112 .IR $LIB " (or equivalently " ${LIB} )
 113 This expands to
 114 .I lib
 115 or
 116 .I lib64
 117 depending on the architecture
 118 (e.g., on x86-64, it expands to
 119 .IR lib64
 120 and
 121 on x86-32, it expands to
 122 .IR lib ).
 123 .TP
 124 .IR $PLATFORM " (or equivalently " ${PLATFORM} )
 125 This expands to a string corresponding to the processor type
 126 of the host system (e.g., "x86_64").
 127 On some architectures, the Linux kernel doesn't provide a platform
 128 string to the dynamic linker.
 129 The value of this string is taken from the
 130 .BR AT_PLATFORM
 131 value in the auxiliary vector (see
 132 .BR getauxval (3)).
 133 .\" To get an idea of the places that $PLATFORM would match,
 134 .\" look at the output of the following:
 135 .\"
 136 .\"     mkdir /tmp/d
 137 .\"     LD_LIBRARY_PATH=/tmp/d strace -e open /bin/date 2>&1 | grep /tmp/d
 138 .\"
 139 .\" ld.so lets names be abbreviated, so $O will work for $ORIGIN;
 140 .\" Don't do this!!
 141 .SH OPTIONS
 142 .TP
 143 .B \-\-list
 144 List all dependencies and how they are resolved.
 145 .TP
 146 .B \-\-verify
 147 Verify that program is dynamically linked and this dynamic linker can handle
 148 it.
 149 .TP
 150 .B \-\-inhibit-cache
 151 Do not use /etc/ld.so.cache.
 152 .TP
 153 .B \-\-library\-path PATH
 154 Use PATH instead of
 155 .B LD_LIBRARY_PATH
 156 environment variable setting (see below).
 157 .TP
 158 .B \-\-inhibit\-rpath LIST
 159 Ignore RPATH and RUNPATH information in object names in LIST.
 160 This option is ignored if
 161 .B ld.so
 162 is set-user-ID or set-group-ID.
 163 .TP
 164 .B \-\-audit LIST
 165 Use objects named in LIST as auditors.
 166 .SH HARDWARE CAPABILITIES
 167 Some libraries are compiled using hardware-specific instructions which do
 168 not exist on every CPU.
 169 Such libraries should be installed in directories whose names define the
 170 required hardware capabilities, such as
 171 .IR /usr/lib/sse2/ .
 172 The dynamic linker checks these directories against the hardware of the
 173 machine and selects the most suitable version of a given library.
 174 Hardware capability directories can be cascaded to combine CPU features.
 175 The list of supported hardware capability names depends on the CPU.
 176 The following names are currently recognized:
 177 .TP
 178 .B Alpha
 179 ev4, ev5, ev56, ev6, ev67
 180 .TP
 181 .B MIPS
 182 loongson2e, loongson2f, octeon, octeon2
 183 .TP
 184 .B PowerPC
 185 4xxmac, altivec, arch_2_05, arch_2_06, booke, cellbe, dfp, efpdouble, efpsingle,
 186 fpu, ic_snoop, mmu, notb, pa6t, power4, power5, power5+, power6x, ppc32, ppc601,
 187 ppc64, smt, spe, ucache, vsx
 188 .TP
 189 .B SPARC
 190 flush, muldiv, stbar, swap, ultra3, v9, v9v, v9v2
 191 .TP
 192 .B s390
 193 dfp, eimm, esan3, etf3enh, g5, highgprs, hpage, ldisp, msa, stfle,
 194 z900, z990, z9-109, z10, zarch
 195 .TP
 196 .B x86 (32-bit only)
 197 acpi, apic, clflush, cmov, cx8, dts, fxsr, ht, i386, i486, i586, i686, mca, mmx,
 198 mtrr, pat, pbe, pge, pn, pse36, sep, ss, sse, sse2, tm
 199 .SH ENVIRONMENT
 200 Among the more important environment variables are the following:
 201 .TP
 202 .B LD_ASSUME_KERNEL
 203 (glibc since 2.2.3)
 204 Each shared library can inform the dynamic linker of the minimum kernel ABI
 205 version that it requires.
 206 (This requirement is encoded in an ELF note section that is viewable via
 207 .IR "readelf\ \-n"
 208 as a section labeled
 209 .BR NT_GNU_ABI_TAG .)
 210 At run time,
 211 the dynamic linker determines the ABI version of the running kernel and
 212 will reject loading shared libraries that specify minimum ABI versions
 213 that exceed that ABI version.
 214
 215 .BR LD_ASSUME_KERNEL
 216 can be used to
 217 cause the dynamic linker to assume that it is running on a system with
 218 a different kernel ABI version.
 219 For example, the following command line causes the
 220 dynamic linker to assume it is running on Linux 2.2.5 when loading
 221 the shared libraries required by
 222 .IR myprog :
 223
 224 .in +4n
 225 .nf
 226 $ \fBLD_ASSUME_KERNEL=2.2.5 ./myprog\fP
 227 .fi
 228 .in
 229
 230 On systems that provide multiple versions of a shared library
 231 (in different directories in the search path) that have
 232 different minimum kernel ABI version requirements,
 233 .BR LD_ASSUME_KERNEL
 234 can be used to select the version of the library that is used
 235 (dependent on the directory search order).
 236 Historically, the most common use of the
 237 .BR LD_ASSUME_KERNEL
 238 feature was to manually select the older
 239 LinuxThreads POSIX threads implementation on systems that provided both
 240 LinuxThreads and NPTL
 241 (which latter was typically the default on such systems);
 242 see
 243 .BR pthreads (7).
 244 .TP
 245 .B LD_BIND_NOT
 246 (glibc since 2.2)
 247 Don't update the Global Offset Table (GOT) and Procedure Linkage Table (PLT)
 248 when resolving a symbol.
 249 .TP
 250 .B LD_BIND_NOW
 251 (libc5; glibc since 2.1.1)
 252 If set to a nonempty string,
 253 causes the dynamic linker to resolve all symbols
 254 at program startup instead of deferring function call resolution to the point
 255 when they are first referenced.
 256 This is useful when using a debugger.
 257 .TP
 258 .B LD_LIBRARY_PATH
 259 A colon-separated list of directories in which to search for
 260 ELF libraries at execution-time.
 261 Similar to the
 262 .B PATH
 263 environment variable.
 264 Ignored in set-user-ID and set-group-ID programs.
 265 .TP
 266 .B LD_PRELOAD
 267 A list of additional, user-specified, ELF shared
 268 libraries to be loaded before all others.
 269 The items of the list can be separated by spaces or colons.
 270 This can be used to selectively override functions in other shared libraries.
 271 The libraries are searched for using the rules given under DESCRIPTION.
 272 For set-user-ID/set-group-ID ELF binaries,
 273 preload pathnames containing slashes are ignored,
 274 and libraries in the standard search directories are loaded
 275 only if the set-user-ID permission bit is enabled on the library file.
 276 .TP
 277 .B LD_TRACE_LOADED_OBJECTS
 278 (ELF only)
 279 If set to a nonempty string, causes the program to list its dynamic library
 280 dependencies, as if run by
 281 .BR ldd (1),
 282 instead of running normally.
 283 .LP
 284 Then there are lots of more or less obscure variables,
 285 many obsolete or only for internal use.
 286 .TP
 287 .B LD_AOUT_LIBRARY_PATH
 288 (libc5)
 289 Version of
 290 .B LD_LIBRARY_PATH
 291 for a.out binaries only.
 292 Old versions of ld\-linux.so.1 also supported
 293 .BR LD_ELF_LIBRARY_PATH .
 294 .TP
 295 .B LD_AOUT_PRELOAD
 296 (libc5)
 297 Version of
 298 .B LD_PRELOAD
 299 for a.out binaries only.
 300 Old versions of ld\-linux.so.1 also supported
 301 .BR LD_ELF_PRELOAD .
 302 .TP
 303 .B LD_AUDIT
 304 (glibc since 2.4)
 305 A colon-separated list of user-specified, ELF shared objects
 306 to be loaded before all others in a separate linker namespace
 307 (i.e., one that does not intrude upon the normal symbol bindings that
 308 would occur in the process).
 309 These libraries can be used to audit the operation of the dynamic linker.
 310 .B LD_AUDIT
 311 is ignored for set-user-ID/set-group-ID binaries.
 312
 313 The dynamic linker will notify the audit
 314 libraries at so-called auditing checkpoints\(emfor example,
 315 loading a new library, resolving a symbol,
 316 or calling a symbol from another shared object\(emby
 317 calling an appropriate function within the audit library.
 318 For details, see
 319 .BR rtld-audit (7).
 320 The auditing interface is largely compatible with that provided on Solaris,
 321 as described in its
 322 .IR "Linker and Libraries Guide" ,
 323 in the chapter
 324 .IR "Runtime Linker Auditing Interface" .
 325 .TP
 326 .B LD_BIND_NOT
 327 (glibc since 2.1.95)
 328 Do not update the GOT (global offset table) and PLT (procedure linkage table)
 329 after resolving a symbol.
 330 .TP
 331 .B LD_DEBUG
 332 (glibc since 2.1)
 333 Output verbose debugging information about the dynamic linker.
 334 If set to
 335 .B all
 336 prints all debugging information it has, if set to
 337 .B help
 338 prints a help message about which categories can be specified in this
 339 environment variable.
 340 Since glibc 2.3.4,
 341 .B LD_DEBUG
 342 is ignored for set-user-ID/set-group-ID binaries.
 343 .TP
 344 .B LD_DEBUG_OUTPUT
 345 (glibc since 2.1)
 346 File in which
 347 .B LD_DEBUG
 348 output should be written.
 349 The default is standard error.
 350 .B LD_DEBUG_OUTPUT
 351 is ignored for set-user-ID/set-group-ID binaries.
 352 .TP
 353 .B LD_DYNAMIC_WEAK
 354 (glibc since 2.1.91)
 355 Allow weak symbols to be overridden (reverting to old glibc behavior).
 356 For security reasons, since glibc 2.3.4,
 357 .B LD_DYNAMIC_WEAK
 358 is ignored for set-user-ID/set-group-ID binaries.
 359 .TP
 360 .B LD_HWCAP_MASK
 361 (glibc since 2.1)
 362 Mask for hardware capabilities.
 363 .TP
 364 .B LD_KEEPDIR
 365 (a.out only)(libc5)
 366 Don't ignore the directory in the names of a.out libraries to be loaded.
 367 Use of this option is strongly discouraged.
 368 .TP
 369 .B LD_NOWARN
 370 (a.out only)(libc5)
 371 Suppress warnings about a.out libraries with incompatible minor
 372 version numbers.
 373 .TP
 374 .B LD_ORIGIN_PATH
 375 (glibc since 2.1)
 376 Path where the binary is found (for non-set-user-ID programs).
 377 For security reasons, since glibc 2.4,
 378 .B LD_ORIGIN_PATH
 379 is ignored for set-user-ID/set-group-ID binaries.
 380 .\" Only used if $ORIGIN can't be determined by normal means
 381 .\" (from the origin path saved at load time, or from /proc/self/exe)?
 382 .TP
 383 .B LD_POINTER_GUARD
 384 (glibc since 2.4)
 385 Set to 0 to disable pointer guarding.
 386 Any other value enables pointer guarding, which is also the default.
 387 Pointer guarding is a security mechanism whereby some pointers to code
 388 stored in writable program memory (return addresses saved by
 389 .BR setjmp (3)
 390 or function pointers used by various glibc internals) are mangled
 391 semi-randomly to make it more difficult for an attacker to hijack
 392 the pointers for use in the event of a buffer overrun or
 393 stack-smashing attack.
 394 .TP
 395 .B LD_PROFILE
 396 (glibc since 2.1)
 397 The name of a (single) shared object to be profiled,
 398 specified either as a pathname or a soname.
 399 Profiling output is appended to the file whose name is:
 400 "\fI$LD_PROFILE_OUTPUT\fP/\fI$LD_PROFILE\fP.profile".
 401 .TP
 402 .B LD_PROFILE_OUTPUT
 403 (glibc since 2.1)
 404 Directory where
 405 .B LD_PROFILE
 406 output should be written.
 407 If this variable is not defined, or is defined as an empty string,
 408 then the default is
 409 .IR /var/tmp .
 410 .B LD_PROFILE_OUTPUT
 411 is ignored for set-user-ID and set-group-ID programs,
 412 which always use
 413 .IR /var/profile .
 414 .TP
 415 .B LD_SHOW_AUXV
 416 (glibc since 2.1)
 417 Show auxiliary array passed up from the kernel.
 418 For security reasons, since glibc 2.3.5,
 419 .B LD_SHOW_AUXV
 420 is ignored for set-user-ID/set-group-ID binaries.
 421 .\" FIXME
 422 .\" Document LD_TRACE_PRELINKING (e.g.: LD_TRACE_PRELINKING=libx1.so ./prog)
 423 .\"     Available since glibc 2.3
 424 .\"     Also enables DL_DEBUG_PRELINK
 425 .TP
 426 .B LD_USE_LOAD_BIAS
 427 .\" http://sources.redhat.com/ml/libc-hacker/2003-11/msg00127.html
 428 .\" Subject: [PATCH] Support LD_USE_LOAD_BIAS
 429 .\" Jakub Jelinek
 430 By default (i.e., if this variable is not defined)
 431 executables and prelinked
 432 shared objects will honor base addresses of their dependent libraries
 433 and (nonprelinked) position-independent executables (PIEs)
 434 and other shared objects will not honor them.
 435 If
 436 .B LD_USE_LOAD_BIAS
 437 is defined with the value 1, both executables and PIEs
 438 will honor the base addresses.
 439 If
 440 .B LD_USE_LOAD_BIAS
 441 is defined with the value 0,
 442 neither executables nor PIEs will honor the base addresses.
 443 This variable is ignored by set-user-ID and set-group-ID programs.
 444 .TP
 445 .B LD_VERBOSE
 446 (glibc since 2.1)
 447 If set to a nonempty string,
 448 output symbol versioning information about the
 449 program if the
 450 .B LD_TRACE_LOADED_OBJECTS
 451 environment variable has been set.
 452 .TP
 453 .B LD_WARN
 454 (ELF only)(glibc since 2.1.3)
 455 If set to a nonempty string, warn about unresolved symbols.
 456 .TP
 457 .B LDD_ARGV0
 458 (libc5)
 459 .IR argv [0]
 460 to be used by
 461 .BR ldd (1)
 462 when none is present.
 463 .SH FILES
 464 .PD 0
 465 .TP
 466 .I /lib/ld.so
 467 a.out dynamic linker/loader
 468 .TP
 469 .IR /lib/ld\-linux.so. { 1 , 2 }
 470 ELF dynamic linker/loader
 471 .TP
 472 .I /etc/ld.so.cache
 473 File containing a compiled list of directories in which to search for
 474 libraries and an ordered list of candidate libraries.
 475 .TP
 476 .I /etc/ld.so.preload
 477 File containing a whitespace-separated list of ELF shared libraries to
 478 be loaded before the program.
 479 .TP
 480 .B lib*.so*
 481 shared libraries
 482 .PD
 483 .SH NOTES
 484 The
 485 .B ld.so
 486 functionality is available for executables compiled using libc version
 487 4.4.3 or greater.
 488 ELF functionality is available since Linux 1.1.52 and libc5.
 489 .SH SEE ALSO
 490 .BR ld (1),
 491 .BR ldd (1),
 492 .BR pldd (1),
 493 .BR sprof (1),
 494 .BR dlopen (3),
 495 .BR getauxval (3),
 496 .BR rtld-audit (7),
 497 .BR ldconfig (8),
 498 .BR sln (8)
 499 .\" .SH AUTHORS
 500 .\" ld.so: David Engel, Eric Youngdale, Peter MacDonald, Hongjiu Lu, Linus
 501 .\"  Torvalds, Lars Wirzenius and Mitch D'Souza
 502 .\" ld-linux.so: Roland McGrath, Ulrich Drepper and others.
 503 .\"
 504 .\" In the above, (libc5) stands for David Engel's ld.so/ld-linux.so.
 505 .SH COLOPHON
 506 This page is part of release 3.79 of the Linux
 507 .I man-pages
 508 project.
 509 A description of the project,
 510 information about reporting bugs,
 511 and the latest version of this page,
 512 can be found at
 513 \%http://www.kernel.org/doc/man\-pages/.