| blob | 57165525cb0ed868d7d7b7442e1c25cc2c3d1a23 |
1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH CRLE 1 "Oct 6, 2008"
7 .SH NAME
8 crle \- configure runtime linking environment
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBcrle\fR [\fB-64\fR] [\fB-a\fR \fIname\fR] [\fB-A\fR \fIname\fR] [\fB-c\fR \fIconf\fR] [\fB-e\fR \fIenv\fR] [\fB-E\fR \fIenv\fR]
13 [\fB-f\fR \fIflags\fR] [\fB-i\fR \fIname\fR] [\fB-I\fR \fIname\fR] [\fB-g\fR \fIname\fR] [\fB-G\fR \fIname\fR]
14 [\fB-l\fR \fIdir\fR] [\fB-o\fR \fIdir\fR] [\fB-s\fR \fIdir\fR] [\fB-t\fR [ ELF | AOUT]] [\fB-u\fR] [\fB-v\fR]
15 .fi
17 .SH DESCRIPTION
18 .sp
19 .LP
20 The \fBcrle\fR utility provides for the creation and display of a runtime
21 linking configuration file. The configuration file is read and interpreted by
22 the runtime linker, \fBld.so.1\fR(1), during process startup. The runtime
23 linker attempts to read a default configuration file for all processes. For
24 32-bit processes, the default configuration file is \fB/var/ld/ld.config\fR.
25 For 64-bit processes, the default configuration file is
26 \fB/var/ld/64/ld.config\fR.
27 .sp
28 .LP
29 Without any arguments, or with just the \fB-c\fR option, \fBcrle\fR displays
30 configuration information. This information includes the contents of a
31 configuration file, any system defaults and the command-line required to
32 regenerate the configuration file. When used with any other options, a new
33 configuration file is created or updated.
34 .sp
35 .LP
36 The runtime linker can also be directed to an alternative configuration file by
37 setting one of the \fBLD_CONFIG\fR family of environment variable.
38 \fBLD_CONFIG\fR applies to both 32-bit and 64-bit programs. Since 32-bit and
39 64-bit configuration files differ, a single configuration file cannot be used
40 for both class of object. Hence, \fBLD_CONFIG\fR can adversely affect program
41 execution in cases where a program of one class executes a program of the other
42 class. In particular, it is common practice for the 32-bit version of standard
43 Solaris utilities to execute their 64-bit counterpart. \fBLD_CONFIG\fR cannot
44 be successfully used in this case. Therefore, the use of the \fBLD_CONFIG_32\fR
45 and \fBLD_CONFIG_64\fR environment variables, that precisely target the
46 appropriate class of process, is recommended.
47 .sp
48 .LP
49 Creating an incorrect configuration file in the standard location,
50 \fB/var/ld\fR, can prevent programs from running, and can therefore be
51 difficult to recover from. To guard against this situation, it is recommented
52 that new configuration files first be created in a temporary location. Then set
53 the appropriate \fBLD_CONFIG\fR environment variable to this new configuration
54 file. This setting causes the new configuration file to be used by the runtime
55 linker instead of any default. After verification, the new configuration file
56 can be moved to the default location if desired. At any time, the environment
57 variable \fBLD_NOCONFIG\fR can be set to any value to instruct the runtime
58 linker to ignore any configuration files. This setting can prove useful during
59 experimentation.
60 .sp
61 .LP
62 A configuration file can contain the following information.
63 .sp
64 .ne 2
65 .na
66 \fBDefault Search Paths\fR
67 .ad
68 .sp .6
69 .RS 4n
70 The runtime linker uses a prescribed search path for locating the dynamic
71 dependencies of an object. This search path starts with the components of any
72 \fBLD_LIBRARY_PATH\fR definition, followed by the components of an object's
73 \fBrunpath\fR. Finally, any default search paths specific to the object's class
74 are used. This last component of the search path can be expressed within the
75 configuration file. Typically, use of this facility should be augmented with
76 any system default. See the \fB-l\fR and \fB-u\fR options.
77 .RE
79 .sp
80 .ne 2
81 .na
82 \fBTrusted Directories\fR
83 .ad
84 .sp .6
85 .RS 4n
86 When processing a secure application, the runtime linker restricts the use of
87 \fBLD_LIBRARY_PATH\fR searches, and \fB$ORIGIN\fR token expansion. See
88 \fISecurity\fR in \fILinker and Libraries Guide\fR. In addition, the
89 directories from which preload and audit libraries can be located are also
90 restricted. The path names that are associated with preload and audit libraries
91 are restricted to known trusted directories. Trusted directories can be
92 expressed within the configuration file. Typically, use of this facility should
93 be augmented with any system defaults. See the \fB-s\fR and \fB-u\fR options.
94 .RE
96 .sp
97 .ne 2
98 .na
99 \fBEnvironment Variables\fR
100 .ad
101 .sp .6
102 .RS 4n
103 Any environment variable interpreted by the runtime linker can be specified
104 within the configuration file.
105 .RE
107 .sp
108 .ne 2
109 .na
110 \fBDirectory Cache\fR
111 .ad
112 .sp .6
113 .RS 4n
114 The location of shared objects within defined directories can be maintained as
115 a cache within the configuration file. This directory cache can reduce the
116 overhead of searching for application dependencies.
117 .RE
119 .sp
120 .ne 2
121 .na
122 \fBAlternative Objects\fR
123 .ad
124 .sp .6
125 .RS 4n
126 In conjunction with the directory cache, shared objects can have alternative
127 objects specified for use at runtime. These alternate objects, can be supplied
128 by the user. Alternative objects can also be created by \fBcrle\fR as copies of
129 shared objects fixed to known memory locations. These fixed alternative objects
130 can require less processing at runtime than their original shared object
131 counterpart.
132 .RE
134 .sp
135 .LP
136 Defining additional default search paths, or additional trusted directories can
137 be useful for administrators who wish to install third party software in a
138 central location, or otherwise alter the search path of applications that might
139 not have been coded with a suitable runpath.
140 .sp
141 .LP
142 The declaration of alternative objects provides a means of replacing
143 dependencies other than by using symbolic links or requiring
144 \fBLD_LIBRARY_PATH\fR settings.
145 .sp
146 .LP
147 The declaration of environment variables that are interpreted by the runtime
148 linker provides a means of centralizing their definition for all applications.
149 .sp
150 .LP
151 The directory cache, and \fBcrle\fR generated alternate objects, can provide a
152 means of reducing the runtime startup overhead of applications. Alternative
153 objects can be useful for applications that require many dependencies, or whose
154 dependencies are expensive to relocate. Shared objects that contain
155 \fBposition-dependent\fR code are often expensive to relocate. Note, the system
156 has many caching facilities that help mitigate expenses such as negative path
157 lookups, and thus employing \fBcrle\fR to create a directory cache may have
158 minimal effect other than for some very specific cases.
159 .sp
160 .LP
161 When alternate objects that are generated by \fBcrle\fR are specified within a
162 configuration file, the runtime linker performs some minimal consistency
163 verification. The alternative objects are verified against their originating
164 objects. This verification is intended to avert application failure should an
165 applications configuration information become out-of-sync with the underlying
166 system components. When this situation arises the flexibility offered by
167 dynamic linking system components can be compromised. This type of application
168 failure can be very difficult to diagnose. No verification of directory cache
169 information is performed. Any changes to the directory structure are not seen
170 by a process until the cache is rebuilt.
171 .sp
172 .LP
173 System shared objects are often well tuned, and can show little benefit from
174 being cached. The directory cache and alternative object features are typically
175 applicable to user applications and shared objects, and may only show
176 improvement in some very specific cases.
177 .sp
178 .LP
179 \fBcrle\fR creates alternate objects for the shared objects that are discovered
180 when using the \fB-I\fR and \fB-G\fR options, using \fBdldump\fR(3C). The
181 alternate object is created in the directory specified by the preceding
182 \fB-o\fR option, or defaults to the directory in which the configuration file
183 is created. The flags used by \fBdldump()\fR are specified using the \fB-f\fR
184 option, or default to \fBRTLD_REL_RELATIVE\fR.
185 .SH OPTIONS
186 .sp
187 .LP
188 The following options are supported.
189 .sp
190 .ne 2
191 .na
192 \fB\fB-64\fR\fR
193 .ad
194 .sp .6
195 .RS 4n
196 Specify to process 64-bit objects, the default is 32-bit. Use \fB-64\fR to
197 create a 64-bit specific configuration file.
198 .RE
200 .sp
201 .ne 2
202 .na
203 \fB\fB-a\fR \fIname\fR\fR
204 .ad
205 .sp .6
206 .RS 4n
207 Create an alternative path name for \fIname\fR. The alternative path name is
208 added to the configuration file.
209 .sp
210 The actual alternative file must be supplied by the user. Multiple occurrences
211 of this option are permitted. If \fIname\fR is a directory, each shared object
212 within the directory is added to the cache. If \fIname\fR does not exist, then
213 \fIname\fR is marked in the cache as a nonexistent file.
214 .sp
215 Typically, this option is used with the \fB-o\fR option.
216 .RE
218 .sp
219 .ne 2
220 .na
221 \fB\fB-A\fR \fIname\fR\fR
222 .ad
223 .sp .6
224 .RS 4n
225 Create an optional alternative path name for \fIname\fR. This alternative path
226 name is added to the configuration file.
227 .sp
228 This option mimics the \fB-a\fR option, except that if the alternative is
229 unavailable at runtime, the original object \fIname\fR is used. This model
230 mimics the use of auxiliary filters. See \fIGenerating Auxiliary Filters\fR in
231 \fILinker and Libraries Guide\fR.
232 .sp
233 Typically, this option is used with the \fB-o\fR option.
234 .RE
236 .sp
237 .ne 2
238 .na
239 \fB\fB-c\fR \fIconf\fR\fR
240 .ad
241 .sp .6
242 .RS 4n
243 Specify to use the configuration file name \fIconf\fR. If this option is not
244 supplied, the default configuration file is used.
245 .RE
247 .sp
248 .ne 2
249 .na
250 \fB\fB-e\fR \fIenv\fR\fR
251 .ad
252 .sp .6
253 .RS 4n
254 Specify a \fBreplaceable\fR environment variable, \fIenv\fR. Only environment
255 variables that are applicable to the runtime linker are meaningful. Multiple
256 occurrences of this option are permitted. This option is similar to the
257 \fB-E\fR option. However, the options differs in how configuration file
258 definitions, and process environment definitions of the same name are resolved
259 at runtime.
260 .sp
261 A definition established in a configuration file can be \fBoverridden\fR by a
262 process environment definition, or be \fBsuppressed\fR by a null-value process
263 environment definition.
264 .sp
265 In other words, these configuration file definitions can be replaced, or
266 removed by the process environment at runtime.
267 .RE
269 .sp
270 .ne 2
271 .na
272 \fB\fB-E\fR \fIenv\fR\fR
273 .ad
274 .sp .6
275 .RS 4n
276 Specify a \fBpermanent\fR environment variable, \fIenv\fR. Only environment
277 variables that are applicable to the runtime linker are meaningful. Multiple
278 occurrences of this option are permitted. This option is similar to the
279 \fB-e\fR option. However, the option differs in how configuration file
280 definitions, and process environment definitions of the same name are resolved
281 at runtime.
282 .sp
283 Environment variable definitions that are meaningful to the runtime linker fall
284 into one of two categories. Singular definitions are definitions such as
285 \fBLD_NOLAZYLOAD=1\fR and \fBLD_DEBUG_OUTPUT=\fR\fIfile\fR. List definitions,
286 which can take one or more values, are definitions such as
287 \fBLD_LIBRARY_PATH=\fR\fIpath\fR, and \fBLD_DEBUG=\fR\fIfiles\fR,\fIdetails\fR.
288 .sp
289 A singular definition that is established in a configuration file takes
290 precedence over a process environment definition. A list definition that is
291 established in a configuration file is \fBappended\fR to a process environment
292 definition. Any definition that is established in a configuration file can
293 \fBnot\fR be suppressed by a null-value process environment definition.
294 .sp
295 In other words, these configuration file definitions can \fBnot\fR be replaced,
296 or removed by the process environment at runtime.
297 .RE
299 .sp
300 .ne 2
301 .na
302 \fB\fB-f\fR \fIflags\fR\fR
303 .ad
304 .sp .6
305 .RS 4n
306 Provide the symbolic \fIflags\fR argument to the \fBdldump\fR(3C) calls used to
307 generate alternate objects. Any of the \fBRTLD_REL\fR flags that are defined in
308 \fB/usr/include/dlfcn.h\fR can be used. Multiple flags can be \fBor\fR'ed
309 together using the "\fB|\fR" character. In this case, the string should be
310 quoted to avoid expansion by the shell. If no \fIflags\fR values are provided
311 the default flag is \fBRTLD_REL_RELATIVE\fR.
312 .RE
314 .sp
315 .ne 2
316 .na
317 \fB\fB-i\fR \fIname\fR\fR
318 .ad
319 .sp .6
320 .RS 4n
321 Add an individual \fIname\fR to the configuration cache. Multiple occurrences
322 of this option are permitted. \fIname\fR can be a shared object or a directory.
323 If \fIname\fR is a directory, each shared object within the directory is added
324 to the cache. If \fIname\fR does not exist, the \fIname\fR is marked in the
325 cache as a nonexistent directory.
326 .RE
328 .sp
329 .ne 2
330 .na
331 \fB\fB-I\fR \fIname\fR\fR
332 .ad
333 .sp .6
334 .RS 4n
335 Mimic the \fB-i\fR, and in addition any shared object that is processed has an
336 alternative created using \fBdldump\fR(3C). If the \fB-f\fR flag contains
337 \fBRTLD_REL_EXEC\fR, then \fIname\fR can be a dynamic executable, for which an
338 alternative is created. Only one dynamic executable can be specified in this
339 manner, as the cache that is created is specific to this application.
340 .RE
342 .sp
343 .ne 2
344 .na
345 \fB\fB-g\fR \fIname\fR\fR
346 .ad
347 .sp .6
348 .RS 4n
349 Add the group \fIname\fR to the configuration cache. Each object is expanded to
350 determine its dependencies. Multiple occurrences of this option are permitted.
351 \fIname\fR can be a dynamic executable, shared object or a directory. If
352 \fIname\fR is a shared object, the shared object and its dependencies are added
353 to the cache. If \fIname\fR is a directory, each shared object within the
354 directory, and its dependencies, are added to the cache.
355 .RE
357 .sp
358 .ne 2
359 .na
360 \fB\fB-G\fR \fIname\fR\fR
361 .ad
362 .sp .6
363 .RS 4n
364 Mimic the \fB-g\fR option, and in addition any shared object that is processed
365 has an alternative created using \fBdldump\fR(3C). If \fIname\fR is a dynamic
366 executable, and the \fB-f\fR flag contains \fBRTLD_REL_EXEC\fR, then an
367 alternative for the dynamic executable is also created. Only one dynamic
368 executable can be specified in this manner as the cache that is created is
369 specific to this application.
370 .RE
372 .sp
373 .ne 2
374 .na
375 \fB\fB-l\fR \fIdir\fR\fR
376 .ad
377 .sp .6
378 .RS 4n
379 Specify a new default search directory \fIdir\fR for \fBELF\fR or \fBAOUT\fR
380 objects. Multiple occurrences of this option are permitted. The type of object
381 that is applicable to the search, is specified by the preceding \fB-t\fR
382 option, or defaults to \fBELF\fR.
383 .sp
384 The default search paths for 32-bit \fBELF\fR objects are \fB/lib\fR followed
385 by \fB/usr/lib\fR. For 64-bit \fBELF\fR objects, the default search paths are
386 \fB/lib/64\fR followed by \fB/usr/lib/64\fR.
387 .sp
388 The default search paths for \fBAOUT\fR objects are \fB/usr/4lib\fR, followed
389 by \fB/usr/lib\fR and finally \fB/usr/local/lib\fR.
390 .sp
391 Use of this option \fBreplaces\fR the default search path. Therefore, a
392 \fB-l\fR option is normally required to specify the original system default in
393 relation to any new paths that are being applied. However, if the \fB-u\fR
394 option is in effect, and a configuration file does \fBnot\fR exist, the system
395 defaults are added to the new configuration file. These defaults are added
396 before the new paths specified with the \fB-l\fR option.
397 .RE
399 .sp
400 .ne 2
401 .na
402 \fB\fB-o\fR \fIdir\fR\fR
403 .ad
404 .sp .6
405 .RS 4n
406 When used with either the \fB-a\fR or \fB-A\fR options, specifies the directory
407 \fIdir\fR in which any alternate objects exist. When alternative objects are
408 created by \fBcrle\fR, this option specified where the alternative are created.
409 Without this option, alternate objects exist in the directory in which the
410 configuration file is created. Multiple occurrences of this option are
411 permitted, the directory \fIdir\fR being used to locate alternatives for any
412 following command-line options. Alternative objects are not permitted to
413 override their associated originals.
414 .sp
415 Typically, this option is used with the \fB-a\fR or \fB-A\fR options.
416 .RE
418 .sp
419 .ne 2
420 .na
421 \fB\fB-s\fR \fIdir\fR\fR
422 .ad
423 .sp .6
424 .RS 4n
425 Specify a new trusted directory \fIdir\fR for \fIsecure\fR \fBELF\fR or
426 \fBAOUT\fR objects. See \fBSECURITY\fR in \fBld.so.1\fR(1) for a definition of
427 secure objects. See \fISecurity\fR in \fILinker and Libraries Guide\fR for a
428 discussion of runtime restrictions imposed on secure applications.
429 .sp
430 Multiple occurrences of this option are permitted. The type of object that is
431 applicable to the search is specified by the preceding \fB-t\fR option, or
432 defaults to \fBELF\fR.
433 .sp
434 The default trusted directories for secure 32-bit \fBELF\fR objects, and
435 \fBAOUT\fR objects, are \fB/lib/secure\fR followed by \fB/usr/lib/secure\fR.
436 For 64-bit secure \fBELF\fR objects, the default trusted directories are
437 \fB/lib/secure/64\fR followed by \fB/usr/lib/secure/64\fR.
438 .sp
439 Use of this option \fBreplaces\fR the default trusted directories. Therefore, a
440 \fB-s\fR option is normally required to specify the original system default in
441 relation to any new directories that are being applied. However, if the
442 \fB-u\fR option is in effect, and a configuration file does \fBnot\fR exist,
443 the system defaults are added to the new configuration file. These defaults are
444 added before the new directories specified with the \fB-l\fR option.
445 .RE
447 .sp
448 .ne 2
449 .na
450 \fB\fB-t\fR \fBELF\fR | \fBAOUT\fR\fR
451 .ad
452 .sp .6
453 .RS 4n
454 Toggle the object type that is applicable to any \fB-l\fR or \fB-s\fR options
455 that follow. The default object type is \fBELF\fR.
456 .RE
458 .sp
459 .ne 2
460 .na
461 \fB\fB-u\fR\fR
462 .ad
463 .sp .6
464 .RS 4n
465 Request that a configuration file be updated, possibly with the addition of new
466 information. Without other options, any existing configuration file is
467 inspected and its contents recomputed. Additional arguments allow information
468 to be appended to the recomputed contents. See NOTES.
469 .sp
470 If a configuration file does not exist, the configuration file is created as
471 directed by the other arguments. In the case of the \fB-l\fR and \fB-s\fR
472 options, any system defaults are first applied to the configuration file before
473 the directories specified with these options.
474 .sp
475 The configuration file can be in the older format that lacks the system
476 identification information that is normally written at the beginning of the
477 file. In this case, \fBcrle\fR does not place system identification information
478 into the resulting file, preserving compatibility of the file with older
479 versions of Solaris. See NOTES.
480 .RE
482 .sp
483 .ne 2
484 .na
485 \fB\fB-v\fR\fR
486 .ad
487 .sp .6
488 .RS 4n
489 Specify verbose mode. When creating a configuration file, a trace of the files
490 that are being processed is written to the standard out. When printing the
491 contents of a configuration file, more extensive directory and file information
492 is provided.
493 .RE
495 .sp
496 .LP
497 By default, the runtime linker attempts to read the configuration file
498 \fB/var/ld/ld.config\fR for each 32-bit application processed.
499 \fB/var/ld/64/ld.config\fR is read for each 64-bit application. When processing
500 an alternative application, the runtime linker uses a
501 \fB$ORIGIN/ld.config.\fIapp-name\fR\fR configuration file if present. See
502 NOTES. Applications can reference an alternative configuration file by setting
503 the \fBLD_CONFIG\fR environment variable. An alternative configuration file can
504 also be specified by recording the configuration file name in the application
505 at the time the application is built. See the \fB-c\fR option of \fBld\fR(1).
506 .SH EXAMPLES
507 .LP
508 \fBExample 1 \fRExperimenting With a Temporary Configuration File
509 .sp
510 .LP
511 The following example creates a temporary configuration file with a new default
512 search path for ELF objects. The environment variable \fBLD_CONFIG_32\fR is
513 used to instruct the runtime linker to use this configuration file for all
514 32-bit processes.
516 .sp
517 .in +2
518 .nf
519 $ \fBcrle -c /tmp/ld.config -u -l /local/lib\fR
520 $ \fBcrle -c /tmp/ld.config\fR
522 Configuration file [version 4]: /tmp/ld.config
523 Platform: 32-bit MSB SPARC
524 Default Library Path (ELF): /lib:/usr/lib:/local/lib
525 Trusted Directories (ELF): /lib/secure:/usr/lib/secure \e
526 (system default)
528 Command line:
529 crle -c /tmp/ld.config -l /lib:/usr/lib:/local/lib
531 $ \fBLD_CONFIG_32=/tmp/ld.config date\fR
532 Thu May 29 17:42:00 PDT 2008
533 .fi
534 .in -2
535 .sp
537 .LP
538 \fBExample 2 \fRUpdating and Displaying a New Default Search Path for ELF
539 Objects
540 .sp
541 .LP
542 The following example updates and displays a new default search path for ELF
543 objects.
545 .sp
546 .in +2
547 .nf
548 # \fBcrle -u -l /local/lib\fR
549 # \fBcrle\fR
551 Configuration file [version 4]: /var/ld/ld.config
552 Platform: 32-bit MSB SPARC
553 Default Library Path (ELF): /lib:/usr/lib:/local/lib
554 Trusted Directories (ELF): /lib/secure:/usr/lib/secure \e
555 (system default)
557 Command line:
558 crle -l /lib:/usr/lib:/local/lib
560 # \fBcrle -u -l /ISV/lib\fR
561 # \fBcrle\fR
563 Configuration file [version 4]: /var/ld/ld.config
564 Platform 32-bit MSB SPARC
565 Default Library Path (ELF): /lib:/usr/lib:/local/lib:/ISV/lib
566 Trusted Directories (ELF): /lib/secure:/usr/lib/secure \e
567 (system default)
569 Command line:
570 crle -l /lib:/usr/lib:/local/lib:/usr/local/lib
571 .fi
572 .in -2
573 .sp
575 .sp
576 .LP
577 In this example, the default configuration file initially did not exist.
578 Therefore, the new search path \fB/local/lib\fR is appended to the system
579 default. The next update appends the search path \fB/ISV/lib\fR to those paths
580 already established in the configuration file.
582 .LP
583 \fBExample 3 \fRRecovering From a Bad Configuration File
584 .sp
585 .LP
586 The following example creates a bad configuration file in the default location.
587 The file can be removed by instructing the runtime linker to ignore any
588 configuration file with the \fBLD_NOCONFIG\fR environment variable. Note, it is
589 recommended that temporary configuration files be created and the environment
590 variable \fBLD_CONFIG\fR used to experiment with these files.
592 .sp
593 .in +2
594 .nf
595 # \fBcrle -l /local/lib\fR
596 # \fBdate\fR
597 ld.so.1: date: fatal: libc.so.1: open failed: \e
598 No such file or directory
599 Killed
600 # \fBLD_NOCONFIG=yes rm /var/ld/ld.config\fR
601 # \fBdate\fR
602 Thu May 29 17:52:00 PDT 2008
603 .fi
604 .in -2
605 .sp
607 .sp
608 .LP
609 Note, the reason the configuration file is bad is because the system default
610 search paths are not present. Hence, the \fBdate\fR utility is not able to
611 locate the system dependencies that it required. In this case, the \fB-u\fR
612 option should have been used.
613 .LP
614 \fBExample 4 \fRCreating and Displaying a New Default Search Path and New
615 Trusted Directory for ELF Objects
616 .sp
617 .LP
618 The following example creates and displays a new default search path and new
619 trusted directory for ELF objects.
621 .sp
622 .in +2
623 .nf
624 # \fBcrle -l /local/lib -l /lib -l /usr/lib -s /local/lib\fR
625 # \fBcrle\fR
627 Configuration file [version 4]: /var/ld/ld.config
628 Platform: 32-bit MSB SPARC
629 Default Library Path (ELF): /local/lib:/lib:/usr/lib
630 Trusted Directories (ELF): /local/lib
632 Command line:
633 crle -l /local/lib:/lib:/usr/lib -s /local/lib
634 .fi
635 .in -2
636 .sp
638 .sp
639 .LP
640 With this configuration file, third party applications could be installed in
641 \fB/local/bin\fR and their associated dependencies in \fB/local/lib\fR. The
642 default search path allows the applications to locate their dependencies
643 without the need to set \fBLD_LIBRARY_PATH\fR. The default trusted directories
644 have also been replaced with this example.
646 .LP
647 \fBExample 5 \fRCreating a Directory Cache for ELF Objects
648 .sp
649 .LP
650 The following example creates a directory cache for ELF objects.
652 .sp
653 .in +2
654 .nf
655 $ \fBcrle -i /usr/dt/lib -i /usr/openwin/lib -i /lib -i /usr/lib \e
656 -c config\fR
657 $ \fBldd -s ./main\fR
658 \&....
659 find object=libc.so.1; required by ./main
660 search path=/usr/dt/lib:/usr/openwin/lib (RUNPATH/RPATH ./main)
661 trying path=/usr/dt/lib/libc.so.1
662 trying path=/usr/openwin/lib/libc.so.1
663 search path=/lib (default)
664 trying path=/lib/libc.so.1
665 libc.so.1 => /lib/libc.so.1
667 $ \fBLD_CONFIG=config ldd -s ./main\fR
668 \&....
669 find object=libc.so.1; required by ./main
670 search path=/usr/dt/lib:/usr/openwin/lib (RUNPATH/RPATH ./main)
671 search path=/lib (default)
672 trying path=/lib/libc.so.1
673 libc.so.1 => /lib/libc.so.1
674 .fi
675 .in -2
676 .sp
678 .sp
679 .LP
680 With this configuration, the cache reflects that the system library
681 \fBlibc.so.1\fR does not exist in the directories \fB/usr/dt/lib\fR or
682 \fB/usr/openwin/lib\fR. Therefore, the search for this system file ignores
683 these directories even though the application's runpath indicates these paths
684 should be searched.
686 .LP
687 \fBExample 6 \fRCreating an Alternative Object Cache for an ELF Executable
688 .sp
689 .LP
690 The following example creates an alternative object cache for an ELF
691 executable.
693 .sp
694 .in +2
695 .nf
696 $ \fBcrle -c /local/$HOST/.xterm/ld.config.xterm \e
697 -f RTLD_REL_ALL -G /usr/openwin/bin/xterm\fR
698 $ \fBln -s /local/$HOST/.xterm/xterm /local/$HOST/xterm\fR
699 $ \fBldd /usr/local/$HOST/xterm\fR
700 libXaw.so.5 => /local/$HOST/.xterm/libWaw.so.5 (alternate)
701 libXmu.so.4 => /local/$HOST/.xterm/libXmu.so.4 (alternate)
702 ....
703 libc.so.1 => /local/$HOST/.xterm/libc.so.1 (alternate)
704 ....
705 .fi
706 .in -2
707 .sp
709 .sp
710 .LP
711 With this configuration, a new \fBxterm\fR and its dependencies are created.
712 These new objects are fully relocated to each other, and result in faster
713 startup than the originating objects. The execution of this application uses
714 its own specific configuration file. This model is generally more flexible than
715 using the environment variable \fBLD_CONFIG\fR, as the configuration file can
716 not be erroneously used by other applications such as \fBldd\fR(1) or
717 \fBtruss\fR(1).
719 .LP
720 \fBExample 7 \fRCreating an Alternative Object Cache to Replace an ELF Shared
721 Object
722 .sp
723 .LP
724 The following example creates an alternative object cache to replace an ELF
725 shared object.
727 .sp
728 .in +2
729 .nf
730 $ \fBldd /usr/bin/vi\fR
731 libcurses.so.1 => /lib/libcurses.so.1
732 ....
734 # \fBcrle -a /lib/libcurses.so.1 -o /usr/something\fR
735 # \fBcrle\fR
737 Configuration file [version 4]: /var/ld/ld.config
738 Platform: 32-bit MSB SPARC
739 Default Library Path (ELF): /lib:/usr/lib (system default)
740 Trusted Directories (ELF): /lib/secure:/usr/lib/secure \e
741 (system default)
743 Directory: /lib
744 libcurses.so.1 (alternate: /usr/something/libcurses.so.1)
745 \&....
747 $ \fBldd /usr/bin/vi\fR
748 libcurses.so.1 => /usr/something/libcurses.so.1 (alternate)
749 ....
750 .fi
751 .in -2
752 .sp
754 .sp
755 .LP
756 With this configuration, any dependency that would normally resolve to
757 \fB/usr/lib/libcurses.so.1\fR instead resolves to
758 \fB/usr/something/libcurses.so.1\fR.
760 .LP
761 \fBExample 8 \fRSetting Replaceable and Permanent Environment Variables
762 .sp
763 .LP
764 The following example sets replaceable and permanent environment variables.
766 .sp
767 .in +2
768 .nf
769 # \fBcrle -e LD_LIBRARY_PATH=/local/lib \e
770 -E LD_PRELOAD=preload.so.1\fR
771 # \fBcrle\fR
772 \&.....
773 Environment Variables:
774 LD_LIBRARY_PATH=/local/lib (replaceable)
775 LD_PRELOAD=preload.so.1 (permanent)
777 \&.....
778 $ \fBLD_DEBUG=files LD_PRELOAD=preload.so.2 ./main\fR
779 \&.....
780 18764: file=preload.so.2; preloaded
781 18764: file=/local/lib/preload.so.2 [ ELF ]; generating link map
782 \&.....
783 18764: file=preload.so.1; preloaded
784 18764: file=/local/lib/preload.so.1 [ ELF ]; generating link map
785 \&.....
786 .fi
787 .in -2
788 .sp
790 .sp
791 .LP
792 With this configuration file, a replaceable search path has been specified
793 together with a permanent preload object which becomes appended to the process
794 environment definition.
796 .SH EXIT STATUS
797 .sp
798 .LP
799 The creation or display of a configuration file results in a \fB0\fR being
800 returned. Otherwise, any error condition is accompanied with a diagnostic
801 message and a non-zero value being returned.
802 .SH NOTES
803 .sp
804 .LP
805 The ability to tag an alternative application to use an application-specific
806 configuration file, is possible if the original application contains one of the
807 \fI\&.dynamic\fR tags \fBDT_FLAGS_1\fR or \fBDT_FEATURE_1\fR. Without these
808 entries, a configuration file must be specified using the \fBLD_CONFIG\fR
809 environment variable. Care should be exercised with this latter method as this
810 environment variable is visible to any forked applications.
811 .sp
812 .LP
813 The use of the \fB-u\fR option requires at least version 2 of \fBcrle\fR. This
814 version level is evident from displaying the contents of a configuration file.
815 .sp
816 .in +2
817 .nf
818 $ \fBcrle\fR
820 Configuration file [2]: /var/ld/ld.config
821 ......
822 .fi
823 .in -2
824 .sp
826 .sp
827 .LP
828 With a version 2 configuration file, \fBcrle\fR is capable of constructing the
829 command-line arguments required to regenerate the configuration file. This
830 command-line construction, provides full update capabilities using the \fB-u\fR
831 option. Although a version 1 configuration file update is possible, the
832 configuration file contents might be insufficient for \fBcrle\fR to compute the
833 entire update requirements.
834 .sp
835 .LP
836 Configuration files contain platform specific binary data. A given
837 configuration file can only be interpreted by software with the same machine
838 class and byte ordering. However, the information necessary to enforce this
839 restriction was not included in configuration files until \fBSXCE\fR build
840 \fB41\fR. As of this \fBSXCE\fR build, configuration files have system
841 identification information at the beginning of the file. This additional
842 information is used by \fBcrle\fR and the runtime to check their compatibility
843 with configuration files. This information also allows the \fBfile\fR(1)
844 command to properly identify configuration files. For backward compatibility,
845 older files that are missing this information are still accepted, although
846 without the identification and error checking that would otherwise be possible.
847 When processing an update (\fB-u\fR) operation for an older file that lacks
848 system information, \fBcrle\fR does not add system identification information
849 to the result.
850 .SH FILES
851 .sp
852 .ne 2
853 .na
854 \fB\fB/var/ld/ld.config\fR\fR
855 .ad
856 .sp .6
857 .RS 4n
858 Default configuration file for 32-bit applications.
859 .RE
861 .sp
862 .ne 2
863 .na
864 \fB\fB/var/ld/64/ld.config\fR\fR
865 .ad
866 .sp .6
867 .RS 4n
868 Default configuration file for 64-bit applications.
869 .RE
871 .sp
872 .ne 2
873 .na
874 \fB\fB/var/tmp\fR\fR
875 .ad
876 .sp .6
877 .RS 4n
878 Default location for temporary configuration file. See \fBtempnam\fR(3C).
879 .RE
881 .sp
882 .ne 2
883 .na
884 \fB\fB/usr/lib/lddstub\fR\fR
885 .ad
886 .sp .6
887 .RS 4n
888 Stub application that is employed to \fBdldump\fR(3C) 32-bit objects.
889 .RE
891 .sp
892 .ne 2
893 .na
894 \fB\fB/usr/lib/64/lddstub\fR\fR
895 .ad
896 .sp .6
897 .RS 4n
898 Stub application that is employed to \fBdldump\fR(3C) 64-bit objects.
899 .RE
901 .sp
902 .ne 2
903 .na
904 \fB\fB/usr/lib/libcrle.so.1\fR\fR
905 .ad
906 .sp .6
907 .RS 4n
908 Audit library that is employed to \fBdldump\fR(3C) 32-bit objects.
909 .RE
911 .sp
912 .ne 2
913 .na
914 \fB\fB/usr/lib/64/libcrle.so.1\fR\fR
915 .ad
916 .sp .6
917 .RS 4n
918 Audit library that is employed to \fBdldump\fR(3C) 64-bit objects.
919 .RE
921 .SH ENVIRONMENT VARIABLES
922 .sp
923 .LP
924 There are no environment variables that are referenced by \fBcrle\fR. However,
925 several environment variables affect the runtime linkers behavior in regard to
926 the processing of configuration files that are created by \fBcrle\fR.
927 .sp
928 .ne 2
929 .na
930 \fB\fBLD_CONFIG\fR, \fBLD_CONFIG_32\fR and \fBLD_CONFIG_64\fR\fR
931 .ad
932 .sp .6
933 .RS 4n
934 Provide an alternative configuration file.
935 .RE
937 .sp
938 .ne 2
939 .na
940 \fB\fBLD_NOCONFIG\fR, \fBLD_NOCONFIG_32\fR and \fBLD_NOCONFIG_64\fR\fR
941 .ad
942 .sp .6
943 .RS 4n
944 Disable configuration file processing.
945 .RE
947 .sp
948 .ne 2
949 .na
950 \fB\fBLD_NODIRCONFIG\fR, \fBLD_NODIRCONFIG_32\fR and \fBLD_NODIRCONFIG_64\fR\fR
951 .ad
952 .sp .6
953 .RS 4n
954 Disable directory cache processing from a configuration file.
955 .RE
957 .sp
958 .ne 2
959 .na
960 \fB\fBLD_NOENVCONFIG\fR, \fBLD_NOENVCONFIG_32\fR and \fBLD_NOENVCONFIG_64\fR\fR
961 .ad
962 .sp .6
963 .RS 4n
964 Disable environment variable processing from a configuration file.
965 .RE
967 .sp
968 .ne 2
969 .na
970 \fB\fBLD_NOOBJALTER\fR, \fBLD_NOOBJALTER_32\fR and \fBLD_NOOBJALTER_64\fR\fR
971 .ad
972 .sp .6
973 .RS 4n
974 Disable alternative object processing from a configuration file.
975 .RE
977 .SH ATTRIBUTES
978 .sp
979 .LP
980 See \fBattributes\fR(5) for descriptions of the following attributes.
981 .sp
983 .sp
984 .TS
985 box;
986 c | c
987 l | l .
988 ATTRIBUTE TYPE ATTRIBUTE VALUE
989 _
990 Interface Stability Committed
991 .TE
993 .SH SEE ALSO
994 .sp
995 .LP
996 \fBfile\fR(1), \fBld\fR(1), \fBld.so.1\fR(1), \fBdldump\fR(3C),
997 \fBtempnam\fR(3C), \fBattributes\fR(5)
998 .sp
999 .LP
1000 \fILinker and Libraries Guide\fR