man8/ld.so.8

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