libexec/rtld-elf/rtld.1

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