1ld.so.1(1)                       User Commands                      ld.so.1(1)
2
3
4

NAME

6       ld.so.1 - runtime linker for dynamic objects
7

SYNOPSIS

9       /lib/ld.so.1
10
11
12       /lib/ld.so.1 [-e envar] dynamic-object [object args]...
13
14

DESCRIPTION

16       Dynamic  applications consist of one or more dynamic objects. A dynamic
17       application is typically a dynamic executable and one  or  more  shared
18       object  dependencies.  As part of the initialization and execution of a
19       dynamic application, an interpreter is called.  This  interpreter  com‐
20       pletes  the  binding  of the application to its shared object dependen‐
21       cies. In Solaris, this  interpreter  is  referred  to  as  the  runtime
22       linker.
23
24
25       During the link-editing of a dynamic executable, a special .interp sec‐
26       tion, together with an associated program header, is created. This sec‐
27       tion  contains  a  path  name  specifying the program's interpreter. An
28       interpreter path name can be specified  when  the  executable  is  con‐
29       structed  using  the  -I  option to ld(1), the link-editor. The default
30       name supplied by the link-editor is the name  of  the  runtime  linker,
31       ld.so.1.
32
33
34       During  the  process of executing a dynamic executable, the kernel maps
35       the file,  and  locates  the  required  interpreter.  See  exec(2)  and
36       mmapobj(2).  The  kernel maps in, and transfers control to, this inter‐
37       preter. Sufficient information is passed to the  interpretor  to  allow
38       the interpreter to continue to bind, and then execute the application.
39
40
41       In addition to initializing an application, the runtime linker provides
42       services that allow the application to extend its address space.  Addi‐
43       tional  shared  objects  can  be  mapped, and symbols within the shared
44       objects can be bound to.
45
46
47       The runtime linker performs the following functions:
48
49           o      A configuration file, if in existence, is processed. Config‐
50                  uration files can be employed to alter default search paths,
51                  provide a directory cache, and  provide  alternative  object
52                  dependencies.  See  crle(1). By default, for 32-bit objects,
53                  the configuration file /var/ld/ld.config is used. For 64-bit
54                  objects, the default configuration file /var/ld/64/ld.config
55                  is used. Alternative configuration files  can  be  specified
56                  with the LD_CONFIG environment variable. Alternative config‐
57                  uration files can also be  encoded  within  a  dynamic  exe‐
58                  cutable by using the -c option of ld(1).
59
60           o      The runtime linker analyzes the application's dynamic infor‐
61                  mation section, .dynamic, to determine which  shared  object
62                  dependencies are required.
63
64           o      The  runtime linker then locates and maps in these dependen‐
65                  cies. The dynamic information section of each dependency  is
66                  then  analyzed  to  determine if any additional dependencies
67                  are required.
68
69           o      Once all the shared object dependencies are loaded, the run‐
70                  time  linker performs any necessary relocations. These relo‐
71                  cations bind the shared objects in preparation  for  process
72                  execution.
73
74           o      Any  initialization  functions provided by the shared object
75                  dependencies and, possibly, by the  dynamic  executable  are
76                  called. The functions are called in the reverse order of the
77                  topologically sorted dependencies.  If  cyclic  dependencies
78                  exist,  the  initialization  functions  are called using the
79                  sorted order with the cycle removed. ldd(1) can be  used  to
80                  display  the initialization order of shared object dependen‐
81                  cies.
82
83           o      Control is passed to the application.
84
85           o      During the application's execution, the runtime  linker  can
86                  be called upon to perform any delayed function binding.
87
88           o      If  any  shared objects are deleted from the process, final‐
89                  ization functions are called. By  default,  these  functions
90                  are  called  in the order of the topologically sorted depen‐
91                  dencies.
92
93           o      The application can also call upon the services of the  run‐
94                  time  linker  to  acquire additional shared objects by using
95                  dlopen(3C). Symbols provided by these objects, can be  bound
96                  to using dlsym(3C).
97
98
99       Further  details  on  each  of  the previous topics can be found in the
100       Linker and Libraries Guide.
101
102
103       The runtime linker uses a  prescribed  search  path  for  locating  the
104       dynamic  dependencies  of  an  object. The default search paths are the
105       runpath recorded in the object, followed by a series of  defaults.  For
106       32-bit  objects, the defaults are /lib followed by /usr/lib. For 64-bit
107       objects, the  defaults  are  /lib/64  followed  by  /usr/lib/64.  These
108       defaults  component  can be modified using a configuration file that is
109       created with crle(1). The runpath is specified when the dynamic  object
110       is  constructed  using the -R option to ld(1). The environment variable
111       LD_LIBRARY_PATH can be used to  indicate  directories  to  be  searched
112       before the default directories.
113
114   Command Line Usage
115       Typically, the runtime linker is invoked indirectly through executing a
116       dynamic executable that declares the runtime linker as its interpreter.
117       The runtime linker can also be executed directly from the command line.
118       This mechanism is most often employed to experiment with new  implemen‐
119       tations  of the runtime linker. Arguments that are supplied on the com‐
120       mand line consist of options that are applicable to the runtime linker.
121       Following  these  options  is the name of the dynamic object to be exe‐
122       cuted, and any options required by this object. Effectively,  the  run‐
123       time linker replaces any interpreter specified by the dynamic object.
124
125
126       The following option is supported:
127
128       -e envar     Specify  a  runtime  linker specific environment variable.
129                    See ENVIRONMENT VARIABLES.
130
131

