i386 removal, part 71/x: Remove legacy FreeBSD brand.
[dragonfly.git] / 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