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 November 13, 2021
  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 translates dynamic token strings in rpath and soname.
  64 If the
  65 .Fl "z origin"
  66 option of the static linker was set when linking the binary,
  67 the token expansion is performed at the object load time, see
  68 .Xr ld 1 .
  69 The following strings are recognized now:
  70 .Bl -tag -width ".Pa $PLATFORM"
  71 .It Pa $ORIGIN
  72 Translated to the full path of the loaded object.
  73 .It Pa $OSNAME
  74 Translated to the name of the operating system implementation.
  75 .It Pa $OSREL
  76 Translated to the release level of the operating system.
  77 .It Pa $PLATFORM
  78 Translated to the machine hardware platform.
  79 .El
  80 .Pp
  81 The
  82 .Nm
  83 utility itself is loaded by the kernel together with any dynamically-linked
  84 program that is to be executed.
  85 The kernel transfers control to the
  86 dynamic linker.
  87 After the dynamic linker has finished loading,
  88 relocating, and initializing the program and its required shared
  89 objects, it transfers control to the entry point of the program.
  90 The following search order is used to locate required shared objects:
  91 .Pp
  92 .Bl -enum -offset indent -compact
  93 .It
  94 .Dv DT_RPATH
  95 of the referencing object unless that object also contains a
  96 .Dv DT_RUNPATH
  97 tag
  98 .It
  99 .Dv DT_RPATH
 100 of the program unless the referencing object contains a
 101 .Dv DT_RUNPATH
 102 tag
 103 .It
 104 Path indicated by
 105 .Ev LD_LIBRARY_PATH
 106 environment variable
 107 .It
 108 .Dv DT_RUNPATH
 109 of the referencing object
 110 .It
 111 Hints file produced by the
 112 .Xr ldconfig 8
 113 utility
 114 .It
 115 The
 116 .Pa /lib
 117 and
 118 .Pa /usr/lib
 119 directories, unless the referencing object was linked using the
 120 .Dq Fl z Ar nodefaultlib
 121 option
 122 .El
 123 .Pp
 124 The
 125 .Nm
 126 utility
 127 recognizes a number of environment variables that can be used to modify
 128 its behaviour.
 129 On 64-bit architectures, the linker for 32-bit objects recognizes
 130 all the environment variables listed below, but is being prefixed with
 131 .Ev LD_32_ ,
 132 for example:
 133 .Ev LD_32_TRACE_LOADED_OBJECTS .
 134 If the activated image is setuid or setgid, the variables are ignored.
 135 .Bl -tag -width ".Ev LD_LIBMAP_DISABLE"
 136 .It Ev LD_DUMP_REL_POST
 137 If set,
 138 .Nm
 139 will print a table containing all relocations after symbol
 140 binding and relocation.
 141 .It Ev LD_DUMP_REL_PRE
 142 If set,
 143 .Nm
 144 will print a table containing all relocations before symbol
 145 binding and relocation.
 146 .It Ev LD_DYNAMIC_WEAK
 147 If set, use the ELF standard-compliant symbol lookup behavior:
 148 resolve to the first found symbol definition.
 149 .Pp
 150 By default,
 151 .Fx
 152 provides the non-standard symbol lookup behavior:
 153 when a weak symbol definition is found, remember the definition and
 154 keep searching in the remaining shared objects for a non-weak definition.
 155 If found, the non-weak definition is preferred, otherwise the remembered
 156 weak definition is returned.
 157 .Pp
 158 Symbols exported by dynamic linker itself (see
 159 .Xr dlfcn 3 )
 160 are always resolved using
 161 .Fx
 162 rules regardless of the presence of the variable.
 163 This variable is unset for set-user-ID and set-group-ID programs.
 164 .It Ev LD_LIBMAP
 165 A library replacement list in the same format as
 166 .Xr libmap.conf 5 .
 167 For convenience, the characters
 168 .Ql =
 169 and
 170 .Ql \&,
 171 can be used instead of a space and a newline.
 172 This variable is parsed after
 173 .Xr libmap.conf 5 ,
 174 and will override its entries.
 175 This variable is unset for set-user-ID and set-group-ID programs.
 176 .It Ev LD_LIBMAP_DISABLE
 177 If set, disables the use of
 178 .Xr libmap.conf 5
 179 and
 180 .Ev LD_LIBMAP .
 181 This variable is unset for set-user-ID and set-group-ID programs.
 182 .It Ev LD_ELF_HINTS_PATH
 183 This variable will override the default location of
 184 .Dq hints
 185 file.
 186 This variable is unset for set-user-ID and set-group-ID programs.
 187 .It Ev LD_LIBRARY_PATH
 188 A colon separated list of directories, overriding the default search path
 189 for shared libraries.
 190 This variable is unset for set-user-ID and set-group-ID programs.
 191 .It Ev LD_LIBRARY_PATH_RPATH
 192 If the variable is specified and has a value starting with
 193 any of \'y\', \'Y\' or \'1\' symbols, the path specified by
 194 .Ev LD_LIBRARY_PATH
 195 variable is allowed to override the path from
 196 .Dv DT_RPATH
 197 for binaries which does not contain
 198 .Dv DT_RUNPATH
 199 tag.
 200 For such binaries, when the variable
 201 .Ev LD_LIBRARY_PATH_RPATH
 202 is set,
 203 .Dq Fl z Ar nodefaultlib
 204 link-time option is ignored as well.
 205 .It Ev LD_PRELOAD
 206 A list of shared libraries, separated by colons and/or white space,
 207 to be linked in before any
 208 other shared libraries.
 209 If the directory is not specified then
 210 the directories specified by
 211 .Ev LD_LIBRARY_PATH
 212 will be searched first
 213 followed by the set of built-in standard directories.
 214 This variable is unset for set-user-ID and set-group-ID programs.
 215 .It Ev LD_PRELOAD_FDS
 216 A colon separated list of file descriptor numbers for libraries.
 217 This is intended for preloading libraries in which we already have a file
 218 descriptor.
 219 This may optimize the process of loading libraries because we do not have to
 220 look for them in directories.
 221 It may also be useful in a capability base system where we do not have access to
 222 global namespaces such as the filesystem.
 223 .It Ev LD_LIBRARY_PATH_FDS
 224 A colon separated list of file descriptor numbers for library directories.
 225 This is intended for use within
 226 .Xr capsicum 4
 227 sandboxes, when global namespaces such as the filesystem are unavailable.
 228 It is consulted just after LD_LIBRARY_PATH.
 229 This variable is unset for set-user-ID and set-group-ID programs.
 230 .It Ev LD_BIND_NOT
 231 When set to a nonempty string, prevents modifications of the PLT slots when
 232 doing bindings.
 233 As result, each call of the PLT-resolved function is resolved.
 234 In combination with debug output, this provides complete account of
 235 all bind actions at runtime.
 236 This variable is unset for set-user-ID and set-group-ID programs.
 237 .It Ev LD_BIND_NOW
 238 When set to a nonempty string, causes
 239 .Nm
 240 to relocate all external function calls before starting execution of the
 241 program.
 242 Normally, function calls are bound lazily, at the first call
 243 of each function.
 244 .Ev LD_BIND_NOW
 245 increases the start-up time of a program, but it avoids run-time
 246 surprises caused by unexpectedly undefined functions.
 247 .It Ev LD_TRACE_LOADED_OBJECTS
 248 When set to a nonempty string, causes
 249 .Nm
 250 to exit after loading the shared objects and printing a summary which includes
 251 the absolute pathnames of all objects, to standard output.
 252 .It Ev LD_TRACE_LOADED_OBJECTS_ALL
 253 When set to a nonempty string, causes
 254 .Nm
 255 to expand the summary to indicate which objects caused each object to
 256 be loaded.
 257 .It Ev LD_TRACE_LOADED_OBJECTS_FMT1
 258 .It Ev LD_TRACE_LOADED_OBJECTS_FMT2
 259 When set, these variables are interpreted as format strings a la
 260 .Xr printf 3
 261 to customize the trace output and are used by
 262 .Xr ldd 1 Ns 's
 263 .Fl f
 264 option and allows
 265 .Xr ldd 1
 266 to be operated as a filter more conveniently.
 267 If the dependency name starts with string
 268 .Pa lib ,
 269 .Ev LD_TRACE_LOADED_OBJECTS_FMT1
 270 is used, otherwise
 271 .Ev LD_TRACE_LOADED_OBJECTS_FMT2
 272 is used.
 273 The following conversions can be used:
 274 .Bl -tag -width 4n
 275 .It Li %a
 276 The main program's name
 277 (also known as
 278 .Dq __progname ) .
 279 .It Li \&%A
 280 The value of the environment variable
 281 .Ev LD_TRACE_LOADED_OBJECTS_PROGNAME .
 282 Typically used to print both the names of programs and shared libraries
 283 being inspected using
 284 .Xr ldd 1 .
 285 .It Li %o
 286 The library name.
 287 .It Li %p
 288 The full pathname as determined by
 289 .Nm rtld Ns 's
 290 library search rules.
 291 .It Li %x
 292 The library's load address.
 293 .El
 294 .Pp
 295 Additionally,
 296 .Ql \en
 297 and
 298 .Ql \et
 299 are recognized and have their usual meaning.
 300 .It Ev LD_UTRACE
 301 If set,
 302 .Nm
 303 will log events such as the loading and unloading of shared objects via
 304 .Xr utrace 2 .
 305 .It Ev LD_LOADFLTR
 306 If set,
 307 .Nm
 308 will process the filtee dependencies of the loaded objects immediately,
 309 instead of postponing it until required.
 310 Normally, the filtees are opened at the time of the first symbol resolution
 311 from the filter object.
 312 .It Ev LD_SHOW_AUXV
 313 If set, causes
 314 .Nm
 315 to dump content of the aux vector to standard output, before passing
 316 control to any user code.
 317 .El
 318 .Sh DIRECT EXECUTION MODE
 319 .Nm
 320 is typically used implicitly, loaded by the kernel as requested by the
 321 .Dv PT_INTERP
 322 program header of the executed binary.
 323 .Fx
 324 also supports a direct execution mode for the dynamic linker.
 325 In this mode, the user explicitly executes
 326 .Nm
 327 and provides the path of the program to be linked and executed as
 328 an argument.
 329 This mode allows use of a non-standard dynamic linker for a program
 330 activation without changing the binary or without changing
 331 the installed dynamic linker.
 332 Execution options may be specified.
 333 .Pp
 334 The syntax of the direct invocation is
 335 .Bd -ragged -offset indent
 336 .Pa /libexec/ld-elf.so.1
 337 .Op Fl b Ar exe
 338 .Op Fl d
 339 .Op Fl f Ar fd
 340 .Op Fl p
 341 .Op Fl u
 342 .Op Fl v
 343 .Op Fl -
 344 .Pa image_path
 345 .Op Ar image arguments
 346 .Ed
 347 .Pp
 348 The options are:
 349 .Bl -tag -width indent
 350 .It Fl b Ar exe
 351 Use the executable
 352 .Fa exe
 353 instead of
 354 .Fa image_path
 355 for activation.
 356 If this option is specified,
 357 .Ar image_path
 358 is only used to provide the
 359 .Va argv[0]
 360 value to the program.
 361 .It Fl d
 362 Turn off the emulation of the binary execute permission.
 363 .It Fl f Ar fd
 364 File descriptor
 365 .Ar fd
 366 references the binary to be activated by
 367 .Nm .
 368 It must already be opened in the process when executing
 369 .Nm .
 370 If this option is specified,
 371 .Ar image_path
 372 is only used to provide the
 373 .Va argv[0]
 374 value to the program.
 375 .It Fl p
 376 If the
 377 .Pa image_path
 378 argument specifies a name which does not contain a slash
 379 .Dq Li /
 380 character,
 381 .Nm
 382 uses the search path provided by the environment variable
 383 .Dv PATH
 384 to find the binary to execute.
 385 .It Fl u
 386 Ignore all
 387 .Ev LD_
 388 environment variables that otherwise affect the dynamic
 389 linker behavior.
 390 .It Fl v
 391 Display information about this run-time linker binary, then exit.
 392 .It Fl -
 393 Ends the
 394 .Nm
 395 options.
 396 The argument following
 397 .Fl -
 398 is interpreted as the path of the binary to execute.
 399 .El
 400 .Pp
 401 In the direct execution mode,
 402 .Nm
 403 emulates verification of the binary execute permission for the
 404 current user.
 405 This is done to avoid breaking user expectations in naively restricted
 406 execution environments.
 407 The verification only uses Unix
 408 .Dv DACs ,
 409 ignores
 410 .Dv ACLs ,
 411 and is naturally prone to race conditions.
 412 Environments which rely on such restrictions are weak
 413 and breakable on their own.
 414 It can be turned off with the
 415 .Fl d
 416 option.
 417 .Sh VERSIONING
 418 Newer
 419 .Nm
 420 might provide some features or changes in runtime behavior that cannot be
 421 easily detected at runtime by checking of the normal exported symbols.
 422 Note that it is almost always wrong to verify
 423 .Dv __FreeBSD_version
 424 in userspace to detect features, either at compile or at run time,
 425 because either kernel, or libc, or environment variables could not
 426 match the running
 427 .Nm .
 428 .Pp
 429 To solve the problem,
 430 .Nm
 431 exports some feature indicators in the
 432 .Fx
 433 private symbols namespace
 434 .Dv FBSDprivate_1.0 .
 435 Symbols start with the
 436 .Dv _rtld_version
 437 prefix.
 438 Current list of defined symbols and corresponding features is:
 439 .Bl -tag -width indent
 440 .It Dv _rtld_version__FreeBSD_version
 441 Symbol exports the value of the
 442 .Dv __FreeBSD_version
 443 definition as it was provided during the
 444 .Nm
 445 build.
 446 The symbol is always present since the
 447 .Dv _rtld_version
 448 facility was introduced.
 449 .It Dv _rtld_version_laddr_offset
 450 The
 451 .Va l_addr
 452 member of the
 453 .Vt link_map
 454 structure contains the load offset of the shared object.
 455 Before that,
 456 .Va l_addr
 457 contained the base address of the library.
 458 See
 459 .Xr dlinfo 3 .
 460 .Pp
 461 Also it indicates the presence of
 462 .Va l_refname
 463 member of the structure.
 464 .It Dv _rtld_version_dlpi_tls_data
 465 The
 466 .Va dlpi_tls_data
 467 member of the structure
 468 .Vt dl_phdr_info
 469 contains the address of the module TLS segment for the calling thread,
 470 and not the address of the initialization segment.
 471 .El
 472 .Sh FILES
 473 .Bl -tag -width ".Pa /var/run/ld-elf32.so.hints" -compact
 474 .It Pa /var/run/ld-elf.so.hints
 475 Hints file.
 476 .It Pa /var/run/ld-elf32.so.hints
 477 Hints file for 32-bit binaries on 64-bit system.
 478 .It Pa /etc/libmap.conf
 479 The libmap configuration file.
 480 .It Pa /etc/libmap32.conf
 481 The libmap configuration file for 32-bit binaries on 64-bit system.
 482 .El
 483 .Sh SEE ALSO
 484 .Xr ld 1 ,
 485 .Xr ldd 1 ,
 486 .Xr dlinfo 3 ,
 487 .Xr capsicum 4 ,
 488 .Xr elf 5 ,
 489 .Xr libmap.conf 5 ,
 490 .Xr ldconfig 8