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 20, 2014 32.Dt RTLD 1 33.Os 34.Sh NAME 35.Nm ld-elf.so.2 , 36.Nm ld-elf.so.1 , 37.Nm rtld , 38.Nm _rtld_functrace 39.Nd run-time link-editor 40.Sh SYNOPSIS 41.Ft int 42.Fn _rtld_functrace "const char *callerso" "const char *calleeso" "const char *calleefun" "void *stack" 43.Sh DESCRIPTION 44The 45.Nm 46utility is a self-contained shared object providing run-time 47support for loading and link-editing shared objects into a process' 48address space. 49It is also commonly known as the dynamic linker. 50It uses the data structures 51contained within dynamically linked programs to determine which shared 52libraries are needed and loads them using the 53.Xr mmap 2 54system call. 55.Pp 56After all shared libraries have been successfully loaded, 57.Nm 58proceeds to resolve external references from both the main program and 59all objects loaded. 60A mechanism is provided for initialization routines 61to be called on a per-object basis, giving a shared object an opportunity 62to perform any extra set-up before execution of the program proper begins. 63This is useful for C++ libraries that contain static constructors. 64.Pp 65When resolving dependencies for the loaded objects, 66.Nm 67may be allowed to translate dynamic token strings in rpath and soname 68by setting 69.Fl "z origin" 70option of the static linker 71.Xr ld 1 . 72The following strings are recognized now: 73.Bl -tag -width ".Pa $PLATFORM" 74.It Pa $ORIGIN 75Translated to the full path of the loaded object. 76.It Pa $OSNAME 77Translated to the name of the operating system implementation. 78.It Pa $OSREL 79Translated to the release level of the operating system. 80.It Pa $PLATFORM 81Translated to the machine hardware platform. 82.El 83.Pp 84The 85.Nm 86utility itself is loaded by the kernel together with any dynamically-linked 87program that is to be executed. 88The kernel transfers control to the 89dynamic linker. 90After the dynamic linker has finished loading, 91relocating, and initializing the program and its required shared 92objects, it transfers control to the entry point of the program. 93The following search order is used to locate required shared objects: 94.Pp 95.Bl -enum -offset indent -compact 96.It 97.Dv DT_RPATH 98of the referencing object unless that object also contains a 99.Dv DT_RUNPATH 100tag 101.It 102.Dv DT_RPATH 103of the program unless the referencing object contains a 104.Dv DT_RUNPATH 105tag 106.It 107Path indicated by 108.Ev LD_LIBRARY_PATH 109environment variable 110.It 111.Dv DT_RUNPATH 112of the referencing object 113.It 114Hints file produced by the 115.Xr ldconfig 8 116utility 117.It 118The 119.Pa /lib 120and 121.Pa /usr/lib 122directories, unless the referencing object was linked using the 123.Dq Fl z Ar nodefaultlib 124option 125.El 126.Pp 127The 128.Nm 129utility 130recognizes a number of environment variables that can be used to modify 131its behaviour. 132for example: 133.Bl -tag -width ".Ev LD_LIBMAP_DISABLE" 134.It Ev LD_DUMP_REL_POST 135If set, 136.Nm 137will print a table containing all relocations after symbol 138binding and relocation. 139.It Ev LD_DUMP_REL_PRE 140If set, 141.Nm 142will print a table containing all relocations before symbol 143binding and relocation. 144.It Ev LD_LIBMAP 145A library replacement list in the same format as 146.Xr libmap.conf 5 . 147For convenience, the characters 148.Ql = 149and 150.Ql \&, 151can be used instead of a space and a newline. 152This variable is parsed after 153.Xr libmap.conf 5 , 154and will override its entries. 155This variable is unset for set-user-ID and set-group-ID programs. 156.It Ev LD_LIBMAP_DISABLE 157If set, disables the use of 158.Xr libmap.conf 5 159and 160.Ev LD_LIBMAP . 161This variable is unset for set-user-ID and set-group-ID programs. 162.It Ev LD_ELF_HINTS_PATH 163This variable will override the default location of 164.Dq hints 165file. 166This variable is unset for set-user-ID and set-group-ID programs. 167.It Ev LD_LIBRARY_PATH 168A colon separated list of directories, overriding the default search path 169for shared libraries. 170This variable is unset for set-user-ID and set-group-ID programs. 171.It Ev LD_PRELOAD 172A list of shared libraries, separated by colons and/or white space, 173to be linked in before any 174other shared libraries. 175If the directory is not specified then 176the directories specified by 177.Ev LD_LIBRARY_PATH 178will be searched first 179followed by the set of built-in standard directories. 180This variable is unset for set-user-ID and set-group-ID programs. 181.Ev LD_LIBRARY_PATH_FDS 182A colon separated list of file descriptor numbers for library directories. 183This is intended for future use within capsicum 184sandboxes, when global namespaces such as the filesystem are unavailable. 185It is consulted just after LD_LIBRARY_PATH. 186This variable is unset for set-user-ID and set-group-ID programs. 187.It Ev LD_BIND_NOW 188When set to a nonempty string, causes 189.Nm 190to relocate all external function calls before starting execution of the 191program. 192Normally, function calls are bound lazily, at the first call 193of each function. 194.Ev LD_BIND_NOW 195increases the start-up time of a program, but it avoids run-time 196surprises caused by unexpectedly undefined functions. 197.It Ev LD_TRACE_LOADED_OBJECTS 198When set to a nonempty string, causes 199.Nm 200to exit after loading the shared objects and printing a summary which includes 201the absolute pathnames of all objects, to standard output. 202.It Ev LD_TRACE_LOADED_OBJECTS_ALL 203When set to a nonempty string, causes 204.Nm 205to expand the summary to indicate which objects caused each object to 206be loaded. 207.It Ev LD_TRACE_LOADED_OBJECTS_FMT1 208.It Ev LD_TRACE_LOADED_OBJECTS_FMT2 209When set, these variables are interpreted as format strings a la 210.Xr printf 3 211to customize the trace output and are used by 212.Xr ldd 1 Ns 's 213.Fl f 214option and allows 215.Xr ldd 1 216to be operated as a filter more conveniently. 217If the dependency name starts with string 218.Pa lib , 219.Ev LD_TRACE_LOADED_OBJECTS_FMT1 220is used, otherwise 221.Ev LD_TRACE_LOADED_OBJECTS_FMT2 222is used. 223The following conversions can be used: 224.Bl -tag -width 4n 225.It Li %a 226The main program's name 227(also known as 228.Dq __progname ) . 229.It Li \&%A 230The value of the environment variable 231.Ev LD_TRACE_LOADED_OBJECTS_PROGNAME . 232Typically used to print both the names of programs and shared libraries 233being inspected using 234.Xr ldd 1 . 235.It Li %o 236The library name. 237.It Li %p 238The full pathname as determined by 239.Nm rtld Ns 's 240library search rules. 241.It Li %x 242The library's load address. 243.El 244.Pp 245Additionally, 246.Ql \en 247and 248.Ql \et 249are recognized and have their usual meaning. 250.It Ev LD_UTRACE 251If set, 252.Nm 253will log events such as the loading and unloading of shared objects via 254.Xr utrace 2 . 255.It Ev LD_LOADFLTR 256If set, 257.Nm 258will process the filtee dependencies of the loaded objects immediately, 259instead of postponing it until required. 260Normally, the filtees are opened at the time of the first symbol resolution 261from the filter object. 262.El 263.Pp 264If a shared object preloaded by the 265.Ev LD_PRELOAD 266mechanism contains a public symbol 267.Dq _rtld_functrace , 268.Nm 269will transfer control to this function each time 270it needs to resolve an unbound function symbol. 271By returning a non-zero value, 272.Fn _rtld_functrace 273can advise the linker to keep tracing the specified 274combination of caller shared object and called function; 275returning 0 will prevent 276.Fn _rtld_functrace 277to be called for this combination again. 278.Pp 279When implementing a custom 280.Fn _rtld_functrace 281function, be aware of the possibility that 282.Fn _rtld_functrace 283might be called for functions called on its behalf, 284or that multiple threads could enter 285.Fn _rtld_functrace 286at the same time. 287.Sh DIFFERENCES BETWEEN .1 and .2 288ABI changes have been made to support TLS allocation and initialization 289and to give threading libraries a chance to complete initialization of the 290TCB prior to the calling of the _init() functions for the dynamically loaded 291libraries. 292.Sh FILES 293.Bl -tag -width ".Pa /var/run/ld-elf.so.hints" -compact 294.It Pa /var/run/ld-elf.so.hints 295Hints file. 296.It Pa /etc/libmap.conf 297The libmap configuration file. 298.El 299.Sh EXAMPLES 300To set up an 301.Fn _rtld_functrace 302for printing out the functions as they are called, this code can be used: 303.Bd -literal -offset indent 304#include <string.h> 305 306static int nl = 10; 307 308int 309_rtld_functrace(const char *callerso, const char *calleeso, 310 const char *calleefun, void *stack) 311{ 312 write(2, "calling ", 8); 313 write(2, calleefun, strlen(calleefun)); 314 write(2, &nl, 1); 315 return 1; 316} 317.Ed 318.Pp 319If put in a file named 320.Pa ft.c 321and compiled with 322.Bd -literal -offset indent 323$ cc -shared -fPIC ft.c -o ft.so 324.Ed 325.Pp 326setting 327.Ev LD_PRELOAD 328to the path of 329.Pa ft.so 330will activate it. 331.Sh SEE ALSO 332.Xr ld 1 , 333.Xr ldd 1 , 334.Xr elf 5 , 335.Xr libmap.conf 5 , 336.Xr ldconfig 8 337