crle man page on Solaris

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
Solaris logo
[printable version]

crle(1)				 User Commands			       crle(1)

NAME
       crle - configure runtime linking environment

SYNOPSIS
       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]

DESCRIPTION
       The  crle  utility  provides  for the creation and display of a runtime
       linking configuration file. The configuration file is read  and	inter‐
       preted  by  the	runtime	 linker,  ld.so.1(1), during process start-up.
       Without any arguments, or with just the -c option, crle	displays  con‐
       figuration  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.con‐
       fig.   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 tem‐
       porary  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 verifi‐
       cation, 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  configu‐
       ration files. This setting can prove useful during experimentation.

       A configuration file can 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 com‐
	   ponents of an object's runpath. Finally, any default	 search	 paths
	   specific  to the object's type are used. This last component of the
	   search path can be expressed within the configuration  file.	 Typi‐
	   cally,  use	of  this  facility should be augmented with 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 can be used. This processing is	restricted  to
	   known  trusted  directories.	 Trusted  directories can be expressed
	   within the configuration file.  Typically,  use  of	this  facility
	   should be augmented with any system defaults. See the -s option.

       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 depen‐
	   dencies.

       Alternative Objects

	   In conjunction with the directory cache, shared  objects  can  have
	   alternative	objects	 specified for use at runtime. These alternate
	   objects, can be supplied by the user. Alternative objects can  also
	   be  created by crle as copies of shared objects fixed to known mem‐
	   ory 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 direc‐
       tories 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 ver‐
       ification. The alternative objects are verified against their originat‐
       ing 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 compro‐
       mised. This type of application failure can be very difficult to	 diag‐
       nose.  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 discov‐
       ered 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.

