Debian Codegraph @

upstream/debian-trixie/man8/ld.so.8

raw
1 .\" %%%LICENSE_START(PUBLIC_DOMAIN)
2 .\" This is in the public domain
3 .\" %%%LICENSE_END
4 .\" Various parts:
5 .\" Copyright (C) 2007-9, 2013, 2016 Michael Kerrisk <[email protected]>
6 .\"
7 .TH ld.so 8 2024-05-08 "Linux man-pages 6.9.1"
8 .SH NAME
9 ld.so, ld\-linux.so \- dynamic linker/loader
10 .SH SYNOPSIS
11 The dynamic linker can be run either indirectly by running some
12 dynamically linked program or shared object
13 (in which case no command-line options
14 to the dynamic linker can be passed and, in the ELF case, the dynamic linker
15 which is stored in the
16 .B .interp
17 section of the program is executed) or directly by running:
18 .P
19 .I /lib/ld\-linux.so.*
20 [OPTIONS] [PROGRAM [ARGUMENTS]]
21 .SH DESCRIPTION
22 The programs
23 .B ld.so
24 and
25 .B ld\-linux.so*
26 find and load the shared objects (shared libraries) needed by a program,
27 prepare the program to run, and then run it.
28 .P
29 Linux binaries require dynamic linking (linking at run time)
30 unless the
31 .B \-static
32 option was given to
33 .BR ld (1)
34 during compilation.
35 .P
36 The program
37 .B ld.so
38 handles a.out binaries, a binary format used long ago.
39 The program
40 .B ld\-linux.so*
41 (\fI/lib/ld\-linux.so.1\fP for libc5, \fI/lib/ld\-linux.so.2\fP for glibc2)
42 handles binaries that are in the more modern ELF format.
43 Both programs have the same behavior, and use the same
44 support files and programs
45 .RB ( ldd (1),
46 .BR ldconfig (8),
47 and
48 .IR /etc/ld.so.conf ).
49 .P
50 When resolving shared object dependencies,
51 the dynamic linker first inspects each dependency
52 string to see if it contains a slash (this can occur if
53 a shared object pathname containing slashes was specified at link time).
54 If a slash is found, then the dependency string is interpreted as
55 a (relative or absolute) pathname,
56 and the shared object is loaded using that pathname.
57 .P
58 If a shared object dependency does not contain a slash,
59 then it is searched for in the following order:
60 .IP (1) 5
61 Using the directories specified in the
62 DT_RPATH dynamic section attribute
63 of the binary if present and DT_RUNPATH attribute does not exist.
64 .IP (2)
65 Using the environment variable
66 .BR LD_LIBRARY_PATH ,
67 unless the executable is being run in secure-execution mode (see below),
68 in which case this variable is ignored.
69 .IP (3)
70 Using the directories specified in the
71 DT_RUNPATH dynamic section attribute
72 of the binary if present.
73 Such directories are searched only to
74 find those objects required by DT_NEEDED (direct dependencies) entries
75 and do not apply to those objects' children,
76 which must themselves have their own DT_RUNPATH entries.
77 This is unlike DT_RPATH, which is applied
78 to searches for all children in the dependency tree.
79 .IP (4)
80 From the cache file
81 .IR /etc/ld.so.cache ,
82 which contains a compiled list of candidate shared objects previously found
83 in the augmented library path.
84 If, however, the binary was linked with the
85 .B \-z nodefaultlib
86 linker option, shared objects in the default paths are skipped.
87 Shared objects installed in hardware capability directories (see below)
88 are preferred to other shared objects.
89 .IP (5)
90 In the default path
91 .IR /lib ,
92 and then
93 .IR /usr/lib .
94 (On some 64-bit architectures, the default paths for 64-bit shared objects are
95 .IR /lib64 ,
96 and then
97 .IR /usr/lib64 .)
98 If the binary was linked with the
99 .B \-z nodefaultlib
100 linker option, this step is skipped.
101 .\"
102 .SS Dynamic string tokens
103 In several places, the dynamic linker expands dynamic string tokens:
104 .IP \[bu] 3
105 In the environment variables
106 .BR LD_LIBRARY_PATH ,
107 .BR LD_PRELOAD ,
108 and
109 .BR LD_AUDIT ,
110 .IP \[bu]
111 inside the values of the dynamic section tags
112 .BR DT_NEEDED ,
113 .BR DT_RPATH ,
114 .BR DT_RUNPATH ,
115 .BR DT_AUDIT ,
116 and
117 .B DT_DEPAUDIT
118 of ELF binaries,
119 .IP \[bu]
120 in the arguments to the
121 .B ld.so
122 command line options
123 .BR \-\-audit ,
124 .BR \-\-library\-path ,
125 and
126 .B \-\-preload
127 (see below), and
128 .IP \[bu]
129 in the filename arguments to the
130 .BR dlopen (3)
131 and
132 .BR dlmopen (3)
133 functions.
134 .P
135 The substituted tokens are as follows:
136 .TP
137 .IR $ORIGIN " (or equivalently " ${ORIGIN} )
138 This expands to
139 the directory containing the program or shared object.
140 Thus, an application located in
141 .I somedir/app
142 could be compiled with
143 .IP
144 .in +4n
145 .EX
146 gcc \-Wl,\-rpath,\[aq]$ORIGIN/../lib\[aq]
147 .EE
148 .in
149 .IP
150 so that it finds an associated shared object in
151 .I somedir/lib
152 no matter where
153 .I somedir
154 is located in the directory hierarchy.
155 This facilitates the creation of "turn-key" applications that
156 do not need to be installed into special directories,
157 but can instead be unpacked into any directory
158 and still find their own shared objects.
159 .TP
160 .IR $LIB " (or equivalently " ${LIB} )
161 This expands to
162 .I lib
163 or
164 .I lib64
165 depending on the architecture
166 (e.g., on x86-64, it expands to
167 .I lib64
168 and
169 on x86-32, it expands to
170 .IR lib ).
171 .TP
172 .IR $PLATFORM " (or equivalently " ${PLATFORM} )
173 This expands to a string corresponding to the processor type
174 of the host system (e.g., "x86_64").
175 On some architectures, the Linux kernel doesn't provide a platform
176 string to the dynamic linker.
177 The value of this string is taken from the
178 .B AT_PLATFORM
179 value in the auxiliary vector (see
180 .BR getauxval (3)).
181 .\" To get an idea of the places that $PLATFORM would match,
182 .\" look at the output of the following:
183 .\"
184 .\" mkdir /tmp/d
185 .\" LD_LIBRARY_PATH=/tmp/d strace -e open /bin/date 2>&1 | grep /tmp/d
186 .\"
187 .\" ld.so lets names be abbreviated, so $O will work for $ORIGIN;
188 .\" Don't do this!!
189 .P
190 Note that the dynamic string tokens have to be quoted properly when
191 set from a shell,
192 to prevent their expansion as shell or environment variables.
193 .SH OPTIONS
194 .TP
195 .BR \-\-argv0 " \fIstring\fP (since glibc 2.33)"
196 Set
197 .I argv[0]
198 to the value
199 .I string
200 before running the program.
201 .TP
202 .BI \-\-audit " list"
203 Use objects named in
204 .I list
205 as auditors.
206 The objects in
207 .I list
208 are delimited by colons.
209 .TP
210 .BI \-\-glibc-hwcaps-mask " list"
211 only search built-in subdirectories if in
212 .IR list .
213 .TP
214 .BI \-\-glibc-hwcaps-prepend " list"
215 Search glibc-hwcaps subdirectories in
216 .IR list .
217 .TP
218 .B \-\-inhibit\-cache
219 Do not use
220 .IR /etc/ld.so.cache .
221 .TP
222 .BI \-\-library\-path " path"
223 Use
224 .I path
225 instead of
226 .B LD_LIBRARY_PATH
227 environment variable setting (see below).
228 The names
229 .IR ORIGIN ,
230 .IR LIB ,
231 and
232 .I PLATFORM
233 are interpreted as for the
234 .B LD_LIBRARY_PATH
235 environment variable.
236 .TP
237 .BI \-\-inhibit\-rpath " list"
238 Ignore RPATH and RUNPATH information in object names in
239 .IR list .
240 This option is ignored when running in secure-execution mode (see below).
241 The objects in
242 .I list
243 are delimited by colons or spaces.
244 .TP
245 .B \-\-list
246 List all dependencies and how they are resolved.
247 .TP
248 .BR \-\-list\-diagnostics " (since glibc 2.33)"
249 Print system diagnostic information in a machine-readable format,
250 such as some internal loader variables,
251 the auxiliary vector
252 (see
253 .BR getauxval (3)),
254 and the environment variables.
255 On some architectures,
256 the command might print additional information
257 (like the cpu features used in GNU indirect function selection on x86).
258 .BR \-\-list\-tunables " (since glibc 2.33)"
259 Print the names and values of all tunables,
260 along with the minimum and maximum allowed values.
261 .TP
262 .BR \-\-preload " \fIlist\fP (since glibc 2.30)"
263 Preload the objects specified in
264 .IR list .
265 The objects in
266 .I list
267 are delimited by colons or spaces.
268 The objects are preloaded as explained in the description of the
269 .B LD_PRELOAD
270 environment variable below.
271 .IP
272 By contrast with
273 .BR LD_PRELOAD ,
274 the
275 .B \-\-preload
276 option provides a way to perform preloading for a single executable
277 without affecting preloading performed in any child process that executes
278 a new program.
279 .TP
280 .B \-\-verify
281 Verify that program is dynamically linked and this dynamic linker can handle
282 it.
283 .SH ENVIRONMENT
284 Various environment variables influence the operation of the dynamic linker.
285 .\"
286 .SS Secure-execution mode
287 For security reasons,
288 if the dynamic linker determines that a binary should be
289 run in secure-execution mode,
290 the effects of some environment variables are voided or modified,
291 and furthermore those environment variables are stripped from the environment,
292 so that the program does not even see the definitions.
293 Some of these environment variables affect the operation of
294 the dynamic linker itself, and are described below.
295 Other environment variables treated in this way include:
296 .BR GCONV_PATH ,
297 .BR GETCONF_DIR ,
298 .BR HOSTALIASES ,
299 .BR LOCALDOMAIN ,
300 .BR LD_AUDIT ,
301 .BR LD_DEBUG ,
302 .BR LD_DEBUG_OUTPUT ,
303 .BR LD_DYNAMIC_WEAK ,
304 .BR LD_HWCAP_MASK ,
305 .BR LD_LIBRARY_PATH ,
306 .BR LD_ORIGIN_PATH ,
307 .BR LD_PRELOAD ,
308 .BR LD_PROFILE ,
309 .BR LD_SHOW_AUXV ,
310 .BR LOCALDOMAIN ,
311 .BR LOCPATH ,
312 .BR MALLOC_TRACE ,
313 .BR NIS_PATH ,
314 .BR NLSPATH ,
315 .BR RESOLV_HOST_CONF ,
316 .BR RES_OPTIONS ,
317 .BR TMPDIR ,
318 and
319 .BR TZDIR .
320 .P
321 A binary is executed in secure-execution mode if the
322 .B AT_SECURE
323 entry in the auxiliary vector (see
324 .BR getauxval (3))
325 has a nonzero value.
326 This entry may have a nonzero value for various reasons, including:
327 .IP \[bu] 3
328 The process's real and effective user IDs differ,
329 or the real and effective group IDs differ.
330 This typically occurs as a result of executing
331 a set-user-ID or set-group-ID program.
332 .IP \[bu]
333 A process with a non-root user ID executed a binary that
334 conferred capabilities to the process.
335 .IP \[bu]
336 A nonzero value may have been set by a Linux Security Module.
337 .\"
338 .SS Environment variables
339 Among the more important environment variables are the following:
340 .TP
341 .BR LD_ASSUME_KERNEL " (from glibc 2.2.3 to glibc 2.36)"
342 Each shared object can inform the dynamic linker of the minimum kernel ABI
343 version that it requires.
344 (This requirement is encoded in an ELF note section that is viewable via
345 .I readelf\~\-n
346 as a section labeled
347 .BR NT_GNU_ABI_TAG .)
348 At run time,
349 the dynamic linker determines the ABI version of the running kernel and
350 will reject loading shared objects that specify minimum ABI versions
351 that exceed that ABI version.
352 .IP
353 .B LD_ASSUME_KERNEL
354 can be used to
355 cause the dynamic linker to assume that it is running on a system with
356 a different kernel ABI version.
357 For example, the following command line causes the
358 dynamic linker to assume it is running on Linux 2.2.5 when loading
359 the shared objects required by
360 .IR myprog :
361 .IP
362 .in +4n
363 .EX
364 $ \fBLD_ASSUME_KERNEL=2.2.5 ./myprog\fP
365 .EE
366 .in
367 .IP
368 On systems that provide multiple versions of a shared object
369 (in different directories in the search path) that have
370 different minimum kernel ABI version requirements,
371 .B LD_ASSUME_KERNEL
372 can be used to select the version of the object that is used
373 (dependent on the directory search order).
374 .IP
375 Historically, the most common use of the
376 .B LD_ASSUME_KERNEL
377 feature was to manually select the older
378 LinuxThreads POSIX threads implementation on systems that provided both
379 LinuxThreads and NPTL
380 (which latter was typically the default on such systems);
381 see
382 .BR pthreads (7).
383 .TP
384 .BR LD_BIND_NOW " (since glibc 2.1.1)"
385 If set to a nonempty string,
386 causes the dynamic linker to resolve all symbols
387 at program startup instead of deferring function call resolution to the point
388 when they are first referenced.
389 This is useful when using a debugger.
390 .TP
391 .B LD_LIBRARY_PATH
392 A list of directories in which to search for
393 ELF libraries at execution time.
394 The items in the list are separated by either colons or semicolons,
395 and there is no support for escaping either separator.
396 A zero-length directory name indicates the current working directory.
397 .IP
398 This variable is ignored in secure-execution mode.
399 .IP
400 Within the pathnames specified in
401 .BR LD_LIBRARY_PATH ,
402 the dynamic linker expands the tokens
403 .IR $ORIGIN ,
404 .IR $LIB ,
405 and
406 .I $PLATFORM
407 (or the versions using curly braces around the names)
408 as described above in
409 .IR "Dynamic string tokens" .
410 Thus, for example,
411 the following would cause a library to be searched for in either the
412 .I lib
413 or
414 .I lib64
415 subdirectory below the directory containing the program to be executed:
416 .IP
417 .in +4n
418 .EX
419 $ \fBLD_LIBRARY_PATH=\[aq]$ORIGIN/$LIB\[aq] prog\fP
420 .EE
421 .in
422 .IP
423 (Note the use of single quotes, which prevent expansion of
424 .I $ORIGIN
425 and
426 .I $LIB
427 as shell variables!)
428 .TP
429 .B LD_PRELOAD
430 A list of additional, user-specified, ELF shared
431 objects to be loaded before all others.
432 This feature can be used to selectively override functions
433 in other shared objects.
434 .IP
435 The items of the list can be separated by spaces or colons,
436 and there is no support for escaping either separator.
437 The objects are searched for using the rules given under DESCRIPTION.
438 Objects are searched for and added to the link map in the left-to-right
439 order specified in the list.
440 .IP
441 In secure-execution mode,
442 preload pathnames containing slashes are ignored.
443 Furthermore, shared objects are preloaded only
444 from the standard search directories and only
445 if they have set-user-ID mode bit enabled (which is not typical).
446 .IP
447 Within the names specified in the
448 .B LD_PRELOAD
449 list, the dynamic linker understands the tokens
450 .IR $ORIGIN ,
451 .IR $LIB ,
452 and
453 .I $PLATFORM
454 (or the versions using curly braces around the names)
455 as described above in
456 .IR "Dynamic string tokens" .
457 (See also the discussion of quoting under the description of
458 .BR LD_LIBRARY_PATH .)
459 .\" Tested with the following:
460 .\"
461 .\" LD_PRELOAD='$LIB/libmod.so' LD_LIBRARY_PATH=. ./prog
462 .\"
463 .\" which will preload the libmod.so in 'lib' or 'lib64', using it
464 .\" in preference to the version in '.'.
465 .IP
466 There are various methods of specifying libraries to be preloaded,
467 and these are handled in the following order:
468 .RS
469 .IP (1) 5
470 The
471 .B LD_PRELOAD
472 environment variable.
473 .IP (2)
474 The
475 .B \-\-preload
476 command-line option when invoking the dynamic linker directly.
477 .IP (3)
478 The
479 .I /etc/ld.so.preload
480 file (described below).
481 .RE
482 .TP
483 .B LD_TRACE_LOADED_OBJECTS
484 If set (to any value), causes the program to list its dynamic
485 dependencies, as if run by
486 .BR ldd (1),
487 instead of running normally.
488 .P
489 Then there are lots of more or less obscure variables,
490 many obsolete or only for internal use.
491 .TP
492 .BR LD_AUDIT " (since glibc 2.4)"
493 A list of user-specified, ELF shared objects
494 to be loaded before all others in a separate linker namespace
495 (i.e., one that does not intrude upon the normal symbol bindings that
496 would occur in the process)
497 These objects can be used to audit the operation of the dynamic linker.
498 The items in the list are colon-separated,
499 and there is no support for escaping the separator.
500 .IP
501 .B LD_AUDIT
502 is ignored in secure-execution mode.
503 .IP
504 The dynamic linker will notify the audit
505 shared objects at so-called auditing checkpoints\[em]for example,
506 loading a new shared object, resolving a symbol,
507 or calling a symbol from another shared object\[em]by
508 calling an appropriate function within the audit shared object.
509 For details, see
510 .BR rtld\-audit (7).
511 The auditing interface is largely compatible with that provided on Solaris,
512 as described in its
513 .IR "Linker and Libraries Guide" ,
514 in the chapter
515 .IR "Runtime Linker Auditing Interface" .
516 .IP
517 Within the names specified in the
518 .B LD_AUDIT
519 list, the dynamic linker understands the tokens
520 .IR $ORIGIN ,
521 .IR $LIB ,
522 and
523 .I $PLATFORM
524 (or the versions using curly braces around the names)
525 as described above in
526 .IR "Dynamic string tokens" .
527 (See also the discussion of quoting under the description of
528 .BR LD_LIBRARY_PATH .)
529 .IP
530 Since glibc 2.13,
531 .\" commit 8e9f92e9d5d7737afdacf79b76d98c4c42980508
532 in secure-execution mode,
533 names in the audit list that contain slashes are ignored,
534 and only shared objects in the standard search directories that
535 have the set-user-ID mode bit enabled are loaded.
536 .TP
537 .BR LD_BIND_NOT " (since glibc 2.1.95)"
538 If this environment variable is set to a nonempty string,
539 do not update the GOT (global offset table) and PLT (procedure linkage table)
540 after resolving a function symbol.
541 By combining the use of this variable with
542 .B LD_DEBUG
543 (with the categories
544 .I bindings
545 and
546 .IR symbols ),
547 one can observe all run-time function bindings.
548 .TP
549 .BR LD_DEBUG " (since glibc 2.1)"
550 Output verbose debugging information about operation of the dynamic linker.
551 The content of this variable is one of more of the following categories,
552 separated by colons, commas, or (if the value is quoted) spaces:
553 .RS
554 .TP 12
555 .I help
556 Specifying
557 .I help
558 in the value of this variable does not run the specified program,
559 and displays a help message about which categories can be specified in this
560 environment variable.
561 .TP
562 .I all
563 Print all debugging information (except
564 .I statistics
565 and
566 .IR unused ;
567 see below).
568 .TP
569 .I bindings
570 Display information about which definition each symbol is bound to.
571 .TP
572 .I files
573 Display progress for input file.
574 .TP
575 .I libs
576 Display library search paths.
577 .TP
578 .I reloc
579 Display relocation processing.
580 .TP
581 .I scopes
582 Display scope information.
583 .TP
584 .I statistics
585 Display relocation statistics.
586 .TP
587 .I symbols
588 Display search paths for each symbol look-up.
589 .TP
590 .I unused
591 Determine unused DSOs.
592 .TP
593 .I versions
594 Display version dependencies.
595 .RE
596 .IP
597 Since glibc 2.3.4,
598 .B LD_DEBUG
599 is ignored in secure-execution mode, unless the file
600 .I /etc/suid\-debug
601 exists (the content of the file is irrelevant).
602 .TP
603 .BR LD_DEBUG_OUTPUT " (since glibc 2.1)"
604 By default,
605 .B LD_DEBUG
606 output is written to standard error.
607 If
608 .B LD_DEBUG_OUTPUT
609 is defined, then output is written to the pathname specified by its value,
610 with the suffix "." (dot) followed by the process ID appended to the pathname.
611 .IP
612 .B LD_DEBUG_OUTPUT
613 is ignored in secure-execution mode.
614 .TP
615 .BR LD_DYNAMIC_WEAK " (since glibc 2.1.91)"
616 By default, when searching shared libraries to resolve a symbol reference,
617 the dynamic linker will resolve to the first definition it finds.
618 .IP
619 Old glibc versions (before glibc 2.2), provided a different behavior:
620 if the linker found a symbol that was weak,
621 it would remember that symbol and
622 keep searching in the remaining shared libraries.
623 If it subsequently found a strong definition of the same symbol,
624 then it would instead use that definition.
625 (If no further symbol was found,
626 then the dynamic linker would use the weak symbol that it initially found.)
627 .IP
628 The old glibc behavior was nonstandard.
629 (Standard practice is that the distinction between
630 weak and strong symbols should have effect only at static link time.)
631 In glibc 2.2,
632 .\" More precisely 2.1.92
633 .\" See weak handling
634 .\" https://www.sourceware.org/ml/libc-hacker/2000-06/msg00029.html
635 .\" To: GNU libc hacker <libc-hacker at sourceware dot cygnus dot com>
636 .\" Subject: weak handling
637 .\" From: Ulrich Drepper <drepper at redhat dot com>
638 .\" Date: 07 Jun 2000 20:08:12 -0700
639 .\" Reply-To: drepper at cygnus dot com (Ulrich Drepper)
640 the dynamic linker was modified to provide the current behavior
641 (which was the behavior that was provided by most other implementations
642 at that time).
643 .IP
644 Defining the
645 .B LD_DYNAMIC_WEAK
646 environment variable (with any value) provides
647 the old (nonstandard) glibc behavior,
648 whereby a weak symbol in one shared library may be overridden by
649 a strong symbol subsequently discovered in another shared library.
650 (Note that even when this variable is set,
651 a strong symbol in a shared library will not override
652 a weak definition of the same symbol in the main program.)
653 .IP
654 Since glibc 2.3.4,
655 .B LD_DYNAMIC_WEAK
656 is ignored in secure-execution mode.
657 .TP
658 .BR LD_HWCAP_MASK " (from glibc 2.1 to glibc 2.38)"
659 Mask for hardware capabilities.
660 Since glibc 2.26,
661 the option might be ignored
662 if glibc does not support tunables.
663 .TP
664 .BR LD_ORIGIN_PATH " (since glibc 2.1)"
665 Path where the binary is found.
666 .\" Used only if $ORIGIN can't be determined by normal means
667 .\" (from the origin path saved at load time, or from /proc/self/exe)?
668 .IP
669 Since glibc 2.4,
670 .B LD_ORIGIN_PATH
671 is ignored in secure-execution mode.
672 .TP
673 .BR LD_POINTER_GUARD " (from glibc 2.4 to glibc 2.22)"
674 Set to 0 to disable pointer guarding.
675 Any other value enables pointer guarding, which is also the default.
676 Pointer guarding is a security mechanism whereby some pointers to code
677 stored in writable program memory (return addresses saved by
678 .BR setjmp (3)
679 or function pointers used by various glibc internals) are mangled
680 semi-randomly to make it more difficult for an attacker to hijack
681 the pointers for use in the event of a buffer overrun or
682 stack-smashing attack.
683 Since glibc 2.23,
684 .\" commit a014cecd82b71b70a6a843e250e06b541ad524f7
685 .B LD_POINTER_GUARD
686 can no longer be used to disable pointer guarding,
687 which is now always enabled.
688 .TP
689 .BR LD_PROFILE " (since glibc 2.1)"
690 The name of a (single) shared object to be profiled,
691 specified either as a pathname or a soname.
692 Profiling output is appended to the file whose name is:
693 .RI \%$LD_PROFILE_OUTPUT /\: $LD_PROFILE .profile .
694 .IP
695 Since glibc 2.2.5,
696 .B LD_PROFILE
697 uses a different default path in secure-execution mode.
698 .TP
699 .BR LD_PROFILE_OUTPUT " (since glibc 2.1)"
700 Directory where
701 .B LD_PROFILE
702 output should be written.
703 If this variable is not defined, or is defined as an empty string,
704 then the default is
705 .IR /var/tmp .
706 .IP
707 .B LD_PROFILE_OUTPUT
708 is ignored in secure-execution mode; instead
709 .I /var/profile
710 is always used.
711 .TP
712 .BR LD_SHOW_AUXV " (since glibc 2.1)"
713 If this environment variable is defined (with any value),
714 show the auxiliary array passed up from the kernel (see also
715 .BR getauxval (3)).
716 .IP
717 Since glibc 2.3.4,
718 .B LD_SHOW_AUXV
719 is ignored in secure-execution mode.
720 .TP
721 .BR LD_TRACE_PRELINKING " (from glibc 2.4 to glibc 2.35)"
722 If this environment variable is defined,
723 trace prelinking of the object whose name is assigned to
724 this environment variable.
725 (Use
726 .BR ldd (1)
727 to get a list of the objects that might be traced.)
728 If the object name is not recognized,
729 .\" (This is what seems to happen, from experimenting)
730 then all prelinking activity is traced.
731 .TP
732 .BR LD_USE_LOAD_BIAS " (from glibc 2.3.3 to glibc 2.35)"
733 .\" http://sources.redhat.com/ml/libc-hacker/2003-11/msg00127.html
734 .\" Subject: [PATCH] Support LD_USE_LOAD_BIAS
735 .\" Jakub Jelinek
736 By default (i.e., if this variable is not defined),
737 executables and prelinked
738 shared objects will honor base addresses of their dependent shared objects
739 and (nonprelinked) position-independent executables (PIEs)
740 and other shared objects will not honor them.
741 If
742 .B LD_USE_LOAD_BIAS
743 is defined with the value 1, both executables and PIEs
744 will honor the base addresses.
745 If
746 .B LD_USE_LOAD_BIAS
747 is defined with the value 0,
748 neither executables nor PIEs will honor the base addresses.
749 .IP
750 Since glibc 2.3.3, this variable is ignored in secure-execution mode.
751 .TP
752 .BR LD_VERBOSE " (since glibc 2.1)"
753 If set to a nonempty string,
754 output symbol versioning information about the
755 program if the
756 .B LD_TRACE_LOADED_OBJECTS
757 environment variable has been set.
758 .TP
759 .BR LD_WARN " (since glibc 2.1.3)"
760 If set to a nonempty string, warn about unresolved symbols.
761 .TP
762 .BR LD_PREFER_MAP_32BIT_EXEC " (x86-64 only; since glibc 2.23)"
763 According to the Intel Silvermont software optimization guide, for 64-bit
764 applications, branch prediction performance can be negatively impacted
765 when the target of a branch is more than 4\ GB away from the branch.
766 If this environment variable is set (to any value),
767 the dynamic linker
768 will first try to map executable pages using the
769 .BR mmap (2)
770 .B MAP_32BIT
771 flag, and fall back to mapping without that flag if that attempt fails.
772 NB: MAP_32BIT will map to the low 2\ GB (not 4\ GB) of the address space.
773 .IP
774 Because
775 .B MAP_32BIT
776 reduces the address range available for address space layout
777 randomization (ASLR),
778 .B LD_PREFER_MAP_32BIT_EXEC
779 is always disabled in secure-execution mode.
780 .SH FILES
781 .TP
782 .I /lib/ld.so
783 a.out dynamic linker/loader
784 .TP
785 .IR /lib/ld\-linux.so. { 1 , 2 }
786 ELF dynamic linker/loader
787 .TP
788 .I /etc/ld.so.cache
789 File containing a compiled list of directories in which to search for
790 shared objects and an ordered list of candidate shared objects.
791 See
792 .BR ldconfig (8).
793 .TP
794 .I /etc/ld.so.preload
795 File containing a whitespace-separated list of ELF shared objects to
796 be loaded before the program.
797 See the discussion of
798 .B LD_PRELOAD
799 above.
800 If both
801 .B LD_PRELOAD
802 and
803 .I /etc/ld.so.preload
804 are employed, the libraries specified by
805 .B LD_PRELOAD
806 are preloaded first.
807 .I /etc/ld.so.preload
808 has a system-wide effect,
809 causing the specified libraries to be preloaded for
810 all programs that are executed on the system.
811 (This is usually undesirable,
812 and is typically employed only as an emergency remedy, for example,
813 as a temporary workaround to a library misconfiguration issue.)
814 .TP
815 .I lib*.so*
816 shared objects
817 .SH NOTES
818 .SS Legacy Hardware capabilities (from glibc 2.5 to glibc 2.37)
819 Some shared objects are compiled using hardware-specific instructions which do
820 not exist on every CPU.
821 Such objects should be installed in directories whose names define the
822 required hardware capabilities, such as
823 .IR /usr/lib/sse2/ .
824 The dynamic linker checks these directories against the hardware of the
825 machine and selects the most suitable version of a given shared object.
826 Hardware capability directories can be cascaded to combine CPU features.
827 The list of supported hardware capability names depends on the CPU.
828 The following names are currently recognized:
829 .\" Presumably, this info comes from sysdeps/i386/dl-procinfo.c and
830 .\" similar files
831 .TP
832 .B Alpha
833 ev4, ev5, ev56, ev6, ev67
834 .TP
835 .B MIPS
836 loongson2e, loongson2f, octeon, octeon2
837 .TP
838 .B PowerPC
839 4xxmac, altivec, arch_2_05, arch_2_06, booke, cellbe, dfp, efpdouble, efpsingle,
840 fpu, ic_snoop, mmu, notb, pa6t, power4, power5, power5+, power6x, ppc32, ppc601,
841 ppc64, smt, spe, ucache, vsx
842 .TP
843 .B SPARC
844 flush, muldiv, stbar, swap, ultra3, v9, v9v, v9v2
845 .TP
846 .B s390
847 dfp, eimm, esan3, etf3enh, g5, highgprs, hpage, ldisp, msa, stfle,
848 z900, z990, z9-109, z10, zarch
849 .TP
850 .B x86 (32-bit only)
851 acpi, apic, clflush, cmov, cx8, dts, fxsr, ht, i386, i486, i586, i686, mca, mmx,
852 mtrr, pat, pbe, pge, pn, pse36, sep, ss, sse, sse2, tm
853 .P
854 The legacy hardware capabilities support has the drawback that
855 each new feature added grows the search path exponentially,
856 because it has to be added to
857 every combination of the other existing features.
858 .P
859 For instance, on x86 32-bit,
860 if the hardware supports
861 .B i686
862 and
863 .BR sse2 ,
864 the resulting search path will be
865 .BR i686/sse2:i686:sse2:. .
866 A new capability
867 .B newcap
868 will set the search path to
869 .BR newcap/i686/sse2:newcap/i686:newcap/sse2:newcap:i686/sse2:i686:sse2: .
870 .\"
871 .SS glibc Hardware capabilities (from glibc 2.33)
872 .TP
873 .\" The initial discussion on various pitfalls of the old scheme is
874 .\" <https://sourceware.org/pipermail/libc-alpha/2020-May/113757.html>
875 .\" and the patchset that proposes the glibc-hwcap support is
876 .\" <https://sourceware.org/pipermail/libc-alpha/2020-June/115250.html>
877 glibc 2.33 added a new hardware capability scheme,
878 where under each CPU architecture,
879 certain levels can be defined,
880 grouping support for certain features or special instructions.
881 Each architecture level has
882 a fixed set of paths that it adds to the dynamic linker search list,
883 depending on the hardware of the machine.
884 Since each new architecture level is
885 not combined with previously existing ones,
886 the new scheme does not have the drawback of
887 growing the dynamic linker search list uncontrollably.
888 .P
889 For instance, on x86 64-bit,
890 if the hardware supports
891 .B x86_64-v3
892 (for instance Intel Haswell or AMD Excavator),
893 the resulting search path will be
894 .B glibc-hwcaps/x86-64-v3:glibc-hwcaps/x86-64-v2:.
895 .\" The x86_64 architectures levels are defined the official ABI:
896 .\" <https://gitlab.com/x86-psABIs/x86-64-ABI/-/blob/master/x86-64-ABI/low-level-sys-info.tex>
897 .\" The PowerPC and s390x are glibc defined ones based on chip
898 .\" support (which maps to ISA levels).
899 The following paths are currently supported, in priority order.
900 .TP
901 .B PowerPC (64-bit little-endian only)
902 power10, power9
903 .TP
904 .B s390 (64-bit only)
905 z16, z15, z14, z13
906 .TP
907 .B x86 (64-bit only)
908 x86-64-v4, x86-64-v3, x86-64-v2
909 .P
910 glibc 2.37 removed support for the legacy hardware capabilities.
911 .\"
912 .SH SEE ALSO
913 .BR ld (1),
914 .BR ldd (1),
915 .BR pldd (1),
916 .BR sprof (1),
917 .BR dlopen (3),
918 .BR getauxval (3),
919 .BR elf (5),
920 .BR capabilities (7),
921 .BR rtld\-audit (7),
922 .BR ldconfig (8),
923 .BR sln (8)
924 .\" .SH AUTHORS
925 .\" ld.so: David Engel, Eric Youngdale, Peter MacDonald, Hongjiu Lu, Linus
926 .\" Torvalds, Lars Wirzenius and Mitch D'Souza
927 .\" ld\-linux.so: Roland McGrath, Ulrich Drepper and others.
928 .\"
929 .\" In the above, (libc5) stands for David Engel's ld.so/ld\-linux.so.