1ld.so(8)                    System Manager'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  binary  format  used  long
26       ago.    The   program   ld-linux.so*   (/lib/ld-linux.so.1  for  libc5,
27       /lib/ld-linux.so.2 for glibc2) handles binaries that are  in  the  more
28       modern  ELF  format.  Both programs have the same behavior, and use the
29       same   support   files   and   programs   (ldd(1),   ldconfig(8),   and
30       /etc/ld.so.conf).
31
32       When resolving shared object dependencies, the dynamic linker first in‐
33       spects each dependency string to see if it contains a slash  (this  can
34       occur  if  a shared object pathname containing slashes was specified at
35       link time).  If a slash is found, then the dependency string is  inter‐
36       preted  as  a (relative or absolute) pathname, and the shared object is
37       loaded using that pathname.
38
39       If a shared object dependency does not contain  a  slash,  then  it  is
40       searched for in the following order:
41
42       (1)  Using  the  directories  specified in the DT_RPATH dynamic section
43            attribute of the binary if present and DT_RUNPATH  attribute  does
44            not exist.  Use of DT_RPATH is deprecated.
45
46       (2)  Using  the  environment  variable LD_LIBRARY_PATH, unless the exe‐
47            cutable is being run in  secure-execution  mode  (see  below),  in
48            which case this variable is ignored.
49
50       (3)  Using  the directories specified in the DT_RUNPATH dynamic section
51            attribute of the binary if present.  Such directories are searched
52            only to find those objects required by DT_NEEDED (direct dependen‐
53            cies) entries and do not apply to those objects'  children,  which
54            must themselves have their own DT_RUNPATH entries.  This is unlike
55            DT_RPATH, which is applied to searches for all children in the de‐
56            pendency tree.
57
58       (4)  From  the  cache  file /etc/ld.so.cache, which contains a compiled
59            list of candidate shared objects previously found in the augmented
60            library  path.   If,  however,  the  binary was linked with the -z
61            nodeflib linker option, shared objects in the  default  paths  are
62            skipped.  Shared objects installed in hardware capability directo‐
63            ries (see below) are preferred to other shared objects.
64
65       (5)  In the default path /lib, and then /usr/lib.  (On some 64-bit  ar‐
66            chitectures,  the  default  paths  for  64-bit  shared objects are
67            /lib64, and then /usr/lib64.)  If the binary was linked  with  the
68            -z nodeflib linker option, this step is skipped.
69
70   Dynamic string tokens
71       In several places, the dynamic linker expands dynamic string tokens:
72
73       •  In the environment variables LD_LIBRARY_PATH, LD_PRELOAD, and LD_AU‐
74          DIT,
75
76       •  inside the values of the dynamic section tags  DT_NEEDED,  DT_RPATH,
77          DT_RUNPATH, DT_AUDIT, and DT_DEPAUDIT of ELF binaries,
78
79       •  in  the  arguments  to the ld.so command line options --audit, --li‐
80          brary-path, and --preload (see below), and
81
82       •  in the filename arguments to the dlopen(3) and dlmopen(3) functions.
83
84       The substituted tokens are as follows:
85
86       $ORIGIN (or equivalently ${ORIGIN})
87              This expands to the directory containing the program  or  shared
88              object.   Thus,  an  application located in somedir/app could be
89              compiled with
90
91                  gcc -Wl,-rpath,'$ORIGIN/../lib'
92
93              so that it finds an associated shared object in  somedir/lib  no
94              matter  where  somedir  is  located  in the directory hierarchy.
95              This facilitates the creation of "turn-key" applications that do
96              not  need  to be installed into special directories, but can in‐
97              stead be unpacked into any directory and still  find  their  own
98              shared objects.
99
100       $LIB (or equivalently ${LIB})
101              This  expands  to  lib  or  lib64  depending on the architecture
102              (e.g., on x86-64, it expands to lib64 and on x86-32, it  expands
103              to lib).
104
105       $PLATFORM (or equivalently ${PLATFORM})
106              This  expands to a string corresponding to the processor type of
107              the host system (e.g., "x86_64").  On  some  architectures,  the
108              Linux  kernel  doesn't  provide a platform string to the dynamic
109              linker.  The value of this string is taken from the  AT_PLATFORM
110              value in the auxiliary vector (see getauxval(3)).
111
112       Note that the dynamic string tokens have to be quoted properly when set
113       from a shell, to prevent their expansion as shell or environment  vari‐
114       ables.
115

OPTIONS