ENVIRONMENT VARIABLES

133       Each environment variable can be specified with a _32  or  _64  suffix.
134       This  makes  the environment variable specific, respectively, to 32-bit
135       or 64-bit processes. This environment variable overrides  any  non-suf‐
136       fixed  version  of  the  environment  variable that might be in effect.
137       Environment variables specified without a value, that have a _32 or _64
138       suffix,  effectively cancel any associated generic environment variable
139       setting.
140
141       LD_AUDIT, LD_AUDIT_32, and LD_AUDIT_64
142
143           A colon-separated list of objects that are loaded  by  the  runtime
144           linker.  As each object is loaded, the object is examined for Link-
145           Auditing interface routines. The  routines  that  are  present  are
146           called as specified in the Link-Auditing interface described in the
147           Linker and Libraries Guide. Also, see the  -p  and  -P  options  of
148           ld(1).
149
150
151       LD_BIND_LAZY, LD_BIND_LAZY_32, and LD_BIND_LAZY_64
152
153           The runtime linker's default mode of performing lazy binding can be
154           enforced by setting the environment variable  LD_BIND_LAZY  to  any
155           non-null  value.  This setting causes the runtime linker to perform
156           only lazy reference relocations for all  objects  that  are  loaded
157           into  the  process. Individual objects can request that lazy refer‐
158           ence relocations are performed when the object is loaded.  See  the
159           -z now option of ld(1), and dlopen(3C) with the mode RTLD_NOW. Such
160           requests to perform lazy reference relocations are suppressed  when
161           LD_BIND_LAZY is in effect.
162
163           If   both   LD_BIND_LAZY   and   LD_BIND_NOW  are  specified,  then
164           LD_BIND_NOW takes precedence.
165
166
167       LD_BIND_NOW, LD_BIND_NOW_32, and LD_BIND_NOW_64
168
169           The runtime linker's default mode of performing lazy binding can be
170           overridden  by  setting the environment variable LD_BIND_NOW to any
171           non-null value. This setting causes the runtime linker  to  perform
172           both  immediate  reference  and  lazy reference relocations for all
173           objects that are loaded into the process.  Individual  objects  can
174           request  that  lazy  reference  relocations  are performed when the
175           object is loaded. See the -z now option of  ld(1),  and  dlopen(3C)
176           with the mode RTLD_NOW.
177
178           If   both   LD_BIND_NOW   and   LD_BIND_LAZY  are  specified,  then
179           LD_BIND_NOW takes precedence.
180
181
182       LD_CONFIG, LD_CONFIG_32, and LD_CONFIG_64
183
184           Provides an alternative configuration file. Configuration files can
185           be  employed  to  alter  default  search paths, provide a directory
186           cache, and provide alternate object dependencies. See crle(1).
187
188
189       LD_DEBUG, LD_DEBUG_32, and LD_DEBUG_64
190
191           Provides a comma, or colon-separated list of tokens  to  cause  the
192           runtime  linker  to  print debugging information to standard error.
193           The special token help indicates the full list of tokens available.
194           The  environment  variable  LD_DEBUG_OUTPUT can also be supplied to
195           specify a file to which the  debugging  information  is  sent.  The
196           filename  is suffixed with the process ID of the application gener‐
197           ating the debugging information. See lari(1).
198
199
200       LD_DEMANGLE, LD_DEMANGLE_32, and LD_DEMANGLE_64
201
202           Any symbol name used as part of a diagnostic message  is  shown  as
203           defined within an ELF file. When LD_DEMANGLE is set to any non-null
204           value, the runtime linker attempts to  decode  (demangle)  any  C++
205           symbol name.
206
207
208       LD_FLAGS, LD_FLAGS_32, and LD_FLAGS_64
209
210           Provides  an  alternative  means  of supplying environment variable
211           information. Any of the LD_XXX environment variables can be  speci‐
212           fied  as  a xxx token. Multiple tokens can be supplied separated by
213           commas. See EXAMPLES.
214
215
216       LD_LIBRARY_PATH, LD_LIBRARY_PATH_32, and LD_LIBRARY_PATH_64
217
218           The LD_LIBRARY_PATH  environment  variable,  if  set,  is  used  to
219           enhance  the  search  path  that  the  runtime  linker uses to find
220           dynamic dependencies. LD_LIBRARY_PATH specifies  a  colon-separated
221           list  of  directories that are searched before the default directo‐
222           ries. Also notice that LD_LIBRARY_PATH adds additional semantics to
223           ld(1).
224
225
226       LD_LOADFLTR, LD_LOADFLTR_32, and LD_LOADFLTR_64
227
228           Filters  are  a form of shared object. Filters allow an alternative
229           shared object to be selected at runtime that provide the  implemen‐
230           tation  for any symbols that are defined within the filter. See the
231           -f and -F options of ld(1).  By  default,  the  alternative  shared
232           object  processing  is  deferred  until  symbol  resolution  occurs
233           against the filter. When LD_LOADFLTR is set to any non-null  value,
234           any  filters  are  processed immediately when the filter is loaded.
235           Also, see the -z loadfltr option of ld(1).
236
237
238       LD_NOAUDIT, LD_NOAUDIT_32, and LD_NOAUDIT_64
239
240           Local auditing libraries can be  defined  within  applications  and
241           shared objects. See the -p and -P options of ld(1). When LD_NOAUDIT
242           is set to any non-null value, the runtime linker ignores any  local
243           auditing libraries.
244
245
246       LD_NOAUXFLTR, LD_NOAUXFLTR_32, and LD_NOAUXFLTR_64
247
248           Auxiliary  filters  are  a form of shared object. Auxiliary filters
249           allow an alternative shared object to be selected at runtime  which
250           provides the implementation for any symbols that are defined within
251           the filter. See the -f option of ld(1). When LD_NOAUXFLTR is set to
252           any  non-null  value,  the runtime linker disables this alternative
253           shared object lookup.
254
255
256       LD_NOCONFIG, LD_NOCONFIG_32, and LD_NOCONFIG_64
257
258           By default the runtime linker attempts to open and process  a  con‐
259           figuration file. When LD_NOCONFIG is set to any non-null value, the
260           runtime linker disables this configuration file processing.
261
262
263       LD_NODIRCONFIG, LD_NODIRCONFIG_32, and LD_NODIRCONFIG_64
264
265           Provides a subset of LD_NOCONFIG in that any directory cache infor‐
266           mation provided in a configuration file is ignored.
267
268
269       LD_NODIRECT, LD_NODIRECT_32, and LD_NODIRECT_64
270
271           Direct  binding  information instructs the runtime linker to search
272           directly for a symbol in an associated object. See  the  -B  direct
273           option  of  ld(1).  Without  direct binding, the symbol search per‐
274           formed by the  runtime  linker  follows  the  default  model.  When
275           LD_NODIRECT  is  set  to  any  non-null  value,  the runtime linker
276           ignores any direct binding information.
277
278
279       LD_NOENVCONFIG, LD_NOENVCONFIG_32, and LD_NOENVCONFIG_64
280
281           Provides a subset of LD_NOCONFIG in that any environment  variables
282           provided in a configuration file are ignored.
283
284
285       LD_NOLAZYLOAD, LD_NOLAZYLOAD_32, and LD_NOLAZYLOAD_64
286
287           Dependencies  that are labeled for lazy loading are not loaded into
288           memory until explicit reference to the dependency  has  been  made.
289           See  the  -z lazyload option of ld(1). When LD_NOLAZYLOAD is set to
290           any non-null value, the runtime linker ignores a dependencies  lazy
291           loading label and loads the dependency immediately.
292
293
294       LD_NOOBJALTER, LD_NOOBJALTER_32, and LD_NOOBJALTER_64
295
296           Provides  a  subset  of  LD_NOCONFIG in that any alternative object
297           dependencies provided in a configuration file are ignored.
298
299
300       LD_NOVERSION, LD_NOVERSION_32, and LD_NOVERSION_64
301
302           By default, the runtime linker verifies  version  dependencies  for
303           the  primary executable and all of its dependencies. When LD_NOVER‐
304           SION is set to any non-null value, the runtime linker disables this
305           version checking.
306
307
308       LD_ORIGIN, LD_ORIGIN_32, and LD_ORIGIN_64
309
310           The immediate processing of $ORIGIN can be triggered by setting the
311           environment  variable  LD_ORIGIN  to  any  non-null  value.  Before
312           Solaris  9,  this  option  was useful for applications that invoked
313           chdir(2) prior to locating dependencies that employed  the  $ORIGIN
314           string token. The establishment of the current working directory by
315           the runtime linker is now default thus making  this  option  redun‐
316           dant.
317
318
319       LD_PRELOAD, LD_PRELOAD_32, and LD_PRELOAD_64
320
321           Provides  a  list  of  shared  objects,  separated by spaces. These
322           objects are loaded after the program being executed but before  any
323           other  shared  objects  that the program references. Symbol defini‐
324           tions provided by the preloaded  objects  interpose  on  references
325           made by the shared objects that the program references. Symbol def‐
326           initions provided by the preloaded objects do not interpose on  the
327           symbol definitions provided by the program.
328
329
330       LD_PROFILE, LD_PROFILE_32, and LD_PROFILE_64
331
332           Defines  a shared object to be profiled by the runtime linker. When
333           profiling is enabled,  a  profiling  buffer  file  is  created  and
334           mapped.  The  name  of  the  buffer  file is the name of the shared
335           object being profiled with a .profile extension. By  default,  this
336           buffer  is  placed under /var/tmp. The environment variable LD_PRO‐
337           FILE_OUTPUT can also be supplied to indicate an alternative  direc‐
338           tory in which to place the profiling buffer.
339
340           The profiling buffer contains profil(2) and call count information.
341           This information is similar to the gmon.out  information  generated
342           by  programs  that have been linked with the -xpg option of cc. Any
343           applications that use the named shared object and  run  while  this
344           environment variable is set, accumulate data in the profile buffer.
345           See also NOTES. The profile  buffer  information  can  be  examined
346           using gprof(1).
347
348           The LD_PROFILE profiling technique is an alternative to other tech‐
349           niques that might be provided by the compilation system. The shared
350           object  being profiled does not have to be instrumented in any way,
351           and LD_PROFILE should not be combined with  a  profile-instrumented
352           application.  See  the Linker and Libraries Guide for more informa‐
353           tion on profiling shared objects.
354
355
356       LD_SIGNAL, LD_SIGNAL_32, and LD_SIGNAL_64
357
358           Provides a numeric signal number that the runtime  linker  uses  to
359           kill  the  process  in  the  event  of  a  fatal runtime error. See
360           thr_kill(3C). By default, SIGKILL is used. For  example,  providing
361           the alternative signal number 6 (SIGABRT), can provide for the cre‐
362           ation of a core file to aid debugging. See also the RTLD_DI_SETSIG‐
363           NAL request to dlinfo(3C).
364
365
366
367       Notice  that  environment  variable names beginning with the characters
368       'LD_' are reserved  for  possible  future  enhancements  to  ld(1)  and
369       ld.so.1.
370

