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 May 6, 2012 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 122directory 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 as follows: 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.It Ev LD_BIND_NOW 181When set to a nonempty string, causes 182.Nm 183to relocate all external function calls before starting execution of the 184program. 185Normally, function calls are bound lazily, at the first call 186of each function. 187.Ev LD_BIND_NOW 188increases the start-up time of a program, but it avoids run-time 189surprises caused by unexpectedly undefined functions. 190.It Ev LD_TRACE_LOADED_OBJECTS 191When set to a nonempty string, causes 192.Nm 193to exit after loading the shared objects and printing a summary which includes 194the absolute pathnames of all objects, to standard output. 195.It Ev LD_TRACE_LOADED_OBJECTS_ALL 196When set to a nonempty string, causes 197.Nm 198to expand the summary to indicate which objects caused each object to 199be loaded. 200.It Ev LD_TRACE_LOADED_OBJECTS_FMT1 201.It Ev LD_TRACE_LOADED_OBJECTS_FMT2 202When set, these variables are interpreted as format strings a la 203.Xr printf 3 204to customize the trace output and are used by 205.Xr ldd 1 Ns 's 206.Fl f 207option and allows 208.Xr ldd 1 209to be operated as a filter more conveniently. 210If the dependency name starts with string 211.Pa lib , 212.Ev LD_TRACE_LOADED_OBJECTS_FMT1 213is used, otherwise 214.Ev LD_TRACE_LOADED_OBJECTS_FMT2 215is used. 216The following conversions can be used: 217.Bl -tag -width 4n 218.It Li %a 219The main program's name 220(also known as 221.Dq __progname ) . 222.It Li \&%A 223The value of the environment variable 224.Ev LD_TRACE_LOADED_OBJECTS_PROGNAME . 225Typically used to print both the names of programs and shared libraries 226being inspected using 227.Xr ldd 1 . 228.It Li %o 229The library name. 230.It Li %p 231The full pathname as determined by 232.Nm rtld Ns 's 233library search rules. 234.It Li %x 235The library's load address. 236.El 237.Pp 238Additionally, 239.Ql \en 240and 241.Ql \et 242are recognized and have their usual meaning. 243.It Ev LD_UTRACE 244If set, 245.Nm 246will log events such as the loading and unloading of shared objects via 247.Xr utrace 2 . 248.It Ev LD_LOADFLTR 249If set, 250.Nm 251will process the filtee dependencies of the loaded objects immediately, 252instead of postponing it until required. 253Normally, the filtees are opened at the time of the first symbol resolution 254from the filter object. 255.El 256.Pp 257If a shared object preloaded by the 258.Ev LD_PRELOAD 259mechanism contains a public symbol 260.Dq _rtld_functrace , 261.Nm 262will transfer control to this function each time 263it needs to resolve an unbound function symbol. 264By returning a non-zero value, 265.Fn _rtld_functrace 266can advise the linker to keep tracing the specified 267combination of caller shared object and called function; 268returning 0 will prevent 269.Fn _rtld_functrace 270to be called for this combination again. 271.Pp 272When implementing a custom 273.Fn _rtld_functrace 274function, be aware of the possibility that 275.Fn _rtld_functrace 276might be called for functions called on its behalf, 277or that multiple threads could enter 278.Fn _rtld_functrace 279at the same time. 280.Sh DIFFERENCES BETWEEN .1 and .2 281ABI changes have been made to support TLS allocation and initialization 282and to give threading libraries a chance to complete initialization of the 283TCB prior to the calling of the _init() functions for the dynamically loaded 284libraries. 285.Sh FILES 286.Bl -tag -width ".Pa /var/run/ld-elf.so.hints" -compact 287.It Pa /var/run/ld-elf.so.hints 288Hints file. 289.It Pa /etc/libmap.conf 290The libmap configuration file. 291.El 292.Sh EXAMPLES 293To set up an 294.Fn _rtld_functrace 295for printing out the functions as they are called, this code can be used: 296.Bd -literal -offset indent 297#include <string.h> 298 299static int nl = 10; 300 301int 302_rtld_functrace(const char *callerso, const char *calleeso, 303 const char *calleefun, void *stack) 304{ 305 write(2, "calling ", 8); 306 write(2, calleefun, strlen(calleefun)); 307 write(2, &nl, 1); 308 return 1; 309} 310.Ed 311.Pp 312If put in a file named 313.Pa ft.c 314and compiled with 315.Bd -literal -offset indent 316$ cc -shared -fPIC ft.c -o ft.so 317.Ed 318.Pp 319setting 320.Ev LD_PRELOAD 321to the path of 322.Pa ft.so 323will activate it. 324.Sh SEE ALSO 325.Xr ld 1 , 326.Xr ldd 1 , 327.Xr elf 5 , 328.Xr libmap.conf 5 , 329.Xr ldconfig 8 330