1 .\" Copyright (c) 1995 Paul Kranenburg
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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
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.
38 .Nd run-time link-editor
42 utility is a self-contained shared object providing run-time
43 support for loading and link-editing shared objects into a process'
45 It is also commonly known as the dynamic linker.
46 It uses the data structures
47 contained within dynamically linked programs to determine which shared
48 libraries are needed and loads them using the
52 After all shared libraries have been successfully loaded,
54 proceeds to resolve external references from both the main program and
56 A mechanism is provided for initialization routines
57 to be called on a per-object basis, giving a shared object an opportunity
58 to perform any extra set-up before execution of the program proper begins.
59 This is useful for C++ libraries that contain static constructors.
61 When resolving dependencies for the loaded objects,
63 translates dynamic token strings in rpath and soname.
66 option of the static linker was set when linking the binary,
67 the token expansion is performed at the object load time, see
69 The following strings are recognized now:
70 .Bl -tag -width ".Pa $PLATFORM"
72 Translated to the full path of the loaded object.
74 Translated to the name of the operating system implementation.
76 Translated to the release level of the operating system.
78 Translated to the machine hardware platform.
80 Translated to the system library path component on the platform.
83 for native binaries, and typically
85 for compat32 binaries.
86 Other translations might exist for other ABIs supported on the platform.
91 utility itself is loaded by the kernel together with any dynamically-linked
92 program that is to be executed.
93 The kernel transfers control to the
95 After the dynamic linker has finished loading,
96 relocating, and initializing the program and its required shared
97 objects, it transfers control to the entry point of the program.
98 The following search order is used to locate required shared objects:
100 .Bl -enum -offset indent -compact
103 of the referencing object unless that object also contains a
108 of the program unless the referencing object contains a
117 of the referencing object
119 Hints file produced by the
127 directories, unless the referencing object was linked using the
128 .Dq Fl z Ar nodefaultlib
135 recognizes a number of environment variables that can be used to modify
137 On 64-bit architectures, the linker for 32-bit objects recognizes
138 all the environment variables listed below, but is being prefixed with
141 .Ev LD_32_TRACE_LOADED_OBJECTS .
142 If the activated image is setuid or setgid, the variables are ignored.
143 .Bl -tag -width ".Ev LD_LIBMAP_DISABLE"
144 .It Ev LD_DUMP_REL_POST
147 will print a table containing all relocations after symbol
148 binding and relocation.
149 .It Ev LD_DUMP_REL_PRE
152 will print a table containing all relocations before symbol
153 binding and relocation.
154 .It Ev LD_DYNAMIC_WEAK
155 If set, use the ELF standard-compliant symbol lookup behavior:
156 resolve to the first found symbol definition.
160 provides the non-standard symbol lookup behavior:
161 when a weak symbol definition is found, remember the definition and
162 keep searching in the remaining shared objects for a non-weak definition.
163 If found, the non-weak definition is preferred, otherwise the remembered
164 weak definition is returned.
166 Symbols exported by dynamic linker itself (see
168 are always resolved using
170 rules regardless of the presence of the variable.
171 This variable is unset for set-user-ID and set-group-ID programs.
173 A library replacement list in the same format as
175 For convenience, the characters
179 can be used instead of a space and a newline.
180 This variable is parsed after
182 and will override its entries.
183 This variable is unset for set-user-ID and set-group-ID programs.
184 .It Ev LD_LIBMAP_DISABLE
185 If set, disables the use of
189 This variable is unset for set-user-ID and set-group-ID programs.
190 .It Ev LD_ELF_HINTS_PATH
191 This variable will override the default location of
194 This variable is unset for set-user-ID and set-group-ID programs.
195 .It Ev LD_LIBRARY_PATH
196 A colon separated list of directories, overriding the default search path
197 for shared libraries.
198 This variable is unset for set-user-ID and set-group-ID programs.
199 .It Ev LD_LIBRARY_PATH_RPATH
200 If the variable is specified and has a value starting with
201 any of \'y\', \'Y\' or \'1\' symbols, the path specified by
203 variable is allowed to override the path from
205 for binaries which does not contain
208 For such binaries, when the variable
209 .Ev LD_LIBRARY_PATH_RPATH
211 .Dq Fl z Ar nodefaultlib
212 link-time option is ignored as well.
214 A list of shared libraries, separated by colons and/or white space,
215 to be linked in before any
216 other shared libraries.
217 If the directory is not specified then
218 the directories specified by
220 will be searched first
221 followed by the set of built-in standard directories.
222 This variable is unset for set-user-ID and set-group-ID programs.
223 .It Ev LD_PRELOAD_FDS
224 A colon separated list of file descriptor numbers for libraries.
225 This is intended for preloading libraries in which we already have a file
227 This may optimize the process of loading libraries because we do not have to
228 look for them in directories.
229 It may also be useful in a capability base system where we do not have access to
230 global namespaces such as the filesystem.
231 .It Ev LD_LIBRARY_PATH_FDS
232 A colon separated list of file descriptor numbers for library directories.
233 This is intended for use within
235 sandboxes, when global namespaces such as the filesystem are unavailable.
236 It is consulted just after LD_LIBRARY_PATH.
237 This variable is unset for set-user-ID and set-group-ID programs.
239 When set to a nonempty string, prevents modifications of the PLT slots when
241 As result, each call of the PLT-resolved function is resolved.
242 In combination with debug output, this provides complete account of
243 all bind actions at runtime.
244 This variable is unset for set-user-ID and set-group-ID programs.
246 When set to a nonempty string, causes
248 to relocate all external function calls before starting execution of the
250 Normally, function calls are bound lazily, at the first call
253 increases the start-up time of a program, but it avoids run-time
254 surprises caused by unexpectedly undefined functions.
255 .It Ev LD_TRACE_LOADED_OBJECTS
256 When set to a nonempty string, causes
258 to exit after loading the shared objects and printing a summary which includes
259 the absolute pathnames of all objects, to standard output.
260 .It Ev LD_TRACE_LOADED_OBJECTS_ALL
261 When set to a nonempty string, causes
263 to expand the summary to indicate which objects caused each object to
265 .It Ev LD_TRACE_LOADED_OBJECTS_FMT1
266 .It Ev LD_TRACE_LOADED_OBJECTS_FMT2
267 When set, these variables are interpreted as format strings a la
269 to customize the trace output and are used by
274 to be operated as a filter more conveniently.
275 If the dependency name starts with string
277 .Ev LD_TRACE_LOADED_OBJECTS_FMT1
279 .Ev LD_TRACE_LOADED_OBJECTS_FMT2
281 The following conversions can be used:
284 The main program's name
288 The value of the environment variable
289 .Ev LD_TRACE_LOADED_OBJECTS_PROGNAME .
290 Typically used to print both the names of programs and shared libraries
291 being inspected using
296 The full pathname as determined by
298 library search rules.
300 The library's load address.
307 are recognized and have their usual meaning.
311 will log events such as the loading and unloading of shared objects via
316 will process the filtee dependencies of the loaded objects immediately,
317 instead of postponing it until required.
318 Normally, the filtees are opened at the time of the first symbol resolution
319 from the filter object.
323 to dump content of the aux vector to standard output, before passing
324 control to any user code.
326 .Sh DIRECT EXECUTION MODE
328 is typically used implicitly, loaded by the kernel as requested by the
330 program header of the executed binary.
332 also supports a direct execution mode for the dynamic linker.
333 In this mode, the user explicitly executes
335 and provides the path of the program to be linked and executed as
337 This mode allows use of a non-standard dynamic linker for a program
338 activation without changing the binary or without changing
339 the installed dynamic linker.
340 Execution options may be specified.
342 The syntax of the direct invocation is
343 .Bd -ragged -offset indent
344 .Pa /libexec/ld-elf.so.1
353 .Op Ar image arguments
357 .Bl -tag -width indent
364 If this option is specified,
366 is only used to provide the
368 value to the program.
370 Turn off the emulation of the binary execute permission.
374 references the binary to be activated by
376 It must already be opened in the process when executing
378 If this option is specified,
380 is only used to provide the
382 value to the program.
386 argument specifies a name which does not contain a slash
390 uses the search path provided by the environment variable
392 to find the binary to execute.
396 environment variables that otherwise affect the dynamic
399 Display information about this run-time linker binary, then exit.
404 The argument following
406 is interpreted as the path of the binary to execute.
409 In the direct execution mode,
411 emulates verification of the binary execute permission for the
413 This is done to avoid breaking user expectations in naively restricted
414 execution environments.
415 The verification only uses Unix
419 and is naturally prone to race conditions.
420 Environments which rely on such restrictions are weak
421 and breakable on their own.
422 It can be turned off with the
428 might provide some features or changes in runtime behavior that cannot be
429 easily detected at runtime by checking of the normal exported symbols.
430 Note that it is almost always wrong to verify
431 .Dv __FreeBSD_version
432 in userspace to detect features, either at compile or at run time,
433 because either kernel, or libc, or environment variables could not
437 To solve the problem,
439 exports some feature indicators in the
441 private symbols namespace
442 .Dv FBSDprivate_1.0 .
443 Symbols start with the
446 Current list of defined symbols and corresponding features is:
447 .Bl -tag -width indent
448 .It Dv _rtld_version__FreeBSD_version
449 Symbol exports the value of the
450 .Dv __FreeBSD_version
451 definition as it was provided during the
454 The symbol is always present since the
456 facility was introduced.
457 .It Dv _rtld_version_laddr_offset
462 structure contains the load offset of the shared object.
465 contained the base address of the library.
469 Also it indicates the presence of
471 member of the structure.
472 .It Dv _rtld_version_dlpi_tls_data
475 member of the structure
477 contains the address of the module TLS segment for the calling thread,
478 and not the address of the initialization segment.
481 .Bl -tag -width ".Pa /var/run/ld-elf32.so.hints" -compact
482 .It Pa /var/run/ld-elf.so.hints
484 .It Pa /var/run/ld-elf32.so.hints
485 Hints file for 32-bit binaries on 64-bit system.
486 .It Pa /etc/libmap.conf
487 The libmap configuration file.
488 .It Pa /etc/libmap32.conf
489 The libmap configuration file for 32-bit binaries on 64-bit system.