Name
crle - configure runtime linking environment
Synopsis
crle [ -64 ] [ -a name ] [ -c conf ] [ -f flags ] [ -i name
] [ -I name ] [ -gname ] [ -G name ] [ -l dir ] [ -o dir ]
[ -s dir ] [ -t [ ELF | AOUT ] ] [ -v]
Description
The crle utility provides for the creation and display of a
runtime linkingconfiguration file. Without any arguments,
or with just the -c option, crledisplays the contents of
the configuration file. When used with any otheroptions, a
new configuration file is created. The configuration file
is readand interpreted by the runtime linker ld.so.1(1) ,
during process start-up andmay contain the following
information:
Default Search Paths
The runtime linker uses a prescribed search path for
locating the dynamicdependencies of an object. This search
path starts with the components of anyLD_LIBRARY_PATH
definition, followed by the components of an
object'srunpath and finally any defaults specific to the
object's type. This lastcomponent of the search path can be
expressed within the configuration file.Note: typical use
of this facility should augment any system defaults; see
the-l and -s options.
Directory Cache
The location of shared objects within defined directories
can be maintained asa cache within the configuration file.
This directory cache can reduce theoverhead of searching
for application dependencies.
Alternative Objects
In conjunction with the directory cache, shared objects may
have alternativeobjects specified for use at runtime. These
alternate objects may be suppliedby the user, or can be
created by crle as copies of shared objects fixed toknown
memory locations. These fixed alternative objects can
require lessprocessing at runtime than their original
shared object counterpart.
Defining alternative default search paths can beuseful for administrators who wish to install third party software in a centrallocation, or otherwise alter the search path of applications that may not havebeen coded with suitable runpaths.
Defining user supplied alternative objects provides ameans of replacing dependencies other than via symbolic links or requiringLD_LIBRARY_PATH settings.
The directory cache and crle generated alternateobjects can provide a means of reducing the runtime start-up overhead ofapplications that require many dependencies, or whose dependencies areexpensive to relocate (this may be the case when shared objects containposition-dependent code).
When crle generated alternate objects are specifiedwithin a configuration file, ld.so.1(1) performs some minimal consistencyverification of the alternative objects against their originating objects. Thisverification is intended to avert application failure should an applicationsconfiguration information become out-of-sync with the underlying systemcomponents. When this situation arises the flexibility offered by dynamiclinking system components may be compromised, and diagnosing the applicationfailure may be difficult. Note: no verification of directory cache informationis performed. Any changes to the directory structure will not be seen by aprocess until the cache is rebuilt.
System shared objects are often well tuned and mayhave no benefit being cached. The directory cache and alternative objectfeatures are typically applicable to user applications and sharedobjects.
crle creates alternate objects for the shared objectsdiscovered when using the -I and -G options by calls to dldump(3DL) . Thealternate object is created in the directory specified by the -o option, ordefaults to the directory in which the configuration file is created. The flagsused for the dldump() are specified using the -f option, or default toRTLD_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
configuration file. The actualalternative file must be
supplied by the user. Multiple occurrences of thisoption
are permitted. If name is a directory each shared object
within thedirectory is added to the cache.
-c conf
Specifies to use the configuration file name conf. If this
option is notsupplied the default configuration file
/var/ld/ld.config is used for 32-bitobjects or
/var/ld/64/ld.config for 64-bit objects. Note: it is
recommendedthat configuration file creation be done in a
temporary location, and afterverification the configuration
file moved to the default location if desired.Setting the
environment variable LD_NOCONFIG to any value results in
theruntime linker ignoring any configuration files, and may
prove useful duringexperimentation.
-f flags
This option provides the symbolic flags argument to the
dldump(3DL) calls usedto generate alternate objects. Any of
the RTLD_REL flags defined in/usr/include/dlfcn.h can be
used. Multiple flags can be or'ed togetherusing the «|»
character, and in this case the string should bequoted to
avoid expansion by the shell. If no flags values are
provided thedefault flag is RTLD_REL_RELATIVE.
-i name
This option adds an individual name to the configuration
cache. Multipleoccurrences of this option are permitted.
name may be a shared object or adirectory. If name is a
directory each shared object within the directory isadded
to the cache. Note: if name does not exist it is marked in
the cache as anonexistent directory.
-I name
This option is the same as -i and in addition any shared
objects havealternatives created via dldump(3DL) . If the
-f flag contains RTLD_REL_EXECthen name may be a dynamic
executable, for which an alternative is created.Only one
dynamic executable can be specified in this manner as the
cachecreated is specific to this application.
-g name
This option adds the group name to the configuration cache.
Each object isexpanded to determine its dependencies.
Multiple occurrences of this option arepermitted. name may
be a dynamic executable, shared object or a directory.
Thename itself, if it is a shared object, and its
dependencies are added to thecache. If name is a directory
each shared object within the directory, and
itsdependencies, are added to the cache.
-G name
This option is the same as -g and in addition any shared
objects havealternatives created via dldump(3DL) . If name
is a dynamic executable, and the-f flag contains
RTLD_REL_EXEC, then an alternative for the dynamic
executableis also created. Only one dynamic executable can
be specified in this manner asthe cache created is specific
to this application.
-l dir
This option specifies a new default search directory dir
for standard ELF orAOUT objects. Multiple occurrences of
this option are permitted. The type ofobject applicable to
the search is specified by the preceding -t option,
ordefaults to ELF.
The default search path for standard ELF objects is
/usr/lib for 32-bitobjects, and /usr/lib/64 for 64-bit
objects. The default search path forstandard AOUT objects
is /usr/4lib, /usr/lib and /usr/local/lib. Use of
thisoption effectively replaces the default search path,
and thus it is normallyrequired that a -l option be used to
specify the original default in relationto any new defaults
being applied.
-o dir
This option specifies the directory dir in which any
alternate objects will becreated. Without this option
alternate objects are created in the directory inwhich the
configuration file is created. Alternative objects are not
permittedto override their associated originals.
-s dir
This option specifies a new default search directory dir
for secure ELF orAOUT objects. Multiple occurrences of this
option are permitted. The type ofobject applicable to the
search is specified by the preceding -t option, ordefaults
to ELF.
The default search path for secure ELF objects is /usr/lib
for 32-bit objectsand /usr/lib/64 for 64-bit objects. The
default search path for secure AOUTobjects is /usr/4lib,
/usr/lib, /usr/ucblib and /usr/local/lib. Use of thisoption
replaces the default search path, and thus it is normally
required thata -s option be used to specify the original
default in relation to any newdefaults being
applied.
-t ELF | AOUT
This option toggles the object type applicable to any -l or
-s options thatfollow. The default object type is ELF.
-v
Verbose mode. Under this option a trace of the files being
processed iswritten to the standard out.
By default the runtime linker attempts to read the
configuration file/var/ld/ld.config for each 32-bit
application it processes or/var/ld/64/ld.config for each
64-bit application. When processing analternative
application the runtime linker will use
a$ORIGIN/ld.config.app-name configuration file if present
(see NOTES).Applications may reference an alternative
configuration file either by settingthe LD_CONFIG
environment variable (see ld.so.1(1) ), or by recording
aconfiguration file name in the application at the time it
is built using thelink-editors -c option (see ld(1)
).
Examples
Example 1: Creation (and display) of a new standard and
secure search path forELF objects
example% crle -l /local/lib -l /usr/lib -s /local/libexample% crle
Configuration file:
/var/ld/ld.config
Default Library Path (ELF): /local/lib:/usr/lib
Secure Directories (ELF):
/local/lib
With this configuration, third party applications may be
installed in/local/bin and their associated dependencies in
/local/lib. The default searchpath allows the applications
to locate their dependencies without the need toset
LD_LIBRARY_PATH.
Example 2: Creation of a directory cache for ELFobjects
example% crle -i /usr/dt/lib -i
/usr/openwin/lib -i/usr/lib \ -c config
example% ldd -s ./main
....
find library=libc.so.1; required by ./main
searchpath=/usr/dt/lib:/usr/openwin/lib (RPATH ./main)
tryingpath=/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 library=libc.so.1; required by ./main
searchpath=/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.1does not exist in the directories
/usr/dt/lib or /usr/openwin/lib. Thereforethe search for
this system file ignores these directories even though
theapplications runpath indicates they should be
searched.
Example 3: Creation of an alternative object cache foran ELF executable
example% crle -c
/local/$HOST/.xterm/ld.config -fRTLD_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. Thesenew objects are fully relocated to
themselves and result in faster start-upthan the
originating objects. Note: the execution of this
application uses itsown specific configuration file. This
model is generally more flexible thanusing the environment
variable LD_CONFIG as the configuration file will not
beerroneously used by other applications such as ldd(1) or
truss(1) .
Example 4: Creating an alternative object cache toreplace an ELF shared object
example% ldd /usr/sbin/vold
libthread.so.1 => /usr/lib/libthread.so.1
....
example% crle -a /usr/lib/libthread.so.1 -o/usr/lib/lwp example% crle
Configuration file: /var/ld/ld.config
Directory: /usr/lib
/usr/lib/libthread.so.1 (alternate:
/usr/lib/lwp/libthread.so.1)
example% ldd /usr/sbin/vold
libthread.so.1 => /usr/lib/lwp/libthread.so.1
(alternate) ....
With this configuration, any dependency that wouldnormally resolve to /usr/lib/libthread.so.1 will instead resolve to/usr/lib/lwp/libthread.so.1. See threads(3THR) .
Notes
Tagging an alternative application to use an application
specificconfiguration file can only be achieved if the
original application containsone of the .dynamic tags
DT_FLAGS_1 or DT_FEATURE_1. Without these entries
anyapplication specific configuration file must be
specified using the LD_CONFIGenvironment variable. Care
should be exercised with this latter method as
thisenvironment variable will be visible to any forked
applications.
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
attributes:
+-----------------------------+-----------------------------+
|
ATTRIBUTE TYPE | ATTRIBUTE
VALUE+-----------------------------+-----------------------------+
|Availability
|SUNWtoo
+-----------------------------+-----------------------------+
See Also
ld(1) , ld.so.1(1) , dldump(3DL) , tempnam(3C) ,
threads(3THR) ,attributes(5)