1ld.so.1(1) User Commands ld.so.1(1)
2
3
4
6 ld.so.1 - runtime linker for dynamic objects
7
9 /lib/ld.so.1
10
11
12 /lib/ld.so.1 [-e envar] dynamic-object [object args]...
13
14
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
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
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
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
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
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
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
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)