libexec/rtld-elf/rtld.1

   1 .\" $FreeBSD: src/libexec/rtld-elf/rtld.1,v 1.18.2.7 2002/01/10 17:51:28 ru Exp $
   2 .\"
   3 .\" Copyright (c) 1995 Paul Kranenburg
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgment:
  16 .\"      This product includes software developed by Paul Kranenburg.
  17 .\" 3. The name of the author may not be used to endorse or promote products
  18 .\"    derived from this software without specific prior written permission
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  21 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  22 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  23 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  24 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  25 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  29 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30 .\"
  31 .Dd February 21, 2011
  32 .Dt RTLD 1
  33 .Os
  34 .Sh NAME
  35 .Nm ld-elf.so.1 ,
  36 .Nm ld-elf.so.2 ,
  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 .Nm
  45 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 .Nm
  65 itself is loaded by the kernel together with any dynamically-linked
  66 program that is to be executed.
  67 The kernel transfers control to the
  68 dynamic linker.
  69 After the dynamic linker has finished loading,
  70 relocating, and initializing the program and its required shared
  71 objects, it transfers control to the entry point of the program.
  72 .Pp
  73 To locate the required shared objects in the filesystem,
  74 .Nm
  75 may use a
  76 .Dq hints
  77 file prepared by the
  78 .Xr ldconfig 8
  79 utility.
  80 .Pp
  81 .Nm
  82 recognizes a number of environment variables that can be used to modify
  83 its behaviour as follows:
  84 .Bl -tag -width ".Ev LD_LIBRARY_PATH"
  85 .It Ev LD_LIBRARY_PATH
  86 A colon separated list of directories, overriding the default search path
  87 for shared libraries.
  88 This is ignored for set-user-ID and set-group-ID programs.
  89 .It Ev LD_PRELOAD
  90 A list of shared libraries, separated by colons and/or white space,
  91 to be linked in before any
  92 other shared libraries.
  93 If the directory is not specified then
  94 the directories specified by
  95 .Ev LD_LIBRARY_PATH
  96 will be searched first
  97 followed by the set of built-in standard directories.
  98 This is ignored for set-user-ID and set-group-ID programs.
  99 .It Ev LD_BIND_NOW
 100 When set to a nonempty string, causes
 101 .Nm
 102 to relocate all external function calls before starting execution of the
 103 program.
 104 Normally, function calls are bound lazily, at the first call
 105 of each function.
 106 .Ev LD_BIND_NOW
 107 increases the start-up time of a program, but it avoids run-time
 108 surprises caused by unexpectedly undefined functions.
 109 .It Ev LD_TRACE_LOADED_OBJECTS
 110 When set to a nonempty string, causes
 111 .Nm
 112 to exit after loading the shared objects and printing a summary which includes
 113 the absolute pathnames of all objects, to standard output.
 114 .It Ev LD_TRACE_LOADED_OBJECTS_FMT1
 115 .It Ev LD_TRACE_LOADED_OBJECTS_FMT2
 116 When set, these variables are interpreted as format strings a la
 117 .Xr printf 3
 118 to customize the trace output and are used by
 119 .Xr ldd 1 Ns 's
 120 .Fl f
 121 option and allows
 122 .Xr ldd 1
 123 to be operated as a filter more conveniently.
 124 The following conversions can be used:
 125 .Bl -tag -width 4n
 126 .It Li %a
 127 The main program's name
 128 (also known as
 129 .Dq __progname ) .
 130 .It Li \&%A
 131 The value of the environment variable
 132 .Ev LD_TRACE_LOADED_OBJECTS_PROGNAME
 133 .It Li %o
 134 The library name.
 135 .It Li %m
 136 The library's major version number.
 137 .It Li %p
 138 The full pathname as determined by
 139 .Nm rtld Ns 's
 140 library search rules.
 141 .It Li %x
 142 The library's load address.
 143 .El
 144 .Pp
 145 Additionally,
 146 .Ql \en
 147 and
 148 .Ql \et
 149 are recognized and have their usual meaning.
 150 .El
 151 .Pp
 152 If a shared object preloaded by the
 153 .Ev LD_PRELOAD
 154 mechanism contains a public symbol
 155 .Dq _rtld_functrace ,
 156 .Nm
 157 will transfer control to this function each time
 158 it needs to resolve an unbound function symbol.
 159 By returning a non-zero value,
 160 .Fn _rtld_functrace
 161 can advise the linker to keep tracing the specified
 162 combination of caller shared object and called function;
 163 returning 0 will prevent
 164 .Fn _rtld_functrace
 165 to be called for this combination again.
 166 .Pp
 167 When implementing a custom
 168 .Fn _rtld_functrace
 169 function, be aware of the possibility that
 170 .Fn _rtld_functrace
 171 might be called for functions called on its behalf,
 172 or that multiple threads could enter
 173 .Fn _rtld_functrace
 174 at the same time.
 175 .Sh DIFFERENCES BETWEEN .1 and .2
 176 ABI changes have been made to support TLS allocation and initialization
 177 and to give threading libraries a chance to complete initialization of the
 178 TCB prior to the calling of the _init() functions for the dynamically loaded
 179 libraries.
 180 .Sh FILES
 181 .Bl -tag -width indent
 182 .It Pa /var/run/ld-elf.so.hints
 183 .El
 184 .Sh EXAMPLES
 185 To set up an
 186 .Fn _rtld_functrace
 187 for printing out the functions as they are called, this code can be used:
 188 .Bd -literal -offset indent
 189 #include <string.h>
 190
 191 static int nl = 10;
 192
 193 int
 194 _rtld_functrace(const char *callerso, const char *calleeso,
 195     const char *calleefun, void *stack)
 196 {
 197         write(2, "calling ", 8);
 198         write(2, calleefun, strlen(calleefun));
 199         write(2, &nl, 1);
 200         return 1;
 201 }
 202 .Ed
 203 .Pp
 204 If put in a file named
 205 .Pa ft.c
 206 and compiled with
 207 .Bd -literal -offset indent
 208 $ cc -shared ft.c -o ft.so
 209 .Ed
 210 .Pp
 211 setting
 212 .Ev LD_PRELOAD
 213 to the path of
 214 .Pa ft.so
 215 will activate it.
 216 .Sh SEE ALSO
 217 .Xr ld 1 ,
 218 .Xr ldd 1 ,
 219 .Xr elf 5 ,
 220 .Xr ldconfig 8