libexec/rtld-elf/rtld.1

   1 .\" Copyright (c) 1995 Paul Kranenburg
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgment:
  14 .\"      This product includes software developed by Paul Kranenburg.
  15 .\" 3. The name of the author may not be used to endorse or promote products
  16 .\"    derived from this software without specific prior written permission
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  19 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  20 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  21 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  22 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  23 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  24 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  25 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  26 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  27 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd June 28, 2012
  32 .Dt RTLD 1
  33 .Os
  34 .Sh NAME
  35 .Nm ld-elf.so.1 ,
  36 .Nm ld.so ,
  37 .Nm rtld
  38 .Nd run-time link-editor
  39 .Sh DESCRIPTION
  40 The
  41 .Nm
  42 utility is a self-contained shared object providing run-time
  43 support for loading and link-editing shared objects into a process'
  44 address space.
  45 It is also commonly known as the dynamic linker.
  46 It uses the data structures
  47 contained within dynamically linked programs to determine which shared
  48 libraries are needed and loads them using the
  49 .Xr mmap 2
  50 system call.
  51 .Pp
  52 After all shared libraries have been successfully loaded,
  53 .Nm
  54 proceeds to resolve external references from both the main program and
  55 all objects loaded.
  56 A mechanism is provided for initialization routines
  57 to be called on a per-object basis, giving a shared object an opportunity
  58 to perform any extra set-up before execution of the program proper begins.
  59 This is useful for C++ libraries that contain static constructors.
  60 .Pp
  61 When resolving dependencies for the loaded objects,
  62 .Nm
  63 may be allowed to translate dynamic token strings in rpath and soname
  64 by setting
  65 .Fl "z origin"
  66 option of the static linker
  67 .Xr ld 1 .
  68 The following strings are recognized now:
  69 .Bl -tag -width ".Pa $PLATFORM"
  70 .It Pa $ORIGIN
  71 Translated to the full path of the loaded object.
  72 .It Pa $OSNAME
  73 Translated to the name of the operating system implementation.
  74 .It Pa $OSREL
  75 Translated to the release level of the operating system.
  76 .It Pa $PLATFORM
  77 Translated to the machine hardware platform.
  78 .El
  79 .Pp
  80 The
  81 .Nm
  82 utility itself is loaded by the kernel together with any dynamically-linked
  83 program that is to be executed.
  84 The kernel transfers control to the
  85 dynamic linker.
  86 After the dynamic linker has finished loading,
  87 relocating, and initializing the program and its required shared
  88 objects, it transfers control to the entry point of the program.
  89 The following search order is used to locate required shared objects:
  90 .Pp
  91 .Bl -enum -offset indent -compact
  92 .It
  93 .Dv DT_RPATH
  94 of the referencing object unless that object also contains a
  95 .Dv DT_RUNPATH
  96 tag
  97 .It
  98 .Dv DT_RPATH
  99 of the program unless the referencing object contains a
 100 .Dv DT_RUNPATH
 101 tag
 102 .It
 103 Path indicated by
 104 .Ev LD_LIBRARY_PATH
 105 environment variable
 106 .It
 107 .Dv DT_RUNPATH
 108 of the referencing object
 109 .It
 110 Hints file produced by the
 111 .Xr ldconfig 8
 112 utility
 113 .It
 114 The
 115 .Pa /lib
 116 and
 117 .Pa /usr/lib
 118 directories, unless the referencing object was linked using the
 119 .Dq Fl z Ar nodefaultlib
 120 option
 121 .El
 122 .Pp
 123 The
 124 .Nm
 125 utility
 126 recognizes a number of environment variables that can be used to modify
 127 its behaviour.
 128 On 64-bit architectures, the linker for 32-bit objects recognizes
 129 all the environment variables listed below, but is being prefixed with
 130 .Ev LD_32_ ,
 131 for example:
 132 .Ev LD_32_TRACE_LOADED_OBJECTS .
 133 .Bl -tag -width ".Ev LD_LIBMAP_DISABLE"
 134 .It Ev LD_DUMP_REL_POST
 135 If set,
 136 .Nm
 137 will print a table containing all relocations after symbol
 138 binding and relocation.
 139 .It Ev LD_DUMP_REL_PRE
 140 If set,
 141 .Nm
 142 will print a table containing all relocations before symbol
 143 binding and relocation.
 144 .It Ev LD_LIBMAP
 145 A library replacement list in the same format as
 146 .Xr libmap.conf 5 .
 147 For convenience, the characters
 148 .Ql =
 149 and
 150 .Ql \&,
 151 can be used instead of a space and a newline.
 152 This variable is parsed after
 153 .Xr libmap.conf 5 ,
 154 and will override its entries.
 155 This variable is unset for set-user-ID and set-group-ID programs.
 156 .It Ev LD_LIBMAP_DISABLE
 157 If set, disables the use of
 158 .Xr libmap.conf 5
 159 and
 160 .Ev LD_LIBMAP .
 161 This variable is unset for set-user-ID and set-group-ID programs.
 162 .It Ev LD_ELF_HINTS_PATH
 163 This variable will override the default location of
 164 .Dq hints
 165 file.
 166 This variable is unset for set-user-ID and set-group-ID programs.
 167 .It Ev LD_LIBRARY_PATH
 168 A colon separated list of directories, overriding the default search path
 169 for shared libraries.
 170 This variable is unset for set-user-ID and set-group-ID programs.
 171 .It Ev LD_LIBRARY_PATH_RPATH
 172 If the variable is specified and has a value starting with
 173 any of \'y\', \'Y\' or \'1\' symbols, the path specified by
 174 .Ev LD_LIBRARY_PATH
 175 variable is allowed to override the path from
 176 .Dv DT_RPATH
 177 for binaries which does not contain
 178 .Dv DT_RUNPATH
 179 tag.
 180 For such binaries, when the variable
 181 .Ev LD_LIBRARY_PATH_RPATH
 182 is set,
 183 .Dq Fl z Ar nodefaultlib
 184 link-time option is ignored as well.
 185 .It Ev LD_PRELOAD
 186 A list of shared libraries, separated by colons and/or white space,
 187 to be linked in before any
 188 other shared libraries.
 189 If the directory is not specified then
 190 the directories specified by
 191 .Ev LD_LIBRARY_PATH
 192 will be searched first
 193 followed by the set of built-in standard directories.
 194 This variable is unset for set-user-ID and set-group-ID programs.
 195 .It Ev LD_BIND_NOW
 196 When set to a nonempty string, causes
 197 .Nm
 198 to relocate all external function calls before starting execution of the
 199 program.
 200 Normally, function calls are bound lazily, at the first call
 201 of each function.
 202 .Ev LD_BIND_NOW
 203 increases the start-up time of a program, but it avoids run-time
 204 surprises caused by unexpectedly undefined functions.
 205 .It Ev LD_TRACE_LOADED_OBJECTS
 206 When set to a nonempty string, causes
 207 .Nm
 208 to exit after loading the shared objects and printing a summary which includes
 209 the absolute pathnames of all objects, to standard output.
 210 .It Ev LD_TRACE_LOADED_OBJECTS_ALL
 211 When set to a nonempty string, causes
 212 .Nm
 213 to expand the summary to indicate which objects caused each object to
 214 be loaded.
 215 .It Ev LD_TRACE_LOADED_OBJECTS_FMT1
 216 .It Ev LD_TRACE_LOADED_OBJECTS_FMT2
 217 When set, these variables are interpreted as format strings a la
 218 .Xr printf 3
 219 to customize the trace output and are used by
 220 .Xr ldd 1 Ns 's
 221 .Fl f
 222 option and allows
 223 .Xr ldd 1
 224 to be operated as a filter more conveniently.
 225 If the dependency name starts with string
 226 .Pa lib ,
 227 .Ev LD_TRACE_LOADED_OBJECTS_FMT1
 228 is used, otherwise
 229 .Ev LD_TRACE_LOADED_OBJECTS_FMT2
 230 is used.
 231 The following conversions can be used:
 232 .Bl -tag -width 4n
 233 .It Li %a
 234 The main program's name
 235 (also known as
 236 .Dq __progname ) .
 237 .It Li \&%A
 238 The value of the environment variable
 239 .Ev LD_TRACE_LOADED_OBJECTS_PROGNAME .
 240 Typically used to print both the names of programs and shared libraries
 241 being inspected using
 242 .Xr ldd 1 .
 243 .It Li %o
 244 The library name.
 245 .It Li %p
 246 The full pathname as determined by
 247 .Nm rtld Ns 's
 248 library search rules.
 249 .It Li %x
 250 The library's load address.
 251 .El
 252 .Pp
 253 Additionally,
 254 .Ql \en
 255 and
 256 .Ql \et
 257 are recognized and have their usual meaning.
 258 .It Ev LD_UTRACE
 259 If set,
 260 .Nm
 261 will log events such as the loading and unloading of shared objects via
 262 .Xr utrace 2 .
 263 .Pp
 264 .It Ev LD_LOADFLTR
 265 If set,
 266 .Nm
 267 will process the filtee dependencies of the loaded objects immediately,
 268 instead of postponing it until required.
 269 Normally, the filtees are opened at the time of the first symbol resolution
 270 from the filter object.
 271 .El
 272 .Sh FILES
 273 .Bl -tag -width ".Pa /var/run/ld-elf32.so.hints" -compact
 274 .It Pa /var/run/ld-elf.so.hints
 275 Hints file.
 276 .It Pa /var/run/ld-elf32.so.hints
 277 Hints file for 32-bit binaries on 64-bit system.
 278 .It Pa /etc/libmap.conf
 279 The libmap configuration file.
 280 .It Pa /etc/libmap32.conf
 281 The libmap configuration file for 32-bit binaries on 64-bit system.
 282 .El
 283 .Sh SEE ALSO
 284 .Xr ld 1 ,
 285 .Xr ldd 1 ,
 286 .Xr elf 5 ,
 287 .Xr libmap.conf 5 ,
 288 .Xr ldconfig 8