1LD.SO(8)                   Linux Programmer's Manual                  LD.SO(8)
2
3
4

NAME

6       ld.so, ld-linux.so - dynamic linker/loader
7

SYNOPSIS

9       The dynamic linker can be run either indirectly by running some dynami‐
10       cally linked program or shared object (in which  case  no  command-line
11       options  to  the dynamic linker can be passed and, in the ELF case, the
12       dynamic linker which is stored in the .interp section of the program is
13       executed) or directly by running:
14
15       /lib/ld-linux.so.*  [OPTIONS] [PROGRAM [ARGUMENTS]]
16

DESCRIPTION

18       The  programs  ld.so  and ld-linux.so* find and load the shared objects
19       (shared libraries) needed by a program, prepare the program to run, and
20       then run it.
21
22       Linux binaries require dynamic linking (linking at run time) unless the
23       -static option was given to ld(1) during compilation.
24
25       The program ld.so handles a.out  binaries,  a  format  used  long  ago;
26       ld-linux.so*  (/lib/ld-linux.so.1  for  libc5,  /lib/ld-linux.so.2  for
27       glibc2) handles ELF, which everybody has  been  using  for  years  now.
28       Otherwise,  both have the same behavior, and use the same support files
29       and programs as ldd(1), ldconfig(8), and /etc/ld.so.conf.
30
31       When resolving shared object dependencies,  the  dynamic  linker  first
32       inspects each dependency string to see if it contains a slash (this can
33       occur if a shared object pathname containing slashes was  specified  at
34       link  time).  If a slash is found, then the dependency string is inter‐
35       preted as a (relative or absolute) pathname, and the shared  object  is
36       loaded using that pathname.
37
38       If  a  shared  object  dependency  does not contain a slash, then it is
39       searched for in the following order:
40
41       o  Using the directories specified  in  the  DT_RPATH  dynamic  section
42          attribute of the binary if present and DT_RUNPATH attribute does not
43          exist.  Use of DT_RPATH is deprecated.
44
45       o  Using the environment  variable  LD_LIBRARY_PATH,  unless  the  exe‐
46          cutable  is being run in secure-execution mode (see below), in which
47          case this variable is ignored.
48
49       o  Using the directories specified in the  DT_RUNPATH  dynamic  section
50          attribute  of  the binary if present.  Such directories are searched
51          only to find those objects required by DT_NEEDED  (direct  dependen‐
52          cies)  entries  and  do  not apply to those objects' children, which
53          must themselves have their own DT_RUNPATH entries.  This  is  unlike
54          DT_RPATH,  which  is  applied  to  searches  for all children in the
55          dependency tree.
56
57       o  From the cache file /etc/ld.so.cache, which contains a compiled list
58          of  candidate  shared  objects  previously  found  in  the augmented
59          library path.  If, however, the binary was linked with the -z  node‐
60          flib linker option, shared objects in the default paths are skipped.
61          Shared objects installed in  hardware  capability  directories  (see
62          below) are preferred to other shared objects.
63
64       o  In the default path /lib, and then /usr/lib.  (On some 64-bit archi‐
65          tectures, the default paths for 64-bit shared  objects  are  /lib64,
66          and then /usr/lib64.)  If the binary was linked with the -z nodeflib
67          linker option, this step is skipped.
68
69   Rpath token expansion
70       The dynamic linker understands certain token strings in an rpath speci‐
71       fication  (DT_RPATH  or  DT_RUNPATH).  Those strings are substituted as
72       follows:
73
74       $ORIGIN (or equivalently ${ORIGIN})
75              This expands to the directory containing the program  or  shared
76              object.   Thus,  an  application located in somedir/app could be
77              compiled with
78
79                  gcc -Wl,-rpath,'$ORIGIN/../lib'
80
81              so that it finds an associated shared object in  somedir/lib  no
82              matter  where  somedir  is  located  in the directory hierarchy.
83              This facilitates the creation of "turn-key" applications that do
84              not  need  to  be  installed  into  special directories, but can
85              instead be unpacked into any directory and still find their  own
86              shared objects.
87
88       $LIB (or equivalently ${LIB})
89              This  expands  to  lib  or  lib64  depending on the architecture
90              (e.g., on x86-64, it expands to lib64 and on x86-32, it  expands
91              to lib).
92
93       $PLATFORM (or equivalently ${PLATFORM})
94              This  expands to a string corresponding to the processor type of
95              the host system (e.g., "x86_64").  On  some  architectures,  the
96              Linux  kernel  doesn't  provide a platform string to the dynamic
97              linker.  The value of this string is taken from the  AT_PLATFORM
98              value in the auxiliary vector (see getauxval(3)).
99

