| .\" %%%LICENSE_START(PUBLIC_DOMAIN) |
| .\" This is in the public domain |
| .\" %%%LICENSE_END |
| .\" |
| .TH LD.SO 8 2017-03-13 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| ld.so, ld-linux.so* \- dynamic linker/loader |
| .SH SYNOPSIS |
| The dynamic linker can be run either indirectly by running some |
| dynamically linked program or shared object |
| (in which case no command-line options |
| to the dynamic linker can be passed and, in the ELF case, the dynamic linker |
| which is stored in the |
| .B .interp |
| section of the program is executed) or directly by running: |
| .P |
| .I /lib/ld-linux.so.* |
| [OPTIONS] [PROGRAM [ARGUMENTS]] |
| .SH DESCRIPTION |
| The programs |
| .B ld.so |
| and |
| .B ld-linux.so* |
| find and load the shared objects (shared libraries) needed by a program, |
| prepare the program to run, and then run it. |
| .LP |
| Linux binaries require dynamic linking (linking at run time) |
| unless the |
| .B \-static |
| option was given to |
| .BR ld (1) |
| during compilation. |
| .LP |
| The program |
| .B ld.so |
| handles a.out binaries, a format used long ago; |
| .B ld-linux.so* |
| (\fI/lib/ld-linux.so.1\fP for libc5, \fI/lib/ld-linux.so.2\fP for glibc2) |
| handles ELF, |
| which everybody has been using for years now. |
| Otherwise, both have the same behavior, and use the same |
| support files and programs |
| .BR ldd (1), |
| .BR ldconfig (8), |
| and |
| .IR /etc/ld.so.conf . |
| .LP |
| When resolving shared object dependencies, |
| the dynamic linker first inspects each dependency |
| string to see if it contains a slash (this can occur if |
| a shared object pathname containing slashes was specified at link time). |
| If a slash is found, then the dependency string is interpreted as |
| a (relative or absolute) pathname, |
| and the shared object is loaded using that pathname. |
| .LP |
| If a shared object dependency does not contain a slash, |
| then it is searched for in the following order: |
| .IP o 3 |
| Using the directories specified in the |
| DT_RPATH dynamic section attribute |
| of the binary if present and DT_RUNPATH attribute does not exist. |
| Use of DT_RPATH is deprecated. |
| .IP o |
| Using the environment variable |
| .BR LD_LIBRARY_PATH |
| (unless the executable is being run in secure-execution mode; see below). |
| in which case it is ignored. |
| .IP o |
| Using the directories specified in the |
| DT_RUNPATH dynamic section attribute |
| of the binary if present. |
| .IP o |
| From the cache file |
| .IR /etc/ld.so.cache , |
| which contains a compiled list of candidate shared objects previously found |
| in the augmented library path. |
| If, however, the binary was linked with the |
| .B \-z nodeflib |
| linker option, shared objects in the default paths are skipped. |
| Shared objects installed in hardware capability directories (see below) |
| are preferred to other shared objects. |
| .IP o |
| In the default path |
| .IR /lib , |
| and then |
| .IR /usr/lib . |
| (On some 64-bit architectures, the default paths for 64-bit shared objects are |
| .IR /lib64 , |
| and then |
| .IR /usr/lib64 .) |
| If the binary was linked with the |
| .B \-z nodeflib |
| linker option, this step is skipped. |
| .SS Rpath token expansion |
| .PP |
| .B ld.so |
| understands certain strings in an rpath specification (DT_RPATH or DT_RUNPATH); those strings are substituted as follows |
| .TP |
| .IR $ORIGIN " (or equivalently " ${ORIGIN} ) |
| This expands to |
| the directory containing the program or shared object. |
| Thus, an application located in |
| .I somedir/app |
| could be compiled with |
| |
| gcc \-Wl,\-rpath,\(aq$ORIGIN/../lib\(aq |
| |
| so that it finds an associated shared object in |
| .I somedir/lib |
| no matter where |
| .I somedir |
| is located in the directory hierarchy. |
| This facilitates the creation of "turn-key" applications that |
| do not need to be installed into special directories, |
| but can instead be unpacked into any directory |
| and still find their own shared objects. |
| .TP |
| .IR $LIB " (or equivalently " ${LIB} ) |
| This expands to |
| .I lib |
| or |
| .I lib64 |
| depending on the architecture |
| (e.g., on x86-64, it expands to |
| .IR lib64 |
| and |
| on x86-32, it expands to |
| .IR lib ). |
| .TP |
| .IR $PLATFORM " (or equivalently " ${PLATFORM} ) |
| This expands to a string corresponding to the processor type |
| of the host system (e.g., "x86_64"). |
| On some architectures, the Linux kernel doesn't provide a platform |
| string to the dynamic linker. |
| The value of this string is taken from the |
| .BR AT_PLATFORM |
| value in the auxiliary vector (see |
| .BR getauxval (3)). |
| .\" To get an idea of the places that $PLATFORM would match, |
| .\" look at the output of the following: |
| .\" |
| .\" mkdir /tmp/d |
| .\" LD_LIBRARY_PATH=/tmp/d strace -e open /bin/date 2>&1 | grep /tmp/d |
| .\" |
| .\" ld.so lets names be abbreviated, so $O will work for $ORIGIN; |
| .\" Don't do this!! |
| .SH OPTIONS |
| .TP |
| .B \-\-list |
| List all dependencies and how they are resolved. |
| .TP |
| .B \-\-verify |
| Verify that program is dynamically linked and this dynamic linker can handle |
| it. |
| .TP |
| .B \-\-inhibit-cache |
| Do not use |
| .IR /etc/ld.so.cache . |
| .TP |
| .BI \-\-library\-path " path" |
| Use |
| .I path |
| instead of |
| .B LD_LIBRARY_PATH |
| environment variable setting (see below). |
| The names |
| .IR ORIGIN , |
| .IR LIB , |
| and |
| .IR PLATFORM |
| are interpreted as for the |
| .BR LD_LIBRARY_PATH |
| environment variable. |
| .TP |
| .BI \-\-inhibit\-rpath " list" |
| Ignore RPATH and RUNPATH information in object names in |
| .IR list . |
| This option is ignored when running in secure-execution mode (see below). |
| .TP |
| .BI \-\-audit " list" |
| Use objects named in |
| .I list |
| as auditors. |
| .SH ENVIRONMENT |
| Various environment variables influence the operation of the dynamic linker. |
| .\" |
| .SS Secure-execution mode |
| For security reasons, |
| the effects of some environment variables are voided or modified if |
| the dynamic linker determines that the binary should be |
| run in secure-execution mode. |
| This determination is made by checking whether the |
| .B AT_SECURE |
| entry in the auxiliary vector (see |
| .BR getauxval (3)) |
| has a nonzero value. |
| This entry may have a nonzero value for various reasons, including: |
| .IP * 3 |
| The process's real and effective user IDs differ, |
| or the real and effective group IDs differ. |
| This typically occurs as a result of executing |
| a set-user-ID or set-group-ID program. |
| .IP * |
| A process with a non-root user ID executed a binary that |
| conferred permitted or effective capabilities. |
| .IP * |
| A nonzero value may have been set by a Linux Security Module. |
| .\" |
| .SS Environment variables |
| Among the more important environment variables are the following: |
| .TP |
| .BR LD_ASSUME_KERNEL " (since glibc 2.2.3)" |
| Each shared object can inform the dynamic linker of the minimum kernel ABI |
| version that it requires. |
| (This requirement is encoded in an ELF note section that is viewable via |
| .IR "readelf\ \-n" |
| as a section labeled |
| .BR NT_GNU_ABI_TAG .) |
| At run time, |
| the dynamic linker determines the ABI version of the running kernel and |
| will reject loading shared objects that specify minimum ABI versions |
| that exceed that ABI version. |
| |
| .BR LD_ASSUME_KERNEL |
| can be used to |
| cause the dynamic linker to assume that it is running on a system with |
| a different kernel ABI version. |
| For example, the following command line causes the |
| dynamic linker to assume it is running on Linux 2.2.5 when loading |
| the shared objects required by |
| .IR myprog : |
| |
| .in +4n |
| .nf |
| $ \fBLD_ASSUME_KERNEL=2.2.5 ./myprog\fP |
| .fi |
| .in |
| |
| On systems that provide multiple versions of a shared object |
| (in different directories in the search path) that have |
| different minimum kernel ABI version requirements, |
| .BR LD_ASSUME_KERNEL |
| can be used to select the version of the object that is used |
| (dependent on the directory search order). |
| Historically, the most common use of the |
| .BR LD_ASSUME_KERNEL |
| feature was to manually select the older |
| LinuxThreads POSIX threads implementation on systems that provided both |
| LinuxThreads and NPTL |
| (which latter was typically the default on such systems); |
| see |
| .BR pthreads (7). |
| .TP |
| .BR LD_BIND_NOW " (since glibc 2.1.1)" |
| If set to a nonempty string, |
| causes the dynamic linker to resolve all symbols |
| at program startup instead of deferring function call resolution to the point |
| when they are first referenced. |
| This is useful when using a debugger. |
| .TP |
| .B LD_LIBRARY_PATH |
| A list of directories in which to search for |
| ELF libraries at execution-time. |
| The items in the list are separated by either colons or semicolons. |
| Similar to the |
| .B PATH |
| environment variable. |
| This variable is ignored in secure-execution mode. |
| |
| Within the pathnames specified in |
| .BR LD_LIBRARY_PATH , |
| the dynamic linker expands the strings |
| .IR $ORIGIN , |
| .IR $LIB , |
| and |
| .IR $PLATFORM |
| (or the versions using curly braces around the names) |
| as described above in |
| .IR "Rpath token expansion" . |
| Thus, for example, |
| the following would cause a library to be searched for in either the |
| .I lib |
| or |
| .I lib64 |
| subdirectory below the directory containing the program to be executed: |
| |
| $ \fBLD_LIBRARY_PATH='$ORIGIN/$LIB' prog\fP |
| |
| (Note the use of single quotes, which prevent expansion of |
| .I ORIGIN |
| and |
| .I LIB |
| as shell variables!) |
| .TP |
| .B LD_PRELOAD |
| A list of additional, user-specified, ELF shared |
| objects to be loaded before all others. |
| The items of the list can be separated by spaces or colons. |
| This can be used to selectively override functions in other shared objects. |
| The objects are searched for using the rules given under DESCRIPTION. |
| |
| In secure-execution mode, |
| preload pathnames containing slashes are ignored, |
| and only shared objects in the standard search directories that |
| have the set-user-ID mode bit enabled are loaded. |
| |
| Within the names specified in the |
| .BR LD_PRELOAD |
| list, the dynamic linker understands the strings |
| .IR $ORIGIN , |
| .IR $LIB , |
| and |
| .IR $PLATFORM |
| (or the versions using curly braces around the names) |
| as described above in |
| .IR "Rpath token expansion" . |
| .\" Tested with the following: |
| .\" |
| .\" LD_PRELOAD='$LIB/libmod.so' LD_LIBRARY_PATH=. ./prog |
| .\" |
| .\" which will reload the libmod.so in 'lib' or 'lib64', using it |
| .\" in preference to the version in '.'. |
| .TP |
| .BR LD_TRACE_LOADED_OBJECTS |
| If set (to any value), causes the program to list its dynamic |
| dependencies, as if run by |
| .BR ldd (1), |
| instead of running normally. |
| .LP |
| Then there are lots of more or less obscure variables, |
| many obsolete or only for internal use. |
| .TP |
| .BR LD_AUDIT " (since glibc 2.4)" |
| A colon-separated list of user-specified, ELF shared objects |
| to be loaded before all others in a separate linker namespace |
| (i.e., one that does not intrude upon the normal symbol bindings that |
| would occur in the process). |
| These objects can be used to audit the operation of the dynamic linker. |
| .B LD_AUDIT |
| is ignored in secure-execution mode. |
| |
| The dynamic linker will notify the audit |
| shared objects at so-called auditing checkpoints\(emfor example, |
| loading a new shared object, resolving a symbol, |
| or calling a symbol from another shared object\(emby |
| calling an appropriate function within the audit shared object. |
| For details, see |
| .BR rtld-audit (7). |
| The auditing interface is largely compatible with that provided on Solaris, |
| as described in its |
| .IR "Linker and Libraries Guide" , |
| in the chapter |
| .IR "Runtime Linker Auditing Interface" . |
| |
| Within the names specified in the |
| .BR LD_AUDIT |
| list, the dynamic linker understands the strings |
| .IR $ORIGIN , |
| .IR $LIB , |
| and |
| .IR $PLATFORM |
| (or the versions using curly braces around the names) |
| as described above in |
| .IR "Rpath token expansion" . |
| |
| Since glibc 2.13, |
| .\" commit 8e9f92e9d5d7737afdacf79b76d98c4c42980508 |
| in secure-execution mode, |
| names in the audit list that contain slashes are ignored, |
| and only shared objects in the standard search directories that |
| have the set-user-ID mode bit enabled are loaded. |
| .TP |
| .BR LD_BIND_NOT " (since glibc 2.1.95)" |
| If this environment variable is set to a nonempty string, |
| do not update the GOT (global offset table) and PLT (procedure linkage table) |
| after resolving a function symbol. |
| By combining the use of this variable with |
| .BR LD_DEBUG |
| (with the categories |
| .IR bindings |
| and |
| .IR symbols ), |
| one can observe all run-time function bindings. |
| .TP |
| .BR LD_DEBUG " (since glibc 2.1)" |
| Output verbose debugging information about the dynamic linker. |
| If set to |
| .BR all , |
| print all debugging information, |
| Setting this variable to |
| .BR help |
| does not run the specified program, |
| and displays a help message about which categories can be specified in this |
| environment variable. |
| The categories are: |
| .RS |
| .TP 12 |
| .I bindings |
| Display information about which definition each symbol is bound to. |
| .TP |
| .I files |
| Display progress for input file. |
| .TP |
| .I libs |
| Display library search paths. |
| .TP |
| .I reloc |
| Display relocation processing. |
| .TP |
| .I scopes |
| Display scope information. |
| .TP |
| .I statistics |
| Display relocation statistics. |
| .TP |
| .I symbols |
| Display search paths for each symbol look-up. |
| .TP |
| .I unused |
| Determine unused DSOs. |
| .TP |
| .I versions |
| Display version dependencies. |
| .RE |
| .IP |
| The value in |
| .BR LD_DEBUG |
| can specify multiple categories, separated by colons, commas, |
| or (if the value is quoted) spaces. |
| |
| Since glibc 2.3.4, |
| .B LD_DEBUG |
| is ignored in secure-execution mode, unless the file |
| .IR /etc/suid\-debug |
| exists (the content of the file is irrelevant). |
| .TP |
| .BR LD_DEBUG_OUTPUT " (since glibc 2.1)" |
| File in which |
| .B LD_DEBUG |
| output should be written. |
| The default is standard error. |
| .B LD_DEBUG_OUTPUT |
| is ignored in secure-execution mode. |
| .TP |
| .BR LD_DYNAMIC_WEAK " (since glibc 2.1.91)" |
| If this environment variable is defined (with any value), |
| allow weak symbols to be overridden (reverting to old glibc behavior). |
| .\" See weak handling |
| .\" https://www.sourceware.org/ml/libc-hacker/2000-06/msg00029.html |
| .\" To: GNU libc hacker <libc-hacker at sourceware dot cygnus dot com> |
| .\" Subject: weak handling |
| .\" From: Ulrich Drepper <drepper at redhat dot com> |
| .\" Date: 07 Jun 2000 20:08:12 -0700 |
| .\" Reply-To: drepper at cygnus dot com (Ulrich Drepper) |
| Since glibc 2.3.4, |
| .B LD_DYNAMIC_WEAK |
| is ignored in secure-execution mode. |
| .TP |
| .BR LD_HWCAP_MASK " (since glibc 2.1)" |
| Mask for hardware capabilities. |
| .TP |
| .BR LD_ORIGIN_PATH " (since glibc 2.1)" |
| Path where the binary is found. |
| Since glibc 2.4, |
| .B LD_ORIGIN_PATH |
| is ignored in secure-execution mode. |
| .\" Used only if $ORIGIN can't be determined by normal means |
| .\" (from the origin path saved at load time, or from /proc/self/exe)? |
| .TP |
| .BR LD_POINTER_GUARD " (glibc from 2.4 to 2.22)" |
| Set to 0 to disable pointer guarding. |
| Any other value enables pointer guarding, which is also the default. |
| Pointer guarding is a security mechanism whereby some pointers to code |
| stored in writable program memory (return addresses saved by |
| .BR setjmp (3) |
| or function pointers used by various glibc internals) are mangled |
| semi-randomly to make it more difficult for an attacker to hijack |
| the pointers for use in the event of a buffer overrun or |
| stack-smashing attack. |
| Since glibc 2.23, |
| .\" commit a014cecd82b71b70a6a843e250e06b541ad524f7 |
| .B LD_POINTER_GUARD |
| can no longer be used to disable pointer guarding, |
| which is now always enabled. |
| .TP |
| .BR LD_PROFILE " (since glibc 2.1)" |
| The name of a (single) shared object to be profiled, |
| specified either as a pathname or a soname. |
| Profiling output is appended to the file whose name is: |
| "\fI$LD_PROFILE_OUTPUT\fP/\fI$LD_PROFILE\fP.profile". |
| .TP |
| .BR LD_PROFILE_OUTPUT " (since glibc 2.1)" |
| Directory where |
| .B LD_PROFILE |
| output should be written. |
| If this variable is not defined, or is defined as an empty string, |
| then the default is |
| .IR /var/tmp . |
| .B LD_PROFILE_OUTPUT |
| is ignored in secure-execution mode; instead |
| .IR /var/profile |
| is always used. |
| .TP |
| .BR LD_SHOW_AUXV " (since glibc 2.1)" |
| If this environment variable is defined (with any value), |
| show the auxiliary array passed up from the kernel (see also |
| .BR getauxval (3)). |
| Since glibc 2.3.5, |
| .B LD_SHOW_AUXV |
| is ignored in secure-execution mode. |
| .TP |
| .BR LD_TRACE_PRELINKING " (since glibc 2.4)" |
| If this environment variable is defined, |
| trace prelinking of the object whose name is assigned to |
| this environment variable. |
| (Use |
| .BR ldd (1) |
| to get a list of the objects that might be traced.) |
| If the object name is not recognized, |
| .\" (This is what seems to happen, from experimenting) |
| then all prelinking activity is traced. |
| .TP |
| .BR LD_USE_LOAD_BIAS " (since glibc 2.3.3)" |
| .\" http://sources.redhat.com/ml/libc-hacker/2003-11/msg00127.html |
| .\" Subject: [PATCH] Support LD_USE_LOAD_BIAS |
| .\" Jakub Jelinek |
| By default (i.e., if this variable is not defined), |
| executables and prelinked |
| shared objects will honor base addresses of their dependent shared objects |
| and (nonprelinked) position-independent executables (PIEs) |
| and other shared objects will not honor them. |
| If |
| .B LD_USE_LOAD_BIAS |
| is defined with the value 1, both executables and PIEs |
| will honor the base addresses. |
| If |
| .B LD_USE_LOAD_BIAS |
| is defined with the value 0, |
| neither executables nor PIEs will honor the base addresses. |
| This variable is ignored in secure-execution mode. |
| .TP |
| .BR LD_VERBOSE " (since glibc 2.1)" |
| If set to a nonempty string, |
| output symbol versioning information about the |
| program if the |
| .B LD_TRACE_LOADED_OBJECTS |
| environment variable has been set. |
| .TP |
| .BR LD_WARN " (since glibc 2.1.3) |
| If set to a nonempty string, warn about unresolved symbols. |
| .TP |
| .BR LD_PREFER_MAP_32BIT_EXEC " (x86-64 only; since glibc 2.23)" |
| According to the Intel Silvermont software optimization guide, for 64-bit |
| applications, branch prediction performance can be negatively impacted |
| when the target of a branch is more than 4GB away from the branch. |
| If this environment variable is set (to any value), |
| .BR ld.so |
| will first try to map executable pages using the |
| .BR mmap (2) |
| .BR MAP_32BIT |
| flag, and fall back to mapping without that flag if that attempt fails. |
| NB: MAP_32BIT will map to the low 2GB (not 4GB) of the address space. |
| Because |
| .B MAP_32BIT |
| reduces the address range available for address space layout |
| randomization (ASLR), |
| .B LD_PREFER_MAP_32BIT_EXEC |
| is always disabled in secure-execution mode. |
| .SH FILES |
| .PD 0 |
| .TP |
| .I /lib/ld.so |
| a.out dynamic linker/loader |
| .TP |
| .IR /lib/ld\-linux.so. { 1 , 2 } |
| ELF dynamic linker/loader |
| .TP |
| .I /etc/ld.so.cache |
| File containing a compiled list of directories in which to search for |
| shared objects and an ordered list of candidate shared objects. |
| .TP |
| .I /etc/ld.so.preload |
| File containing a whitespace-separated list of ELF shared objects to |
| be loaded before the program. |
| .TP |
| .B lib*.so* |
| shared objects |
| .PD |
| .SH NOTES |
| .SS Hardware capabilities |
| Some shared objects are compiled using hardware-specific instructions which do |
| not exist on every CPU. |
| Such objects should be installed in directories whose names define the |
| required hardware capabilities, such as |
| .IR /usr/lib/sse2/ . |
| The dynamic linker checks these directories against the hardware of the |
| machine and selects the most suitable version of a given shared object. |
| Hardware capability directories can be cascaded to combine CPU features. |
| The list of supported hardware capability names depends on the CPU. |
| The following names are currently recognized: |
| .TP |
| .B Alpha |
| ev4, ev5, ev56, ev6, ev67 |
| .TP |
| .B MIPS |
| loongson2e, loongson2f, octeon, octeon2 |
| .TP |
| .B PowerPC |
| 4xxmac, altivec, arch_2_05, arch_2_06, booke, cellbe, dfp, efpdouble, efpsingle, |
| fpu, ic_snoop, mmu, notb, pa6t, power4, power5, power5+, power6x, ppc32, ppc601, |
| ppc64, smt, spe, ucache, vsx |
| .TP |
| .B SPARC |
| flush, muldiv, stbar, swap, ultra3, v9, v9v, v9v2 |
| .TP |
| .B s390 |
| dfp, eimm, esan3, etf3enh, g5, highgprs, hpage, ldisp, msa, stfle, |
| z900, z990, z9-109, z10, zarch |
| .TP |
| .B x86 (32-bit only) |
| acpi, apic, clflush, cmov, cx8, dts, fxsr, ht, i386, i486, i586, i686, mca, mmx, |
| mtrr, pat, pbe, pge, pn, pse36, sep, ss, sse, sse2, tm |
| .SH SEE ALSO |
| .BR ld (1), |
| .BR ldd (1), |
| .BR pldd (1), |
| .BR sprof (1), |
| .BR dlopen (3), |
| .BR getauxval (3), |
| .BR capabilities (7), |
| .BR rtld-audit (7), |
| .BR ldconfig (8), |
| .BR sln (8) |
| .\" .SH AUTHORS |
| .\" ld.so: David Engel, Eric Youngdale, Peter MacDonald, Hongjiu Lu, Linus |
| .\" Torvalds, Lars Wirzenius and Mitch D'Souza |
| .\" ld-linux.so: Roland McGrath, Ulrich Drepper and others. |
| .\" |
| .\" In the above, (libc5) stands for David Engel's ld.so/ld-linux.so. |