crle(1)
NAME
crle - configure runtime linking environment
SYNOPSIS
crle [-64] [-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. Without any arguments,
or with just the -c option, crle displays 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. The configuration file is read and interpreted
by the runtime linker, ld.so.1(1), during process start-up.
The default configuration file is /var/ld/ld.config for 32-
bit objects and /var/ld/64/ld.config for 64-bit objects.
Note: It is recommended that any new configuration file is
first created in a temporary location. The environment vari-
able LD_CONFIG can be set to this new configuration file to
cause its use by the runtime linker instead of any default.
After verification, the new configuration file can be moved
to the default location if desired. Setting the environment
variable LD_NOCONFIG to any value results in the runtime
linker ignoring any configuration files, and may prove use-
ful during experimentation.
The configuration file may contain the following informa-
tion:
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 components
of an object's runpath and finally any defaults
specific to the object's type. This last component of
the search path can be expressed within the configura-
tion file. Note: Typical use of this facility should
augment 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 may
be used to known trusted directories. These trusted
directories can be expressed within the configuration
file. Note: Typical use of this facility should aug-
ment any system defaults; see the -s option.
Directory Cache
The 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
overhead of searching for application dependencies.
Alternative Objects
In conjunction with the directory cache, shared
objects may have alternative objects specified for use
at runtime. These alternate objects may be supplied by
the user, or can be created by crle as copies of
shared objects fixed to known memory 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 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 may
not have been coded with suitable runpaths.
Defining user supplied alternative objects provides a means
of replacing dependencies other than via symbolic links or
requiring LD_LIBRARY_PATH settings.
Defining runtime linker environment variables 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 that require many dependencies, or whose depen-
dencies are expensive to relocate (this may be the case when
shared objects contain position-dependent code).
When alternate objects generated by crle are specified
within a configuration file, ld.so.1(1) performs some
minimal consistency verification of the alternative objects
against their originating objects. This verification is
intended to avert application failure should an applications
configuration information become out-of-sync with the under-
lying system components. When this situation arises the
flexibility offered by dynamic linking system components may
be compromised, and diagnosing the application failure may
be difficult. Note: No verification of directory cache
information is performed. Any changes to the directory
structure will not be seen by a process until the cache is
rebuilt.
System shared objects are often well tuned and may have no
benefit being cached. The directory cache and alternative
object features are typically applicable to user applica-
tions and shared objects.
crle creates alternate objects for the shared objects
discovered when using the -I and -G options by calls to
dldump(3DL). The alternate object is created in the direc-
tory 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 Specifies to process 64-bit objects, the default is
32-bit.
-a name
This option adds an alternative to name to the confi-
guration 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, it is marked in the
cache as a nonexistent file.
-c conf
Specifies to use the configuration file name conf. If
this option is not supplied the default configuration
file is used.
-e env
This option specifies a replaceable environment vari-
able, env. Only environment variables applicable to
the runtime linker are meaningful. Multiple
occurrences of this option are permitted. This option
is similar to the -E option, but differs in how confi-
guration 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
This option specifies a permanent environment vari-
able, env. Only environment variables applicable to
the runtime linker are meaningful. Multiple
occurrences of this option are permitted. This option
is similar to the -e option, but differs in how confi-
guration file definitions and process environment
definitions of the same name are resolved at runtime.
Environment variable definitions meaningful to the
runtime linker fall into one of two categories, that
is, singular definitions such as LD_NOLAZYLOAD=1 and
LD_DEBUG_OUTPUT=file, or list definitions which can
take one or more values such as LD_LIBRARY_PATH=path,
and LD_DEBUG=files,details.
A singular definition established in a configuration
file will take precedence over a process environment
definition. A list definition established in a confi-
guration file will be appended to a process environ-
ment definition. Any definition established in a con-
figuration 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 environ-
ment at runtime.
-f flags
This option provides the symbolic flags argument to
the dldump(3DL) calls used to generate alternate
objects. Any of the RTLD_REL flags defined in
/usr/include/dlfcn.h can be used. Multiple flags can
be or'ed together using the "|" character, and in this
case the string should be quoted to avoid expansion by
the shell. If no flags values are provided the default
flag is RTLD_REL_RELATIVE.
-i name
This option adds an individual name to the configura-
tion cache. Multiple occurrences of this option are
permitted. name may be a shared object or a directory.
If name is a directory each shared object within the
directory is added to the cache. Note: If name does
not exist, it is marked in the cache as a nonexistent
directory.
-I name
This option is the same as -i and in addition any
shared objects have alternatives created via
dldump(3DL). If the -f flag contains RTLD_REL_EXEC
then name may be a dynamic executable, for which an
alternative is created. Only one dynamic executable
can be specified in this manner as the cache created
is specific to this application.
-g name
This option adds the group name to the configuration
cache. Each object is expanded to determine its depen-
dencies. Multiple occurrences of this option are per-
mitted. name may be a dynamic executable, shared
object or a directory. The name itself, if it is a
shared object, and its dependencies are added to the
cache. If name is a directory each shared object
within the directory, and its dependencies, are added
to the cache.
-G name
This option is the same as -g and in addition any
shared objects have alternatives created via
dldump(3DL). 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 created is specific to this application.
-l dir
This option specifies a new default search directory
dir for ELF or AOUT objects. Multiple occurrences of
this option are permitted. The type of object applica-
ble to the search is specified by the preceding -t
option, or defaults to ELF.
The system default search path for ELF objects is
/usr/lib for 32-bit objects, and /usr/lib/64 for 64-
bit objects. The system default search paths for AOUT
objects is /usr/4lib, /usr/lib and /usr/local/lib.
Use of this option replaces the system default search
path, and thus it is normally required that a -l
option be used to specify the original system default
in relation to any new paths 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 before the new paths speci-
fied with the -l option.
-o dir
This option specifies the directory dir in which any
alternate objects must exist (in the case of using the
-a option), or will be created (in the case of alter-
natives created by crle). Without this option, alter-
nate objects will 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 per-
mitted to override their associated originals.
-s dir
This option specifies 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 applicable to the search is specified
by the preceding -t option, or defaults to ELF.
The system default trusted directory for secure ELF
objects is /usr/lib/secure for 32-bit objects and
/usr/lib/secure/64 for 64-bit objects. The system
default trusted directories for secure AOUT objects
are /usr/4lib, /usr/lib, /usr/ucblib, and
/usr/local/lib.
Use of this option replaces the system default trusted
directories, and thus it is normally required that a
-s option be used to specify the original system
default in relation to any new directories 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 before the new
directories specified with the -s option.
-t ELF | AOUT
This option toggles the object type applicable to any
-l or -s options that follow. The default object type
is ELF.
-u This option requests that a configuration file be
updated, possibly with the addition of new informa-
tion. 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 it will be
created as directed by the other arguments. In the
case of the -l and -s options any system defaults will
first be applied to the configuration file before the
directories specified with these options.
-v Verbose mode. When creating a configuration file, a
trace of the files 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
it processes or /var/ld/64/ld.config for each 64-bit appli-
cation. When processing an alternative application, the run-
time linker will use a $ORIGIN/ld.config.app-name configura-
tion file if present (see NOTES). Applications may reference
an alternative configuration file either by setting the
LD_CONFIG environment variable (see ld.so.1(1)), or by
recording a configuration file name in the application at
the time it is built using the link-editors -c option (see
ld(1)).
EXAMPLES
Example 1: Update (and display) of a new default search path
for ELF objects
example% crle -u -l /local/lib
example% crle
Configuration file [3]: /var/ld/ld.config
Default Library Path (ELF): /usr/lib:/local/lib
Trusted Directories (ELF): /usr/lib/secure (system default)
Command line:
crle -l /usr/lib:/local/lib
example% crle -u -l /usr/local/lib
example% crle
Configuration file [3]: /var/ld/ld.config
Default Library Path (ELF): /usr/lib:/local/lib:/usr/local/lib
Trusted Directories (ELF): /usr/lib/secure (system default)
Command line:
crle -l /usr/lib:/local/lib:/usr/local/lib
In this example, the default configuration file initially
did not exist, and thus the new search path /local/lib is
appended to the system default. The next update appends the
search path /usr/local/lib to those already established in
the configuration file.
Example 2: Creation (and display) of a new default search
path and new trusted directory for ELF objects
example% crle -l /local/lib -l /usr/lib -s /local/lib
example% crle
Configuration file [2]: /var/ld/ld.config
Default Library Path (ELF): /local/lib:/usr/lib
Trusted Directories (ELF): /local/lib
Command line:
crle -l /local/lib:/usr/lib -s /local/lib
With this configuration, third party applications may be
installed in /local/bin and their associated dependencies in
/local/lib. The default search path allows the applications
to locate their dependencies without the need to set
LD_LIBRARY_PATH. Note: The system default trusted directory
has been replaced with this example.
Example 3: Creation of a directory cache for ELF objects
example% crle -i /usr/dt/lib -i /usr/openwin/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=/usr/lib (default)
trying path=/usr/lib/libc.so.1
libc.so.1 => /usr/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=/usr/lib (default)
trying path=/usr/lib/libc.so.1
libc.so.1 => /usr/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 they should be searched.
Example 4: Creation of 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 them-
selves and result in faster start-up than the originating
objects. Note: 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 will not be erroneously used by
other applications such as ldd(1) or truss(1).
Example 5: Creating an alternative object cache to replace
an ELF shared object
example% ldd /usr/bin/vi
libcurses.so.1 => /usr/lib/libcurses.so.1
....
example% crle -a /usr/lib/libcurses.so.1 -o /usr/ucblib
example% crle
Configuration file [3]: /var/ld/ld.config
Default Library Path (ELF): /usr/lib (system default)
Trusted Directories (ELF): /usr/lib/secure (system default)
Directory: /usr/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 will instead resolve to
/usr/ucblib/libcurses.so.1.
Example 6: Setting replaceable and permanent environment
variables
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 specified together with a permanent preload object
which becomes appended to the process environment defini-
tion.
EXIT STATUS
The creation or display of a configuration file results in a
0 being returned; otherwise any error condition is accom-
panied with a diagnostic message and a non-zero value being
returned.
NOTES
Tagging an alternative application to use an application
specific configuration file can only be achieved if the ori-
ginal application contains one of the .dynamic tags
DT_FLAGS_1 or DT_FEATURE_1. Without these entries any appli-
cation specific configuration file must be specified using
the LD_CONFIG environment variable. Care should be exercised
with this latter method as this environment variable will be
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:
example% 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 and to provide full update capabili-
ties. Although the update of a version 1 configuration file
is possible, the contents of the configuration file may be
insufficient for crle to compute the entire update require-
ments.
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 employed to dldump(3DL) 32-bit
objects.
/usr/lib/64/lddstub
Stub application employed to dldump(3DL) 64-bit
objects.
/usr/lib/libcrle.so.1
Audit library employed to dldump(3DL) 32-bit objects.
/usr/lib/64/libcrle.so.1
Audit library employed to dldump(3DL) 64-bit objects.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWtoo |
|_____________________________|_____________________________|
SEE ALSO
ld(1), ld.so.1(1), dldump(3DL), tempnam(3C), attributes(5)
Man(1) output converted with
man2html