User Commands crle(1)
NAME
crle - configure runtime linking environment
SYNOPSIS
crle [-64] [-a name] [-A name] [-c conf] [-e env] [-E env]
[-f flags] [-i name] [-I name] [-g name] [-G name]
[-l dir] [-o dir] [-s dir] [-t [ ELF | AOUT]] [-u] [-v]
DESCRIPTION
The crle utility provides for the creation and display of a
runtime linking configuration file. The configuration file is read and interpreted by the runtime linker, ld.so.1(1), during process startup. The runtime linker attempts to reada default configuration file for all processes. For 32-bit
processes, the default configuration file is/var/ld/ld.config. For 64-bit processes, the default confi-
guration file is /var/ld/64/ld.config.Without any arguments, or with just the -c option, crle
displays configuration information. This information includes the contents of a configuration file, any systemdefaults and the command-line required to regenerate the
configuration file. When used with any other options, a new configuration file is created or updated. The runtime linker can also be directed to an alternativeconfiguration file by setting one of the LD_CONFIG family of
environment variable. LD_CONFIG applies to both 32-bit and
64-bit programs. Since 32-bit and 64-bit configuration files
differ, a single configuration file cannot be used for bothclass of object. Hence, LD_CONFIG can adversely affect pro-
gram execution in cases where a program of one class exe-
cutes a program of the other class. In particular, it iscommon practice for the 32-bit version of standard Solaris
utilities to execute their 64-bit counterpart. LD_CONFIG
cannot be successfully used in this case. Therefore, the useof the LD_CONFIG_32 and LD_CONFIG_64 environment variables,
that precisely target the appropriate class of process, is recommended. Creating an incorrect configuration file in the standard location, /var/ld, can prevent programs from running, and can therefore be difficult to recover from. To guard against this situation, it is recommented that new configuration files first be created in a temporary location. Then set theappropriate LD_CONFIG environment variable to this new con-
figuration file. This setting causes the new configuration file to be used by the runtime linker instead of anySunOS 5.11 Last change: 6 Oct 2008 1
User Commands crle(1)
default. After verification, the new configuration file can be moved to the default location if desired. At any time,the environment variable LD_NOCONFIG can be set to any value
to instruct the runtime linker to ignore any configuration files. This setting can prove useful during experimentation. A configuration file can contain the following information. Default Search Paths The runtime linker uses a prescribed search path for locating the dynamic dependencies of an object. This search path starts with the components of anyLD_LIBRARY_PATH definition, followed by the components
of an object's runpath. Finally, any default search paths specific to the object's class are used. This last component of the search path can be expressed within the configuration file. Typically, use of this facilityshould be augmented with any system default. See the -l
and -u options.
Trusted Directories When processing a secure application, the runtime linkerrestricts the use of LD_LIBRARY_PATH searches, and $ORI-
GIN token expansion. See Security in Linker and Libraries Guide. In addition, the directories from whichpreload and audit libraries can be located are also res-
tricted. The path names that are associated with preload and audit libraries are restricted to known trusted directories. Trusted directories can be expressed within the configuration file. Typically, use of this facilityshould be augmented with any system defaults. See the -s
and -u options.
Environment Variables Any environment variable interpreted by the runtime linker can be specified within the configuration file. Directory CacheThe location of shared objects within defined direc-
tories can be maintained as a cache within the confi-
guration file. This directory cache can reduce the over-
head of searching for application dependencies.SunOS 5.11 Last change: 6 Oct 2008 2
User Commands crle(1)
Alternative Objects In conjunction with the directory cache, shared objectscan have alternative objects specified for use at run-
time. These alternate objects, can be supplied by theuser. Alternative objects can also be created by crle as
copies of shared objects fixed to known memory loca-
tions. These fixed alternative objects can require less processing at runtime than their original shared object counterpart. Defining additional default search paths, or additional trusted directories can be useful for administrators who wish to install third party software in a central location, or otherwise alter the search path of applications that might not have been coded with a suitable runpath. The declaration of alternative objects provides a means of replacing dependencies other than by using symbolic links orrequiring LD_LIBRARY_PATH settings.
The declaration of environment variables that are inter-
preted by the runtime linker provides a means of centraliz-
ing their definition for all applications.The directory cache, and crle generated alternate objects,
can provide a means of reducing the runtime startup overhead of applications. Alternative objects can be useful forapplications that require many dependencies, or whose depen-
dencies are expensive to relocate. Shared objects that con-
tain position-dependent code are often expensive to relo-
cate. Note, the system has many caching facilities that help mitigate expenses such as negative path lookups, and thusemploying crle to create a directory cache may have minimal
effect other than for some very specific cases.When alternate objects that are generated by crle are speci-
fied within a configuration file, the runtime linker per-
forms some minimal consistency verification. The alternative objects are verified against their originating objects. This verification is intended to avert application failure shouldan applications configuration information become out-of-sync
with the underlying system components. When this situation arises the flexibility offered by dynamic linking system components can be compromised. This type of application failure can be very difficult to diagnose. No verificationSunOS 5.11 Last change: 6 Oct 2008 3
User Commands crle(1)
of directory cache information is performed. Any changes to the directory structure are not seen by a process until the cache is rebuilt. System shared objects are often well tuned, and can show little benefit from being cached. The directory cache and alternative object features are typically applicable to userapplications and shared objects, and may only show improve-
ment in some very specific cases.crle creates alternate objects for the shared objects that
are discovered when using the -I and -G options, using
dldump(3C). The alternate object is created in the directoryspecified by the preceding -o option, or defaults to the
directory in which the configuration file is created. Theflags used by dldump() are specified using the -f option, or
default to RTLD_REL_RELATIVE.
OPTIONS The following options are supported.-64
Specify to process 64-bit objects, the default is 32-
bit. Use -64 to create a 64-bit specific configuration
file.-a name
Create an alternative path name for name. The alterna-
tive path name is added to the configuration file. The actual alternative file must be supplied by the user. Multiple occurrences of this option are permitted. If name is a directory, each shared object within the directory is added to the cache. If name does not exist, then name is marked in the cache as a nonexistent file.Typically, this option is used with the -o option.
-A name
Create an optional alternative path name for name. This alternative path name is added to the configuration file.This option mimics the -a option, except that if the
alternative is unavailable at runtime, the originalSunOS 5.11 Last change: 6 Oct 2008 4
User Commands crle(1)
object name is used. This model mimics the use of auxi-
liary filters. See Generating Auxiliary Filters in Linker and Libraries Guide.Typically, this option is used with the -o option.
-c conf
Specify to use the configuration file name conf. If this option is not supplied, the default configuration file is used.-e env
Specify a replaceable environment variable, env. Only environment variables that are applicable to the runtime linker are meaningful. Multiple occurrences of thisoption are permitted. This option is similar to the -E
option. However, the options differs in how configura-
tion file definitions, and process environment defini-
tions of the same name are resolved at runtime. A definition established in a configuration file can be overridden by a process environment definition, or besuppressed by a null-value process environment defini-
tion. In other words, these configuration file definitions can be replaced, or removed by the process environment at runtime.-E env
Specify a permanent environment variable, env. Only environment variables that are applicable to the runtime linker are meaningful. Multiple occurrences of thisoption are permitted. This option is similar to the -e
option. However, the option differs in how configuration file definitions, and process environment definitions of the same name are resolved at runtime. Environment variable definitions that are meaningful to the runtime linker fall into one of two categories. Singular definitions are definitions such asLD_NOLAZYLOAD=1 and LD_DEBUG_OUTPUT=file. List defini-
tions, which can take one or more values, are defini-
tions such as LD_LIBRARY_PATH=path, and
LD_DEBUG=files,details.
SunOS 5.11 Last change: 6 Oct 2008 5
User Commands crle(1)
A singular definition that is established in a confi-
guration file takes precedence over a process environ-
ment definition. A list definition that is established in a configuration file is appended to a processenvironment definition. Any definition that is esta-
blished in a configuration file can not be suppressed bya null-value process environment definition.
In other words, these configuration file definitions can not be replaced, or removed by the process environment at runtime.-f flags
Provide the symbolic flags argument to the dldump(3C) calls used to generate alternate objects. Any of theRTLD_REL flags that are defined in /usr/include/dlfcn.h
can be used. Multiple flags can be or'ed together using the "|" character. In this case, the string should be quoted to avoid expansion by the shell. If no flags values are provided the default flag isRTLD_REL_RELATIVE.
-i name
Add an individual name to the configuration cache. Mul-
tiple occurrences of this option are permitted. name canbe a shared object or a directory. If name is a direc-
tory, each shared object within the directory is added to the cache. If name does not exist, the name is marked in the cache as a nonexistent directory.-I name
Mimic the -i, and in addition any shared object that is
processed has an alternative created using dldump(3C).If the -f flag contains RTLD_REL_EXEC, then name can be
a dynamic executable, for which an alternative is created. Only one dynamic executable can be specified in this manner, as the cache that is created is specific to this application.-g name
Add the group name to the configuration cache. Eachobject is expanded to determine its dependencies. Multi-
ple occurrences of this option are permitted. name can be a dynamic executable, shared object or a directory.SunOS 5.11 Last change: 6 Oct 2008 6
User Commands crle(1)
If name is a shared object, the shared object and itsdependencies are added to the cache. If name is a direc-
tory, each shared object within the directory, and its dependencies, are added to the cache.-G name
Mimic the -g option, and in addition any shared object
that is processed has an alternative created usingdldump(3C). If name is a dynamic executable, and the -f
flag contains RTLD_REL_EXEC, then an alternative for the
dynamic executable is also created. Only one dynamic executable can be specified in this manner as the cache that is created is specific to this application.-l dir
Specify a new default search directory dir for ELF or AOUT objects. Multiple occurrences of this option are permitted. The type of object that is applicable to thesearch, is specified by the preceding -t option, or
defaults to ELF.The default search paths for 32-bit ELF objects are /lib
followed by /usr/lib. For 64-bit ELF objects, the
default search paths are /lib/64 followed by /usr/lib/64. The default search paths for AOUT objects are /usr/4lib, followed by /usr/lib and finally /usr/local/lib. Use of this option replaces the default search path.Therefore, a -l option is normally required to specify
the original system default in relation to any new pathsthat are being applied. However, if the -u option is in
effect, and a configuration file does not exist, the system defaults are added to the new configuration file. These defaults are added before the new paths specifiedwith the -l option.
-o dir
When used with either the -a or -A options, specifies
the directory dir in which any alternate objects exist.When alternative objects are created by crle, this
option specified where the alternative are created. Without this option, alternate objects exist in the directory in which the configuration file is created. Multiple occurrences of this option are permitted, theSunOS 5.11 Last change: 6 Oct 2008 7
User Commands crle(1)
directory dir being used to locate alternatives for anyfollowing command-line options. Alternative objects are
not permitted to override their associated originals.Typically, this option is used with the -a or -A
options.-s dir
Specify a new trusted directory dir for secure ELF orAOUT objects. See SECURITY in ld.so.1(1) for a defini-
tion of secure objects. See Security in Linker and Libraries Guide for a discussion of runtime restrictions imposed on secure applications. Multiple occurrences of this option are permitted. The type of object that is applicable to the search isspecified by the preceding -t option, or defaults to
ELF.The default trusted directories for secure 32-bit ELF
objects, and AOUT objects, are /lib/secure followed by/usr/lib/secure. For 64-bit secure ELF objects, the
default trusted directories are /lib/secure/64 followed by /usr/lib/secure/64.Use of this option replaces the default trusted direc-
tories. Therefore, a -s option is normally required to
specify the original system default in relation to any new directories that are being applied. However, if the-u option is in effect, and a configuration file does
not exist, the system defaults are added to the new con-
figuration file. These defaults are added before the newdirectories specified with the -l option.
-t ELF | AOUT
Toggle the object type that is applicable to any -l or
-s options that follow. The default object type is ELF.
-u
Request that a configuration file be updated, possibly with the addition of new information. Without other options, any existing configuration file is inspected and its contents recomputed. Additional arguments allow information to be appended to the recomputed contents. See NOTES.SunOS 5.11 Last change: 6 Oct 2008 8
User Commands crle(1)
If a configuration file does not exist, the configura-
tion file is created as directed by the other arguments.In the case of the -l and -s options, any system
defaults are first applied to the configuration file before the directories specified with these options. The configuration file can be in the older format thatlacks the system identification information that is nor-
mally written at the beginning of the file. In thiscase, crle does not place system identification informa-
tion into the resulting file, preserving compatibility of the file with older versions of Solaris. See NOTES.-v
Specify verbose mode. When creating a configuration file, a trace of the files that are being processed is written to the standard out. When printing the contents of a configuration file, more extensive directory and file information is provided.By default, the runtime linker attempts to read the confi-
guration file /var/ld/ld.config for each 32-bit application
processed. /var/ld/64/ld.config is read for each 64-bit
application. When processing an alternative application, theruntime linker uses a $ORIGIN/ld.config.app-name configura-
tion file if present. See NOTES. Applications can referencean alternative configuration file by setting the LD_CONFIG
environment variable. An alternative configuration file can also be specified by recording the configuration file name in the application at the time the application is built. Seethe -c option of ld(1).
EXAMPLES
Example 1 Experimenting With a Temporary Configuration File The following example creates a temporary configuration filewith a new default search path for ELF objects. The environ-
ment variable LD_CONFIG_32 is used to instruct the runtime
linker to use this configuration file for all 32-bit
processes.$ crle -c /tmp/ld.config -u -l /local/lib
$ crle -c /tmp/ld.config
Configuration file [version 4]: /tmp/ld.configPlatform: 32-bit MSB SPARC
SunOS 5.11 Last change: 6 Oct 2008 9
User Commands crle(1)
Default Library Path (ELF): /lib:/usr/lib:/local/lib Trusted Directories (ELF): /lib/secure:/usr/lib/secure \ (system default) Command line:crle -c /tmp/ld.config -l /lib:/usr/lib:/local/lib
$ LD_CONFIG_32=/tmp/ld.config date
Thu May 29 17:42:00 PDT 2008 Example 2 Updating and Displaying a New Default Search Path for ELF Objects The following example updates and displays a new default search path for ELF objects.# crle -u -l /local/lib
# crle
Configuration file [version 4]: /var/ld/ld.configPlatform: 32-bit MSB SPARC
Default Library Path (ELF): /lib:/usr/lib:/local/lib Trusted Directories (ELF): /lib/secure:/usr/lib/secure \ (system default) Command line:crle -l /lib:/usr/lib:/local/lib
# crle -u -l /ISV/lib
# crle
Configuration file [version 4]: /var/ld/ld.configPlatform 32-bit MSB SPARC
Default Library Path (ELF): /lib:/usr/lib:/local/lib:/ISV/lib Trusted Directories (ELF): /lib/secure:/usr/lib/secure \ (system default) Command line:
crle -l /lib:/usr/lib:/local/lib:/usr/local/lib
In this example, the default configuration file initially did not exist. Therefore, the new search path /local/lib is appended to the system default. The next update appends thesearch path /ISV/lib to those paths already established in the configuration file.
SunOS 5.11 Last change: 6 Oct 2008 10
User Commands crle(1)
Example 3 Recovering From a Bad Configuration File The following example creates a bad configuration file in the default location. The file can be removed by instructing the runtime linker to ignore any configuration file with theLD_NOCONFIG environment variable. Note, it is recommended
that temporary configuration files be created and theenvironment variable LD_CONFIG used to experiment with these
files.# crle -l /local/lib
# date
ld.so.1: date: fatal: libc.so.1: open failed: \ No such file or directory Killed# LD_NOCONFIG=yes rm /var/ld/ld.config
# date
Thu May 29 17:52:00 PDT 2008 Note, the reason the configuration file is bad is because the system default search paths are not present. Hence, the date utility is not able to locate the system dependenciesthat it required. In this case, the -u option should have
been used. Example 4 Creating and Displaying a New Default Search Path and New Trusted Directory for ELF Objects The following example creates and displays a new default search path and new trusted directory for ELF objects.# crle -l /local/lib -l /lib -l /usr/lib -s /local/lib
# crle
Configuration file [version 4]: /var/ld/ld.configPlatform: 32-bit MSB SPARC
Default Library Path (ELF): /local/lib:/lib:/usr/lib Trusted Directories (ELF): /local/lib Command line:crle -l /local/lib:/lib:/usr/lib -s /local/lib
SunOS 5.11 Last change: 6 Oct 2008 11
User Commands crle(1)
With this configuration file, third party applications could be installed in /local/bin and their associated dependenciesin /local/lib. The default search path allows the applica-
tions to locate their dependencies without the need to setLD_LIBRARY_PATH. The default trusted directories have also
been replaced with this example. Example 5 Creating a Directory Cache for ELF Objects The following example creates a directory cache for ELF objects.$ crle -i /usr/dt/lib -i /usr/openwin/lib -i /lib -i /usr/lib \
-c config
$ ldd -s ./main
.... find object=libc.so.1; required by ./mainsearch path=/usr/dt/lib:/usr/openwin/lib (RUNPATH/RPATH ./main) trying path=/usr/dt/lib/libc.so.1 trying path=/usr/openwin/lib/libc.so.1 search path=/lib (default) trying path=/lib/libc.so.1 libc.so.1 => /lib/libc.so.1
$ LD_CONFIG=config ldd -s ./main
.... find object=libc.so.1; required by ./mainsearch path=/usr/dt/lib:/usr/openwin/lib (RUNPATH/RPATH ./main) search path=/lib (default) trying path=/lib/libc.so.1 libc.so.1 => /lib/libc.so.1 With this configuration, the cache reflects that the system library libc.so.1 does not exist in the directories /usr/dt/lib or /usr/openwin/lib. Therefore, the search for this system file ignores these directories even though the application's runpath indicates these paths should be searched. Example 6 Creating an Alternative Object Cache for an ELF Executable The following example creates an alternative object cache for an ELF executable.
SunOS 5.11 Last change: 6 Oct 2008 12
User Commands crle(1)
$ crle -c /local/$HOST/.xterm/ld.config.xterm \
-f RTLD_REL_ALL -G /usr/openwin/bin/xterm
$ ln -s /local/$HOST/.xterm/xterm /local/$HOST/xterm
$ ldd /usr/local/$HOST/xterm
libXaw.so.5 => /local/$HOST/.xterm/libWaw.so.5 (alternate)
libXmu.so.4 => /local/$HOST/.xterm/libXmu.so.4 (alternate)
....libc.so.1 => /local/$HOST/.xterm/libc.so.1 (alternate)
.... With this configuration, a new xterm and its dependencies are created. These new objects are fully relocated to each other, and result in faster startup than the originating objects. The execution of this application uses its own specific configuration file. This model is generally moreflexible than using the environment variable LD_CONFIG, as
the configuration file can not be erroneously used by other applications such as ldd(1) or truss(1). Example 7 Creating an Alternative Object Cache to Replace an ELF Shared Object The following example creates an alternative object cache to replace an ELF shared object.$ ldd /usr/bin/vi
libcurses.so.1 => /lib/libcurses.so.1 ....# crle -a /lib/libcurses.so.1 -o /usr/ucblib
# crle
Configuration file [version 4]: /var/ld/ld.configPlatform: 32-bit MSB SPARC
Default Library Path (ELF): /lib:/usr/lib (system default) Trusted Directories (ELF): /lib/secure:/usr/lib/secure \ (system default) Directory: /lib libcurses.so.1 (alternate: /usr/ucblib/libcurses.so.1) ....$ ldd /usr/bin/vi
libcurses.so.1 => /usr/ucblib/libcurses.so.1 (alternate) ....SunOS 5.11 Last change: 6 Oct 2008 13
User Commands crle(1)
With this configuration, any dependency that would normally resolve to /usr/lib/libcurses.so.1 instead resolves to /usr/ucblib/libcurses.so.1. Example 8 Setting Replaceable and Permanent Environment Variables The following example sets replaceable and permanent environment variables.# crle -e LD_LIBRARY_PATH=/local/lib \
-E LD_PRELOAD=preload.so.1
# crle
..... Environment Variables:LD_LIBRARY_PATH=/local/lib (replaceable)
LD_PRELOAD=preload.so.1 (permanent)
.....$ LD_DEBUG=files LD_PRELOAD=preload.so.2 ./main
..... 18764: file=preload.so.2; preloaded 18764: file=/local/lib/preload.so.2 [ ELF ]; generating link map ..... 18764: file=preload.so.1; preloaded 18764: file=/local/lib/preload.so.1 [ ELF ]; generating link map ..... With this configuration file, a replaceable search path has been specified together with a permanent preload objectwhich becomes appended to the process environment defini-
tion. EXIT STATUS The creation or display of a configuration file results in a0 being returned. Otherwise, any error condition is accom-
panied with a diagnostic message and a non-zero value being
returned. NOTES The ability to tag an alternative application to use anapplication-specific configuration file, is possible if the
original application contains one of the .dynamic tagsDT_FLAGS_1 or DT_FEATURE_1. Without these entries, a confi-
guration file must be specified using the LD_CONFIG
SunOS 5.11 Last change: 6 Oct 2008 14
User Commands crle(1)
environment variable. Care should be exercised with this latter method as this environment variable is visible to any forked applications.The use of the -u option requires at least version 2 of
crle. This version level is evident from displaying the con-
tents of a configuration file.$ crle
Configuration file [2]: /var/ld/ld.config ......With a version 2 configuration file, crle is capable of con-
structing the command-line arguments required to regenerate
the configuration file. This command-line construction, pro-
vides full update capabilities using the -u option. Although
a version 1 configuration file update is possible, the con-
figuration file contents might be insufficient for crle to
compute the entire update requirements. Configuration files contain platform specific binary data. A given configuration file can only be interpreted by software with the same machine class and byte ordering. However, the information necessary to enforce this restriction was not included in configuration files until SXCE build 41. As ofthis SXCE build, configuration files have system identifica-
tion information at the beginning of the file. This addi-
tional information is used by crle and the runtime to check
their compatibility with configuration files. This informa-
tion also allows the file(1) command to properly identify configuration files. For backward compatibility, older files that are missing this information are still accepted, although without the identification and error checking thatwould otherwise be possible. When processing an update (-u)
operation for an older file that lacks system information,crle does not add system identification information to the
result. FILES /var/ld/ld.configDefault configuration file for 32-bit applications.
/var/ld/64/ld.configSunOS 5.11 Last change: 6 Oct 2008 15
User Commands crle(1)
Default configuration file for 64-bit applications.
/var/tmp Default location for temporary configuration file. See tempnam(3C). /usr/lib/lddstubStub application that is employed to dldump(3C) 32-bit
objects. /usr/lib/64/lddstubStub application that is employed to dldump(3C) 64-bit
objects./usr/lib/libcrle.so.1
Audit library that is employed to dldump(3C) 32-bit
objects./usr/lib/64/libcrle.so.1
Audit library that is employed to dldump(3C) 64-bit
objects. ENVIRONMENT VARIABLES There are no environment variables that are referenced bycrle. However, several environment variables affect the run-
time linkers behavior in regard to the processing of confi-
guration files that are created by crle.
LD_CONFIG, LD_CONFIG_32 and LD_CONFIG_64
Provide an alternative configuration file.LD_NOCONFIG, LD_NOCONFIG_32 and LD_NOCONFIG_64
Disable configuration file processing.LD_NODIRCONFIG, LD_NODIRCONFIG_32 and LD_NODIRCONFIG_64
Disable directory cache processing from a configurationSunOS 5.11 Last change: 6 Oct 2008 16
User Commands crle(1)
file.LD_NOENVCONFIG, LD_NOENVCONFIG_32 and LD_NOENVCONFIG_64
Disable environment variable processing from a confi-
guration file.LD_NOOBJALTER, LD_NOOBJALTER_32 and LD_NOOBJALTER_64
Disable alternative object processing from a configura-
tion file.ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes.____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | developer/linker ||_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
SEE ALSO
file(1), ld(1), ld.so.1(1), dldump(3C), tempnam(3C), attri-
butes(5) Linker and Libraries GuideSunOS 5.11 Last change: 6 Oct 2008 17