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 .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
  78 
  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
  95 
  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
 106 
 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
 118 
 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
 133 
 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
 199 
 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
 217 
 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
 235 
 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
 246 
 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
 268 
 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
 298 
 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
 313 
 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
 327 
 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
 341 
 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
 356 
 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
 371 
 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
 398 
 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
 417 
 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
 446 
 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
 457 
 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
 481 
 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
 494 
 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.
 515 
 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
 521 
 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)
 527 
 528 Command line:
 529   crle -c /tmp/ld.config -l /lib:/usr/lib:/local/lib
 530 
 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
 536 
 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.
 544 
 545 .sp
 546 .in +2
 547 .nf
 548 # \fBcrle -u -l /local/lib\fR
 549 # \fBcrle\fR
 550 
 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)
 556 
 557 Command line:
 558   crle -l /lib:/usr/lib:/local/lib
 559 
 560 # \fBcrle -u -l /ISV/lib\fR
 561 # \fBcrle\fR
 562 
 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)
 568 
 569 Command line:
 570   crle -l /lib:/usr/lib:/local/lib:/usr/local/lib
 571 .fi
 572 .in -2
 573 .sp
 574 
 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.
 581 
 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.
 591 
 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
 606 
 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.
 620 
 621 .sp
 622 .in +2
 623 .nf
 624 # \fBcrle -l /local/lib -l /lib -l /usr/lib -s /local/lib\fR
 625 # \fBcrle\fR
 626 
 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
 631 
 632 Command line:
 633   crle -l /local/lib:/lib:/usr/lib -s /local/lib
 634 .fi
 635 .in -2
 636 .sp
 637 
 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.
 645 
 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.
 651 
 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
 666 
 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
 677 
 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.
 685 
 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.
 692 
 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
 708 
 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).
 718 
 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.
 726 
 727 .sp
 728 .in +2
 729 .nf
 730 $ \fBldd /usr/bin/vi\fR
 731     libcurses.so.1 =>  /lib/libcurses.so.1
 732     ....
 733 
 734 # \fBcrle -a /lib/libcurses.so.1 -o /usr/ucblib\fR
 735 # \fBcrle\fR
 736 
 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)
 742 
 743 Directory: /lib
 744   libcurses.so.1  (alternate: /usr/ucblib/libcurses.so.1)
 745 \&....
 746 
 747 $ \fBldd /usr/bin/vi\fR
 748     libcurses.so.1 => /usr/ucblib/libcurses.so.1 (alternate)
 749     ....
 750 .fi
 751 .in -2
 752 .sp
 753 
 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/ucblib/libcurses.so.1\fR.
 759 
 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.
 765 
 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)
 776 
 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
 789 
 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.
 795 
 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
 819 
 820 Configuration file [2]: /var/ld/ld.config
 821   ......
 822 .fi
 823 .in -2
 824 .sp
 825 
 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
 860 
 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
 870 
 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
 880 
 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
 890 
 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
 900 
 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
 910 
 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
 920 
 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
 936 
 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
 946 
 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
 956 
 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
 966 
 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
 976 
 977 .SH ATTRIBUTES
 978 .sp
 979 .LP
 980 See \fBattributes\fR(5) for descriptions of the following attributes.
 981 .sp
 982 
 983 .sp
 984 .TS
 985 box;
 986 c | c
 987 l | l .
 988 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 989 _
 990 Interface Stability     Committed
 991 .TE
 992 
 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