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