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 .B \-\-audit LIST
 130 Use objects named in LIST as auditors.
 131 .SH ENVIRONMENT
 132 There are four important environment variables.
 133 .TP
 134 .B LD_BIND_NOW
 135 (libc5; glibc since 2.1.1)
 136 If set to a nonempty string,
 137 causes the dynamic linker to resolve all symbols
 138 at program startup instead of deferring function call resolution to the point
 139 when they are first referenced.
 140 This is useful when using a debugger.
 141 .TP
 142 .B LD_LIBRARY_PATH
 143 A colon-separated list of directories in which to search for
 144 ELF libraries at execution-time.
 145 Similar to the
 146 .B PATH
 147 environment variable.
 148 .TP
 149 .B LD_PRELOAD
 150 A whitespace-separated list of additional, user-specified, ELF shared
 151 libraries to be loaded before all others.
 152 This can be used to selectively override functions in other shared libraries.
 153 For set-user-ID/set-group-ID ELF binaries,
 154 only libraries in the standard search
 155 directories that are also set-user-ID will be loaded.
 156 .TP
 157 .B LD_TRACE_LOADED_OBJECTS
 158 (ELF only)
 159 If set to a nonempty string, causes the program to list its dynamic library
 160 dependencies, as if run by
 161 .BR ldd (1),
 162 instead of running normally.
 163 .LP
 164 Then there are lots of more or less obscure variables,
 165 many obsolete or only for internal use.
 166 .TP
 167 .B LD_AOUT_LIBRARY_PATH
 168 (libc5)
 169 Version of
 170 .B LD_LIBRARY_PATH
 171 for a.out binaries only.
 172 Old versions of ld\-linux.so.1 also supported
 173 .BR LD_ELF_LIBRARY_PATH .
 174 .TP
 175 .B LD_AOUT_PRELOAD
 176 (libc5)
 177 Version of
 178 .B LD_PRELOAD
 179 for a.out binaries only.
 180 Old versions of ld\-linux.so.1 also supported
 181 .BR LD_ELF_PRELOAD .
 182 .TP
 183 .B LD_AUDIT
 184 (glibc since 2.4)
 185 A colon-separated list of user-specified, ELF shared objects
 186 to be loaded before all others in a separate linker namespace
 187 (i.e., one that does not intrude upon the normal symbol bindings that
 188 would occur in the process).
 189 These libraries can be used to audit the operation of the dynamic linker.
 190 .B LD_AUDIT
 191 is ignored for set-user-ID/set-group-ID binaries.
 192
 193 The dynamic linker will notify the audit
 194 libraries at so-called auditing checkpoints\(emfor example,
 195 loading a new library, resolving a symbol,
 196 or calling a symbol from another shared object\(emby
 197 calling an appropriate function within the audit library.
 198 For details, see
 199 .BR rtld-audit (7).
 200 The auditing interface is largely compatible with that provided on Solaris,
 201 as described in its
 202 .IR "Linker and Libraries Guide" ,
 203 in the chapter
 204 .IR "Runtime Linker Auditing Interface" .
 205 .TP
 206 .B LD_BIND_NOT
 207 (glibc since 2.1.95)
 208 Do not update the GOT (global offset table) and PLT (procedure linkage table)
 209 after resolving a symbol.
 210 .TP
 211 .B LD_DEBUG
 212 (glibc since 2.1)
 213 Output verbose debugging information about the dynamic linker.
 214 If set to
 215 .B all
 216 prints all debugging information it has, if set to
 217 .B help
 218 prints a help message about which categories can be specified in this
 219 environment variable.
 220 Since glibc 2.3.4,
 221 .B LD_DEBUG
 222 is ignored for set-user-ID/set-group-ID binaries.
 223 .TP
 224 .B LD_DEBUG_OUTPUT
 225 (glibc since 2.1)
 226 File where
 227 .B LD_DEBUG
 228 output should be fed into, default is standard output.
 229 .B LD_DEBUG_OUTPUT
 230 is ignored for set-user-ID/set-group-ID binaries.
 231 .TP
 232 .B LD_DYNAMIC_WEAK
 233 (glibc since 2.1.91)
 234 Allow weak symbols to be overridden (reverting to old glibc behavior).
 235 For security reasons, since glibc 2.3.4,
 236 .B LD_DYNAMIC_WEAK
 237 is ignored for set-user-ID/set-group-ID binaries.
 238 .TP
 239 .B LD_HWCAP_MASK
 240 (glibc since 2.1)
 241 Mask for hardware capabilities.
 242 .TP
 243 .B LD_KEEPDIR
 244 (a.out only)(libc5)
 245 Don't ignore the directory in the names of a.out libraries to be loaded.
 246 Use of this option is strongly discouraged.
 247 .TP
 248 .B LD_NOWARN
 249 (a.out only)(libc5)
 250 Suppress warnings about a.out libraries with incompatible minor
 251 version numbers.
 252 .TP
 253 .B LD_ORIGIN_PATH
 254 (glibc since 2.1)
 255 Path where the binary is found (for non-set-user-ID programs).
 256 For security reasons, since glibc 2.4,
 257 .B LD_ORIGIN_PATH
 258 is ignored for set-user-ID/set-group-ID binaries.
 259 .\" Only used if $ORIGIN can't be determined by normal means
 260 .\" (from the origin path saved at load time, or from /proc/self/exe)?
 261 .TP
 262 .B LD_POINTER_GUARD
 263 (glibc since 2.4)
 264 Set to 0 to disable pointer guarding.
 265 Any other value enables pointer guarding, which is also the default.
 266 Pointer guarding is a security mechanism whereby some pointers to code
 267 stored in writable program memory (return addresses saved by
 268 .BR setjmp (3)
 269 or function pointers used by various glibc internals) are mangled
 270 semi-randomly to make it more difficult for an attacker to hijack
 271 the pointers for use in the event of a buffer overrun or
 272 stack-smashing attack.
 273 .TP
 274 .B LD_PROFILE
 275 (glibc since 2.1)
 276 Shared object to be profiled,
 277 specified either as a pathname or a soname.
 278 Profiling output is written to the file whose name is:
 279 "\fI$LD_PROFILE_OUTPUT\fP/\fI$LD_PROFILE\fP.profile".
 280 .TP
 281 .B LD_PROFILE_OUTPUT
 282 (glibc since 2.1)
 283 Directory where
 284 .B LD_PROFILE
 285 output should be written.
 286 If this variable is not defined, or is defined as an empty string,
 287 then the default is
 288 .IR /var/tmp .
 289 .B LD_PROFILE_OUTPUT
 290 is ignored for set-user-ID and set-group-ID programs,
 291 which always use
 292 .IR /var/profile .
 293 .TP
 294 .B LD_SHOW_AUXV
 295 (glibc since 2.1)
 296 Show auxiliary array passed up from the kernel.
 297 For security reasons, since glibc 2.3.5,
 298 .B LD_SHOW_AUXV
 299 is ignored for set-user-ID/set-group-ID binaries.
 300 .\" FIXME
 301 .\" Document LD_TRACE_PRELINKING (e.g.: LD_TRACE_PRELINKING=libx1.so ./prog)
 302 .\" Since glibc 2.3
 303 .\" Also enables DL_DEBUG_PRELINK
 304 .TP
 305 .B LD_USE_LOAD_BIAS
 306 .\" http://sources.redhat.com/ml/libc-hacker/2003-11/msg00127.html
 307 .\" Subject: [PATCH] Support LD_USE_LOAD_BIAS
 308 .\" Jakub Jelinek
 309 By default (i.e., if this variable is not defined)
 310 executables and prelinked
 311 shared objects will honor base addresses of their dependent libraries
 312 and (nonprelinked) position-independent executables (PIEs)
 313 and other shared objects will not honor them.
 314 If
 315 .B LD_USE_LOAD_BIAS
 316 is defined wit the value, both executables and PIEs
 317 will honor the base addresses.
 318 If
 319 .B LD_USE_LOAD_BIAS
 320 is defined with the value 0,
 321 neither executables nor PIEs will honor the base addresses.
 322 This variable is ignored by set-user-ID and set-group-ID programs.
 323 .TP
 324 .B LD_VERBOSE
 325 (glibc since 2.1)
 326 If set to a nonempty string,
 327 output symbol versioning information about the
 328 program if querying information about the program (i.e., either
 329 .B LD_TRACE_LOADED_OBJECTS
 330 has been set, or
 331 .B \-\-list
 332 or
 333 .B \-\-verify
 334 options have been given to the dynamic linker).
 335 .TP
 336 .B LD_WARN
 337 (ELF only)(glibc since 2.1.3)
 338 If set to a nonempty string, warn about unresolved symbols.
 339 .TP
 340 .B LDD_ARGV0
 341 (libc5)
 342 .IR argv [0]
 343 to be used by
 344 .BR ldd (1)
 345 when none is present.
 346 .SH FILES
 347 .PD 0
 348 .TP
 349 .I /lib/ld.so
 350 a.out dynamic linker/loader
 351 .TP
 352 .IR /lib/ld\-linux.so. { 1 , 2 }
 353 ELF dynamic linker/loader
 354 .TP
 355 .I /etc/ld.so.cache
 356 File containing a compiled list of directories in which to search for
 357 libraries and an ordered list of candidate libraries.
 358 .TP
 359 .I /etc/ld.so.preload
 360 File containing a whitespace separated list of ELF shared libraries to
 361 be loaded before the program.
 362 .TP
 363 .B lib*.so*
 364 shared libraries
 365 .PD
 366 .SH NOTES
 367 The
 368 .B ld.so
 369 functionality is available for executables compiled using libc version
 370 4.4.3 or greater.
 371 ELF functionality is available since Linux 1.1.52 and libc5.
 372 .SH SEE ALSO
 373 .BR ldd (1),
 374 .BR rtld-audit (7),
 375 .BR ldconfig (8)
 376 .\" .SH AUTHORS
 377 .\" ld.so: David Engel, Eric Youngdale, Peter MacDonald, Hongjiu Lu, Linus
 378 .\"  Torvalds, Lars Wirzenius and Mitch D'Souza
 379 .\" ld-linux.so: Roland McGrath, Ulrich Drepper and others.
 380 .\"
 381 .\" In the above, (libc5) stands for David Engel's ld.so/ld-linux.so.