OPTIONS

101       --list List all dependencies and how they are resolved.
102
103       --verify
104              Verify  that  program  is  dynamically  linked  and this dynamic
105              linker can handle it.
106
107       --inhibit-cache
108              Do not use /etc/ld.so.cache.
109
110       --library-path path
111              Use path instead of LD_LIBRARY_PATH environment variable setting
112              (see  below).   The  names  ORIGIN, LIB, and PLATFORM are inter‐
113              preted as for the LD_LIBRARY_PATH environment variable.
114
115       --inhibit-rpath list
116              Ignore RPATH and RUNPATH information in object  names  in  list.
117              This  option  is  ignored  when running in secure-execution mode
118              (see below).
119
120       --audit list
121              Use objects named in list as auditors.
122

ENVIRONMENT

124       Various environment variables influence the operation  of  the  dynamic
125       linker.
126
127   Secure-execution mode
128       For  security  reasons,  the  effects of some environment variables are
129       voided or modified if the dynamic linker  determines  that  the  binary
130       should  be run in secure-execution mode.  (For details, see the discus‐
131       sion of individual environment variables below.)  A binary is  executed
132       in secure-execution mode if the AT_SECURE entry in the auxiliary vector
133       (see getauxval(3)) has a nonzero value.  This entry may have a  nonzero
134       value for various reasons, including:
135
136       *  The  process's  real  and effective user IDs differ, or the real and
137          effective group IDs differ.  This typically occurs as  a  result  of
138          executing a set-user-ID or set-group-ID program.
139
140       *  A  process  with a non-root user ID executed a binary that conferred
141          capabilities to the process.
142
143       *  A nonzero value may have been set by a Linux Security Module.
144
145   Environment variables
146       Among the more important environment variables are the following:
147
148       LD_ASSUME_KERNEL (since glibc 2.2.3)
149              Each shared object can inform the dynamic linker of the  minimum
150              kernel  ABI  version  that  it  requires.   (This requirement is
151              encoded in an ELF note section that is viewable  via  readelf -n
152              as  a section labeled NT_GNU_ABI_TAG.)  At run time, the dynamic
153              linker determines the ABI version of the running kernel and will
154              reject  loading shared objects that specify minimum ABI versions
155              that exceed that ABI version.
156
157              LD_ASSUME_KERNEL can be used to  cause  the  dynamic  linker  to
158              assume  that  it  is running on a system with a different kernel
159              ABI version.  For example, the following command line causes the
160              dynamic linker to assume it is running on Linux 2.2.5 when load‐
161              ing the shared objects required by myprog:
162
163                  $ LD_ASSUME_KERNEL=2.2.5 ./myprog
164
165              On systems that provide multiple versions of a shared object (in
166              different  directories  in  the search path) that have different
167              minimum kernel ABI version requirements, LD_ASSUME_KERNEL can be
168              used to select the version of the object that is used (dependent
169              on the directory search order).
170
171              Historically, the most common use of the  LD_ASSUME_KERNEL  fea‐
172              ture was to manually select the older LinuxThreads POSIX threads
173              implementation on systems that provided  both  LinuxThreads  and
174              NPTL  (which  latter was typically the default on such systems);
175              see pthreads(7).
176
177       LD_BIND_NOW (since glibc 2.1.1)
178              If set to a  nonempty  string,  causes  the  dynamic  linker  to
179              resolve  all  symbols  at  program  startup instead of deferring
180              function call resolution to the point when they are first refer‐
181              enced.  This is useful when using a debugger.
182
183       LD_LIBRARY_PATH
184              A  list  of  directories in which to search for ELF libraries at
185              execution time.  The items in the list are separated  by  either
186              colons  or  semicolons,  and  there  is  no support for escaping
187              either separator.
188
189              This variable is ignored in secure-execution mode.
190
191              Within the pathnames specified in LD_LIBRARY_PATH,  the  dynamic
192              linker  expands  the tokens $ORIGIN, $LIB, and $PLATFORM (or the
193              versions using curly braces around the names) as described above
194              in  Rpath  token  expansion.   Thus,  for example, the following
195              would cause a library to be searched for in either  the  lib  or
196              lib64 subdirectory below the directory containing the program to
197              be executed:
198
199                  $ LD_LIBRARY_PATH='$ORIGIN/$LIB' prog
200
201              (Note the use of single quotes, which prevent expansion of $ORI‐
202              GIN and $LIB as shell variables!)
203
204       LD_PRELOAD
205              A  list  of additional, user-specified, ELF shared objects to be
206              loaded before all others.  The items of the list  can  be  sepa‐
207              rated  by spaces or colons, and there is no support for escaping
208              either separator.  This can  be  used  to  selectively  override
209              functions in other shared objects.  The objects are searched for
210              using the rules given under DESCRIPTION.
211
212              In secure-execution mode, preload pathnames  containing  slashes
213              are  ignored.   Furthermore,  shared  objects are preloaded only
214              from the standard search directories and only if they have  set-
215              user-ID mode bit enabled (which is not typical).
216
217              Within  the  names specified in the LD_PRELOAD list, the dynamic
218              linker understands the tokens $ORIGIN, $LIB, and  $PLATFORM  (or
219              the  versions  using curly braces around the names) as described
220              above in Rpath token expansion.  (See  also  the  discussion  of
221              quoting under the description of LD_LIBRARY_PATH.)
222
223       LD_TRACE_LOADED_OBJECTS
224              If  set  (to  any value), causes the program to list its dynamic
225              dependencies, as if run by ldd(1), instead of running normally.
226
227       Then there are lots of more or less obscure variables, many obsolete or
228       only for internal use.
229
230       LD_AUDIT (since glibc 2.4)
231              A  colon-separated list of user-specified, ELF shared objects to
232              be loaded before all  others  in  a  separate  linker  namespace
233              (i.e., one that does not intrude upon the normal symbol bindings
234              that would occur in the process) and there  is  no  support  for
235              escaping  the separator.  These objects can be used to audit the
236              operation of the dynamic linker.
237
238              LD_AUDIT is ignored in secure-execution mode.
239
240              The dynamic linker will notify the audit shared objects  at  so-
241              called  auditing  checkpoints—for  example, loading a new shared
242              object, resolving a symbol, or calling  a  symbol  from  another
243              shared  object—by  calling  an  appropriate  function within the
244              audit shared  object.   For  details,  see  rtld-audit(7).   The
245              auditing  interface  is largely compatible with that provided on
246              Solaris, as described in its Linker and Libraries Guide, in  the
247              chapter Runtime Linker Auditing Interface.
248
249              Within  the  names  specified  in the LD_AUDIT list, the dynamic
250              linker understands the tokens $ORIGIN, $LIB, and  $PLATFORM  (or
251              the  versions  using curly braces around the names) as described
252              above in Rpath token expansion.  (See  also  the  discussion  of
253              quoting under the description of LD_LIBRARY_PATH.)
254
255              Since  glibc  2.13, in secure-execution mode, names in the audit
256              list that contain slashes are ignored, and only  shared  objects
257              in  the  standard  search  directories that have the set-user-ID
258              mode bit enabled are loaded.
259
260       LD_BIND_NOT (since glibc 2.1.95)
261              If this environment variable is set to a nonempty string, do not
262              update  the GOT (global offset table) and PLT (procedure linkage
263              table) after resolving a function symbol.  By combining the  use
264              of this variable with LD_DEBUG (with the categories bindings and
265              symbols), one can observe all run-time function bindings.
266
267       LD_DEBUG (since glibc 2.1)
268              Output verbose debugging  information  about  operation  of  the
269              dynamic  linker.  The content of this variable is one of more of
270              the following categories, separated by colons,  commas,  or  (if
271              the value is quoted) spaces:
272
273              help        Specifying  help  in the value of this variable does
274                          not run the specified program, and displays  a  help
275                          message  about  which categories can be specified in
276                          this environment variable.
277
278              all         Print all debugging information  (except  statistics
279                          and unused; see below).
280
281              bindings    Display information about which definition each sym‐
282                          bol is bound to.
283
284              files       Display progress for input file.
285
286              libs        Display library search paths.
287
288              reloc       Display relocation processing.
289
290              scopes      Display scope information.
291
292              statistics  Display relocation statistics.
293
294              symbols     Display search paths for each symbol look-up.
295
296              unused      Determine unused DSOs.
297
298              versions    Display version dependencies.
299
300              Since glibc 2.3.4, LD_DEBUG is ignored in secure-execution mode,
301              unless  the file /etc/suid-debug exists (the content of the file
302              is irrelevant).
303
304       LD_DEBUG_OUTPUT (since glibc 2.1)
305              By default, LD_DEBUG output is written to  standard  error.   If
306              LD_DEBUG_OUTPUT  is defined, then output is written to the path‐
307              name specified by its value, with the suffix "." (dot)  followed
308              by the process ID appended to the pathname.
309
310              LD_DEBUG_OUTPUT is ignored in secure-execution mode.
311
312       LD_DYNAMIC_WEAK (since glibc 2.1.91)
313              By  default, when searching shared libraries to resolve a symbol
314              reference, the dynamic linker will resolve to the first  defini‐
315              tion it finds.
316
317              Old  glibc versions (before 2.2), provided a different behavior:
318              if the linker found a symbol that was weak,  it  would  remember
319              that   symbol   and  keep  searching  in  the  remaining  shared
320              libraries.  If it subsequently found a strong definition of  the
321              same  symbol, then it would instead use that definition.  (If no
322              further symbol was found, then the dynamic linker would use  the
323              weak symbol that it initially found.)
324
325              The  old  glibc behavior was nonstandard.  (Standard practice is
326              that the distinction between weak and strong symbols should have
327              effect  only  at  static  link time.)  In glibc 2.2, the dynamic
328              linker was modified to provide the current behavior  (which  was
329              the  behavior that was provided by most other implementations at
330              that time).
331
332              Defining the  LD_DYNAMIC_WEAK  environment  variable  (with  any
333              value)  provides the old (nonstandard) glibc behavior, whereby a
334              weak symbol in one shared library may be overridden by a  strong
335              symbol subsequently discovered in another shared library.  (Note
336              that even when this variable is set, a strong symbol in a shared
337              library  will  not override a weak definition of the same symbol
338              in the main program.)
339
340              Since glibc 2.3.4, LD_DYNAMIC_WEAK is ignored  in  secure-execu‐
341              tion mode.
342
343       LD_HWCAP_MASK (since glibc 2.1)
344              Mask for hardware capabilities.
345
346       LD_ORIGIN_PATH (since glibc 2.1)
347              Path where the binary is found.
348
349              Since  glibc  2.4, LD_ORIGIN_PATH is ignored in secure-execution
350              mode.
351
352       LD_POINTER_GUARD (glibc from 2.4 to 2.22)
353              Set to 0 to disable pointer guarding.  Any other  value  enables
354              pointer  guarding,  which is also the default.  Pointer guarding
355              is a security mechanism whereby some pointers to code stored  in
356              writable  program memory (return addresses saved by setjmp(3) or
357              function pointers used by various glibc internals)  are  mangled
358              semi-randomly  to  make  it  more  difficult  for an attacker to
359              hijack the pointers for use in the event of a buffer overrun  or
360              stack-smashing  attack.   Since glibc 2.23, LD_POINTER_GUARD can
361              no longer be used to disable  pointer  guarding,  which  is  now
362              always enabled.
363
364       LD_PROFILE (since glibc 2.1)
365              The  name  of a (single) shared object to be profiled, specified
366              either as a pathname or a soname.  Profiling output is  appended
367              to  the file whose name is: "$LD_PROFILE_OUTPUT/$LD_PROFILE.pro‐
368              file".
369
370              Since glibc 2.2.5, LD_PROFILE  is  ignored  in  secure-execution
371              mode.
372
373       LD_PROFILE_OUTPUT (since glibc 2.1)
374              Directory  where  LD_PROFILE  output should be written.  If this
375              variable is not defined, or is defined as an empty string,  then
376              the default is /var/tmp.
377
378              LD_PROFILE_OUTPUT  is  ignored in secure-execution mode; instead
379              /var/profile is always used.   (This  detail  is  relevant  only
380              before glibc 2.2.5, since in later glibc versions, LD_PROFILE is
381              also ignored in secure-execution mode.)
382
383       LD_SHOW_AUXV (since glibc 2.1)
384              If this environment variable is defined (with any  value),  show
385              the  auxiliary array passed up from the kernel (see also getaux‐
386              val(3)).
387
388              Since glibc 2.3.4, LD_SHOW_AUXV is ignored  in  secure-execution
389              mode.
390
391       LD_TRACE_PRELINKING (since glibc 2.4)
392              If this environment variable is defined, trace prelinking of the
393              object whose name is  assigned  to  this  environment  variable.
394              (Use  ldd(1) to get a list of the objects that might be traced.)
395              If the object name is not recognized, then all prelinking activ‐
396              ity is traced.
397
398       LD_USE_LOAD_BIAS (since glibc 2.3.3)
399              By  default (i.e., if this variable is not defined), executables
400              and prelinked shared objects will honor base addresses of  their
401              dependent shared objects and (nonprelinked) position-independent
402              executables (PIEs) and other shared objects will not honor them.
403              If  LD_USE_LOAD_BIAS  is defined with the value 1, both executa‐
404              bles   and   PIEs   will   honor   the   base   addresses.    If
405              LD_USE_LOAD_BIAS  is  defined with the value 0, neither executa‐
406              bles nor PIEs will honor the base addresses.
407
408              Since glibc 2.3.3, this variable is ignored in  secure-execution
409              mode.
410
411       LD_VERBOSE (since glibc 2.1)
412              If  set  to a nonempty string, output symbol versioning informa‐
413              tion about the program if the  LD_TRACE_LOADED_OBJECTS  environ‐
414              ment variable has been set.
415
416       LD_WARN (since glibc 2.1.3)
417              If set to a nonempty string, warn about unresolved symbols.
418
419       LD_PREFER_MAP_32BIT_EXEC (x86-64 only; since glibc 2.23)
420              According  to  the Intel Silvermont software optimization guide,
421              for 64-bit applications, branch prediction  performance  can  be
422              negatively  impacted  when  the  target of a branch is more than
423              4 GB away from the branch.  If this environment variable is  set
424              (to  any  value),  the dynamic linker will first try to map exe‐
425              cutable pages using the mmap(2) MAP_32BIT flag, and fall back to
426              mapping  without that flag if that attempt fails.  NB: MAP_32BIT
427              will map to the low 2 GB (not 4 GB) of the address space.
428
429              Because  MAP_32BIT  reduces  the  address  range  available  for
430              address    space    layout    randomization    (ASLR),   LD_PRE‐
431              FER_MAP_32BIT_EXEC is always disabled in secure-execution mode.
432

