9842 man page typos and spelling

          --- old/usr/src/man/man1/crle.1
          +++ new/usr/src/man/man1/crle.1

   1    1  '\" te
   2    2  .\"  Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
   3    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    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    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    6  .TH CRLE 1 "Oct 6, 2008"
   7    7  .SH NAME

   8    8  crle \- configure runtime linking environment
   9    9  .SH SYNOPSIS
  10   10  .LP
  11   11  .nf
  12   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   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   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   15  .fi
  16   16  
  17   17  .SH DESCRIPTION
  18      -.sp
  19   18  .LP
  20   19  The \fBcrle\fR utility provides for the creation and display of a runtime
  21   20  linking configuration file. The configuration file is read and interpreted by
  22   21  the runtime linker, \fBld.so.1\fR(1), during process startup. The runtime
  23   22  linker attempts to read a default configuration file for all processes. For
  24   23  32-bit processes, the default configuration file is \fB/var/ld/ld.config\fR.
  25   24  For 64-bit processes, the default configuration file is
  26   25  \fB/var/ld/64/ld.config\fR.
  27   26  .sp
  28   27  .LP

  29   28  Without any arguments, or with just the \fB-c\fR option, \fBcrle\fR displays
  30   29  configuration information. This information includes the contents of a
  31   30  configuration file, any system defaults and the command-line required to
  32   31  regenerate the configuration file. When used with any other options, a new
  33   32  configuration file is created or updated.
  34   33  .sp
  35   34  .LP
  36   35  The runtime linker can also be directed to an alternative configuration file by
  37   36  setting one of the \fBLD_CONFIG\fR family of environment variable.
  38   37  \fBLD_CONFIG\fR applies to both 32-bit and 64-bit programs. Since 32-bit and
  39   38  64-bit configuration files differ, a single configuration file cannot be used
  40   39  for both class of object. Hence, \fBLD_CONFIG\fR can adversely affect program

  41   40  execution in cases where a program of one class executes a program of the other
  42   41  class. In particular, it is common practice for the 32-bit version of standard
  43   42  Solaris utilities to execute their 64-bit counterpart. \fBLD_CONFIG\fR cannot
  44   43  be successfully used in this case. Therefore, the use of the \fBLD_CONFIG_32\fR
  45   44  and \fBLD_CONFIG_64\fR environment variables, that precisely target the
  46   45  appropriate class of process, is recommended.
  47   46  .sp
  48   47  .LP
  49   48  Creating an incorrect configuration file in the standard location,
  50   49  \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
       50 +difficult to recover from. To guard against this situation, it is recommended
  52   51  that new configuration files first be created in a temporary location. Then set
  53   52  the appropriate \fBLD_CONFIG\fR environment variable to this new configuration
  54   53  file. This setting causes the new configuration file to be used by the runtime
  55   54  linker instead of any default. After verification, the new configuration file
  56   55  can be moved to the default location if desired. At any time, the environment
  57   56  variable \fBLD_NOCONFIG\fR can be set to any value to instruct the runtime
  58   57  linker to ignore any configuration files. This setting can prove useful during
  59   58  experimentation.
  60   59  .sp
  61   60  .LP

  62   61  A configuration file can contain the following information.
  63   62  .sp
  64   63  .ne 2
  65   64  .na
  66   65  \fBDefault Search Paths\fR
  67   66  .ad
  68   67  .sp .6
  69   68  .RS 4n
  70   69  The runtime linker uses a prescribed search path for locating the dynamic
  71   70  dependencies of an object. This search path starts with the components of any
  72   71  \fBLD_LIBRARY_PATH\fR definition, followed by the components of an object's
  73   72  \fBrunpath\fR. Finally, any default search paths specific to the object's class
  74   73  are used. This last component of the search path can be expressed within the
  75   74  configuration file. Typically, use of this facility should be augmented with
  76   75  any system default. See the \fB-l\fR and \fB-u\fR options.
  77   76  .RE
  78   77  
  79   78  .sp
  80   79  .ne 2
  81   80  .na
  82   81  \fBTrusted Directories\fR
  83   82  .ad
  84   83  .sp .6
  85   84  .RS 4n
  86   85  When processing a secure application, the runtime linker restricts the use of
  87   86  \fBLD_LIBRARY_PATH\fR searches, and \fB$ORIGIN\fR token expansion. See
  88   87  \fISecurity\fR in \fILinker and Libraries Guide\fR. In addition, the
  89   88  directories from which preload and audit libraries can be located are also
  90   89  restricted. The path names that are associated with preload and audit libraries
  91   90  are restricted to known trusted directories. Trusted directories can be
  92   91  expressed within the configuration file. Typically, use of this facility should
  93   92  be augmented with any system defaults. See the \fB-s\fR and \fB-u\fR options.
  94   93  .RE
  95   94  
  96   95  .sp
  97   96  .ne 2
  98   97  .na
  99   98  \fBEnvironment Variables\fR
 100   99  .ad
 101  100  .sp .6
 102  101  .RS 4n
 103  102  Any environment variable interpreted by the runtime linker can be specified
 104  103  within the configuration file.
 105  104  .RE
 106  105  
 107  106  .sp
 108  107  .ne 2
 109  108  .na
 110  109  \fBDirectory Cache\fR
 111  110  .ad
 112  111  .sp .6
 113  112  .RS 4n
 114  113  The location of shared objects within defined directories can be maintained as
 115  114  a cache within the configuration file. This directory cache can reduce the
 116  115  overhead of searching for application dependencies.
 117  116  .RE
 118  117  
 119  118  .sp
 120  119  .ne 2
 121  120  .na
 122  121  \fBAlternative Objects\fR
 123  122  .ad
 124  123  .sp .6
 125  124  .RS 4n
 126  125  In conjunction with the directory cache, shared objects can have alternative
 127  126  objects specified for use at runtime. These alternate objects, can be supplied
 128  127  by the user. Alternative objects can also be created by \fBcrle\fR as copies of
 129  128  shared objects fixed to known memory locations. These fixed alternative objects
 130  129  can require less processing at runtime than their original shared object
 131  130  counterpart.
 132  131  .RE
 133  132  
 134  133  .sp
 135  134  .LP
 136  135  Defining additional default search paths, or additional trusted directories can
 137  136  be useful for administrators who wish to install third party software in a
 138  137  central location, or otherwise alter the search path of applications that might
 139  138  not have been coded with a suitable runpath.
 140  139  .sp
 141  140  .LP
 142  141  The declaration of alternative objects provides a means of replacing
 143  142  dependencies other than by using symbolic links or requiring
 144  143  \fBLD_LIBRARY_PATH\fR settings.
 145  144  .sp
 146  145  .LP
 147  146  The declaration of environment variables that are interpreted by the runtime
 148  147  linker provides a means of centralizing their definition for all applications.
 149  148  .sp
 150  149  .LP
 151  150  The directory cache, and \fBcrle\fR generated alternate objects, can provide a
 152  151  means of reducing the runtime startup overhead of applications. Alternative
 153  152  objects can be useful for applications that require many dependencies, or whose
 154  153  dependencies are expensive to relocate. Shared objects that contain
 155  154  \fBposition-dependent\fR code are often expensive to relocate. Note, the system
 156  155  has many caching facilities that help mitigate expenses such as negative path
 157  156  lookups, and thus employing \fBcrle\fR to create a directory cache may have
 158  157  minimal effect other than for some very specific cases.
 159  158  .sp
 160  159  .LP
 161  160  When alternate objects that are generated by \fBcrle\fR are specified within a
 162  161  configuration file, the runtime linker performs some minimal consistency
 163  162  verification. The alternative objects are verified against their originating
 164  163  objects. This verification is intended to avert application failure should an
 165  164  applications configuration information become out-of-sync with the underlying
 166  165  system components. When this situation arises the flexibility offered by
 167  166  dynamic linking system components can be compromised. This type of application
 168  167  failure can be very difficult to diagnose. No verification of directory cache
 169  168  information is performed. Any changes to the directory structure are not seen
 170  169  by a process until the cache is rebuilt.
 171  170  .sp
 172  171  .LP
 173  172  System shared objects are often well tuned, and can show little benefit from
 174  173  being cached. The directory cache and alternative object features are typically
 175  174  applicable to user applications and shared objects, and may only show

 176  175  improvement in some very specific cases.
 177  176  .sp
 178  177  .LP
 179  178  \fBcrle\fR creates alternate objects for the shared objects that are discovered
 180  179  when using the \fB-I\fR and \fB-G\fR options, using \fBdldump\fR(3C). The
 181  180  alternate object is created in the directory specified by the preceding
 182  181  \fB-o\fR option, or defaults to the directory in which the configuration file
 183  182  is created. The flags used by \fBdldump()\fR are specified using the \fB-f\fR
 184  183  option, or default to \fBRTLD_REL_RELATIVE\fR.
 185  184  .SH OPTIONS
 186      -.sp
 187  185  .LP
 188  186  The following options are supported.
 189  187  .sp
 190  188  .ne 2
 191  189  .na
 192  190  \fB\fB-64\fR\fR
 193  191  .ad
 194  192  .sp .6
 195  193  .RS 4n
 196  194  Specify to process 64-bit objects, the default is 32-bit. Use \fB-64\fR to

 197  195  create a 64-bit specific configuration file.
 198  196  .RE
 199  197  
 200  198  .sp
 201  199  .ne 2
 202  200  .na
 203  201  \fB\fB-a\fR \fIname\fR\fR
 204  202  .ad
 205  203  .sp .6
 206  204  .RS 4n
 207  205  Create an alternative path name for \fIname\fR. The alternative path name is
 208  206  added to the configuration file.
 209  207  .sp
 210  208  The actual alternative file must be supplied by the user. Multiple occurrences
 211  209  of this option are permitted. If \fIname\fR is a directory, each shared object
 212  210  within the directory is added to the cache. If \fIname\fR does not exist, then
 213  211  \fIname\fR is marked in the cache as a nonexistent file.
 214  212  .sp
 215  213  Typically, this option is used with the \fB-o\fR option.
 216  214  .RE
 217  215  
 218  216  .sp
 219  217  .ne 2
 220  218  .na
 221  219  \fB\fB-A\fR \fIname\fR\fR
 222  220  .ad
 223  221  .sp .6
 224  222  .RS 4n
 225  223  Create an optional alternative path name for \fIname\fR. This alternative path
 226  224  name is added to the configuration file.
 227  225  .sp
 228  226  This option mimics the \fB-a\fR option, except that if the alternative is
 229  227  unavailable at runtime, the original object \fIname\fR is used. This model
 230  228  mimics the use of auxiliary filters. See \fIGenerating Auxiliary Filters\fR in
 231  229  \fILinker and Libraries Guide\fR.
 232  230  .sp
 233  231  Typically, this option is used with the \fB-o\fR option.
 234  232  .RE
 235  233  
 236  234  .sp
 237  235  .ne 2
 238  236  .na
 239  237  \fB\fB-c\fR \fIconf\fR\fR
 240  238  .ad
 241  239  .sp .6
 242  240  .RS 4n
 243  241  Specify to use the configuration file name \fIconf\fR. If this option is not
 244  242  supplied, the default configuration file is used.
 245  243  .RE
 246  244  
 247  245  .sp
 248  246  .ne 2
 249  247  .na
 250  248  \fB\fB-e\fR \fIenv\fR\fR
 251  249  .ad
 252  250  .sp .6
 253  251  .RS 4n
 254  252  Specify a \fBreplaceable\fR environment variable, \fIenv\fR. Only environment
 255  253  variables that are applicable to the runtime linker are meaningful. Multiple
 256  254  occurrences of this option are permitted. This option is similar to the
 257  255  \fB-E\fR option. However, the options differs in how configuration file
 258  256  definitions, and process environment definitions of the same name are resolved
 259  257  at runtime.
 260  258  .sp
 261  259  A definition established in a configuration file can be \fBoverridden\fR by a
 262  260  process environment definition, or be \fBsuppressed\fR by a null-value process
 263  261  environment definition.
 264  262  .sp
 265  263  In other words, these configuration file definitions can be replaced, or
 266  264  removed by the process environment at runtime.
 267  265  .RE
 268  266  
 269  267  .sp
 270  268  .ne 2
 271  269  .na
 272  270  \fB\fB-E\fR \fIenv\fR\fR
 273  271  .ad
 274  272  .sp .6
 275  273  .RS 4n
 276  274  Specify a \fBpermanent\fR environment variable, \fIenv\fR. Only environment
 277  275  variables that are applicable to the runtime linker are meaningful. Multiple
 278  276  occurrences of this option are permitted. This option is similar to the
 279  277  \fB-e\fR option. However, the option differs in how configuration file
 280  278  definitions, and process environment definitions of the same name are resolved
 281  279  at runtime.
 282  280  .sp
 283  281  Environment variable definitions that are meaningful to the runtime linker fall
 284  282  into one of two categories. Singular definitions are definitions such as
 285  283  \fBLD_NOLAZYLOAD=1\fR and \fBLD_DEBUG_OUTPUT=\fR\fIfile\fR. List definitions,
 286  284  which can take one or more values, are definitions such as
 287  285  \fBLD_LIBRARY_PATH=\fR\fIpath\fR, and \fBLD_DEBUG=\fR\fIfiles\fR,\fIdetails\fR.
 288  286  .sp
 289  287  A singular definition that is established in a configuration file takes
 290  288  precedence over a process environment definition. A list definition that is
 291  289  established in a configuration file is \fBappended\fR to a process environment
 292  290  definition. Any definition that is established in a configuration file can
 293  291  \fBnot\fR be suppressed by a null-value process environment definition.
 294  292  .sp
 295  293  In other words, these configuration file definitions can \fBnot\fR be replaced,
 296  294  or removed by the process environment at runtime.
 297  295  .RE
 298  296  
 299  297  .sp
 300  298  .ne 2
 301  299  .na
 302  300  \fB\fB-f\fR \fIflags\fR\fR
 303  301  .ad
 304  302  .sp .6
 305  303  .RS 4n
 306  304  Provide the symbolic \fIflags\fR argument to the \fBdldump\fR(3C) calls used to
 307  305  generate alternate objects. Any of the \fBRTLD_REL\fR flags that are defined in
 308  306  \fB/usr/include/dlfcn.h\fR can be used. Multiple flags can be \fBor\fR'ed
 309  307  together using the "\fB|\fR" character. In this case, the string should be
 310  308  quoted to avoid expansion by the shell. If no \fIflags\fR values are provided
 311  309  the default flag is \fBRTLD_REL_RELATIVE\fR.
 312  310  .RE
 313  311  
 314  312  .sp
 315  313  .ne 2
 316  314  .na
 317  315  \fB\fB-i\fR \fIname\fR\fR
 318  316  .ad
 319  317  .sp .6
 320  318  .RS 4n
 321  319  Add an individual \fIname\fR to the configuration cache. Multiple occurrences
 322  320  of this option are permitted. \fIname\fR can be a shared object or a directory.
 323  321  If \fIname\fR is a directory, each shared object within the directory is added
 324  322  to the cache. If \fIname\fR does not exist, the \fIname\fR is marked in the
 325  323  cache as a nonexistent directory.
 326  324  .RE
 327  325  
 328  326  .sp
 329  327  .ne 2
 330  328  .na
 331  329  \fB\fB-I\fR \fIname\fR\fR
 332  330  .ad
 333  331  .sp .6
 334  332  .RS 4n
 335  333  Mimic the \fB-i\fR, and in addition any shared object that is processed has an
 336  334  alternative created using \fBdldump\fR(3C). If the \fB-f\fR flag contains
 337  335  \fBRTLD_REL_EXEC\fR, then \fIname\fR can be a dynamic executable, for which an
 338  336  alternative is created. Only one dynamic executable can be specified in this
 339  337  manner, as the cache that is created is specific to this application.
 340  338  .RE
 341  339  
 342  340  .sp
 343  341  .ne 2
 344  342  .na
 345  343  \fB\fB-g\fR \fIname\fR\fR
 346  344  .ad
 347  345  .sp .6
 348  346  .RS 4n
 349  347  Add the group \fIname\fR to the configuration cache. Each object is expanded to
 350  348  determine its dependencies. Multiple occurrences of this option are permitted.
 351  349  \fIname\fR can be a dynamic executable, shared object or a directory. If
 352  350  \fIname\fR is a shared object, the shared object and its dependencies are added
 353  351  to the cache. If \fIname\fR is a directory, each shared object within the
 354  352  directory, and its dependencies, are added to the cache.
 355  353  .RE
 356  354  
 357  355  .sp
 358  356  .ne 2
 359  357  .na
 360  358  \fB\fB-G\fR \fIname\fR\fR
 361  359  .ad
 362  360  .sp .6
 363  361  .RS 4n
 364  362  Mimic the \fB-g\fR option, and in addition any shared object that is processed
 365  363  has an alternative created using \fBdldump\fR(3C). If \fIname\fR is a dynamic
 366  364  executable, and the \fB-f\fR flag contains \fBRTLD_REL_EXEC\fR, then an
 367  365  alternative for the dynamic executable is also created. Only one dynamic
 368  366  executable can be specified in this manner as the cache that is created is
 369  367  specific to this application.
 370  368  .RE
 371  369  
 372  370  .sp
 373  371  .ne 2
 374  372  .na
 375  373  \fB\fB-l\fR \fIdir\fR\fR
 376  374  .ad
 377  375  .sp .6
 378  376  .RS 4n
 379  377  Specify a new default search directory \fIdir\fR for \fBELF\fR or \fBAOUT\fR
 380  378  objects. Multiple occurrences of this option are permitted. The type of object
 381  379  that is applicable to the search, is specified by the preceding \fB-t\fR
 382  380  option, or defaults to \fBELF\fR.
 383  381  .sp
 384  382  The default search paths for 32-bit \fBELF\fR objects are \fB/lib\fR followed
 385  383  by \fB/usr/lib\fR. For 64-bit \fBELF\fR objects, the default search paths are
 386  384  \fB/lib/64\fR followed by \fB/usr/lib/64\fR.
 387  385  .sp
 388  386  The default search paths for \fBAOUT\fR objects are \fB/usr/4lib\fR, followed
 389  387  by \fB/usr/lib\fR and finally \fB/usr/local/lib\fR.
 390  388  .sp
 391  389  Use of this option \fBreplaces\fR the default search path. Therefore, a
 392  390  \fB-l\fR option is normally required to specify the original system default in
 393  391  relation to any new paths that are being applied. However, if the \fB-u\fR
 394  392  option is in effect, and a configuration file does \fBnot\fR exist, the system
 395  393  defaults are added to the new configuration file. These defaults are added
 396  394  before the new paths specified with the \fB-l\fR option.
 397  395  .RE
 398  396  
 399  397  .sp
 400  398  .ne 2
 401  399  .na
 402  400  \fB\fB-o\fR \fIdir\fR\fR
 403  401  .ad
 404  402  .sp .6
 405  403  .RS 4n
 406  404  When used with either the \fB-a\fR or \fB-A\fR options, specifies the directory
 407  405  \fIdir\fR in which any alternate objects exist. When alternative objects are
 408  406  created by \fBcrle\fR, this option specified where the alternative are created.
 409  407  Without this option, alternate objects exist in the directory in which the
 410  408  configuration file is created. Multiple occurrences of this option are
 411  409  permitted, the directory \fIdir\fR being used to locate alternatives for any
 412  410  following command-line options. Alternative objects are not permitted to
 413  411  override their associated originals.
 414  412  .sp
 415  413  Typically, this option is used with the \fB-a\fR or \fB-A\fR options.
 416  414  .RE
 417  415  
 418  416  .sp
 419  417  .ne 2
 420  418  .na
 421  419  \fB\fB-s\fR \fIdir\fR\fR
 422  420  .ad
 423  421  .sp .6
 424  422  .RS 4n
 425  423  Specify a new trusted directory \fIdir\fR for \fIsecure\fR \fBELF\fR or
 426  424  \fBAOUT\fR objects. See \fBSECURITY\fR in \fBld.so.1\fR(1) for a definition of
 427  425  secure objects. See \fISecurity\fR in \fILinker and Libraries Guide\fR for a
 428  426  discussion of runtime restrictions imposed on secure applications.
 429  427  .sp
 430  428  Multiple occurrences of this option are permitted. The type of object that is
 431  429  applicable to the search is specified by the preceding \fB-t\fR option, or
 432  430  defaults to \fBELF\fR.
 433  431  .sp
 434  432  The default trusted directories for secure 32-bit \fBELF\fR objects, and
 435  433  \fBAOUT\fR objects, are \fB/lib/secure\fR followed by \fB/usr/lib/secure\fR.
 436  434  For 64-bit secure \fBELF\fR objects, the default trusted directories are
 437  435  \fB/lib/secure/64\fR followed by \fB/usr/lib/secure/64\fR.
 438  436  .sp
 439  437  Use of this option \fBreplaces\fR the default trusted directories. Therefore, a
 440  438  \fB-s\fR option is normally required to specify the original system default in
 441  439  relation to any new directories that are being applied. However, if the
 442  440  \fB-u\fR option is in effect, and a configuration file does \fBnot\fR exist,
 443  441  the system defaults are added to the new configuration file. These defaults are
 444  442  added before the new directories specified with the \fB-l\fR option.
 445  443  .RE
 446  444  
 447  445  .sp
 448  446  .ne 2
 449  447  .na
 450  448  \fB\fB-t\fR \fBELF\fR | \fBAOUT\fR\fR
 451  449  .ad
 452  450  .sp .6
 453  451  .RS 4n
 454  452  Toggle the object type that is applicable to any \fB-l\fR or \fB-s\fR options
 455  453  that follow. The default object type is \fBELF\fR.
 456  454  .RE
 457  455  
 458  456  .sp
 459  457  .ne 2
 460  458  .na
 461  459  \fB\fB-u\fR\fR
 462  460  .ad
 463  461  .sp .6
 464  462  .RS 4n
 465  463  Request that a configuration file be updated, possibly with the addition of new
 466  464  information. Without other options, any existing configuration file is
 467  465  inspected and its contents recomputed. Additional arguments allow information
 468  466  to be appended to the recomputed contents. See NOTES.
 469  467  .sp
 470  468  If a configuration file does not exist, the configuration file is created as
 471  469  directed by the other arguments. In the case of the \fB-l\fR and \fB-s\fR
 472  470  options, any system defaults are first applied to the configuration file before
 473  471  the directories specified with these options.
 474  472  .sp
 475  473  The configuration file can be in the older format that lacks the system
 476  474  identification information that is normally written at the beginning of the
 477  475  file. In this case, \fBcrle\fR does not place system identification information
 478  476  into the resulting file, preserving compatibility of the file with older
 479  477  versions of Solaris. See NOTES.
 480  478  .RE
 481  479  
 482  480  .sp
 483  481  .ne 2
 484  482  .na
 485  483  \fB\fB-v\fR\fR
 486  484  .ad
 487  485  .sp .6
 488  486  .RS 4n
 489  487  Specify verbose mode. When creating a configuration file, a trace of the files
 490  488  that are being processed is written to the standard out. When printing the
 491  489  contents of a configuration file, more extensive directory and file information
 492  490  is provided.
 493  491  .RE
 494  492  
 495  493  .sp
 496  494  .LP
 497  495  By default, the runtime linker attempts to read the configuration file
 498  496  \fB/var/ld/ld.config\fR for each 32-bit application processed.
 499  497  \fB/var/ld/64/ld.config\fR is read for each 64-bit application. When processing
 500  498  an alternative application, the runtime linker uses a
 501  499  \fB$ORIGIN/ld.config.\fIapp-name\fR\fR configuration file if present. See
 502  500  NOTES. Applications can reference an alternative configuration file by setting
 503  501  the \fBLD_CONFIG\fR environment variable. An alternative configuration file can
 504  502  also be specified by recording the configuration file name in the application
 505  503  at the time the application is built. See the \fB-c\fR option of \fBld\fR(1).
 506  504  .SH EXAMPLES
 507  505  .LP
 508  506  \fBExample 1 \fRExperimenting With a Temporary Configuration File
 509  507  .sp
 510  508  .LP
 511  509  The following example creates a temporary configuration file with a new default
 512  510  search path for ELF objects. The environment variable \fBLD_CONFIG_32\fR is
 513  511  used to instruct the runtime linker to use this configuration file for all
 514  512  32-bit processes.
 515  513  
 516  514  .sp
 517  515  .in +2
 518  516  .nf
 519  517  $ \fBcrle -c /tmp/ld.config -u -l /local/lib\fR
 520  518  $ \fBcrle -c /tmp/ld.config\fR
 521  519  
 522  520  Configuration file [version 4]: /tmp/ld.config
 523  521    Platform:     32-bit MSB SPARC
 524  522    Default Library Path (ELF):  /lib:/usr/lib:/local/lib
 525  523    Trusted Directories (ELF):   /lib/secure:/usr/lib/secure  \e
 526  524                                 (system default)
 527  525  
 528  526  Command line:
 529  527    crle -c /tmp/ld.config -l /lib:/usr/lib:/local/lib
 530  528  
 531  529  $ \fBLD_CONFIG_32=/tmp/ld.config date\fR
 532  530  Thu May 29 17:42:00 PDT 2008
 533  531  .fi
 534  532  .in -2
 535  533  .sp
 536  534  
 537  535  .LP
 538  536  \fBExample 2 \fRUpdating and Displaying a New Default Search Path for ELF
 539  537  Objects
 540  538  .sp
 541  539  .LP
 542  540  The following example updates and displays a new default search path for ELF
 543  541  objects.
 544  542  
 545  543  .sp
 546  544  .in +2
 547  545  .nf
 548  546  # \fBcrle -u -l /local/lib\fR
 549  547  # \fBcrle\fR
 550  548  
 551  549  Configuration file [version 4]: /var/ld/ld.config
 552  550    Platform:     32-bit MSB SPARC
 553  551    Default Library Path (ELF):  /lib:/usr/lib:/local/lib
 554  552    Trusted Directories (ELF):   /lib/secure:/usr/lib/secure  \e
 555  553                                 (system default)
 556  554  
 557  555  Command line:
 558  556    crle -l /lib:/usr/lib:/local/lib
 559  557  
 560  558  # \fBcrle -u -l /ISV/lib\fR
 561  559  # \fBcrle\fR
 562  560  
 563  561  Configuration file [version 4]: /var/ld/ld.config
 564  562    Platform      32-bit MSB SPARC
 565  563    Default Library Path (ELF):  /lib:/usr/lib:/local/lib:/ISV/lib
 566  564    Trusted Directories (ELF):   /lib/secure:/usr/lib/secure  \e
 567  565                                 (system default)
 568  566  
 569  567  Command line:
 570  568    crle -l /lib:/usr/lib:/local/lib:/usr/local/lib
 571  569  .fi
 572  570  .in -2
 573  571  .sp
 574  572  
 575  573  .sp
 576  574  .LP
 577  575  In this example, the default configuration file initially did not exist.
 578  576  Therefore, the new search path \fB/local/lib\fR is appended to the system
 579  577  default. The next update appends the search path \fB/ISV/lib\fR to those paths
 580  578  already established in the configuration file.
 581  579  
 582  580  .LP
 583  581  \fBExample 3 \fRRecovering From a Bad Configuration File
 584  582  .sp
 585  583  .LP
 586  584  The following example creates a bad configuration file in the default location.
 587  585  The file can be removed by instructing the runtime linker to ignore any
 588  586  configuration file with the \fBLD_NOCONFIG\fR environment variable. Note, it is
 589  587  recommended that temporary configuration files be created and the environment
 590  588  variable \fBLD_CONFIG\fR used to experiment with these files.
 591  589  
 592  590  .sp
 593  591  .in +2
 594  592  .nf
 595  593  # \fBcrle -l /local/lib\fR
 596  594  # \fBdate\fR
 597  595  ld.so.1: date: fatal: libc.so.1: open failed:  \e
 598  596     No such file or directory
 599  597  Killed
 600  598  # \fBLD_NOCONFIG=yes rm /var/ld/ld.config\fR
 601  599  # \fBdate\fR
 602  600  Thu May 29 17:52:00 PDT 2008
 603  601  .fi
 604  602  .in -2
 605  603  .sp
 606  604  
 607  605  .sp
 608  606  .LP
 609  607  Note, the reason the configuration file is bad is because the system default
 610  608  search paths are not present. Hence, the \fBdate\fR utility is not able to
 611  609  locate the system dependencies that it required. In this case, the \fB-u\fR
 612  610  option should have been used.
 613  611  .LP
 614  612  \fBExample 4 \fRCreating and Displaying a New Default Search Path and New
 615  613  Trusted Directory for ELF Objects
 616  614  .sp
 617  615  .LP
 618  616  The following example creates and displays a new default search path and new
 619  617  trusted directory for ELF objects.
 620  618  
 621  619  .sp
 622  620  .in +2
 623  621  .nf
 624  622  # \fBcrle -l /local/lib -l /lib -l /usr/lib -s /local/lib\fR
 625  623  # \fBcrle\fR
 626  624  
 627  625  Configuration file [version 4]: /var/ld/ld.config
 628  626    Platform:     32-bit MSB SPARC
 629  627    Default Library Path (ELF):  /local/lib:/lib:/usr/lib
 630  628    Trusted Directories (ELF):   /local/lib
 631  629  
 632  630  Command line:
 633  631    crle -l /local/lib:/lib:/usr/lib -s /local/lib
 634  632  .fi
 635  633  .in -2
 636  634  .sp
 637  635  
 638  636  .sp
 639  637  .LP
 640  638  With this configuration file, third party applications could be installed in
 641  639  \fB/local/bin\fR and their associated dependencies in \fB/local/lib\fR. The
 642  640  default search path allows the applications to locate their dependencies
 643  641  without the need to set \fBLD_LIBRARY_PATH\fR. The default trusted directories
 644  642  have also been replaced with this example.
 645  643  
 646  644  .LP
 647  645  \fBExample 5 \fRCreating a Directory Cache for ELF Objects
 648  646  .sp
 649  647  .LP
 650  648  The following example creates a directory cache for ELF objects.
 651  649  
 652  650  .sp
 653  651  .in +2
 654  652  .nf
 655  653  $ \fBcrle -i /usr/dt/lib -i /usr/openwin/lib -i /lib -i /usr/lib  \e
 656  654          -c config\fR
 657  655  $ \fBldd -s ./main\fR
 658  656  \&....
 659  657     find object=libc.so.1; required by ./main
 660  658      search path=/usr/dt/lib:/usr/openwin/lib  (RUNPATH/RPATH ./main)
 661  659      trying path=/usr/dt/lib/libc.so.1
 662  660      trying path=/usr/openwin/lib/libc.so.1
 663  661      search path=/lib  (default)
 664  662      trying path=/lib/libc.so.1
 665  663          libc.so.1 =>     /lib/libc.so.1
 666  664  
 667  665  $ \fBLD_CONFIG=config ldd -s ./main\fR
 668  666  \&....
 669  667     find object=libc.so.1; required by ./main
 670  668      search path=/usr/dt/lib:/usr/openwin/lib  (RUNPATH/RPATH ./main)
 671  669      search path=/lib  (default)
 672  670      trying path=/lib/libc.so.1
 673  671          libc.so.1 =>     /lib/libc.so.1
 674  672  .fi
 675  673  .in -2
 676  674  .sp
 677  675  
 678  676  .sp
 679  677  .LP
 680  678  With this configuration, the cache reflects that the system library
 681  679  \fBlibc.so.1\fR does not exist in the directories \fB/usr/dt/lib\fR or
 682  680  \fB/usr/openwin/lib\fR. Therefore, the search for this system file ignores
 683  681  these directories even though the application's runpath indicates these paths
 684  682  should be searched.
 685  683  
 686  684  .LP
 687  685  \fBExample 6 \fRCreating an Alternative Object Cache for an ELF Executable
 688  686  .sp
 689  687  .LP
 690  688  The following example creates an alternative object cache for an ELF
 691  689  executable.
 692  690  
 693  691  .sp
 694  692  .in +2
 695  693  .nf
 696  694  $ \fBcrle -c /local/$HOST/.xterm/ld.config.xterm  \e
 697  695          -f RTLD_REL_ALL  -G /usr/openwin/bin/xterm\fR
 698  696  $ \fBln  -s /local/$HOST/.xterm/xterm  /local/$HOST/xterm\fR
 699  697  $ \fBldd /usr/local/$HOST/xterm\fR
 700  698      libXaw.so.5 =>  /local/$HOST/.xterm/libWaw.so.5  (alternate)
 701  699      libXmu.so.4 =>  /local/$HOST/.xterm/libXmu.so.4  (alternate)
 702  700      ....
 703  701      libc.so.1 =>    /local/$HOST/.xterm/libc.so.1  (alternate)
 704  702      ....
 705  703  .fi
 706  704  .in -2
 707  705  .sp
 708  706  
 709  707  .sp
 710  708  .LP
 711  709  With this configuration, a new \fBxterm\fR and its dependencies are created.
 712  710  These new objects are fully relocated to each other, and result in faster
 713  711  startup than the originating objects. The execution of this application uses
 714  712  its own specific configuration file. This model is generally more flexible than
 715  713  using the environment variable \fBLD_CONFIG\fR, as the configuration file can
 716  714  not be erroneously used by other applications such as \fBldd\fR(1) or
 717  715  \fBtruss\fR(1).
 718  716  
 719  717  .LP
 720  718  \fBExample 7 \fRCreating an Alternative Object Cache to Replace an ELF Shared
 721  719  Object
 722  720  .sp
 723  721  .LP
 724  722  The following example creates an alternative object cache to replace an ELF
 725  723  shared object.
 726  724  
 727  725  .sp
 728  726  .in +2
 729  727  .nf
 730  728  $ \fBldd /usr/bin/vi\fR
 731  729      libcurses.so.1 =>  /lib/libcurses.so.1
 732  730      ....
 733  731  
 734  732  # \fBcrle -a /lib/libcurses.so.1 -o /usr/ucblib\fR
 735  733  # \fBcrle\fR
 736  734  
 737  735  Configuration file [version 4]: /var/ld/ld.config
 738  736    Platform:     32-bit MSB SPARC
 739  737    Default Library Path (ELF):  /lib:/usr/lib  (system default)
 740  738    Trusted Directories (ELF):   /lib/secure:/usr/lib/secure  \e
 741  739                                 (system default)
 742  740  
 743  741  Directory: /lib
 744  742    libcurses.so.1  (alternate: /usr/ucblib/libcurses.so.1)
 745  743  \&....
 746  744  
 747  745  $ \fBldd /usr/bin/vi\fR
 748  746      libcurses.so.1 => /usr/ucblib/libcurses.so.1 (alternate)
 749  747      ....
 750  748  .fi
 751  749  .in -2
 752  750  .sp
 753  751  
 754  752  .sp
 755  753  .LP
 756  754  With this configuration, any dependency that would normally resolve to
 757  755  \fB/usr/lib/libcurses.so.1\fR instead resolves to
 758  756  \fB/usr/ucblib/libcurses.so.1\fR.
 759  757  
 760  758  .LP
 761  759  \fBExample 8 \fRSetting Replaceable and Permanent Environment Variables
 762  760  .sp
 763  761  .LP
 764  762  The following example sets replaceable and permanent environment variables.
 765  763  
 766  764  .sp
 767  765  .in +2
 768  766  .nf
 769  767  # \fBcrle -e LD_LIBRARY_PATH=/local/lib  \e
 770  768          -E LD_PRELOAD=preload.so.1\fR
 771  769  # \fBcrle\fR
 772  770  \&.....
 773  771  Environment Variables:
 774  772    LD_LIBRARY_PATH=/local/lib  (replaceable)
 775  773    LD_PRELOAD=preload.so.1  (permanent)
 776  774  
 777  775  \&.....
 778  776  $ \fBLD_DEBUG=files LD_PRELOAD=preload.so.2 ./main\fR
 779  777  \&.....
 780  778  18764: file=preload.so.2;  preloaded
 781  779  18764: file=/local/lib/preload.so.2  [ ELF ]; generating link map
 782  780  \&.....
 783  781  18764: file=preload.so.1;  preloaded
 784  782  18764: file=/local/lib/preload.so.1  [ ELF ]; generating link map
 785  783  \&.....
 786  784  .fi

 787  785  .in -2
 788  786  .sp
 789  787  
 790  788  .sp
 791  789  .LP
 792  790  With this configuration file, a replaceable search path has been specified
 793  791  together with a permanent preload object which becomes appended to the process
 794  792  environment definition.
 795  793  
 796  794  .SH EXIT STATUS
 797      -.sp
 798  795  .LP
 799  796  The creation or display of a configuration file results in a \fB0\fR being
 800  797  returned. Otherwise, any error condition is accompanied with a diagnostic
 801  798  message and a non-zero value being returned.
 802  799  .SH NOTES
 803      -.sp
 804  800  .LP
 805  801  The ability to tag an alternative application to use an application-specific
 806  802  configuration file, is possible if the original application contains one of the
 807  803  \fI\&.dynamic\fR tags \fBDT_FLAGS_1\fR or \fBDT_FEATURE_1\fR. Without these
 808  804  entries, a configuration file must be specified using the \fBLD_CONFIG\fR
 809  805  environment variable. Care should be exercised with this latter method as this
 810  806  environment variable is visible to any forked applications.
 811  807  .sp
 812  808  .LP
 813  809  The use of the \fB-u\fR option requires at least version 2 of \fBcrle\fR. This

 814  810  version level is evident from displaying the contents of a configuration file.
 815  811  .sp
 816  812  .in +2
 817  813  .nf
 818  814  $ \fBcrle\fR
 819  815  
 820  816  Configuration file [2]: /var/ld/ld.config
 821  817    ......
 822  818  .fi
 823  819  .in -2
 824  820  .sp
 825  821  
 826  822  .sp
 827  823  .LP
 828  824  With a version 2 configuration file, \fBcrle\fR is capable of constructing the
 829  825  command-line arguments required to regenerate the configuration file. This
 830  826  command-line construction, provides full update capabilities using the \fB-u\fR
 831  827  option. Although a version 1 configuration file update is possible, the
 832  828  configuration file contents might be insufficient for \fBcrle\fR to compute the
 833  829  entire update requirements.
 834  830  .sp
 835  831  .LP
 836  832  Configuration files contain platform specific binary data. A given
 837  833  configuration file can only be interpreted by software with the same machine
 838  834  class and byte ordering. However, the information necessary to enforce this
 839  835  restriction was not included in configuration files until \fBSXCE\fR build
 840  836  \fB41\fR. As of this \fBSXCE\fR build, configuration files have system

 841  837  identification information at the beginning of the file. This additional
 842  838  information is used by \fBcrle\fR and the runtime to check their compatibility
 843  839  with configuration files. This information also allows the \fBfile\fR(1)
 844  840  command to properly identify  configuration files. For backward compatibility,
 845  841  older files that are missing this information are still accepted, although
 846  842  without the identification and error checking that would otherwise be possible.
 847  843  When processing an update (\fB-u\fR) operation for an older file that lacks
 848  844  system information, \fBcrle\fR does not add system identification information
 849  845  to the result.
 850  846  .SH FILES
 851      -.sp
 852  847  .ne 2
 853  848  .na
 854  849  \fB\fB/var/ld/ld.config\fR\fR
 855  850  .ad
 856  851  .sp .6
 857  852  .RS 4n
 858  853  Default configuration file for 32-bit applications.
 859  854  .RE
 860  855  
 861  856  .sp

 862  857  .ne 2
 863  858  .na
 864  859  \fB\fB/var/ld/64/ld.config\fR\fR
 865  860  .ad
 866  861  .sp .6
 867  862  .RS 4n
 868  863  Default configuration file for 64-bit applications.
 869  864  .RE
 870  865  
 871  866  .sp
 872  867  .ne 2
 873  868  .na
 874  869  \fB\fB/var/tmp\fR\fR
 875  870  .ad
 876  871  .sp .6
 877  872  .RS 4n
 878  873  Default location for temporary configuration file. See \fBtempnam\fR(3C).
 879  874  .RE
 880  875  
 881  876  .sp
 882  877  .ne 2
 883  878  .na
 884  879  \fB\fB/usr/lib/lddstub\fR\fR
 885  880  .ad
 886  881  .sp .6
 887  882  .RS 4n
 888  883  Stub application that is employed to \fBdldump\fR(3C) 32-bit objects.
 889  884  .RE
 890  885  
 891  886  .sp
 892  887  .ne 2
 893  888  .na
 894  889  \fB\fB/usr/lib/64/lddstub\fR\fR
 895  890  .ad
 896  891  .sp .6
 897  892  .RS 4n
 898  893  Stub application that is employed to \fBdldump\fR(3C) 64-bit objects.
 899  894  .RE
 900  895  
 901  896  .sp
 902  897  .ne 2
 903  898  .na
 904  899  \fB\fB/usr/lib/libcrle.so.1\fR\fR
 905  900  .ad
 906  901  .sp .6
 907  902  .RS 4n
 908  903  Audit library that is employed to \fBdldump\fR(3C) 32-bit objects.
 909  904  .RE
 910  905  
 911  906  .sp

 912  907  .ne 2
 913  908  .na
 914  909  \fB\fB/usr/lib/64/libcrle.so.1\fR\fR
 915  910  .ad
 916  911  .sp .6
 917  912  .RS 4n
 918  913  Audit library that is employed to \fBdldump\fR(3C) 64-bit objects.
 919  914  .RE
 920  915  
 921  916  .SH ENVIRONMENT VARIABLES
 922      -.sp
 923  917  .LP
 924  918  There are no environment variables that are referenced by \fBcrle\fR. However,
 925  919  several environment variables affect the runtime linkers behavior in regard to
 926  920  the processing of configuration files that are created by \fBcrle\fR.
 927  921  .sp
 928  922  .ne 2
 929  923  .na
 930  924  \fB\fBLD_CONFIG\fR, \fBLD_CONFIG_32\fR and \fBLD_CONFIG_64\fR\fR
 931  925  .ad
 932  926  .sp .6

 933  927  .RS 4n
 934  928  Provide an alternative configuration file.
 935  929  .RE
 936  930  
 937  931  .sp
 938  932  .ne 2
 939  933  .na
 940  934  \fB\fBLD_NOCONFIG\fR, \fBLD_NOCONFIG_32\fR and \fBLD_NOCONFIG_64\fR\fR
 941  935  .ad
 942  936  .sp .6
 943  937  .RS 4n
 944  938  Disable configuration file processing.
 945  939  .RE
 946  940  
 947  941  .sp
 948  942  .ne 2
 949  943  .na
 950  944  \fB\fBLD_NODIRCONFIG\fR, \fBLD_NODIRCONFIG_32\fR and \fBLD_NODIRCONFIG_64\fR\fR
 951  945  .ad
 952  946  .sp .6
 953  947  .RS 4n
 954  948  Disable directory cache processing from a configuration file.
 955  949  .RE
 956  950  
 957  951  .sp
 958  952  .ne 2
 959  953  .na
 960  954  \fB\fBLD_NOENVCONFIG\fR, \fBLD_NOENVCONFIG_32\fR and \fBLD_NOENVCONFIG_64\fR\fR
 961  955  .ad
 962  956  .sp .6
 963  957  .RS 4n
 964  958  Disable environment variable processing from a configuration file.
 965  959  .RE
 966  960  
 967  961  .sp

 968  962  .ne 2
 969  963  .na
 970  964  \fB\fBLD_NOOBJALTER\fR, \fBLD_NOOBJALTER_32\fR and \fBLD_NOOBJALTER_64\fR\fR
 971  965  .ad
 972  966  .sp .6
 973  967  .RS 4n
 974  968  Disable alternative object processing from a configuration file.
 975  969  .RE
 976  970  
 977  971  .SH ATTRIBUTES
 978      -.sp
 979  972  .LP
 980  973  See \fBattributes\fR(5) for descriptions of the following attributes.
 981  974  .sp
 982  975  
 983  976  .sp
 984  977  .TS
 985  978  box;
 986  979  c | c
 987  980  l | l .
 988  981  ATTRIBUTE TYPE  ATTRIBUTE VALUE
 989  982  _
 990  983  Interface Stability     Committed
 991  984  .TE
 992  985  
 993  986  .SH SEE ALSO
 994      -.sp
 995  987  .LP
 996  988  \fBfile\fR(1), \fBld\fR(1), \fBld.so.1\fR(1), \fBdldump\fR(3C),
 997  989  \fBtempnam\fR(3C), \fBattributes\fR(5)
 998  990  .sp
 999  991  .LP
1000  992  \fILinker and Libraries Guide\fR
    

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX