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