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 March 16, 2017
  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 .Ev LD_LIBRARY_PATH_FDS
 196 A colon separated list of file descriptor numbers for library directories.
 197 This is intended for use within
 198 .Xr capsicum 4
 199 sandboxes, when global namespaces such as the filesystem are unavailable.
 200 It is consulted just after LD_LIBRARY_PATH.
 201 This variable is unset for set-user-ID and set-group-ID programs.
 202 .It Ev LD_BIND_NOT
 203 When set to a nonempty string, prevents modifications of the PLT slots when
 204 doing bindings.
 205 As result, each call of the PLT-resolved function is resolved.
 206 In combination with debug output, this provides complete account of
 207 all bind actions at runtime.
 208 This variable is unset for set-user-ID and set-group-ID programs.
 209 .It Ev LD_BIND_NOW
 210 When set to a nonempty string, causes
 211 .Nm
 212 to relocate all external function calls before starting execution of the
 213 program.
 214 Normally, function calls are bound lazily, at the first call
 215 of each function.
 216 .Ev LD_BIND_NOW
 217 increases the start-up time of a program, but it avoids run-time
 218 surprises caused by unexpectedly undefined functions.
 219 .It Ev LD_TRACE_LOADED_OBJECTS
 220 When set to a nonempty string, causes
 221 .Nm
 222 to exit after loading the shared objects and printing a summary which includes
 223 the absolute pathnames of all objects, to standard output.
 224 .It Ev LD_TRACE_LOADED_OBJECTS_ALL
 225 When set to a nonempty string, causes
 226 .Nm
 227 to expand the summary to indicate which objects caused each object to
 228 be loaded.
 229 .It Ev LD_TRACE_LOADED_OBJECTS_FMT1
 230 .It Ev LD_TRACE_LOADED_OBJECTS_FMT2
 231 When set, these variables are interpreted as format strings a la
 232 .Xr printf 3
 233 to customize the trace output and are used by
 234 .Xr ldd 1 Ns 's
 235 .Fl f
 236 option and allows
 237 .Xr ldd 1
 238 to be operated as a filter more conveniently.
 239 If the dependency name starts with string
 240 .Pa lib ,
 241 .Ev LD_TRACE_LOADED_OBJECTS_FMT1
 242 is used, otherwise
 243 .Ev LD_TRACE_LOADED_OBJECTS_FMT2
 244 is used.
 245 The following conversions can be used:
 246 .Bl -tag -width 4n
 247 .It Li %a
 248 The main program's name
 249 (also known as
 250 .Dq __progname ) .
 251 .It Li \&%A
 252 The value of the environment variable
 253 .Ev LD_TRACE_LOADED_OBJECTS_PROGNAME .
 254 Typically used to print both the names of programs and shared libraries
 255 being inspected using
 256 .Xr ldd 1 .
 257 .It Li %o
 258 The library name.
 259 .It Li %p
 260 The full pathname as determined by
 261 .Nm rtld Ns 's
 262 library search rules.
 263 .It Li %x
 264 The library's load address.
 265 .El
 266 .Pp
 267 Additionally,
 268 .Ql \en
 269 and
 270 .Ql \et
 271 are recognized and have their usual meaning.
 272 .It Ev LD_UTRACE
 273 If set,
 274 .Nm
 275 will log events such as the loading and unloading of shared objects via
 276 .Xr utrace 2 .
 277 .It Ev LD_LOADFLTR
 278 If set,
 279 .Nm
 280 will process the filtee dependencies of the loaded objects immediately,
 281 instead of postponing it until required.
 282 Normally, the filtees are opened at the time of the first symbol resolution
 283 from the filter object.
 284 .El
 285 .Sh FILES
 286 .Bl -tag -width ".Pa /var/run/ld-elf32.so.hints" -compact
 287 .It Pa /var/run/ld-elf.so.hints
 288 Hints file.
 289 .It Pa /var/run/ld-elf32.so.hints
 290 Hints file for 32-bit binaries on 64-bit system.
 291 .It Pa /etc/libmap.conf
 292 The libmap configuration file.
 293 .It Pa /etc/libmap32.conf
 294 The libmap configuration file for 32-bit binaries on 64-bit system.
 295 .El
 296 .Sh SEE ALSO
 297 .Xr ld 1 ,
 298 .Xr ldd 1 ,
 299 .Xr capsicum 4 ,
 300 .Xr elf 5 ,
 301 .Xr libmap.conf 5 ,
 302 .Xr ldconfig 8