FILES

434       /lib/ld.so
435              a.out dynamic linker/loader
436       /lib/ld-linux.so.{1,2}
437              ELF dynamic linker/loader
438       /etc/ld.so.cache
439              File containing a compiled  list  of  directories  in  which  to
440              search  for  shared  objects  and  an  ordered list of candidate
441              shared objects.  See ldconfig(8).
442       /etc/ld.so.preload
443              File  containing  a  whitespace-separated  list  of  ELF  shared
444              objects  to be loaded before the program.  See the discussion of
445              LD_PRELOAD above.  If both LD_PRELOAD and /etc/ld.so.preload are
446              employed,  the  libraries  specified by LD_PRELOAD are preloaded
447              first.  /etc/ld.so.preload has a system-wide effect, causing the
448              specified  libraries  to  be preloaded for all programs that are
449              executed on the system.  (This is usually  undesirable,  and  is
450              typically  employed only as an emergency remedy, for example, as
451              a temporary workaround to a library misconfiguration issue.)
452       lib*.so*
453              shared objects
454

NOTES

456   Hardware capabilities
457       Some shared objects are compiled using  hardware-specific  instructions
458       which  do  not exist on every CPU.  Such objects should be installed in
459       directories whose names define the required hardware capabilities, such
460       as /usr/lib/sse2/.  The dynamic linker checks these directories against
461       the hardware of the machine and selects the most suitable version of  a
462       given  shared  object.  Hardware capability directories can be cascaded
463       to combine CPU features.  The list  of  supported  hardware  capability
464       names  depends  on  the  CPU.  The following names are currently recog‐
465       nized:
466
467       Alpha  ev4, ev5, ev56, ev6, ev67
468
469       MIPS   loongson2e, loongson2f, octeon, octeon2
470
471       PowerPC
472              4xxmac, altivec, arch_2_05, arch_2_06, booke, cellbe, dfp,  efp‐
473              double,  efpsingle,  fpu,  ic_snoop,  mmu,  notb,  pa6t, power4,
474              power5,  power5+,  power6x,  ppc32,  ppc601,  ppc64,  smt,  spe,
475              ucache, vsx
476
477       SPARC  flush, muldiv, stbar, swap, ultra3, v9, v9v, v9v2
478
479       s390   dfp,  eimm,  esan3,  etf3enh,  g5,  highgprs, hpage, ldisp, msa,
480              stfle, z900, z990, z9-109, z10, zarch
481
482       x86 (32-bit only)
483              acpi, apic, clflush, cmov, cx8, dts, fxsr, ht, i386, i486, i586,
484              i686,  mca,  mmx,  mtrr, pat, pbe, pge, pn, pse36, sep, ss, sse,
485              sse2, tm
486

SEE ALSO

488       ld(1), ldd(1),  pldd(1),  sprof(1),  dlopen(3),  getauxval(3),  elf(5),
489       capabilities(7), rtld-audit(7), ldconfig(8), sln(8)
490

COLOPHON

492       This  page  is  part of release 4.16 of the Linux man-pages project.  A
493       description of the project, information about reporting bugs,  and  the
494       latest     version     of     this    page,    can    be    found    at
495       https://www.kernel.org/doc/man-pages/.
496
497
498
499GNU                               2018-04-30                          LD.SO(8)
Impressum