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 January 20, 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. 93.Pp 94To locate the required shared objects in the file system, 95.Nm 96may use a 97.Dq hints 98file prepared by the 99.Xr ldconfig 8 100utility. 101.Pp 102The 103.Nm 104utility 105recognizes a number of environment variables that can be used to modify 106its behaviour as follows: 107.Bl -tag -width ".Ev LD_LIBMAP_DISABLE" 108.It Ev LD_DUMP_REL_POST 109If set, 110.Nm 111will print a table containing all relocations after symbol 112binding and relocation. 113.It Ev LD_DUMP_REL_PRE 114If set, 115.Nm 116will print a table containing all relocations before symbol 117binding and relocation. 118.It Ev LD_LIBMAP 119A library replacement list in the same format as 120.Xr libmap.conf 5 . 121For convenience, the characters 122.Ql = 123and 124.Ql \&, 125can be used instead of a space and a newline. 126This variable is parsed after 127.Xr libmap.conf 5 , 128and will override its entries. 129This variable is unset for set-user-ID and set-group-ID programs. 130.It Ev LD_LIBMAP_DISABLE 131If set, disables the use of 132.Xr libmap.conf 5 133and 134.Ev LD_LIBMAP . 135This variable is unset for set-user-ID and set-group-ID programs. 136.It Ev LD_ELF_HINTS_PATH 137This variable will override the default location of 138.Dq hints 139file. 140This variable is unset for set-user-ID and set-group-ID programs. 141.It Ev LD_LIBRARY_PATH 142A colon separated list of directories, overriding the default search path 143for shared libraries. 144This variable is unset for set-user-ID and set-group-ID programs. 145.It Ev LD_PRELOAD 146A list of shared libraries, separated by colons and/or white space, 147to be linked in before any 148other shared libraries. 149If the directory is not specified then 150the directories specified by 151.Ev LD_LIBRARY_PATH 152will be searched first 153followed by the set of built-in standard directories. 154This variable is unset for set-user-ID and set-group-ID programs. 155.It Ev LD_BIND_NOW 156When set to a nonempty string, causes 157.Nm 158to relocate all external function calls before starting execution of the 159program. 160Normally, function calls are bound lazily, at the first call 161of each function. 162.Ev LD_BIND_NOW 163increases the start-up time of a program, but it avoids run-time 164surprises caused by unexpectedly undefined functions. 165.It Ev LD_TRACE_LOADED_OBJECTS 166When set to a nonempty string, causes 167.Nm 168to exit after loading the shared objects and printing a summary which includes 169the absolute pathnames of all objects, to standard output. 170.It Ev LD_TRACE_LOADED_OBJECTS_ALL 171When set to a nonempty string, causes 172.Nm 173to expand the summary to indicate which objects caused each object to 174be loaded. 175.It Ev LD_TRACE_LOADED_OBJECTS_FMT1 176.It Ev LD_TRACE_LOADED_OBJECTS_FMT2 177When set, these variables are interpreted as format strings a la 178.Xr printf 3 179to customize the trace output and are used by 180.Xr ldd 1 Ns 's 181.Fl f 182option and allows 183.Xr ldd 1 184to be operated as a filter more conveniently. 185If the dependency name starts with string 186.Pa lib , 187.Ev LD_TRACE_LOADED_OBJECTS_FMT1 188is used, otherwise 189.Ev LD_TRACE_LOADED_OBJECTS_FMT2 190is used. 191The following conversions can be used: 192.Bl -tag -width 4n 193.It Li %a 194The main program's name 195(also known as 196.Dq __progname ) . 197.It Li \&%A 198The value of the environment variable 199.Ev LD_TRACE_LOADED_OBJECTS_PROGNAME . 200Typically used to print both the names of programs and shared libraries 201being inspected using 202.Xr ldd 1 . 203.It Li %o 204The library name. 205.It Li %p 206The full pathname as determined by 207.Nm rtld Ns 's 208library search rules. 209.It Li %x 210The library's load address. 211.El 212.Pp 213Additionally, 214.Ql \en 215and 216.Ql \et 217are recognized and have their usual meaning. 218.It Ev LD_UTRACE 219If set, 220.Nm 221will log events such as the loading and unloading of shared objects via 222.Xr utrace 2 . 223.Pp 224.It Ev LD_LOADFLTR 225If set, 226.Nm 227will process the filtee dependencies of the loaded objects immediately, 228instead of postponing it until required. 229Normally, the filtees are opened at the time of the first symbol resolution 230from the filter object. 231.El 232.Pp 233If a shared object preloaded by the 234.Ev LD_PRELOAD 235mechanism contains a public symbol 236.Dq _rtld_functrace , 237.Nm 238will transfer control to this function each time 239it needs to resolve an unbound function symbol. 240By returning a non-zero value, 241.Fn _rtld_functrace 242can advise the linker to keep tracing the specified 243combination of caller shared object and called function; 244returning 0 will prevent 245.Fn _rtld_functrace 246to be called for this combination again. 247.Pp 248When implementing a custom 249.Fn _rtld_functrace 250function, be aware of the possibility that 251.Fn _rtld_functrace 252might be called for functions called on its behalf, 253or that multiple threads could enter 254.Fn _rtld_functrace 255at the same time. 256.Sh DIFFERENCES BETWEEN .1 and .2 257ABI changes have been made to support TLS allocation and initialization 258and to give threading libraries a chance to complete initialization of the 259TCB prior to the calling of the _init() functions for the dynamically loaded 260libraries. 261.Sh FILES 262.Bl -tag -width ".Pa /var/run/ld-elf.so.hints" -compact 263.It Pa /var/run/ld-elf.so.hints 264Hints file. 265.It Pa /etc/libmap.conf 266The libmap configuration file. 267.El 268.Sh EXAMPLES 269To set up an 270.Fn _rtld_functrace 271for printing out the functions as they are called, this code can be used: 272.Bd -literal -offset indent 273#include <string.h> 274 275static int nl = 10; 276 277int 278_rtld_functrace(const char *callerso, const char *calleeso, 279 const char *calleefun, void *stack) 280{ 281 write(2, "calling ", 8); 282 write(2, calleefun, strlen(calleefun)); 283 write(2, &nl, 1); 284 return 1; 285} 286.Ed 287.Pp 288If put in a file named 289.Pa ft.c 290and compiled with 291.Bd -literal -offset indent 292$ cc -shared -fPIC ft.c -o ft.so 293.Ed 294.Pp 295setting 296.Ev LD_PRELOAD 297to the path of 298.Pa ft.so 299will activate it. 300.Sh SEE ALSO 301.Xr ld 1 , 302.Xr ldd 1 , 303.Xr elf 5 , 304.Xr libmap.conf 5 , 305.Xr ldconfig 8 306