kernel - Correct null pointer panic in debug code
[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
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
dff6f2a0
SW
95.Bl -enum -offset indent -compact
96.It
97.Dv DT_RPATH
98of the referencing object unless that object also contains a
99.Dv DT_RUNPATH
100tag
101.It
102.Dv DT_RPATH
103of the program unless the referencing object contains a
104.Dv DT_RUNPATH
105tag
106.It
107Path indicated by
108.Ev LD_LIBRARY_PATH
109environment variable
110.It
111.Dv DT_RUNPATH
112of the referencing object
113.It
114Hints file produced by the
115.Xr ldconfig 8
116utility
117.It
118The
17f97226
FT
119.Pa /lib
120and
dff6f2a0 121.Pa /usr/lib
98e4cb42 122directories, unless the referencing object was linked using the
dff6f2a0
SW
123.Dq Fl z Ar nodefaultlib
124option
125.El
984263bc 126.Pp
fcf53d9b 127The
984263bc 128.Nm
fcf53d9b 129utility
984263bc 130recognizes a number of environment variables that can be used to modify
98e4cb42
JM
131its behaviour.
132for example:
fcf53d9b
JM
133.Bl -tag -width ".Ev LD_LIBMAP_DISABLE"
134.It Ev LD_DUMP_REL_POST
135If set,
136.Nm
137will print a table containing all relocations after symbol
138binding and relocation.
139.It Ev LD_DUMP_REL_PRE
140If set,
141.Nm
142will print a table containing all relocations before symbol
143binding and relocation.
144.It Ev LD_LIBMAP
145A library replacement list in the same format as
146.Xr libmap.conf 5 .
147For convenience, the characters
148.Ql =
149and
150.Ql \&,
151can be used instead of a space and a newline.
152This variable is parsed after
153.Xr libmap.conf 5 ,
154and will override its entries.
155This variable is unset for set-user-ID and set-group-ID programs.
156.It Ev LD_LIBMAP_DISABLE
157If set, disables the use of
158.Xr libmap.conf 5
159and
160.Ev LD_LIBMAP .
161This variable is unset for set-user-ID and set-group-ID programs.
162.It Ev LD_ELF_HINTS_PATH
163This variable will override the default location of
164.Dq hints
165file.
166This variable is unset for set-user-ID and set-group-ID programs.
984263bc
MD
167.It Ev LD_LIBRARY_PATH
168A colon separated list of directories, overriding the default search path
169for shared libraries.
fcf53d9b 170This variable is unset for set-user-ID and set-group-ID programs.
984263bc
MD
171.It Ev LD_PRELOAD
172A list of shared libraries, separated by colons and/or white space,
173to be linked in before any
174other shared libraries.
175If the directory is not specified then
176the directories specified by
177.Ev LD_LIBRARY_PATH
178will be searched first
179followed by the set of built-in standard directories.
fcf53d9b 180This variable is unset for set-user-ID and set-group-ID programs.
98e4cb42
JM
181.Ev LD_LIBRARY_PATH_FDS
182A colon separated list of file descriptor numbers for library directories.
183This is intended for future use within capsicum
184sandboxes, when global namespaces such as the filesystem are unavailable.
185It is consulted just after LD_LIBRARY_PATH.
186This variable is unset for set-user-ID and set-group-ID programs.
984263bc
MD
187.It Ev LD_BIND_NOW
188When set to a nonempty string, causes
189.Nm
190to relocate all external function calls before starting execution of the
191program.
192Normally, function calls are bound lazily, at the first call
193of each function.
194.Ev LD_BIND_NOW
195increases the start-up time of a program, but it avoids run-time
196surprises caused by unexpectedly undefined functions.
197.It Ev LD_TRACE_LOADED_OBJECTS
198When set to a nonempty string, causes
199.Nm
200to exit after loading the shared objects and printing a summary which includes
201the absolute pathnames of all objects, to standard output.
fcf53d9b
JM
202.It Ev LD_TRACE_LOADED_OBJECTS_ALL
203When set to a nonempty string, causes
204.Nm
205to expand the summary to indicate which objects caused each object to
206be loaded.
984263bc
MD
207.It Ev LD_TRACE_LOADED_OBJECTS_FMT1
208.It Ev LD_TRACE_LOADED_OBJECTS_FMT2
209When set, these variables are interpreted as format strings a la
210.Xr printf 3
211to customize the trace output and are used by
212.Xr ldd 1 Ns 's
213.Fl f
214option and allows
215.Xr ldd 1
216to be operated as a filter more conveniently.
fcf53d9b
JM
217If the dependency name starts with string
218.Pa lib ,
219.Ev LD_TRACE_LOADED_OBJECTS_FMT1
220is used, otherwise
221.Ev LD_TRACE_LOADED_OBJECTS_FMT2
222is used.
984263bc
MD
223The following conversions can be used:
224.Bl -tag -width 4n
225.It Li %a
226The main program's name
227(also known as
228.Dq __progname ) .
229.It Li \&%A
230The value of the environment variable
fcf53d9b
JM
231.Ev LD_TRACE_LOADED_OBJECTS_PROGNAME .
232Typically used to print both the names of programs and shared libraries
233being inspected using
234.Xr ldd 1 .
984263bc
MD
235.It Li %o
236The library name.
984263bc
MD
237.It Li %p
238The full pathname as determined by
239.Nm rtld Ns 's
240library search rules.
241.It Li %x
242The library's load address.
243.El
244.Pp
245Additionally,
246.Ql \en
247and
248.Ql \et
249are recognized and have their usual meaning.
fcf53d9b
JM
250.It Ev LD_UTRACE
251If set,
252.Nm
253will log events such as the loading and unloading of shared objects via
254.Xr utrace 2 .
35b2b265
JM
255.It Ev LD_LOADFLTR
256If set,
257.Nm
258will process the filtee dependencies of the loaded objects immediately,
259instead of postponing it until required.
260Normally, the filtees are opened at the time of the first symbol resolution
261from the filter object.
984263bc 262.El
38e4b3b6
SS
263.Pp
264If a shared object preloaded by the
265.Ev LD_PRELOAD
266mechanism contains a public symbol
267.Dq _rtld_functrace ,
268.Nm
269will transfer control to this function each time
270it needs to resolve an unbound function symbol.
271By returning a non-zero value,
272.Fn _rtld_functrace
273can advise the linker to keep tracing the specified
274combination of caller shared object and called function;
275returning 0 will prevent
276.Fn _rtld_functrace
277to be called for this combination again.
278.Pp
279When implementing a custom
280.Fn _rtld_functrace
281function, be aware of the possibility that
282.Fn _rtld_functrace
283might be called for functions called on its behalf,
284or that multiple threads could enter
285.Fn _rtld_functrace
286at the same time.
a1eee96a 287.Sh DIFFERENCES BETWEEN .1 and .2
a1eee96a
MD
288ABI changes have been made to support TLS allocation and initialization
289and to give threading libraries a chance to complete initialization of the
290TCB prior to the calling of the _init() functions for the dynamically loaded
291libraries.
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