117       --argv0 string (since glibc 2.33)
118              Set argv[0] to the value string before running the program.
119
120       --audit list
121              Use  objects named in list as auditors.  The objects in list are
122              delimited by colons.
123
124       --inhibit-cache
125              Do not use /etc/ld.so.cache.
126
127       --library-path path
128              Use path instead of LD_LIBRARY_PATH environment variable setting
129              (see  below).   The  names  ORIGIN, LIB, and PLATFORM are inter‐
130              preted as for the LD_LIBRARY_PATH environment variable.
131
132       --inhibit-rpath list
133              Ignore RPATH and RUNPATH information in object  names  in  list.
134              This  option  is  ignored  when running in secure-execution mode
135              (see below).  The objects in list are  delimited  by  colons  or
136              spaces.
137
138       --list List all dependencies and how they are resolved.
139
140       --list-tunables (since glibc 2.33)
141              Print the names and values of all tunables, along with the mini‐
142              mum and maximum allowed values.
143
144       --preload list (since glibc 2.30)
145              Preload the objects specified in list.  The objects in list  are
146              delimited by colons or spaces.  The objects are preloaded as ex‐
147              plained in the description of the LD_PRELOAD  environment  vari‐
148              able below.
149
150              By contrast with LD_PRELOAD, the --preload option provides a way
151              to perform preloading for a single executable without  affecting
152              preloading  performed  in  any child process that executes a new
153              program.
154
155       --verify
156              Verify that program  is  dynamically  linked  and  this  dynamic
157              linker can handle it.
158

ENVIRONMENT

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

FILES

491       /lib/ld.so
492              a.out dynamic linker/loader
493
494       /lib/ld-linux.so.{1,2}
495              ELF dynamic linker/loader
496
497       /etc/ld.so.cache
498              File containing a compiled  list  of  directories  in  which  to
499              search  for  shared  objects  and  an  ordered list of candidate
500              shared objects.  See ldconfig(8).
501
502       /etc/ld.so.preload
503              File containing a whitespace-separated list of  ELF  shared  ob‐
504              jects  to  be  loaded before the program.  See the discussion of
505              LD_PRELOAD above.  If both LD_PRELOAD and /etc/ld.so.preload are
506              employed,  the  libraries  specified by LD_PRELOAD are preloaded
507              first.  /etc/ld.so.preload has a system-wide effect, causing the
508              specified  libraries  to  be preloaded for all programs that are
509              executed on the system.  (This is usually  undesirable,  and  is
510              typically  employed only as an emergency remedy, for example, as
511              a temporary workaround to a library misconfiguration issue.)
512
513       lib*.so*
514              shared objects
515

NOTES

517   Hardware capabilities
518       Some shared objects are compiled using  hardware-specific  instructions
519       which  do  not exist on every CPU.  Such objects should be installed in
520       directories whose names define the required hardware capabilities, such
521       as /usr/lib/sse2/.  The dynamic linker checks these directories against
522       the hardware of the machine and selects the most suitable version of  a
523       given  shared  object.  Hardware capability directories can be cascaded
524       to combine CPU features.  The list  of  supported  hardware  capability
525       names  depends  on  the  CPU.  The following names are currently recog‐
526       nized:
527
528       Alpha  ev4, ev5, ev56, ev6, ev67
529
530       MIPS   loongson2e, loongson2f, octeon, octeon2
531
532       PowerPC
533              4xxmac, altivec, arch_2_05, arch_2_06, booke, cellbe, dfp,  efp‐
534              double,  efpsingle,  fpu,  ic_snoop,  mmu,  notb,  pa6t, power4,
535              power5,  power5+,  power6x,  ppc32,  ppc601,  ppc64,  smt,  spe,
536              ucache, vsx
537
538       SPARC  flush, muldiv, stbar, swap, ultra3, v9, v9v, v9v2
539
540       s390   dfp,  eimm,  esan3,  etf3enh,  g5,  highgprs, hpage, ldisp, msa,
541              stfle, z900, z990, z9-109, z10, zarch
542
543       x86 (32-bit only)
544              acpi, apic, clflush, cmov, cx8, dts, fxsr, ht, i386, i486, i586,
545              i686,  mca,  mmx,  mtrr, pat, pbe, pge, pn, pse36, sep, ss, sse,
546              sse2, tm
547

SEE ALSO

549       ld(1), ldd(1), pldd(1), sprof(1), dlopen(3), getauxval(3), elf(5),  ca‐
550       pabilities(7), rtld-audit(7), ldconfig(8), sln(8)
551
552
553
554Linux man-pages 6.04              2023-02-05                          ld.so(8)
Impressum