xref: /freebsd/libexec/rtld-elf/rtld.1 (revision ec0ea6efa1ad229d75c394c1a9b9cac33af2b1d3)
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 November 13, 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 .
134If the activated image is setuid or setgid, the variables are ignored.
135.Bl -tag -width ".Ev LD_LIBMAP_DISABLE"
136.It Ev LD_DUMP_REL_POST
137If set,
138.Nm
139will print a table containing all relocations after symbol
140binding and relocation.
141.It Ev LD_DUMP_REL_PRE
142If set,
143.Nm
144will print a table containing all relocations before symbol
145binding and relocation.
146.It Ev LD_DYNAMIC_WEAK
147If set, use the ELF standard-compliant symbol lookup behavior:
148resolve to the first found symbol definition.
149.Pp
150By default,
151.Fx
152provides the non-standard symbol lookup behavior:
153when a weak symbol definition is found, remember the definition and
154keep searching in the remaining shared objects for a non-weak definition.
155If found, the non-weak definition is preferred, otherwise the remembered
156weak definition is returned.
157.Pp
158Symbols exported by dynamic linker itself (see
159.Xr dlfcn 3 )
160are always resolved using
161.Fx
162rules regardless of the presence of the variable.
163This variable is unset for set-user-ID and set-group-ID programs.
164.It Ev LD_LIBMAP
165A library replacement list in the same format as
166.Xr libmap.conf 5 .
167For convenience, the characters
168.Ql =
169and
170.Ql \&,
171can be used instead of a space and a newline.
172This variable is parsed after
173.Xr libmap.conf 5 ,
174and will override its entries.
175This variable is unset for set-user-ID and set-group-ID programs.
176.It Ev LD_LIBMAP_DISABLE
177If set, disables the use of
178.Xr libmap.conf 5
179and
180.Ev LD_LIBMAP .
181This variable is unset for set-user-ID and set-group-ID programs.
182.It Ev LD_ELF_HINTS_PATH
183This variable will override the default location of
184.Dq hints
185file.
186This variable is unset for set-user-ID and set-group-ID programs.
187.It Ev LD_LIBRARY_PATH
188A colon separated list of directories, overriding the default search path
189for shared libraries.
190This variable is unset for set-user-ID and set-group-ID programs.
191.It Ev LD_LIBRARY_PATH_RPATH
192If the variable is specified and has a value starting with
193any of \'y\', \'Y\' or \'1\' symbols, the path specified by
194.Ev LD_LIBRARY_PATH
195variable is allowed to override the path from
196.Dv DT_RPATH
197for binaries which does not contain
198.Dv DT_RUNPATH
199tag.
200For such binaries, when the variable
201.Ev LD_LIBRARY_PATH_RPATH
202is set,
203.Dq Fl z Ar nodefaultlib
204link-time option is ignored as well.
205.It Ev LD_PRELOAD
206A list of shared libraries, separated by colons and/or white space,
207to be linked in before any
208other shared libraries.
209If the directory is not specified then
210the directories specified by
211.It Ev LD_PRELOAD_FDS
212A colon separated list of file descriptor numbers for libraries.
213This is intended for preloading libraries in which we already have a file
214descriptor.
215This may optimize the process of loading libraries because we do not have to
216look for them in directories.
217It may also be useful in a capability base system where we do not have access to
218global namespaces such as the filesystem.
219.Ev LD_LIBRARY_PATH
220will be searched first
221followed by the set of built-in standard directories.
222This variable is unset for set-user-ID and set-group-ID programs.
223.It Ev LD_LIBRARY_PATH_FDS
224A colon separated list of file descriptor numbers for library directories.
225This is intended for use within
226.Xr capsicum 4
227sandboxes, when global namespaces such as the filesystem are unavailable.
228It is consulted just after LD_LIBRARY_PATH.
229This variable is unset for set-user-ID and set-group-ID programs.
230.It Ev LD_BIND_NOT
231When set to a nonempty string, prevents modifications of the PLT slots when
232doing bindings.
233As result, each call of the PLT-resolved function is resolved.
234In combination with debug output, this provides complete account of
235all bind actions at runtime.
236This variable is unset for set-user-ID and set-group-ID programs.
237.It Ev LD_BIND_NOW
238When set to a nonempty string, causes
239.Nm
240to relocate all external function calls before starting execution of the
241program.
242Normally, function calls are bound lazily, at the first call
243of each function.
244.Ev LD_BIND_NOW
245increases the start-up time of a program, but it avoids run-time
246surprises caused by unexpectedly undefined functions.
247.It Ev LD_TRACE_LOADED_OBJECTS
248When set to a nonempty string, causes
249.Nm
250to exit after loading the shared objects and printing a summary which includes
251the absolute pathnames of all objects, to standard output.
252.It Ev LD_TRACE_LOADED_OBJECTS_ALL
253When set to a nonempty string, causes
254.Nm
255to expand the summary to indicate which objects caused each object to
256be loaded.
257.It Ev LD_TRACE_LOADED_OBJECTS_FMT1
258.It Ev LD_TRACE_LOADED_OBJECTS_FMT2
259When set, these variables are interpreted as format strings a la
260.Xr printf 3
261to customize the trace output and are used by
262.Xr ldd 1 Ns 's
263.Fl f
264option and allows
265.Xr ldd 1
266to be operated as a filter more conveniently.
267If the dependency name starts with string
268.Pa lib ,
269.Ev LD_TRACE_LOADED_OBJECTS_FMT1
270is used, otherwise
271.Ev LD_TRACE_LOADED_OBJECTS_FMT2
272is used.
273The following conversions can be used:
274.Bl -tag -width 4n
275.It Li %a
276The main program's name
277(also known as
278.Dq __progname ) .
279.It Li \&%A
280The value of the environment variable
281.Ev LD_TRACE_LOADED_OBJECTS_PROGNAME .
282Typically used to print both the names of programs and shared libraries
283being inspected using
284.Xr ldd 1 .
285.It Li %o
286The library name.
287.It Li %p
288The full pathname as determined by
289.Nm rtld Ns 's
290library search rules.
291.It Li %x
292The library's load address.
293.El
294.Pp
295Additionally,
296.Ql \en
297and
298.Ql \et
299are recognized and have their usual meaning.
300.It Ev LD_UTRACE
301If set,
302.Nm
303will log events such as the loading and unloading of shared objects via
304.Xr utrace 2 .
305.It Ev LD_LOADFLTR
306If set,
307.Nm
308will process the filtee dependencies of the loaded objects immediately,
309instead of postponing it until required.
310Normally, the filtees are opened at the time of the first symbol resolution
311from the filter object.
312.It Ev LD_SHOW_AUXV
313If set, causes
314.Nm
315to dump content of the aux vector to standard output, before passing
316control to any user code.
317.El
318.Sh DIRECT EXECUTION MODE
319.Nm
320is typically used implicitly, loaded by the kernel as requested by the
321.Dv PT_INTERP
322program header of the executed binary.
323.Fx
324also supports a direct execution mode for the dynamic linker.
325In this mode, the user explicitly executes
326.Nm
327and provides the path of the program to be linked and executed as
328an argument.
329This mode allows use of a non-standard dynamic linker for a program
330activation without changing the binary or without changing
331the installed dynamic linker.
332Execution options may be specified.
333.Pp
334The syntax of the direct invocation is
335.Bd -ragged -offset indent
336.Pa /libexec/ld-elf.so.1
337.Op Fl b Ar exe
338.Op Fl d
339.Op Fl f Ar fd
340.Op Fl p
341.Op Fl u
342.Op Fl v
343.Op Fl -
344.Pa image_path
345.Op Ar image arguments
346.Ed
347.Pp
348The options are:
349.Bl -tag -width indent
350.It Fl b Ar exe
351Use the executable
352.Fa exe
353instead of
354.Fa image_path
355for activation.
356If this option is specified,
357.Ar image_path
358is only used to provide the
359.Va argv[0]
360value to the program.
361.It Fl d
362Turn off the emulation of the binary execute permission.
363.It Fl f Ar fd
364File descriptor
365.Ar fd
366references the binary to be activated by
367.Nm .
368It must already be opened in the process when executing
369.Nm .
370If this option is specified,
371.Ar image_path
372is only used to provide the
373.Va argv[0]
374value to the program.
375.It Fl p
376If the
377.Pa image_path
378argument specifies a name which does not contain a slash
379.Dq Li /
380character,
381.Nm
382uses the search path provided by the environment variable
383.Dv PATH
384to find the binary to execute.
385.It Fl u
386Ignore all
387.Ev LD_
388environment variables that otherwise affect the dynamic
389linker behavior.
390.It Fl v
391Display information about this run-time linker binary, then exit.
392.It Fl -
393Ends the
394.Nm
395options.
396The argument following
397.Fl -
398is interpreted as the path of the binary to execute.
399.El
400.Pp
401In the direct execution mode,
402.Nm
403emulates verification of the binary execute permission for the
404current user.
405This is done to avoid breaking user expectations in naively restricted
406execution environments.
407The verification only uses Unix
408.Dv DACs ,
409ignores
410.Dv ACLs ,
411and is naturally prone to race conditions.
412Environments which rely on such restrictions are weak
413and breakable on their own.
414It can be turned off with the
415.Fl d
416option.
417.Sh VERSIONING
418Newer
419.Nm
420might provide some features or changes in runtime behavior that cannot be
421easily detected at runtime by checking of the normal exported symbols.
422Note that it is almost always wrong to verify
423.Dv __FreeBSD_version
424in userspace to detect features, either at compile or at run time,
425because either kernel, or libc, or environment variables could not
426match the running
427.Nm .
428.Pp
429To solve the problem,
430.Nm
431exports some feature indicators in the
432.Fx
433private symbols namespace
434.Dv FBSDprivate_1.0 .
435Symbols start with the
436.Dv _rtld_version
437prefix.
438Current list of defined symbols and corresponding features is:
439.Bl -tag -width indent
440.It Dv _rtld_version__FreeBSD_version
441Symbol exports the value of the
442.Dv __FreeBSD_version
443definition as it was provided during the
444.Nm
445build.
446The symbol is always present since the
447.Dv _rtld_version
448facility was introduced.
449.It Dv _rtld_version_laddr_offset
450The
451.Va l_addr
452member of the
453.Vt link_map
454structure contains the load offset of the shared object.
455Before that,
456.Va l_addr
457contained the base address of the library.
458See
459.Xr dlinfo 3 .
460.Pp
461Also it indicates the presence of
462.Va l_refname
463member of the structure.
464.It Dv _rtld_version_dlpi_tls_data
465The
466.Va dlpi_tls_data
467member of the structure
468.Vt dl_phdr_info
469contains the address of the module TLS segment for the calling thread,
470and not the address of the initialization segment.
471.El
472.Sh FILES
473.Bl -tag -width ".Pa /var/run/ld-elf32.so.hints" -compact
474.It Pa /var/run/ld-elf.so.hints
475Hints file.
476.It Pa /var/run/ld-elf32.so.hints
477Hints file for 32-bit binaries on 64-bit system.
478.It Pa /etc/libmap.conf
479The libmap configuration file.
480.It Pa /etc/libmap32.conf
481The libmap configuration file for 32-bit binaries on 64-bit system.
482.El
483.Sh SEE ALSO
484.Xr ld 1 ,
485.Xr ldd 1 ,
486.Xr dlinfo 3 ,
487.Xr capsicum 4 ,
488.Xr elf 5 ,
489.Xr libmap.conf 5 ,
490.Xr ldconfig 8
491