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