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