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