crle(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | NOTES | FILES | ATTRIBUTES | SEE ALSO

NAME

crle- configure runtime linking environment

SYNOPSIS

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]] [-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 the configuration file. When used with any other options, a new configuration file is created. The configuration file is read and interpreted by the runtime linker ld.so.1(1), during process start-up and may 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 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 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 as a cache within the configuration 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 counterpart.

Defining alternative default search paths 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 dependencies 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 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 underlying 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 applications 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 directory specified by the -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 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.

-c conf

Specifies to use the configuration file name conf. If this option is not supplied the default configuration file /var/ld/ld.config is used for 32-bit objects or /var/ld/64/ld.config for 64-bit objects. Note: it is recommended that configuration file creation be done in a temporary location, and after verification the configuration file 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 useful during experimentation.

-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 configuration 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 dependencies. Multiple occurrences of this option are permitted. 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 standard ELF or AOUT 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 default search path for standard ELF objects is /usr/lib for 32-bit objects, and /usr/lib/64 for 64-bit objects. The default search path for standard AOUT objects is /usr/4lib, /usr/lib and /usr/local/lib. Use of this option effectively replaces the default search path, and thus it is normally required that a -l option be used to specify the original default in relation to any new defaults being applied.

-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. Alternative objects are not permitted to override their associated originals.

-s dir

This option specifies a new default search directory dir for secure ELF or AOUT 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 default search path for secure ELF objects is /usr/lib for 32-bit objects and /usr/lib/64 for 64-bit objects. The default search path for secure AOUT objects is /usr/4lib, /usr/lib, /usr/ucblib and /usr/local/lib. Use of this option replaces the default search path, and thus it is normally required that a -s option be used to specify the original default in relation to any new defaults being applied.

-t ELF | AOUT

This option toggles the object type applicable to any -l or -s options that follow. The default object type is ELF.

-v

Verbose mode. Under this option a trace of the files being processed is written 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 an alternative 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 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 Creation (and display) of a new standard and secure search path for ELF objects




example% crle -l /local/lib -l /usr/lib -s /local/lib example% 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 search path allows the applications to locate their dependencies without the need to set LD_LIBRARY_PATH.

---

---

Example 2 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 library=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 library=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 applications runpath indicates they should be searched.

---

---

Example 3 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 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 themselves 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 4 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: /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 would normally 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 specific configuration file can only be achieved if the original application contains one of the .dynamic tags DT_FLAGS_1 or DT_FEATURE_1. Without these entries any application 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.

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)

SunOS 5.8  Last Revised 2 Sept 1999

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | NOTES | FILES | ATTRIBUTES | SEE ALSO