original/man8/ld.so.8

   1 .\" This is in the public domain
   2 .TH LD.SO 8 2012-03-06 "GNU" "Linux Programmer's Manual"
   3 .SH NAME
   4 ld.so, ld-linux.so* \- dynamic linker/loader
   5 .SH SYNOPSIS
   6 The dynamic linker can be run either indirectly by running some
   7 dynamically linked program or library (in which case no command-line options
   8 to the dynamic linker can be passed and, in the ELF case, the dynamic linker
   9 which is stored in the
  10 .B .interp
  11 section of the program is executed) or directly by running:
  12 .P
  13 .I /lib/ld-linux.so.*
  14 [OPTIONS] [PROGRAM [ARGUMENTS]]
  15 .SH DESCRIPTION
  16 The programs
  17 .B ld.so
  18 and
  19 .B ld-linux.so*
  20 find and load the shared libraries needed by a program, prepare
  21 the program to run, and then run it.
  22 .LP
  23 Linux binaries require dynamic linking (linking at run time)
  24 unless the
  25 .B \-static
  26 option was given to
  27 .BR ld (1)
  28 during compilation.
  29 .LP
  30 The program
  31 .B ld.so
  32 handles a.out binaries, a format used long ago;
  33 .B ld-linux.so*
  34 handles ELF (\fI/lib/ld-linux.so.1\fP for libc5, \fI/lib/ld-linux.so.2\fP
  35 for glibc2), which everybody has been using for years now.
  36 Otherwise both have the same behavior, and use the same
  37 support files and programs
  38 .BR ldd (1),
  39 .BR ldconfig (8)
  40 and
  41 .IR /etc/ld.so.conf .
  42 .LP
  43 The shared libraries needed by the program are searched for
  44 in the following order:
  45 .IP o 3
  46 (ELF only) Using the directories specified in the
  47 DT_RPATH dynamic section attribute
  48 of the binary if present and DT_RUNPATH attribute does not exist.
  49 Use of DT_RPATH is deprecated.
  50 .IP o
  51 Using the environment variable
  52 .BR LD_LIBRARY_PATH .
  53 Except if the executable is a set-user-ID/set-group-ID binary,
  54 in which case it is ignored.
  55 .IP o
  56 (ELF only) Using the directories specified in the
  57 DT_RUNPATH dynamic section attribute
  58 of the binary if present.
  59 .IP o
  60 From the cache file
  61 .I /etc/ld.so.cache
  62 which contains a compiled list of candidate libraries previously found
  63 in the augmented library path.
  64 If, however, the binary was linked with the
  65 .B \-z nodeflib
  66 linker option, libraries in the default library paths are skipped.
  67 .IP o
  68 In the default path
  69 .IR /lib ,
  70 and then
  71 .IR /usr/lib .
  72 If the binary was linked with the
  73 .B \-z nodeflib
  74 linker option, this step is skipped.
  75 .SS $ORIGIN and rpath
  76 .PP
  77 .B ld.so
  78 understands the string
  79 .I $ORIGIN
  80 (or equivalently
  81 .IR ${ORIGIN} )
  82 in an rpath specification (DT_RPATH or DT_RUNPATH) to mean
  83 the directory containing the application executable.
  84 Thus, an application located in
  85 .I somedir/app
  86 could be compiled with
  87 .I gcc -Wl,-rpath,\(aq$ORIGIN/../lib\(aq
  88 so that it finds an associated shared library in
  89 .I somedir/lib
  90 no matter where
  91 .I somedir
  92 is located in the directory hierarchy.
  93 This facilitates the creation of "turn-key" applications that
  94 do not need to be installed into special directories,
  95 but can instead be unpacked into any directory
  96 and still find their own shared libraries.
  97 .\" ld.so also understands $LIB, with the same meaning as $ORIGIN/lib,
  98 .\" it appears.
  99 .\"
 100 .\" There is also $PLATFORM.  This is a kind of wildcard
 101 .\" of directories related at AT_HWCAP.  To get an idea of the
 102 .\" places that $PLATFORM would match, look at the output of the
 103 .\" following:
 104 .\"
 105 .\" mkdir /tmp/d
 106 .\" LD_LIBRARY_PATH=/tmp/d strace -e open /bin/date 2>&1 | grep /tmp/d
 107 .\"
 108 .\" ld.so lets names be abbreviated, so $O will work for $ORIGIN;
 109 .\" Don't do this!!
 110 .SH OPTIONS
 111 .TP
 112 .B \-\-list
 113 List all dependencies and how they are resolved.
 114 .TP
 115 .B \-\-verify
 116 Verify that program is dynamically linked and this dynamic linker can handle
 117 it.
 118 .TP
 119 .B \-\-library\-path PATH
 120 Use PATH instead of
 121 .B LD_LIBRARY_PATH
 122 environment variable setting (see below).
 123 .TP
 124 .B \-\-inhibit\-rpath LIST
 125 Ignore RPATH and RUNPATH information in object names in LIST.
 126 This option is ignored if
 127 .B ld.so
 128 is set-user-ID or set-group-ID.
 129 .TP
 130 .B \-\-audit LIST
 131 Use objects named in LIST as auditors.
 132 .SH ENVIRONMENT
 133 There are four important environment variables.
 134 .TP
 135 .B LD_BIND_NOW
 136 (libc5; glibc since 2.1.1)
 137 If set to a nonempty string,
 138 causes the dynamic linker to resolve all symbols
 139 at program startup instead of deferring function call resolution to the point
 140 when they are first referenced.
 141 This is useful when using a debugger.
 142 .TP
 143 .B LD_LIBRARY_PATH
 144 A colon-separated list of directories in which to search for
 145 ELF libraries at execution-time.
 146 Similar to the
 147 .B PATH
 148 environment variable.
 149 .TP
 150 .B LD_PRELOAD
 151 A whitespace-separated list of additional, user-specified, ELF shared
 152 libraries to be loaded before all others.
 153 This can be used to selectively override functions in other shared libraries.
 154 For set-user-ID/set-group-ID ELF binaries,
 155 only libraries in the standard search
 156 directories that are also set-user-ID will be loaded.
 157 .TP
 158 .B LD_TRACE_LOADED_OBJECTS
 159 (ELF only)
 160 If set to a nonempty string, causes the program to list its dynamic library
 161 dependencies, as if run by
 162 .BR ldd (1),
 163 instead of running normally.
 164 .LP
 165 Then there are lots of more or less obscure variables,
 166 many obsolete or only for internal use.
 167 .TP
 168 .B LD_AOUT_LIBRARY_PATH
 169 (libc5)
 170 Version of
 171 .B LD_LIBRARY_PATH
 172 for a.out binaries only.
 173 Old versions of ld\-linux.so.1 also supported
 174 .BR LD_ELF_LIBRARY_PATH .
 175 .TP
 176 .B LD_AOUT_PRELOAD
 177 (libc5)
 178 Version of
 179 .B LD_PRELOAD
 180 for a.out binaries only.
 181 Old versions of ld\-linux.so.1 also supported
 182 .BR LD_ELF_PRELOAD .
 183 .TP
 184 .B LD_AUDIT
 185 (glibc since 2.4)
 186 A colon-separated list of user-specified, ELF shared objects
 187 to be loaded before all others in a separate linker namespace
 188 (i.e., one that does not intrude upon the normal symbol bindings that
 189 would occur in the process).
 190 These libraries can be used to audit the operation of the dynamic linker.
 191 .B LD_AUDIT
 192 is ignored for set-user-ID/set-group-ID binaries.
 193
 194 The dynamic linker will notify the audit
 195 libraries at so-called auditing checkpoints\(emfor example,
 196 loading a new library, resolving a symbol,
 197 or calling a symbol from another shared object\(emby
 198 calling an appropriate function within the audit library.
 199 For details, see
 200 .BR rtld-audit (7).
 201 The auditing interface is largely compatible with that provided on Solaris,
 202 as described in its
 203 .IR "Linker and Libraries Guide" ,
 204 in the chapter
 205 .IR "Runtime Linker Auditing Interface" .
 206 .TP
 207 .B LD_BIND_NOT
 208 (glibc since 2.1.95)
 209 Do not update the GOT (global offset table) and PLT (procedure linkage table)
 210 after resolving a symbol.
 211 .TP
 212 .B LD_DEBUG
 213 (glibc since 2.1)
 214 Output verbose debugging information about the dynamic linker.
 215 If set to
 216 .B all
 217 prints all debugging information it has, if set to
 218 .B help
 219 prints a help message about which categories can be specified in this
 220 environment variable.
 221 Since glibc 2.3.4,
 222 .B LD_DEBUG
 223 is ignored for set-user-ID/set-group-ID binaries.
 224 .TP
 225 .B LD_DEBUG_OUTPUT
 226 (glibc since 2.1)
 227 File where
 228 .B LD_DEBUG
 229 output should be fed into, default is standard output.
 230 .B LD_DEBUG_OUTPUT
 231 is ignored for set-user-ID/set-group-ID binaries.
 232 .TP
 233 .B LD_DYNAMIC_WEAK
 234 (glibc since 2.1.91)
 235 Allow weak symbols to be overridden (reverting to old glibc behavior).
 236 For security reasons, since glibc 2.3.4,
 237 .B LD_DYNAMIC_WEAK
 238 is ignored for set-user-ID/set-group-ID binaries.
 239 .TP
 240 .B LD_HWCAP_MASK
 241 (glibc since 2.1)
 242 Mask for hardware capabilities.
 243 .TP
 244 .B LD_KEEPDIR
 245 (a.out only)(libc5)
 246 Don't ignore the directory in the names of a.out libraries to be loaded.
 247 Use of this option is strongly discouraged.
 248 .TP
 249 .B LD_NOWARN
 250 (a.out only)(libc5)
 251 Suppress warnings about a.out libraries with incompatible minor
 252 version numbers.
 253 .TP
 254 .B LD_ORIGIN_PATH
 255 (glibc since 2.1)
 256 Path where the binary is found (for non-set-user-ID programs).
 257 For security reasons, since glibc 2.4,
 258 .B LD_ORIGIN_PATH
 259 is ignored for set-user-ID/set-group-ID binaries.
 260 .\" Only used if $ORIGIN can't be determined by normal means
 261 .\" (from the origin path saved at load time, or from /proc/self/exe)?
 262 .TP
 263 .B LD_POINTER_GUARD
 264 (glibc since 2.4)
 265 Set to 0 to disable pointer guarding.
 266 Any other value enables pointer guarding, which is also the default.
 267 Pointer guarding is a security mechanism whereby some pointers to code
 268 stored in writable program memory (return addresses saved by
 269 .BR setjmp (3)
 270 or function pointers used by various glibc internals) are mangled
 271 semi-randomly to make it more difficult for an attacker to hijack
 272 the pointers for use in the event of a buffer overrun or
 273 stack-smashing attack.
 274 .TP
 275 .B LD_PROFILE
 276 (glibc since 2.1)
 277 Shared object to be profiled,
 278 specified either as a pathname or a soname.
 279 Profiling output is written to the file whose name is:
 280 "\fI$LD_PROFILE_OUTPUT\fP/\fI$LD_PROFILE\fP.profile".
 281 .TP
 282 .B LD_PROFILE_OUTPUT
 283 (glibc since 2.1)
 284 Directory where
 285 .B LD_PROFILE
 286 output should be written.
 287 If this variable is not defined, or is defined as an empty string,
 288 then the default is
 289 .IR /var/tmp .
 290 .B LD_PROFILE_OUTPUT
 291 is ignored for set-user-ID and set-group-ID programs,
 292 which always use
 293 .IR /var/profile .
 294 .TP
 295 .B LD_SHOW_AUXV
 296 (glibc since 2.1)
 297 Show auxiliary array passed up from the kernel.
 298 For security reasons, since glibc 2.3.5,
 299 .B LD_SHOW_AUXV
 300 is ignored for set-user-ID/set-group-ID binaries.
 301 .\" FIXME
 302 .\" Document LD_TRACE_PRELINKING (e.g.: LD_TRACE_PRELINKING=libx1.so ./prog)
 303 .\" Since glibc 2.3
 304 .\" Also enables DL_DEBUG_PRELINK
 305 .TP
 306 .B LD_USE_LOAD_BIAS
 307 .\" http://sources.redhat.com/ml/libc-hacker/2003-11/msg00127.html
 308 .\" Subject: [PATCH] Support LD_USE_LOAD_BIAS
 309 .\" Jakub Jelinek
 310 By default (i.e., if this variable is not defined)
 311 executables and prelinked
 312 shared objects will honor base addresses of their dependent libraries
 313 and (nonprelinked) position-independent executables (PIEs)
 314 and other shared objects will not honor them.
 315 If
 316 .B LD_USE_LOAD_BIAS
 317 is defined wit the value, both executables and PIEs
 318 will honor the base addresses.
 319 If
 320 .B LD_USE_LOAD_BIAS
 321 is defined with the value 0,
 322 neither executables nor PIEs will honor the base addresses.
 323 This variable is ignored by set-user-ID and set-group-ID programs.
 324 .TP
 325 .B LD_VERBOSE
 326 (glibc since 2.1)
 327 If set to a nonempty string,
 328 output symbol versioning information about the
 329 program if querying information about the program (i.e., either
 330 .B LD_TRACE_LOADED_OBJECTS
 331 has been set, or
 332 .B \-\-list
 333 or
 334 .B \-\-verify
 335 options have been given to the dynamic linker).
 336 .TP
 337 .B LD_WARN
 338 (ELF only)(glibc since 2.1.3)
 339 If set to a nonempty string, warn about unresolved symbols.
 340 .TP
 341 .B LDD_ARGV0
 342 (libc5)
 343 .IR argv [0]
 344 to be used by
 345 .BR ldd (1)
 346 when none is present.
 347 .SH FILES
 348 .PD 0
 349 .TP
 350 .I /lib/ld.so
 351 a.out dynamic linker/loader
 352 .TP
 353 .IR /lib/ld\-linux.so. { 1 , 2 }
 354 ELF dynamic linker/loader
 355 .TP
 356 .I /etc/ld.so.cache
 357 File containing a compiled list of directories in which to search for
 358 libraries and an ordered list of candidate libraries.
 359 .TP
 360 .I /etc/ld.so.preload
 361 File containing a whitespace separated list of ELF shared libraries to
 362 be loaded before the program.
 363 .TP
 364 .B lib*.so*
 365 shared libraries
 366 .PD
 367 .SH NOTES
 368 The
 369 .B ld.so
 370 functionality is available for executables compiled using libc version
 371 4.4.3 or greater.
 372 ELF functionality is available since Linux 1.1.52 and libc5.
 373 .SH SEE ALSO
 374 .BR ldd (1),
 375 .BR rtld-audit (7),
 376 .BR ldconfig (8)
 377 .\" .SH AUTHORS
 378 .\" ld.so: David Engel, Eric Youngdale, Peter MacDonald, Hongjiu Lu, Linus
 379 .\"  Torvalds, Lars Wirzenius and Mitch D'Souza
 380 .\" ld-linux.so: Roland McGrath, Ulrich Drepper and others.
 381 .\"
 382 .\" In the above, (libc5) stands for David Engel's ld.so/ld-linux.so.