xref: /freebsd/libexec/rtld-elf/rtld.1 (revision d36d6816151705907393889d661cbfd25c630ca8)
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.\"
29.\" $FreeBSD$
30.\"
31.Dd March 24, 2021
32.Dt RTLD 1
33.Os
34.Sh NAME
35.Nm ld-elf.so.1 ,
36.Nm ld.so ,
37.Nm rtld
38.Nd run-time link-editor
39.Sh DESCRIPTION
40The
41.Nm
42utility is a self-contained shared object providing run-time
43support for loading and link-editing shared objects into a process'
44address space.
45It is also commonly known as the dynamic linker.
46It uses the data structures
47contained within dynamically linked programs to determine which shared
48libraries are needed and loads them using the
49.Xr mmap 2
50system call.
51.Pp
52After all shared libraries have been successfully loaded,
53.Nm
54proceeds to resolve external references from both the main program and
55all objects loaded.
56A mechanism is provided for initialization routines
57to be called on a per-object basis, giving a shared object an opportunity
58to perform any extra set-up before execution of the program proper begins.
59This is useful for C++ libraries that contain static constructors.
60.Pp
61When resolving dependencies for the loaded objects,
62.Nm
63translates dynamic token strings in rpath and soname.
64If the
65.Fl "z origin"
66option of the static linker was set when linking the binary,
67the token expansion is performed at the object load time, see
68.Xr ld 1 .
69The following strings are recognized now:
70.Bl -tag -width ".Pa $PLATFORM"
71.It Pa $ORIGIN
72Translated to the full path of the loaded object.
73.It Pa $OSNAME
74Translated to the name of the operating system implementation.
75.It Pa $OSREL
76Translated to the release level of the operating system.
77.It Pa $PLATFORM
78Translated to the machine hardware platform.
79.El
80.Pp
81The
82.Nm
83utility itself is loaded by the kernel together with any dynamically-linked
84program that is to be executed.
85The kernel transfers control to the
86dynamic linker.
87After the dynamic linker has finished loading,
88relocating, and initializing the program and its required shared
89objects, it transfers control to the entry point of the program.
90The following search order is used to locate required shared objects:
91.Pp
92.Bl -enum -offset indent -compact
93.It
94.Dv DT_RPATH
95of the referencing object unless that object also contains a
96.Dv DT_RUNPATH
97tag
98.It
99.Dv DT_RPATH
100of the program unless the referencing object contains a
101.Dv DT_RUNPATH
102tag
103.It
104Path indicated by
105.Ev LD_LIBRARY_PATH
106environment variable
107.It
108.Dv DT_RUNPATH
109of the referencing object
110.It
111Hints file produced by the
112.Xr ldconfig 8
113utility
114.It
115The
116.Pa /lib
117and
118.Pa /usr/lib
119directories, unless the referencing object was linked using the
120.Dq Fl z Ar nodefaultlib
121option
122.El
123.Pp
124The
125.Nm
126utility
127recognizes a number of environment variables that can be used to modify
128its behaviour.
129On 64-bit architectures, the linker for 32-bit objects recognizes
130all the environment variables listed below, but is being prefixed with
131.Ev LD_32_ ,
132for example:
133.Ev LD_32_TRACE_LOADED_OBJECTS .
134.Bl -tag -width ".Ev LD_LIBMAP_DISABLE"
135.It Ev LD_DUMP_REL_POST
136If set,
137.Nm
138will print a table containing all relocations after symbol
139binding and relocation.
140.It Ev LD_DUMP_REL_PRE
141If set,
142.Nm
143will print a table containing all relocations before symbol
144binding and relocation.
145.It Ev LD_LIBMAP
146A library replacement list in the same format as
147.Xr libmap.conf 5 .
148For convenience, the characters
149.Ql =
150and
151.Ql \&,
152can be used instead of a space and a newline.
153This variable is parsed after
154.Xr libmap.conf 5 ,
155and will override its entries.
156This variable is unset for set-user-ID and set-group-ID programs.
157.It Ev LD_LIBMAP_DISABLE
158If set, disables the use of
159.Xr libmap.conf 5
160and
161.Ev LD_LIBMAP .
162This variable is unset for set-user-ID and set-group-ID programs.
163.It Ev LD_ELF_HINTS_PATH
164This variable will override the default location of
165.Dq hints
166file.
167This variable is unset for set-user-ID and set-group-ID programs.
168.It Ev LD_LIBRARY_PATH
169A colon separated list of directories, overriding the default search path
170for shared libraries.
171This variable is unset for set-user-ID and set-group-ID programs.
172.It Ev LD_LIBRARY_PATH_RPATH
173If the variable is specified and has a value starting with
174any of \'y\', \'Y\' or \'1\' symbols, the path specified by
175.Ev LD_LIBRARY_PATH
176variable is allowed to override the path from
177.Dv DT_RPATH
178for binaries which does not contain
179.Dv DT_RUNPATH
180tag.
181For such binaries, when the variable
182.Ev LD_LIBRARY_PATH_RPATH
183is set,
184.Dq Fl z Ar nodefaultlib
185link-time option is ignored as well.
186.It Ev LD_PRELOAD
187A list of shared libraries, separated by colons and/or white space,
188to be linked in before any
189other shared libraries.
190If the directory is not specified then
191the directories specified by
192.It Ev LD_PRELOAD_FDS
193A colon separated list of file descriptor numbers for libraries.
194This is intended for preloading libraries in which we already have a file
195descriptor.
196This may optimize the process of loading libraries because we do not have to
197look for them in directories.
198It may also be useful in a capability base system where we do not have access to
199global namespaces such as the filesystem.
200.Ev LD_LIBRARY_PATH
201will be searched first
202followed by the set of built-in standard directories.
203This variable is unset for set-user-ID and set-group-ID programs.
204.It Ev LD_LIBRARY_PATH_FDS
205A colon separated list of file descriptor numbers for library directories.
206This is intended for use within
207.Xr capsicum 4
208sandboxes, when global namespaces such as the filesystem are unavailable.
209It is consulted just after LD_LIBRARY_PATH.
210This variable is unset for set-user-ID and set-group-ID programs.
211.It Ev LD_BIND_NOT
212When set to a nonempty string, prevents modifications of the PLT slots when
213doing bindings.
214As result, each call of the PLT-resolved function is resolved.
215In combination with debug output, this provides complete account of
216all bind actions at runtime.
217This variable is unset for set-user-ID and set-group-ID programs.
218.It Ev LD_BIND_NOW
219When set to a nonempty string, causes
220.Nm
221to relocate all external function calls before starting execution of the
222program.
223Normally, function calls are bound lazily, at the first call
224of each function.
225.Ev LD_BIND_NOW
226increases the start-up time of a program, but it avoids run-time
227surprises caused by unexpectedly undefined functions.
228.It Ev LD_TRACE_LOADED_OBJECTS
229When set to a nonempty string, causes
230.Nm
231to exit after loading the shared objects and printing a summary which includes
232the absolute pathnames of all objects, to standard output.
233.It Ev LD_TRACE_LOADED_OBJECTS_ALL
234When set to a nonempty string, causes
235.Nm
236to expand the summary to indicate which objects caused each object to
237be loaded.
238.It Ev LD_TRACE_LOADED_OBJECTS_FMT1
239.It Ev LD_TRACE_LOADED_OBJECTS_FMT2
240When set, these variables are interpreted as format strings a la
241.Xr printf 3
242to customize the trace output and are used by
243.Xr ldd 1 Ns 's
244.Fl f
245option and allows
246.Xr ldd 1
247to be operated as a filter more conveniently.
248If the dependency name starts with string
249.Pa lib ,
250.Ev LD_TRACE_LOADED_OBJECTS_FMT1
251is used, otherwise
252.Ev LD_TRACE_LOADED_OBJECTS_FMT2
253is used.
254The following conversions can be used:
255.Bl -tag -width 4n
256.It Li %a
257The main program's name
258(also known as
259.Dq __progname ) .
260.It Li \&%A
261The value of the environment variable
262.Ev LD_TRACE_LOADED_OBJECTS_PROGNAME .
263Typically used to print both the names of programs and shared libraries
264being inspected using
265.Xr ldd 1 .
266.It Li %o
267The library name.
268.It Li %p
269The full pathname as determined by
270.Nm rtld Ns 's
271library search rules.
272.It Li %x
273The library's load address.
274.El
275.Pp
276Additionally,
277.Ql \en
278and
279.Ql \et
280are recognized and have their usual meaning.
281.It Ev LD_UTRACE
282If set,
283.Nm
284will log events such as the loading and unloading of shared objects via
285.Xr utrace 2 .
286.It Ev LD_LOADFLTR
287If set,
288.Nm
289will process the filtee dependencies of the loaded objects immediately,
290instead of postponing it until required.
291Normally, the filtees are opened at the time of the first symbol resolution
292from the filter object.
293.El
294.Sh DIRECT EXECUTION MODE
295.Nm
296is typically used implicitly, loaded by the kernel as requested by the
297.Dv PT_INTERP
298program header of the executed binary.
299.Fx
300also supports a direct execution mode for the dynamic linker.
301In this mode, the user explicitly executes
302.Nm
303and provides the path of the program to be linked and executed as
304an argument.
305This mode allows use of a non-standard dynamic linker for a program
306activation without changing the binary or without changing
307the installed dynamic linker.
308Execution options may be specified.
309.Pp
310The syntax of the direct invocation is
311.Bd -ragged -offset indent
312.Pa /libexec/ld-elf.so.1
313.Op Fl b Ar exe
314.Op Fl f Ar fd
315.Op Fl p
316.Op Fl -
317.Pa image_path
318.Op Ar image arguments
319.Ed
320.Pp
321The options are:
322.Bl -tag -width indent
323.It Fl b Ar exe
324Use the executable
325.Fa exe
326instead of
327.Fa image_path
328for activation.
329If this option is specified,
330.Ar image_path
331is only used to provide the
332.Va argv[0]
333value to the program.
334.It Fl f Ar fd
335File descriptor
336.Ar fd
337references the binary to be activated by
338.Nm .
339It must already be opened in the process when executing
340.Nm .
341If this option is specified,
342.Ar image_path
343is only used to provide the
344.Va argv[0]
345value to the program.
346.It Fl p
347If the
348.Pa image_path
349argument specifies a name which does not contain a slash
350.Dq Li /
351character,
352.Nm
353uses the search path provided by the environment variable
354.Dv PATH
355to find the binary to execute.
356.It Fl v
357Display information about this run-time linker binary, then exit.
358.It Fl -
359Ends the
360.Nm
361options.
362The argument following
363.Fl -
364is interpreted as the path of the binary to execute.
365.El
366.Pp
367In the direct execution mode,
368.Nm
369emulates verification of the binary execute permission for the
370current user.
371This is done to avoid breaking user expectations in naively restricted
372execution environments.
373The verification only uses Unix
374.Dv DACs ,
375ignores
376.Dv ACLs ,
377and is naturally prone to race conditions.
378Environments which rely on such restrictions are weak
379and breakable on their own.
380.Sh VERSIONING
381Newer
382.Nm
383might provide some features or changes in runtime behavior that cannot be
384easily detected at runtime by checking of the normal exported symbols.
385Note that it is almost always wrong to verify
386.Dv __FreeBSD_version
387in userspace to detect features, either at compile or at run time,
388because either kernel, or libc, or environment variables could not
389match the running
390.Nm .
391.Pp
392To solve the problem,
393.Nm
394exports some feature indicators in the
395.Fx
396private symbols namespace
397.Dv FBSDprivate_1.0 .
398Symbols start with the
399.Dv _rtld_version
400prefix.
401Current list of defined symbols and corresponding features is:
402.Bl -tag -width indent
403.It Dv _rtld_version__FreeBSD_version
404Symbol exports the value of the
405.Dv __FreeBSD_version
406definition as it was provided during the
407.Nm
408build.
409The symbol is always present since the
410.Dv _rtld_version
411facility was introduced.
412.It Dv _rtld_version_laddr_offset
413The
414.Va l_addr
415member of the
416.Vt link_map
417structure contains the load offset of the shared object.
418Before that,
419.Va l_addr
420contained the base address of the library.
421See
422.Xr dlinfo 3 .
423.Pp
424Also it indicates the presence of
425.Va l_refname
426member of the structure.
427.It Dv _rtld_version_dlpi_tls_data
428The
429.Va dlpi_tls_data
430member of the structure
431.Vt dl_phdr_info
432contains the address of the module TLS segment for the calling thread,
433and not the address of the initialization segment.
434.El
435.Sh FILES
436.Bl -tag -width ".Pa /var/run/ld-elf32.so.hints" -compact
437.It Pa /var/run/ld-elf.so.hints
438Hints file.
439.It Pa /var/run/ld-elf32.so.hints
440Hints file for 32-bit binaries on 64-bit system.
441.It Pa /etc/libmap.conf
442The libmap configuration file.
443.It Pa /etc/libmap32.conf
444The libmap configuration file for 32-bit binaries on 64-bit system.
445.El
446.Sh SEE ALSO
447.Xr ld 1 ,
448.Xr ldd 1 ,
449.Xr dlinfo 3 ,
450.Xr capsicum 4 ,
451.Xr elf 5 ,
452.Xr libmap.conf 5 ,
453.Xr ldconfig 8
454