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