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