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