SECURITY

372       Secure  processes  have  some restrictions applied to the evaluation of
373       their dependencies and runpaths to prevent malicious dependency substi‐
374       tution or symbol interposition.
375
376
377       The  runtime linker categorizes a process as secure if the issetugid(2)
378       system call returns true for the process.
379
380
381       For 32-bit objects, the default trusted directories that are  known  to
382       the  runtime  linker  are  /lib/secure  and /usr/lib/secure. For 64-bit
383       objects,  the  default  trusted  directories  are  /lib/secure/64   and
384       /usr/lib/secure/64.  The  utility  crle(1) can be used to specify addi‐
385       tional trusted directories that are applicable for secure applications.
386       Administrators  who  use  this  technique should ensure that the target
387       directories are suitably protected from malicious intrusion.
388
389
390       If an LD_LIBRARY_PATH family environment variable is in  effect  for  a
391       secure process, only the trusted directories specified by this variable
392       are used to augment the runtime linker's search rules.
393
394
395       In a secure process, runpath components that are provided by the appli‐
396       cation or any of its dependencies are used, provided the component is a
397       full path name, that is, the path name starts with a '/'.
398
399
400       In a secure process, the expansion of the  $ORIGIN  string  is  allowed
401       only  if  the  string expands to a trusted directory. However, should a
402       $ORIGIN expansion match a directory that has already provided dependen‐
403       cies,  then  the  directory is implicitly secure. This directory can be
404       used to provide additional dependencies.
405
406
407       In a secure process, LD_CONFIG is  ignored.  However,  a  configuration
408       file  that  is  recorded  in  a  secure application is used. See the -c
409       option of ld(1). A recorded configuration file  must  be  a  full  path
410       name,  that  is, the path name starts with a '/'. A recorded configura‐
411       tion file that employs  the  $ORIGIN  string  is  restricted  to  known
412       trusted  directories. Developers who record a configuration file within
413       a secure application should ensure that the configuration  file  direc‐
414       tory  is suitably protected from malicious intrusion. In the absence of
415       a recorded configuration file, a secure process uses the  default  con‐
416       figuration file, if a configuration file exists. See crle(1).
417
418
419       In a secure process, LD_SIGNAL is ignored.
420
421
422       Additional  objects  can  be  loaded  with  a  secure process using the
423       LD_PRELOAD, or LD_AUDIT environment variables. These  objects  must  be
424       specified  as full path names or simple file names. Full path names are
425       restricted to known trusted directories. Simple file names, in which no
426       '/'  appears  in  the  name,  are  located  subject  to the search path
427       restrictions previously described. Simple file names  resolve  only  to
428       known trusted directories.
429
430
431       In  a secure process, any dependencies that consist of simple filenames
432       are processed using the path name  restrictions  previously  described.
433       Dependencies  expressed  as  full path names or relative path names are
434       used as is. Therefore, the developer of a secure process should  ensure
435       that  the  target  directory referenced as a full path name or relative
436       path name dependency is suitably protected from malicious intrusion.
437
438
439       When creating a secure process, relative path names should not be  used
440       to  express  dependencies,  or to construct dlopen(3C) path names. This
441       restriction should be applied to the application and to  all  dependen‐
442       cies.
443

