Commit | Line | Data |
---|---|---|
984263bc MD |
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 | .\" | |
f4f4bfd5 | 29 | .\" $FreeBSD$ |
fcf53d9b | 30 | .\" |
98e4cb42 | 31 | .Dd June 20, 2014 |
984263bc MD |
32 | .Dt RTLD 1 |
33 | .Os | |
34 | .Sh NAME | |
40146e6a | 35 | .Nm rtld , |
70839a95 | 36 | .Nm ld-elf.so.2 , |
40146e6a | 37 | .Nm _rtld_functrace |
984263bc | 38 | .Nd run-time link-editor |
40146e6a SW |
39 | .Sh SYNOPSIS |
40 | .Ft int | |
41 | .Fn _rtld_functrace "const char *callerso" "const char *calleeso" "const char *calleefun" "void *stack" | |
984263bc | 42 | .Sh DESCRIPTION |
fcf53d9b | 43 | The |
984263bc | 44 | .Nm |
fcf53d9b | 45 | utility is a self-contained shared object providing run-time |
984263bc MD |
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 | |
fcf53d9b | 64 | When resolving dependencies for the loaded objects, |
984263bc | 65 | .Nm |
fcf53d9b JM |
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 | |
984263bc MD |
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. | |
f560f0d6 | 92 | The following search order is used to locate required shared objects: |
984263bc | 93 | .Pp |
dff6f2a0 SW |
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 | |
17f97226 FT |
118 | .Pa /lib |
119 | and | |
dff6f2a0 | 120 | .Pa /usr/lib |
98e4cb42 | 121 | directories, unless the referencing object was linked using the |
dff6f2a0 SW |
122 | .Dq Fl z Ar nodefaultlib |
123 | option | |
124 | .El | |
984263bc | 125 | .Pp |
fcf53d9b | 126 | The |
984263bc | 127 | .Nm |
fcf53d9b | 128 | utility |
984263bc | 129 | recognizes a number of environment variables that can be used to modify |
98e4cb42 JM |
130 | its behaviour. |
131 | for example: | |
fcf53d9b JM |
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. | |
984263bc MD |
166 | .It Ev LD_LIBRARY_PATH |
167 | A colon separated list of directories, overriding the default search path | |
168 | for shared libraries. | |
fcf53d9b | 169 | This variable is unset for set-user-ID and set-group-ID programs. |
984263bc MD |
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. | |
fcf53d9b | 179 | This variable is unset for set-user-ID and set-group-ID programs. |
98e4cb42 JM |
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. | |
984263bc MD |
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. | |
fcf53d9b JM |
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. | |
984263bc MD |
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. | |
fcf53d9b JM |
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. | |
984263bc MD |
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 | |
fcf53d9b JM |
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 . | |
984263bc MD |
234 | .It Li %o |
235 | The library name. | |
984263bc MD |
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. | |
fcf53d9b JM |
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 . | |
35b2b265 JM |
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. | |
984263bc | 261 | .El |
38e4b3b6 SS |
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. | |
a1eee96a | 286 | .Sh DIFFERENCES BETWEEN .1 and .2 |
a1eee96a MD |
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 | |
d4155bf4 SW |
289 | TCB prior to the calling of the |
290 | .Fn _init | |
291 | functions for the dynamically loaded libraries. | |
984263bc | 292 | .Sh FILES |
fcf53d9b | 293 | .Bl -tag -width ".Pa /var/run/ld-elf.so.hints" -compact |
984263bc | 294 | .It Pa /var/run/ld-elf.so.hints |
fcf53d9b JM |
295 | Hints file. |
296 | .It Pa /etc/libmap.conf | |
297 | The libmap configuration file. | |
984263bc | 298 | .El |
40146e6a SW |
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> | |
6e86fc6e | 305 | #include <unistd.h> |
40146e6a | 306 | |
4ee0d876 | 307 | static int nl = 10; |
40146e6a SW |
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 | |
0e759e7d | 324 | $ cc -shared -fPIC ft.c -o ft.so |
40146e6a SW |
325 | .Ed |
326 | .Pp | |
327 | setting | |
328 | .Ev LD_PRELOAD | |
329 | to the path of | |
330 | .Pa ft.so | |
331 | will activate it. | |
984263bc MD |
332 | .Sh SEE ALSO |
333 | .Xr ld 1 , | |
334 | .Xr ldd 1 , | |
335 | .Xr elf 5 , | |
fcf53d9b | 336 | .Xr libmap.conf 5 , |
984263bc | 337 | .Xr ldconfig 8 |