Debian Codegraph @

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

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