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.
83 utility itself is loaded by the kernel together with any dynamically-linked
84 program that is to be executed.
85 The kernel transfers control to the
87 After the dynamic linker has finished loading,
88 relocating, and initializing the program and its required shared
89 objects, it transfers control to the entry point of the program.
90 The following search order is used to locate required shared objects:
92 .Bl -enum -offset indent -compact
95 of the referencing object unless that object also contains a
100 of the program unless the referencing object contains a
109 of the referencing object
111 Hints file produced by the
119 directories, unless the referencing object was linked using the
120 .Dq Fl z Ar nodefaultlib
127 recognizes a number of environment variables that can be used to modify
129 On 64-bit architectures, the linker for 32-bit objects recognizes
130 all the environment variables listed below, but is being prefixed with
133 .Ev LD_32_TRACE_LOADED_OBJECTS .
134 If 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
139 will print a table containing all relocations after symbol
140 binding and relocation.
141 .It Ev LD_DUMP_REL_PRE
144 will print a table containing all relocations before symbol
145 binding and relocation.
146 .It Ev LD_DYNAMIC_WEAK
147 If set, use the ELF standard-compliant symbol lookup behavior:
148 resolve to the first found symbol definition.
152 provides the non-standard symbol lookup behavior:
153 when a weak symbol definition is found, remember the definition and
154 keep searching in the remaining shared objects for a non-weak definition.
155 If found, the non-weak definition is preferred, otherwise the remembered
156 weak definition is returned.
158 Symbols exported by dynamic linker itself (see
160 are always resolved using
162 rules regardless of the presence of the variable.
163 This variable is unset for set-user-ID and set-group-ID programs.
165 A library replacement list in the same format as
167 For convenience, the characters
171 can be used instead of a space and a newline.
172 This variable is parsed after
174 and will override its entries.
175 This variable is unset for set-user-ID and set-group-ID programs.
176 .It Ev LD_LIBMAP_DISABLE
177 If set, disables the use of
181 This variable is unset for set-user-ID and set-group-ID programs.
182 .It Ev LD_ELF_HINTS_PATH
183 This variable will override the default location of
186 This variable is unset for set-user-ID and set-group-ID programs.
187 .It Ev LD_LIBRARY_PATH
188 A colon separated list of directories, overriding the default search path
189 for shared libraries.
190 This variable is unset for set-user-ID and set-group-ID programs.
191 .It Ev LD_LIBRARY_PATH_RPATH
192 If the variable is specified and has a value starting with
193 any of \'y\', \'Y\' or \'1\' symbols, the path specified by
195 variable is allowed to override the path from
197 for binaries which does not contain
200 For such binaries, when the variable
201 .Ev LD_LIBRARY_PATH_RPATH
203 .Dq Fl z Ar nodefaultlib
204 link-time option is ignored as well.
206 A list of shared libraries, separated by colons and/or white space,
207 to be linked in before any
208 other shared libraries.
209 If the directory is not specified then
210 the directories specified by
212 will be searched first
213 followed by the set of built-in standard directories.
214 This variable is unset for set-user-ID and set-group-ID programs.
215 .It Ev LD_PRELOAD_FDS
216 A colon separated list of file descriptor numbers for libraries.
217 This is intended for preloading libraries in which we already have a file
219 This may optimize the process of loading libraries because we do not have to
220 look for them in directories.
221 It may also be useful in a capability base system where we do not have access to
222 global namespaces such as the filesystem.
223 .It Ev LD_LIBRARY_PATH_FDS
224 A colon separated list of file descriptor numbers for library directories.
225 This is intended for use within
227 sandboxes, when global namespaces such as the filesystem are unavailable.
228 It is consulted just after LD_LIBRARY_PATH.
229 This variable is unset for set-user-ID and set-group-ID programs.
231 When set to a nonempty string, prevents modifications of the PLT slots when
233 As result, each call of the PLT-resolved function is resolved.
234 In combination with debug output, this provides complete account of
235 all bind actions at runtime.
236 This variable is unset for set-user-ID and set-group-ID programs.
238 When set to a nonempty string, causes
240 to relocate all external function calls before starting execution of the
242 Normally, function calls are bound lazily, at the first call
245 increases the start-up time of a program, but it avoids run-time
246 surprises caused by unexpectedly undefined functions.
247 .It Ev LD_TRACE_LOADED_OBJECTS
248 When set to a nonempty string, causes
250 to exit after loading the shared objects and printing a summary which includes
251 the absolute pathnames of all objects, to standard output.
252 .It Ev LD_TRACE_LOADED_OBJECTS_ALL
253 When set to a nonempty string, causes
255 to expand the summary to indicate which objects caused each object to
257 .It Ev LD_TRACE_LOADED_OBJECTS_FMT1
258 .It Ev LD_TRACE_LOADED_OBJECTS_FMT2
259 When set, these variables are interpreted as format strings a la
261 to customize the trace output and are used by
266 to be operated as a filter more conveniently.
267 If the dependency name starts with string
269 .Ev LD_TRACE_LOADED_OBJECTS_FMT1
271 .Ev LD_TRACE_LOADED_OBJECTS_FMT2
273 The following conversions can be used:
276 The main program's name
280 The value of the environment variable
281 .Ev LD_TRACE_LOADED_OBJECTS_PROGNAME .
282 Typically used to print both the names of programs and shared libraries
283 being inspected using
288 The full pathname as determined by
290 library search rules.
292 The library's load address.
299 are recognized and have their usual meaning.
303 will log events such as the loading and unloading of shared objects via
308 will process the filtee dependencies of the loaded objects immediately,
309 instead of postponing it until required.
310 Normally, the filtees are opened at the time of the first symbol resolution
311 from the filter object.
315 to dump content of the aux vector to standard output, before passing
316 control to any user code.
318 .Sh DIRECT EXECUTION MODE
320 is typically used implicitly, loaded by the kernel as requested by the
322 program header of the executed binary.
324 also supports a direct execution mode for the dynamic linker.
325 In this mode, the user explicitly executes
327 and provides the path of the program to be linked and executed as
329 This mode allows use of a non-standard dynamic linker for a program
330 activation without changing the binary or without changing
331 the installed dynamic linker.
332 Execution options may be specified.
334 The syntax of the direct invocation is
335 .Bd -ragged -offset indent
336 .Pa /libexec/ld-elf.so.1
345 .Op Ar image arguments
349 .Bl -tag -width indent
356 If this option is specified,
358 is only used to provide the
360 value to the program.
362 Turn off the emulation of the binary execute permission.
366 references the binary to be activated by
368 It must already be opened in the process when executing
370 If this option is specified,
372 is only used to provide the
374 value to the program.
378 argument specifies a name which does not contain a slash
382 uses the search path provided by the environment variable
384 to find the binary to execute.
388 environment variables that otherwise affect the dynamic
391 Display information about this run-time linker binary, then exit.
396 The argument following
398 is interpreted as the path of the binary to execute.
401 In the direct execution mode,
403 emulates verification of the binary execute permission for the
405 This is done to avoid breaking user expectations in naively restricted
406 execution environments.
407 The verification only uses Unix
411 and is naturally prone to race conditions.
412 Environments which rely on such restrictions are weak
413 and breakable on their own.
414 It can be turned off with the
420 might provide some features or changes in runtime behavior that cannot be
421 easily detected at runtime by checking of the normal exported symbols.
422 Note that it is almost always wrong to verify
423 .Dv __FreeBSD_version
424 in userspace to detect features, either at compile or at run time,
425 because either kernel, or libc, or environment variables could not
429 To solve the problem,
431 exports some feature indicators in the
433 private symbols namespace
434 .Dv FBSDprivate_1.0 .
435 Symbols start with the
438 Current list of defined symbols and corresponding features is:
439 .Bl -tag -width indent
440 .It Dv _rtld_version__FreeBSD_version
441 Symbol exports the value of the
442 .Dv __FreeBSD_version
443 definition as it was provided during the
446 The symbol is always present since the
448 facility was introduced.
449 .It Dv _rtld_version_laddr_offset
454 structure contains the load offset of the shared object.
457 contained the base address of the library.
461 Also it indicates the presence of
463 member of the structure.
464 .It Dv _rtld_version_dlpi_tls_data
467 member of the structure
469 contains the address of the module TLS segment for the calling thread,
470 and not the address of the initialization segment.
473 .Bl -tag -width ".Pa /var/run/ld-elf32.so.hints" -compact
474 .It Pa /var/run/ld-elf.so.hints
476 .It Pa /var/run/ld-elf32.so.hints
477 Hints file for 32-bit binaries on 64-bit system.
478 .It Pa /etc/libmap.conf
479 The libmap configuration file.
480 .It Pa /etc/libmap32.conf
481 The libmap configuration file for 32-bit binaries on 64-bit system.