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 | .\" |
35b2b265 | 31 | .Dd January 20, 2012 |
984263bc MD |
32 | .Dt RTLD 1 |
33 | .Os | |
34 | .Sh NAME | |
a1eee96a | 35 | .Nm ld-elf.so.2 , |
fcf53d9b | 36 | .Nm ld-elf.so.1 , |
40146e6a SW |
37 | .Nm rtld , |
38 | .Nm _rtld_functrace | |
984263bc | 39 | .Nd run-time link-editor |
40146e6a SW |
40 | .Sh SYNOPSIS |
41 | .Ft int | |
42 | .Fn _rtld_functrace "const char *callerso" "const char *calleeso" "const char *calleefun" "void *stack" | |
984263bc | 43 | .Sh DESCRIPTION |
fcf53d9b | 44 | The |
984263bc | 45 | .Nm |
fcf53d9b | 46 | utility is a self-contained shared object providing run-time |
984263bc MD |
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 | |
fcf53d9b | 65 | When resolving dependencies for the loaded objects, |
984263bc | 66 | .Nm |
fcf53d9b JM |
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 | |
984263bc MD |
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 | .Pp | |
fcf53d9b | 94 | To locate the required shared objects in the file system, |
984263bc MD |
95 | .Nm |
96 | may use a | |
97 | .Dq hints | |
98 | file prepared by the | |
99 | .Xr ldconfig 8 | |
100 | utility. | |
101 | .Pp | |
fcf53d9b | 102 | The |
984263bc | 103 | .Nm |
fcf53d9b | 104 | utility |
984263bc MD |
105 | recognizes a number of environment variables that can be used to modify |
106 | its behaviour as follows: | |
fcf53d9b JM |
107 | .Bl -tag -width ".Ev LD_LIBMAP_DISABLE" |
108 | .It Ev LD_DUMP_REL_POST | |
109 | If set, | |
110 | .Nm | |
111 | will print a table containing all relocations after symbol | |
112 | binding and relocation. | |
113 | .It Ev LD_DUMP_REL_PRE | |
114 | If set, | |
115 | .Nm | |
116 | will print a table containing all relocations before symbol | |
117 | binding and relocation. | |
118 | .It Ev LD_LIBMAP | |
119 | A library replacement list in the same format as | |
120 | .Xr libmap.conf 5 . | |
121 | For convenience, the characters | |
122 | .Ql = | |
123 | and | |
124 | .Ql \&, | |
125 | can be used instead of a space and a newline. | |
126 | This variable is parsed after | |
127 | .Xr libmap.conf 5 , | |
128 | and will override its entries. | |
129 | This variable is unset for set-user-ID and set-group-ID programs. | |
130 | .It Ev LD_LIBMAP_DISABLE | |
131 | If set, disables the use of | |
132 | .Xr libmap.conf 5 | |
133 | and | |
134 | .Ev LD_LIBMAP . | |
135 | This variable is unset for set-user-ID and set-group-ID programs. | |
136 | .It Ev LD_ELF_HINTS_PATH | |
137 | This variable will override the default location of | |
138 | .Dq hints | |
139 | file. | |
140 | This variable is unset for set-user-ID and set-group-ID programs. | |
984263bc MD |
141 | .It Ev LD_LIBRARY_PATH |
142 | A colon separated list of directories, overriding the default search path | |
143 | for shared libraries. | |
fcf53d9b | 144 | This variable is unset for set-user-ID and set-group-ID programs. |
984263bc MD |
145 | .It Ev LD_PRELOAD |
146 | A list of shared libraries, separated by colons and/or white space, | |
147 | to be linked in before any | |
148 | other shared libraries. | |
149 | If the directory is not specified then | |
150 | the directories specified by | |
151 | .Ev LD_LIBRARY_PATH | |
152 | will be searched first | |
153 | followed by the set of built-in standard directories. | |
fcf53d9b | 154 | This variable is unset for set-user-ID and set-group-ID programs. |
984263bc MD |
155 | .It Ev LD_BIND_NOW |
156 | When set to a nonempty string, causes | |
157 | .Nm | |
158 | to relocate all external function calls before starting execution of the | |
159 | program. | |
160 | Normally, function calls are bound lazily, at the first call | |
161 | of each function. | |
162 | .Ev LD_BIND_NOW | |
163 | increases the start-up time of a program, but it avoids run-time | |
164 | surprises caused by unexpectedly undefined functions. | |
165 | .It Ev LD_TRACE_LOADED_OBJECTS | |
166 | When set to a nonempty string, causes | |
167 | .Nm | |
168 | to exit after loading the shared objects and printing a summary which includes | |
169 | the absolute pathnames of all objects, to standard output. | |
fcf53d9b JM |
170 | .It Ev LD_TRACE_LOADED_OBJECTS_ALL |
171 | When set to a nonempty string, causes | |
172 | .Nm | |
173 | to expand the summary to indicate which objects caused each object to | |
174 | be loaded. | |
984263bc MD |
175 | .It Ev LD_TRACE_LOADED_OBJECTS_FMT1 |
176 | .It Ev LD_TRACE_LOADED_OBJECTS_FMT2 | |
177 | When set, these variables are interpreted as format strings a la | |
178 | .Xr printf 3 | |
179 | to customize the trace output and are used by | |
180 | .Xr ldd 1 Ns 's | |
181 | .Fl f | |
182 | option and allows | |
183 | .Xr ldd 1 | |
184 | to be operated as a filter more conveniently. | |
fcf53d9b JM |
185 | If the dependency name starts with string |
186 | .Pa lib , | |
187 | .Ev LD_TRACE_LOADED_OBJECTS_FMT1 | |
188 | is used, otherwise | |
189 | .Ev LD_TRACE_LOADED_OBJECTS_FMT2 | |
190 | is used. | |
984263bc MD |
191 | The following conversions can be used: |
192 | .Bl -tag -width 4n | |
193 | .It Li %a | |
194 | The main program's name | |
195 | (also known as | |
196 | .Dq __progname ) . | |
197 | .It Li \&%A | |
198 | The value of the environment variable | |
fcf53d9b JM |
199 | .Ev LD_TRACE_LOADED_OBJECTS_PROGNAME . |
200 | Typically used to print both the names of programs and shared libraries | |
201 | being inspected using | |
202 | .Xr ldd 1 . | |
984263bc MD |
203 | .It Li %o |
204 | The library name. | |
984263bc MD |
205 | .It Li %p |
206 | The full pathname as determined by | |
207 | .Nm rtld Ns 's | |
208 | library search rules. | |
209 | .It Li %x | |
210 | The library's load address. | |
211 | .El | |
212 | .Pp | |
213 | Additionally, | |
214 | .Ql \en | |
215 | and | |
216 | .Ql \et | |
217 | are recognized and have their usual meaning. | |
fcf53d9b JM |
218 | .It Ev LD_UTRACE |
219 | If set, | |
220 | .Nm | |
221 | will log events such as the loading and unloading of shared objects via | |
222 | .Xr utrace 2 . | |
35b2b265 JM |
223 | .Pp |
224 | .It Ev LD_LOADFLTR | |
225 | If set, | |
226 | .Nm | |
227 | will process the filtee dependencies of the loaded objects immediately, | |
228 | instead of postponing it until required. | |
229 | Normally, the filtees are opened at the time of the first symbol resolution | |
230 | from the filter object. | |
984263bc | 231 | .El |
38e4b3b6 SS |
232 | .Pp |
233 | If a shared object preloaded by the | |
234 | .Ev LD_PRELOAD | |
235 | mechanism contains a public symbol | |
236 | .Dq _rtld_functrace , | |
237 | .Nm | |
238 | will transfer control to this function each time | |
239 | it needs to resolve an unbound function symbol. | |
240 | By returning a non-zero value, | |
241 | .Fn _rtld_functrace | |
242 | can advise the linker to keep tracing the specified | |
243 | combination of caller shared object and called function; | |
244 | returning 0 will prevent | |
245 | .Fn _rtld_functrace | |
246 | to be called for this combination again. | |
247 | .Pp | |
248 | When implementing a custom | |
249 | .Fn _rtld_functrace | |
250 | function, be aware of the possibility that | |
251 | .Fn _rtld_functrace | |
252 | might be called for functions called on its behalf, | |
253 | or that multiple threads could enter | |
254 | .Fn _rtld_functrace | |
255 | at the same time. | |
a1eee96a | 256 | .Sh DIFFERENCES BETWEEN .1 and .2 |
a1eee96a MD |
257 | ABI changes have been made to support TLS allocation and initialization |
258 | and to give threading libraries a chance to complete initialization of the | |
259 | TCB prior to the calling of the _init() functions for the dynamically loaded | |
260 | libraries. | |
984263bc | 261 | .Sh FILES |
fcf53d9b | 262 | .Bl -tag -width ".Pa /var/run/ld-elf.so.hints" -compact |
984263bc | 263 | .It Pa /var/run/ld-elf.so.hints |
fcf53d9b JM |
264 | Hints file. |
265 | .It Pa /etc/libmap.conf | |
266 | The libmap configuration file. | |
984263bc | 267 | .El |
40146e6a SW |
268 | .Sh EXAMPLES |
269 | To set up an | |
270 | .Fn _rtld_functrace | |
271 | for printing out the functions as they are called, this code can be used: | |
272 | .Bd -literal -offset indent | |
273 | #include <string.h> | |
274 | ||
4ee0d876 | 275 | static int nl = 10; |
40146e6a SW |
276 | |
277 | int | |
278 | _rtld_functrace(const char *callerso, const char *calleeso, | |
279 | const char *calleefun, void *stack) | |
280 | { | |
281 | write(2, "calling ", 8); | |
282 | write(2, calleefun, strlen(calleefun)); | |
283 | write(2, &nl, 1); | |
284 | return 1; | |
285 | } | |
286 | .Ed | |
287 | .Pp | |
288 | If put in a file named | |
289 | .Pa ft.c | |
290 | and compiled with | |
291 | .Bd -literal -offset indent | |
292 | $ cc -shared ft.c -o ft.so | |
293 | .Ed | |
294 | .Pp | |
295 | setting | |
296 | .Ev LD_PRELOAD | |
297 | to the path of | |
298 | .Pa ft.so | |
299 | will activate it. | |
984263bc MD |
300 | .Sh SEE ALSO |
301 | .Xr ld 1 , | |
302 | .Xr ldd 1 , | |
303 | .Xr elf 5 , | |
fcf53d9b | 304 | .Xr libmap.conf 5 , |
984263bc | 305 | .Xr ldconfig 8 |