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