EXAMPLES

445       Example 1 Using LD_FLAGS to group environment variable information
446
447
448       The  following  use of LD_FLAGS is equivalent to setting the individual
449       environment variables LD_BIND_NOW and LD_LIBRARY_PATH for 32-bit appli‐
450       cations:
451
452
453         example% LD_FLAGS_32=bind_now,library_path=/lib/one:/lib/two
454
455
456
457
458       The  following  use of LD_FLAGS is equivalent to setting the individual
459       environment variables LD_LIBRARY_PATH and LD_PRELOAD for 64-bit  appli‐
460       cations:
461
462
463         example% LD_FLAGS_64=library_path=/lib/one/64,preload=foo.so
464
465
466

FILES

468       /lib/ld.so.1
469
470           Default runtime linker.
471
472
473       /lib/libc.so.1
474
475           Alternate interpreter for SVID ABI compatibility.
476
477
478       /usr/lib/ld.so
479
480           AOUT (BCP) runtime linker.
481
482
483       /usr/lib/0@0.so.1
484
485           A  compatibility  library  to  support null character pointers. See
486           NOTES.
487
488
489       /lib/secure and /usr/lib/secure
490
491           LD_PRELOAD location for secure applications.
492
493
494       /lib/secure/64 and /usr/lib/secure/64
495
496           LD_PRELOAD location for secure 64-bit applications.
497
498
499       /lib/64/ld.so.1
500
501           Default runtime linker for 64-bit applications.
502
503
504       /usr/lib/64/0@0.so.1
505
506           A 64-bit compatibility library to support null character  pointers.
507           See NOTES.
508
509
510       /var/ld/ld.config
511
512           Default configuration file for 32-bit applications.
513
514
515       /var/ld/64/ld.config
516
517           Default configuration file for 64-bit applications.
518
519

