crle(1) User Commands crle(1)NAMEcrle - configure runtime linking environment
SYNOPSIScrle [-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 inter‐
preted by the runtime linker, ld.so.1(1), during process start-up.
Without any arguments, or with just the -c option, crle displays con‐
figuration information. This information includes the contents of a
configuration file, any system defaults and the command-line required
to regenerate the configuration file. When used with any other options,
a new configuration file is created or updated.
For 32-bit objects, the default configuration file is /var/ld/ld.con‐
fig. For 64-bit objects, the default configuration file is
/var/ld/64/ld.config.
When creating a new configuration file, first create the file in a tem‐
porary location. The environment variable LD_CONFIG can then be set to
this new configuration file. This setting causes the new configuration
to be used by the runtime linker instead of any default. After verifi‐
cation, 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 configu‐
ration 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 any LD_LIBRARY_PATH definition, followed by the com‐
ponents of an object's runpath. Finally, any default search paths
specific to the object's type are used. This last component of the
search path can be expressed within the configuration file. Typi‐
cally, use of this facility should be augmented with any system
defaults. See the -l option.
Trusted Directories
When processing a secure application, the runtime linker restricts
the use of LD_LIBRARY_PATH and the directories from which preload
and audit libraries can be used. This processing is restricted to
known trusted directories. Trusted directories can be expressed
within the configuration file. Typically, use of this facility
should be augmented with any system defaults. See the -s option.
Directory Cache
The location of shared objects within defined directories can be
maintained as a cache within the configuration file. This directory
cache can reduce the overhead of searching for application depen‐
dencies.
Alternative Objects
In conjunction with the directory cache, shared objects can have
alternative objects specified for use at runtime. These alternate
objects, can be supplied by the user. Alternative objects can also
be created by crle as copies of shared objects fixed to known mem‐
ory locations. These fixed alternative objects can require less
processing at runtime than their original shared object counter‐
part.
Environment Variables
Any environment variable interpreted by the runtime linker can be
specified within the configuration file.
Defining alternative default search paths, or additional trusted direc‐
tories 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 suitable runpaths.
The declaration of alternative objects, provides a means of replacing
dependencies other than by using symbolic links, or requiring
LD_LIBRARY_PATH settings.
The declaration of environment variables that are interpreted by the
runtime linker, provides a means of centralizing their definition for
all applications.
The directory cache, and crle generated alternate objects, can provide
a means of reducing the runtime start-up overhead of applications.
Alternative objects can be useful for applications that require many
dependencies, or whose dependencies are expensive to relocate. Shared
objects that contain position-dependent code are often expensive to
relocate.
When alternate objects that are generated by crle are specified within
a configuration file, ld.so.1(1) performs some minimal consistency ver‐
ification. The alternative objects are verified against their originat‐
ing objects. This verification is intended to avert application failure
should an 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 compro‐
mised. This type of application failure can be very difficult to diag‐
nose. No verification 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 user applications and shared objects.
crle creates alternate objects for the shared objects that are discov‐
ered when using the -I and -G options, by calls to dldump(3C). The
alternate object is created in the directory specified by the preceding
-o option, or defaults to the directory in which the configuration file
is created. The flags used for the 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.
-a name
Create an alternative pathname for name. The alternative pathname
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 nonexis‐
tent file.
Typically, this option is used with the -o option.
-A name
Create an optional alternative pathname for name. This alternative
pathname is added to the configuration file.
This option mimics the -a option, except that if the alternative is
unavailable at runtime, the original object name is used. This
model mimics the use of auxiliary filters. See the 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 this option are permitted. This option is
similar to the -E option. However, the options differs in how con‐
figuration file definitions, and process environment definitions of
the same name are resolved at runtime.
A definition established in a configuration file can be overridden
by a process environment definition, or be suppressed by a null-
value process environment definition.
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 this option are permitted. This option is
similar to the -e option. However, the option differs in how con‐
figuration 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 as LD_NOLAZYLOAD=1 and LD_DEBUG_OUTPUT=file. List
definitions, which can take one or more values, are definitions
such as LD_LIBRARY_PATH=path, and LD_DEBUG=files,details.
A singular definition that is established in a configuration file
takes precedence over a process environment definition. A list def‐
inition that is established in a configuration file is appended to
a process environment definition. Any definition that is estab‐
lished in a configuration file can not be suppressed by a 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 the RTLD_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 val‐
ues are provided the default flag is RTLD_REL_RELATIVE.
-i name
Add an individual name to the configuration cache. Multiple occur‐
rences of this option are permitted. name can be a shared object or
a directory. If name is a directory, 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 con‐
tains 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. Each object is
expanded to determine its dependencies. Multiple occurrences of
this option are permitted. name can be a dynamic executable, shared
object or a directory. If name is a shared object, the shared
object and its dependencies are added to the cache. If name is a
directory, each shared object within the directory, and its depen‐
dencies, are added to the cache.
-G name
Mimic the -g option, and in addition any shared object that is pro‐
cessed has an alternative created using dldump(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 the search, is specified by the pre‐
ceding -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 paths that are being applied. How‐
ever, 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 specified with
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, the directory dir being
used to locate alternatives for any following 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 or AOUT objects.
See SECURITY in ld.so.1(1) for a definition of secure objects.
Multiple occurrences of this option are permitted. The type of
object that is applicable to the search is specified by the preced‐
ing -t option, or defaults to ELF.
The default trusted directories for secure 32-bit ELF objects are
/lib/secure followed by /usr/lib/secure. For 64-bit secure ELF
objects, the default trusted directories are /lib/secure/64 fol‐
lowed by /usr/lib/secure/64.
The default trusted directories for secure AOUT objects are
/usr/4lib, followed by /usr/lib, followed by /usr/ucblib, and
finally /usr/local/lib.
Use of this option replaces the default trusted directories. There‐
fore, a -s option is normally required to specify the original sys‐
tem default in relation to any new directories that are being
applied. However, if the -u option is in effect, and a configura‐
tion file does not exist, the system defaults are added to the new
configuration file. These defaults are added before the new direc‐
tories 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. Addi‐
tional arguments allow information to be appended to the recomputed
contents. See NOTES.
If a configuration file does not exist, the configuration 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 con‐
figuration file before the directories specified with these
options.
-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 configuration file
/var/ld/ld.config for each 32-bit application processesed.
/var/ld/64/ld.config is read for each 64-bit application. When process‐
ing an alternative application, the runtime linker uses a $ORI‐
GIN/ld.config.app-name configuration file if present. See NOTES. Appli‐
cations can reference an alternative configuration file by setting the
LD_CONFIG environment variable. See ld.so.1(1). An alternative configu‐
ration file can also be specified by recording the configuration file
name in the application at the time the application is built. See the
-c option of ld(1).
EXAMPLES
Example 1 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:
example% crle-u -l /local/lib
example% crle
Configuration file [version 4]: /var/ld/ld.config
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
example% crle-u -l /usr/local/lib
example% crle
Configuration file [version 4]: /var/ld/ld.config
Default Library Path (ELF): /lib:/usr/lib:/local/lib:/usr/local/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 the search path /usr/local/lib
to those paths already established in the configuration file.
Example 2 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:
example% crle-l /local/lib -l /lib -l /usr/lib -s /local/lib
example% crle
Configuration file [version 4]: /var/ld/ld.config
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
With this configuration, third party applications could be installed in
/local/bin and their associated dependencies in /local/lib. The default
search path allows the applications to locate their dependencies with‐
out the need to set LD_LIBRARY_PATH. The default trusted directories
have also been replaced with this example.
Example 3 Creating a Directory Cache for ELF Objects
The following example creates a directory cache for ELF objects:
example% crle-i /usr/dt/lib -i /usr/openwin/lib -i /lib -i /usr/lib \
-c config
example% ldd -s ./main
....
find object=libc.so.1; required by ./main
search path=/usr/dt/lib:/usr/openwin/lib (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
example% LD_CONFIG=config ldd -s ./main
....
find object=libc.so.1; required by ./main
search path=/usr/dt/lib:/usr/openwin/lib (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/open‐
win/lib. Therefore, the search for this system file ignores these
directories even though the application's runpath indicates these paths
should be searched.
Example 4 Creating an Alternative Object Cache for an ELF Executable
The following example creates an alternative object cache for an ELF
executable:
example% crle-c /local/$HOST/.xterm/ld.config.xterm \
-f RTLD_REL_ALL -G /usr/openwin/bin/xterm
example% ln -s /local/$HOST/.xterm/xterm /local/$HOST/xterm
example% 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 start-up than the originating objects. The execution of this
application uses its own specific configuration file. This model is
generally more flexible than using the environment variable LD_CONFIG,
as the configuration file can not be erroneously used by other applica‐
tions such as ldd(1) or truss(1).
Example 5 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:
example% ldd /usr/bin/vi
libcurses.so.1 => /lib/libcurses.so.1
....
example% crle-a /lib/libcurses.so.1 -o /usr/ucblib
example% crle
Configuration file [version 4]: /var/ld/ld.config
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)
....
example% ldd /usr/bin/vi
libcurses.so.1 => /usr/ucblib/libcurses.so.1 (alternate)
....
With this configuration, any dependency that would normally resolve to
/usr/lib/libcurses.so.1 instead resolves to /usr/ucblib/libcurses.so.1.
Example 6 Setting Replaceable and Permanent Environment Variables
The following example sets replaceable and permanent environment vari‐
ables:
example% crle-e LD_LIBRARY_PATH=/local/lib \
-E LD_PRELOAD=preload.so.1
example% crle
.....
Environment Variables:
LD_LIBRARY_PATH=/local/lib (replaceable)
LD_PRELOAD=preload.so.1 (permanent)
.....
example% 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 speci‐
fied together with a permanent preload object which becomes appended to
the process environment definition.
EXIT STATUS
The creation or display of a configuration file results in a 0 being
returned. Otherwise, any error condition is accompanied with a diagnos‐
tic message and a non-zero value being returned.
NOTES
The ability to tag an alternative application to use an application-
specific configuration file, is possible if the original application
contains one of the .dynamic tags DT_FLAGS_1 or DT_FEATURE_1. Without
these entries, a configuration file must be specified using the LD_CON‐
FIG environment variable. Care should be exercised with this latter
method as this environment variable is visible to any forked applica‐
tions.
The use of the -u option requires at least version 2 of crle. This ver‐
sion level is evident from displaying the contents of a configuration
file:
example% crle
Configuration file [2]: /var/ld/ld.config
......
With a version 2 configuration file, crle is capable of constructing
the command-line arguments required to regenerate the configuration
file. This command-line construction, provides full update capabilities
using the -u option. Although a version 1 configuration file update is
possible, the configuration file contents might be insufficient for
crle to compute the entire update requirements.
FILES
/var/ld/ld.config
Default configuration file for 32-bit applications.
/var/ld/64/ld.config
Default configuration file for 64-bit applications.
/var/tmp
Default location for temporary configuration file. See tempnam(3C).
/usr/lib/lddstub
Stub application that is employed to dldump(3C) 32-bit objects.
/usr/lib/64/lddstub
Stub 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.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWtoo │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Stable │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOld(1), ld.so.1(1), dldump(3C), tempnam(3C), attributes(5)
Linker and Libraries Guide
SunOS 5.10 4 Feb 2005 crle(1)