crle
User Commands crle(1)NAME
crle - configure runtime linking environmentSYNOPSIS
crle [ -64 ] [ -a name ] [ -c conf ] [ -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 SunOS 5.8 Last change: 5 Jan 2001 1 User Commands crle(1) augment 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. 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. 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 crle generated alternate objects are specified within a configuration file, ld.so.1(1) performs some minimal con- sistency verification of the alternative objects against their originating objects. This verification is intended to avert application failure should an applications configura- tion information become out-of-sync with the underlying sys- tem components. When this situation arises the flexibility offered by dynamic linking system components may be comprom- ised, and diagnosing the application failure may be diffi- cult. 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. SunOS 5.8 Last change: 5 Jan 2001 2 User Commands crle(1) 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. -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 SunOS 5.8 Last change: 5 Jan 2001 3 User Commands crle(1) 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 will be created. Without this option alternate objects are created in the directory in which the configuration file is created. Multiple occurrences of this option are permitted, the SunOS 5.8 Last change: 5 Jan 2001 4 User Commands crle(1) directory dir being used to locate alternatives for any following command-line options. Alternative objects are not permitted 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 SunOS 5.8 Last change: 5 Jan 2001 5 User Commands crle(1) 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 [2]: /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 [2]: /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 SunOS 5.8 Last change: 5 Jan 2001 6 User Commands crle(1) 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 -f RTLD_REL_ALL \ -G /usr/openwin/bin/xterm SunOS 5.8 Last change: 5 Jan 2001 7 User Commands crle(1) 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/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 [2]: /var/ld/ld.config Default Library Path (ELF): /usr/lib system(default) Trusted Directories (ELF): /usr/lib/secure system(default) Directory: /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 would normally resolve to /usr/lib/libthread.so.1 will instead resolve to /usr/lib/lwp/libthread.so.1. See threads(3THR). 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 SunOS 5.8 Last change: 5 Jan 2001 8 User Commands crle(1) 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 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 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. SunOS 5.8 Last change: 5 Jan 2001 9 User Commands crle(1)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), threads(3THR), attributes(5) SunOS 5.8 Last change: 5 Jan 2001 10