ATTRIBUTES

521       See attributes(5) for descriptions of the following attributes:
522
523
524
525
526       ┌─────────────────────────────┬─────────────────────────────┐
527       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
528       ├─────────────────────────────┼─────────────────────────────┤
529       │Availability                 │SUNWcsu                      │
530       └─────────────────────────────┴─────────────────────────────┘
531

SEE ALSO

533       crle(1),  gprof(1),  lari(1),  ld(1),  ldd(1),  exec(2),  issetugid(2),
534       mmapobj(2),  profil(2),  dladdr(3C),  dlclose(3C),  dldump(3C),   dler‐
535       ror(3C),  dlinfo(3C),  dlopen(3C),  dlsym(3C),  thr_kill(3C),  proc(4),
536       attributes(5)
537
538
539       Linker and Libraries Guide
540

NOTES

542       Care should be exercised when  using  LD_PROFILE  in  combination  with
543       other process monitoring techniques, such as users of proc(4). Multiple
544       process monitoring techniques can result in  deadlock  conditions  that
545       leave  the  profile buffer locked. A locked buffer blocks any processes
546       that try to record profiling information. To  reduce  this  likelihood,
547       the  runtime  linker's profile implementation determines if the process
548       is being monitored at startup. If  so,  profiling  of  the  process  is
549       silently  disabled.  However,  this  mechanism can not catch monitoring
550       processes that attach to the process during its execution.
551
552
553       The user compatibility library /usr/lib/0@0.so.1 provides  a  mechanism
554       that  establishes  a  value of 0 at location 0. Some applications exist
555       that erroneously assume a null character pointer should be treated  the
556       same  as a pointer to a null string. A segmentation violation occurs in
557       these applications when a null character pointer is accessed.  If  this
558       library  is  added  to such an application at runtime using LD_PRELOAD,
559       the library provides an environment that is sympathetic to this  errant
560       behavior.  However,  the user compatibility library is intended neither
561       to enable the generation of such applications, nor to endorse this par‐
562       ticular programming practice.
563
564
565       In  many cases, the presence of /usr/lib/0@0.so.1 is benign, and it can
566       be pre-loaded into programs that do not require it. However, there  are
567       exceptions.  Some applications, such as the JVM (Java Virtual Machine),
568       require that a segmentation violation be generated from a null  pointer
569       access.   Applications   such   as   the   JVM   should   not   preload
570       /usr/lib/0@0.so.
571
572
573
574SunOS 5.11                        26 Aug 2009                       ld.so.1(1)
Impressum