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]
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 start-up. Without any arguments, or with just the -c option, crle displays configuration 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.config. 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 temporary 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 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
Trusted Directories
Directory Cache
Alternative Objects
Environment Variables
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 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 verification. The alternative objects are verified against their originating 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 compromised. This type of application failure can be very difficult to diagnose. 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 discovered 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.
The following options are supported.
-64
-a name
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
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
-e env
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
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 definition that is established in a configuration file is appended to a process environment definition. Any definition that is established 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
-i name
-I name
-g name
-G name
-l dir
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. 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 specified with the -l option.
-o dir
Typically, this option is used with the -a or -A options.
-s dir
Multiple occurrences of this option are permitted. The type of object that is applicable to the search is specified by the preceding -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 followed 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. 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 configuration file. These defaults are added before the new directories specified with the -l option.
-t ELF | AOUT
-u
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 configuration file before the directories specified with these options.
-v
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 processing an alternative application, the runtime linker uses a $ORIGIN/ld.config.app-name configuration file if present. See NOTES. Applications can reference an alternative configuration file by setting the LD_CONFIG environment variable. See ld.so.1(1). An alternative configuration 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).
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 without 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/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 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 applications 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 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 definition.
The creation or display of a configuration file results in a 0 being returned. Otherwise, any error condition is accompanied with a diagnostic message and a non-zero value being returned.
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_CONFIG 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 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.
/var/ld/ld.config
/var/ld/64/ld.config
/var/tmp
/usr/lib/lddstub
/usr/lib/64/lddstub
/usr/lib/libcrle.so.1
/usr/lib/64/libcrle.so.1
See attributes(5) for descriptions of the following attributes:
| |||||||||
ld(1), ld.so.1(1), dldump(3C), tempnam(3C), attributes(5)
Linker and Libraries Guide