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