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