Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
crle(1)								       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]

       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 op-
       tions, 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 de-
	   faults. 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_LI-
       BRARY_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. Al-
       ternative objects can be	useful for applications	that require many  de-
       pendencies, or whose dependencies are expensive to relocate. Shared ob-
       jects that contain position-dependent code are often expensive to relo-
       cate.

       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  al-
       ternate	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

	   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 .

	   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  re-
	   placed, 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 re-
	   placed, 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 de-
	   fined 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  ex-
	   panded  to determine	its dependencies. Multiple occurrences of this
	   option are permitted. name can be a dynamic executable, shared  ob-
	   ject	 or a directory. If name is a shared object, the shared	object
	   and its dependencies	are added to the cache.	If name	 is  a	direc-
	   tory,  each	shared	object within the directory, and its dependen-
	   cies, 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  ob-
	   ject	 that is applicable to the search, is specified	by the preced-
	   ing -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  de-
	   fault 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

	   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 oc-
	   currences 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  ob-
	   ject	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 ob-
	   jects, 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  fi-
	   nally /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 ap-
	   plied. However, if the -u option is in effect, and a	 configuration
	   file	 does not exist, the system defaults are added to the new con-
	   figuration file. These defaults are added before the	 new  directo-
	   ries	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 ad-
	   dition of new information. Without other options, any existing con-
	   figuration file is inspected	and  its  contents  recomputed.	 Addi-
	   tional arguments allow information to be appended to	the recomputed
	   contents. See .

	   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 op-
	   tions.

       -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  ex-
	   tensive 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 . Applica-
       tions 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).

       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  ex-
       ist.  Therefore,	the new	search path /local/lib is appended to the sys-
       tem 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 di-
       rectories 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 ap-
       plication  uses its own specific	configuration file. This model is gen-
       erally 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.

       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.

       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.

       /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.

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWtoo			   |
       +-----------------------------+-----------------------------+

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

				  4 Feb	2005			       crle(1)

NAME | SYNOPSIS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=crle&sektion=1&manpath=SunOS+5.10>

home | help