OPTIONS
       The following options are supported.

       -64

	   Specify to process 64-bit objects, the default is 32-bit.

       -a name

	   Create an alternative pathname for name. The	 alternative  pathname
	   is added 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. If
	   name does not exist, then name is marked in the cache as a nonexis‐
	   tent file.

	   Typically, this option is used with the -o option.

       -A name

	   Create  an optional alternative pathname for name. This alternative
	   pathname is added to the configuration file.

	   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

	   Specify  to use the configuration file name conf. If this option is
	   not supplied, the default configuration file is used.

       -e env

	   Specify a replaceable environment variable, env.  Only  environment
	   variables that are applicable to the runtime linker are meaningful.
	   Multiple occurrences of this option are permitted. This  option  is
	   similar to the -E option.  However, the options differs in how con‐
	   figuration 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

	   Specify a permanent environment  variable,  env.  Only  environment
	   variables that are applicable to the runtime linker are meaningful.
	   Multiple occurrences of this option are permitted. This  option  is
	   similar  to the -e option.  However, the option differs in how con‐
	   figuration file definitions, and process environment definitions of
	   the same name are resolved at runtime.

	   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 def‐
	   inition  that is established in a configuration file is appended to
	   a process environment definition. Any  definition  that  is	estab‐
	   lished  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

	   Provide the symbolic flags argument to the dldump(3C) calls used to
	   generate alternate objects. Any of  the  RTLD_REL  flags  that  are
	   defined  in /usr/include/dlfcn.h can be used. Multiple flags can be
	   or'ed together using the "|" character. In this  case,  the	string
	   should  be quoted to avoid expansion by the shell. If no flags val‐
	   ues are provided the default flag is RTLD_REL_RELATIVE.

       -i name

	   Add an individual name to the configuration cache. Multiple	occur‐
	   rences of this option are permitted. name can be a shared object or
	   a directory. If name is a directory, each shared object within  the
	   directory  is  added to the cache. If name does not exist, the name
	   is marked in the cache as a nonexistent directory.

       -I name

	   Mimic the -i, and in addition any shared object that	 is  processed
	   has	an  alternative	 created using dldump(3C). If the -f flag con‐
	   tains RTLD_REL_EXEC, then name can be  a  dynamic  executable,  for
	   which an alternative is created. Only one dynamic executable can be
	   specified in this manner, as the cache that is created is  specific
	   to this application.

       -g name

	   Add	the  group  name  to  the  configuration cache. Each object is
	   expanded to determine its  dependencies.  Multiple  occurrences  of
	   this option are permitted. name can be a dynamic executable, shared
	   object or a directory. If name  is  a  shared  object,  the	shared
	   object  and	its  dependencies are added to the cache. If name is a
	   directory, each shared object within the directory, and its	depen‐
	   dencies, are added to the cache.

       -G name

	   Mimic the -g option, and in addition any shared object that is pro‐
	   cessed has an alternative created using dldump(3C). 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
	   that is created is specific to this application.

       -l dir

	   Specify a new default search directory dir for ELF or AOUT objects.
	   Multiple  occurrences  of  this  option  are permitted. The type of
	   object that is applicable to the search, is specified by  the  pre‐
	   ceding -t option, or defaults to ELF.

	   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.  How‐
	   ever,  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

	   When used with either the -a or -A options, specifies the directory
	   dir	in which any alternate objects exist. When alternative objects
	   are created by crle, this option specified  where  the  alternative
	   are	created.  Without  this option, alternate objects 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 permitted to override their associated
	   originals.

	   Typically, this option is used with the -a or -A options.

       -s dir

	   Specify 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 that is applicable to the search is specified by the preced‐
	   ing -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 fol‐
	   lowed 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. There‐
	   fore, a -s option is normally required to specify the original sys‐
	   tem default in relation to  any  new	 directories  that  are	 being
	   applied.  However,  if the -u option is in effect, and a configura‐
	   tion file does not exist, the system defaults are added to the  new
	   configuration  file. These defaults are added before the new direc‐
	   tories specified with the -l option.

       -t ELF | AOUT

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

       -u

	   Request  that  a  configuration  file be updated, possibly with the
	   addition of new information. 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, 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 con‐
	   figuration  file  before  the  directories  specified  with	 these
	   options.

       -v

	   Specify  verbose  mode. When creating a configuration file, a trace
	   of the files that are 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 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 process‐
       ing  an	alternative  application,  the	runtime	 linker	 uses  a $ORI‐
       GIN/ld.config.app-name configuration file if present. See NOTES. Appli‐
       cations	can reference an alternative configuration file by setting the
       LD_CONFIG environment variable. See ld.so.1(1). An alternative configu‐
       ration  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).

EXAMPLES
       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	 with‐
       out  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/open‐
       win/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 applica‐
       tions 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	 vari‐
       ables:

	 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 speci‐
       fied together with a permanent preload object which becomes appended to
       the process environment definition.

EXIT STATUS
       The  creation  or  display of a configuration file results in a 0 being
       returned. Otherwise, any error condition is accompanied with a diagnos‐
       tic message and a non-zero value being returned.

NOTES
       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_CON‐
       FIG  environment	 variable.  Care  should be exercised with this latter
       method as this environment variable is visible to any  forked  applica‐
       tions.

       The use of the -u option requires at least version 2 of crle. This ver‐
       sion 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.

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 that is employed to dldump(3C) 32-bit objects.

       /usr/lib/64/lddstub

	   Stub application that is employed to dldump(3C) 64-bit objects.

       /usr/lib/libcrle.so.1

	   Audit library that is employed to dldump(3C) 32-bit objects.

       /usr/lib/64/libcrle.so.1

	   Audit library that is employed to dldump(3C) 64-bit objects.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Availability		     │SUNWtoo			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │Stable			   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       ld(1), ld.so.1(1), dldump(3C), tempnam(3C), attributes(5)

       Linker and Libraries Guide

SunOS 5.10			  4 Feb 2005			       crle(1)
[top]

List of man pages available for Solaris

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net