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

FreeBSD Manual Pages

  
 
  

home | help
ld.so.1(1)							    ld.so.1(1)

NAME
       ld.so.1 - runtime linker	for dynamic objects

SYNOPSIS
       /lib/ld.so.1

       /lib/ld.so.1 [-e	envar] dynamic-object [object args...]

       Dynamic	applications consist of	one or more dynamic objects. A dynamic
       application is typically	a dynamic executable and one  or  more	shared
       object  dependencies.  As part of the initialization and	execution of a
       dynamic application, an interpreter is called.  This  interpreter  com-
       pletes  the  binding  of	the application	to its shared object dependen-
       cies. In	Solaris, this  interpreter  is	referred  to  as  the  runtime
       linker.

       During the link-editing of a dynamic executable,	a special .interp sec-
       tion, together with an associated program header, is created. This sec-
       tion  contains  a  pathname  specifying	the  program's interpreter. An
       interpreter pathname can	be  specified  when  the  executable  is  con-
       structed	 using	the  -I	 option	to ld(1), the link-editor. The default
       name supplied by	the link-editor	is the name  of	 the  runtime  linker,
       ld.so.1.

       During  the  process of executing a dynamic executable, the kernel maps
       the file,  and  locates	the  required  interpreter.  See  exec(2)  and
       mmap(2).	 The  kernel  maps  in,	 and transfers control to, this	inter-
       preter. Sufficient information is passed	to the	interpretor  to	 allow
       the  interpreter	to continue to bind, and then execute the application.

       In addition to initializing an application, the runtime linker provides
       services	 that allow the	application to extend its address space. Addi-
       tional shared objects can be mapped,  and  symbols  within  the	shared
       objects can be bound to.

       The runtime linker performs the following functions:

	 o  A configuration file, if in	existence, is processed. Configuration
	    files can be employed to alter default  search  paths,  provide  a
	    directory  cache, and provide alternative object dependencies. See
	    crle(1). By	default, for 32-bit objects,  the  configuration  file
	    /var/ld/ld.config  is  used.  For 64-bit objects, the default con-
	    figuration file /var/ld/64/ld.config is used. Alternative configu-
	    ration files can be	specified with the LD_CONFIG environment vari-
	    able. Alternative configuration files can also be encoded within a
	    dynamic executable by using	the -c option of ld(1).

	 o  The	 runtime linker	analyzes the application's dynamic information
	    section, .dynamic, to determine which shared  object  dependencies
	    are	required.

	 o  The	 runtime  linker  then locates and maps	in these dependencies.
	    The	dynamic	information section of each dependency	is  then  ana-
	    lyzed to determine if any additional dependencies are required.

	 o  Once  all  the  shared object dependencies are loaded, the runtime
	    linker performs any	necessary relocations. These relocations  bind
	    the	shared objects in preparation for process execution.

	 o  Any	 initialization	functions provided by the shared object	depen-
	    dencies and, possibly, by the dynamic executable are  called.  The
	    functions  are  called  in	the reverse order of the topologically
	    sorted dependencies. If cyclic dependencies	exist, the initializa-
	    tion  functions  are  called using the sorted order	with the cycle
	    removed. ldd(1) can	be used	to display the initialization order of
	    shared object dependencies.

	 o  Control is passed to the application.

	 o  During  the	 application's	execution,  the	 runtime linker	can be
	    called upon	to perform any delayed function	binding.

	 o  If any shared objects are deleted from the	process,  finalization
	    functions  are  called.  By	default, these functions are called in
	    the	order of the topologically sorted dependencies.

	 o  The	application can	also call upon the  services  of  the  runtime
	    linker  to	acquire	additional shared objects by using dlopen(3C).
	    Symbols provided by	these objects, can be bound to using dlsym(3C)

       Further details on each of the previous topics can be found in the .

       The  runtime  linker  uses  a  prescribed  search path for locating the
       dynamic dependencies of an object. The default  search  paths  are  the
       runpath	recorded in the	object,	followed by a series of	defaults.  For
       32-bit objects, the defaults are	/lib followed by /usr/lib. For	64-bit
       objects,	 the  defaults	are  /lib/64  followed	by  /usr/lib/64. These
       defaults	component can be modified using	a configuration	file  that  is
       created	with crle(1). The runpath is specified when the	dynamic	object
       is constructed using the	-R option to ld(1). The	 environment  variable
       LD_LIBRARY_PATH	can  be	 used  to  indicate directories	to be searched
       before the default directories.

   Command Line	Usage
       Typically, the runtime linker is	invoked	indirectly through executing a
       dynamic executable that declares	the runtime linker as its interpreter.
       The runtime linker can also be executed directly	from the command line.
       This  mechanism is most often employed to experiment with new implemen-
       tations of the runtime linker. Arguments	that are supplied on the  com-
       mand line consist of options that are applicable	to the runtime linker.
       Following these options is the name of the dynamic object  to  be  exe-
       cuted,  and  any	options	required by this object. Effectively, the run-
       time linker replaces any	interpreter specified by the dynamic object.

       The following option is supported:

       -e envar	       Specify a runtime linker	specific environment variable.
		       See .

       Each  environment  variable  can	be specified with a _32	or _64 suffix.
       This makes the environment variable specific, respectively,  to	32-bit
       or  64-bit  processes. This environment variable	overrides any non-suf-
       fixed version of	the environment	variable that may be in	effect.	 Envi-
       ronment	variables  specified  without  a value,	that have a _32	or _64
       suffix, effectively cancel any associated generic environment  variable
       setting.

       LD_AUDIT, LD_AUDIT_32, and LD_AUDIT_64

	   A  colon-separated  list  of	objects	that are loaded	by the runtime
	   linker. As each object is loaded, the object	is examined for	 Link-
	   Auditing  interface	routines.  The	routines  that are present are
	   called as specified in the Link-Auditing interface described	in the
	   . Also, see the -p and -P options of	ld(1).

       LD_BIND_LAZY, LD_BIND_LAZY_32, and LD_BIND_LAZY_64

	   The runtime linker's	default	mode of	performing lazy	binding	can be
	   enforced by setting the environment variable	 LD_BIND_LAZY  to  any
	   non-null  value.  This setting causes the runtime linker to perform
	   only	lazy reference relocations for all  objects  that  are	loaded
	   into	 the  process. Individual objects can request that lazy	refer-
	   ence	relocations are	performed when the object is loaded.  See  the
	   -z now option of ld(1), and dlopen(3C) with the mode	RTLD_NOW. Such
	   requests to perform lazy reference relocations are suppressed  when
	   LD_BIND_LAZY	is in effect.

	   If	both   LD_BIND_LAZY   and   LD_BIND_NOW	 are  specified,  then
	   LD_BIND_NOW takes precedence.

       LD_BIND_NOW, LD_BIND_NOW_32, and	LD_BIND_NOW_64

	   The runtime linker's	default	mode of	performing lazy	binding	can be
	   overridden  by  setting the environment variable LD_BIND_NOW	to any
	   non-null value. This	setting	causes the runtime linker  to  perform
	   both	 immediate  reference  and  lazy reference relocations for all
	   objects that	are loaded into	the process.  Individual  objects  can
	   request  that  lazy	reference  relocations	are performed when the
	   object is loaded. See the -z	now option of  ld(1),  and  dlopen(3C)
	   with	the mode RTLD_NOW.

	   If	both   LD_BIND_NOW   and   LD_BIND_LAZY	 are  specified,  then
	   LD_BIND_NOW takes precedence.

       LD_CONFIG, LD_CONFIG_32,	and LD_CONFIG_64

	   Provides an alternative configuration file. Configuration files can
	   be  employed	 to  alter  default  search paths, provide a directory
	   cache, and provide alternate	object dependencies.  See crle(1).

       LD_DEBUG, LD_DEBUG_32, and LD_DEBUG_64

	   Provides a comma, or	colon-separated	list of	tokens	to  cause  the
	   runtime  linker  to	print debugging	information to standard	error.
	   The special token help indicates the	full list of tokens available.
	   The	environment  variable  LD_DEBUG_OUTPUT can also	be supplied to
	   specify a file to which the	debugging  information	is  sent.  The
	   filename  is	suffixed with the process ID of	the application	gener-
	   ating the debugging information. See	lari(1).

       LD_DEMANGLE, LD_DEMANGLE_32, and	LD_DEMANGLE_64

	   Any symbol name used	as part	of a diagnostic	message	 is  shown  as
	   defined within an ELF file. When LD_DEMANGLE	is set to any non-null
	   value, the runtime linker attempts to  decode  (demangle)  any  C++
	   symbol name.

       LD_FLAGS, LD_FLAGS_32, and LD_FLAGS_64

	   Provides  an	 alternative  means  of	supplying environment variable
	   information.	Any of the LD_XXX environment variables	can be	speci-
	   fied	 as  a xxx token. Multiple tokens can be supplied separated by
	   commas. See .

       LD_LIBRARY_PATH,	LD_LIBRARY_PATH_32, and	LD_LIBRARY_PATH_64

	   The LD_LIBRARY_PATH	environment  variable,	if  set,  is  used  to
	   enhance  the	 search	 path  that  the  runtime  linker uses to find
	   dynamic dependencies. LD_LIBRARY_PATH specifies  a  colon-separated
	   list	 of  directories that are searched before the default directo-
	   ries. Also notice that LD_LIBRARY_PATH adds additional semantics to
	   ld(1).

       LD_LOADFLTR, LD_LOADFLTR_32, and	LD_LOADFLTR_64

	   Filters  are	 a form	of shared object. Filters allow	an alternative
	   shared object to be selected	at runtime that	provide	the  implemen-
	   tation  for any symbols that	are defined within the filter. See the
	   -f and -F options of	ld(1).	By  default,  the  alternative	shared
	   object  processing  is  deferred  until  symbol  resolution	occurs
	   against the filter. When LD_LOADFLTR	is set to any non-null	value,
	   any	filters	 are  processed	immediately when the filter is loaded.
	   Also, see the -z loadfltr option of ld(1).

       LD_NOAUDIT, LD_NOAUDIT_32, and LD_NOAUDIT_64

	   Local auditing libraries can	be  defined  within  applications  and
	   shared objects. See the -p and -P options of	ld(1). When LD_NOAUDIT
	   is set to any non-null value, the runtime linker ignores any	 local
	   auditing libraries.

       LD_NOAUXFLTR, LD_NOAUXFLTR_32, and LD_NOAUXFLTR_64

	   Auxiliary  filters  are  a form of shared object. Auxiliary filters
	   allow an alternative	shared object to be selected at	runtime	 which
	   provides the	implementation for any symbols that are	defined	within
	   the filter. See the -f option of ld(1). When	LD_NOAUXFLTR is	set to
	   any	non-null  value,  the runtime linker disables this alternative
	   shared object lookup.

       LD_NOCONFIG, LD_NOCONFIG_32, and	LD_NOCONFIG_64

	   By default the runtime linker attempts to open and process  a  con-
	   figuration file. When LD_NOCONFIG is	set to any non-null value, the
	   runtime linker disables this	configuration file processing.

       LD_NODIRCONFIG, LD_NODIRCONFIG_32, and LD_NODIRCONFIG_64

	   Provides a subset of	LD_NOCONFIG in that any	directory cache	infor-
	   mation provided in a	configuration file is ignored.

       LD_NODIRECT, LD_NODIRECT_32, and	LD_NODIRECT_64

	   Direct  binding  information	instructs the runtime linker to	search
	   directly for	a symbol in an associated object.  See the  -B	direct
	   option  of  ld(1).  Without	direct binding,	the symbol search per-
	   formed by the  runtime  linker  follows  the	 default  model.  When
	   LD_NODIRECT	is  set	 to  any  non-null  value,  the	runtime	linker
	   ignores any direct binding information.

       LD_NOENVCONFIG, LD_NOENVCONFIG_32, and LD_NOENVCONFIG_64

	   Provides a subset of	LD_NOCONFIG in that any	environment  variables
	   provided in a configuration file are	ignored.

       LD_NOLAZYLOAD, LD_NOLAZYLOAD_32,	and LD_NOLAZYLOAD_64

	   Dependencies	 that are labeled for lazy loading are not loaded into
	   memory until	explicit reference to the dependency  has  been	 made.
	   See	the  -z	lazyload option	of ld(1). When LD_NOLAZYLOAD is	set to
	   any non-null	value, the runtime linker ignores a dependencies  lazy
	   loading label and loads the dependency immediately.

       LD_NOOBJALTER, LD_NOOBJALTER_32,	and LD_NOOBJALTER_64

	   Provides  a	subset	of  LD_NOCONFIG	in that	any alternative	object
	   dependencies	provided in a configuration file are ignored.

       LD_NOVERSION, LD_NOVERSION_32, and LD_NOVERSION_64

	   By default, the runtime linker verifies  version  dependencies  for
	   the	primary	executable and all of its dependencies.	When LD_NOVER-
	   SION	is set to any non-null value, the runtime linker disables this
	   version checking.

       LD_ORIGIN, LD_ORIGIN_32,	and LD_ORIGIN_64

	   The immediate processing of $ORIGIN can be triggered	by setting the
	   environment variable	 LD_ORIGIN  to	any  non-null  value.	Before
	   Solaris  9,	this  option  was useful for applications that invoked
	   chdir(2) prior to locating dependencies that	employed  the  $ORIGIN
	   string token. The establishment of the current working directory by
	   the runtime linker is now default thus making  this	option	redun-
	   dant.

       LD_PRELOAD, LD_PRELOAD_32, and LD_PRELOAD_64

	   Provides  a	list  of  shared  objects,  separated by spaces. These
	   objects are loaded after the	program	being executed but before  any
	   other  shared  objects that the program references.	Symbol defini-
	   tions provided by the preloaded  objects  interpose	on  references
	   made	by the shared objects that the program references. Symbol def-
	   initions provided by	the preloaded objects do not interpose on  the
	   symbol definitions provided by the program.

       LD_PROFILE, LD_PROFILE_32, and LD_PROFILE_64

	   Defines  a shared object to be profiled by the runtime linker. When
	   profiling is	enabled,  a  profiling	buffer	file  is  created  and
	   mapped.  The	 name  of  the	buffer	file is	the name of the	shared
	   object being	profiled with a	.profile extension. By	default,  this
	   buffer  is  placed under /var/tmp. The environment variable LD_PRO-
	   FILE_OUTPUT can also	be supplied to indicate	an alternative	direc-
	   tory	in which to place the profiling	buffer.

	   The profiling buffer	contains profil(2) and call count information.
	   This	information is similar to the gmon.out	information  generated
	   by  programs	 that have been	linked with the	-xpg option of cc. Any
	   applications	that use the named shared object and  run  while  this
	   environment variable	is set,	accumulate data	in the profile buffer.
	   See also . The profile buffer information  can  be  examined	 using
	   gprof(1).

	   The LD_PROFILE profiling technique is an alternative	to other tech-
	   niques that might be	provided by the	compilation system. The	shared
	   object  being profiled does not have	to be instrumented in any way,
	   and LD_PROFILE should not be	combined with  a  profile-instrumented
	   application.	 See  the   for	 more  information on profiling	shared
	   objects.

       LD_SIGNAL, LD_SIGNAL_32,	and LD_SIGNAL_64

	   Provides a numeric signal number that the runtime  linker  uses  to
	   kill	 the  process  in  the	event  of  a  fatal runtime error. See
	   thr_kill(3C). By default, SIGKILL is	used. For  example,  providing
	   the alternative signal number 6 (SIGABRT), can provide for the cre-
	   ation of a core file	to aid debugging. See also the RTLD_DI_SETSIG-
	   NAL request to dlinfo(3C).

       Notice  that  environment  variable names beginning with	the characters
       'LD_' are reserved  for	possible  future  enhancements	to  ld(1)  and
       ld.so.1.

SECURITY
       Secure  processes  have	some restrictions applied to the evaluation of
       their dependencies and runpaths to prevent malicious dependency substi-
       tution or symbol	interposition.

       The  runtime linker categorizes a process as secure if the issetugid(2)
       system call returns true	for the	process.

       For 32-bit objects, the default trusted directories that	are  known  to
       the  runtime  linker  are  /lib/secure and /usr/lib/secure.  For	64-bit
       objects,	 the  default  trusted	directories  are  /lib/secure/64   and
       /usr/lib/secure/64.   The  utility crle(1) can be used to specify addi-
       tional trusted directories that are applicable for secure applications.
       Administrators  who  use	 this  technique should	ensure that the	target
       directories are suitably	protected from malicious intrusion.

       If an LD_LIBRARY_PATH family environment	variable is in	effect	for  a
       secure process, only the	trusted	directories specified by this variable
       are used	to augment the runtime linker's	search rules.

       In a secure process, runpath components that are	provided by the	appli-
       cation or any of	its dependencies are used, provided the	component is a
       full pathname, that is, the pathname starts with	a '/'.

       In a secure process, the	expansion of the  $ORIGIN  string  is  allowed
       only if the string expands to a trusted directory.

       In  a  secure  process, LD_CONFIG is ignored. A secure process uses the
       default	configuration  file,  if  a  configuration  file  exists.  See
       crle(1).

       In a secure process, LD_SIGNAL is ignored.

       Additional  objects  can	 be  loaded  with  a  secure process using the
       LD_PRELOAD, or LD_AUDIT environment variables. These  objects  must  be
       specified  as  full  pathnames or simple	file names. Full pathnames are
       restricted to known trusted directories.	Simple file names, in which no
       '/'  appears  in	 the  name,  are  located  subject  to the search path
       restrictions previously described. Simple file names  resolve  only  to
       known trusted directories.

       In  a secure process, any dependencies that consist of simple filenames
       are processed using the	pathname  restrictions	previously  described.
       Dependencies expressed as full pathnames	or relative pathnames are used
       as is. Therefore, the developer of a secure process should ensure  that
       the target directory referenced as a full pathname or relative pathname
       dependency is suitably protected	from malicious intrusion.

       When creating a secure process, relative	pathnames should not  be  used
       to  express  dependencies,  or to construct dlopen(3C) pathnames.  This
       restriction should be applied to	the application	and to	all  dependen-
       cies.

       Example 1: Using	LD_FLAGS to group environment variable information

       The  following  use of LD_FLAGS is equivalent to	setting	the individual
       environment variables LD_BIND_NOW and LD_LIBRARY_PATH for 32-bit	appli-
       cations:

       example%	LD_FLAGS_32=bind_now,library_path=/lib/one:/lib/two

       The  following  use of LD_FLAGS is equivalent to	setting	the individual
       environment variables LD_LIBRARY_PATH and LD_PRELOAD for	64-bit	appli-
       cations:

       example%	LD_FLAGS_64=library_path=/lib/one/64,preload=foo.so

       /lib/ld.so.1

	   Default runtime linker.

       /lib/libc.so.1

	   Alternate interpreter for SVID ABI compatibility.

       /usr/lib/ld.so

	   AOUT	(BCP) runtime linker.

       /usr/lib/0@0.so.1

	   A compatibility library to support null character pointers. See .

       /lib/secure and /usr/lib/secure

	   LD_PRELOAD location for secure applications.

       /lib/secure/64 and /usr/lib/secure/64

	   LD_PRELOAD location for secure 64-bit applications.

       /lib/64/ld.so.1

	   Default runtime linker for 64-bit applications.

       /usr/lib/64/0@0.so.1

	   A  64-bit compatibility library to support null character pointers.
	   See .

       /var/ld/ld.config

	   Default configuration file for 32-bit applications.

       /var/ld/64/ld.config

	   Default configuration file for 64-bit applications.

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsu			   |
       +-----------------------------+-----------------------------+

       crle(1),	 gprof(1),  lari(1),  ld(1),  ldd(1),  exec(2),	 issetugid(2),
       mmap(2),	 profil(2),  dladdr(3C), dlclose(3C), dldump(3C), dlerror(3C),
       dlinfo(3C), dlopen(3C), dlsym(3C), thr_kill(3C),	proc(4), attributes(5)

       Care  should  be	 exercised  when  using	LD_PROFILE in combination with
       other process monitoring	techniques, such as users of proc(4). Multiple
       process	monitoring  techniques	can result in deadlock conditions that
       leave the profile buffer	locked.	A locked buffer	blocks	any  processes
       that  try  to  record profiling information. To reduce this likelihood,
       the runtime linker's profile implementation determines if  the  process
       is  being  monitored  at	 startup.  If  so, profiling of	the process is
       silently	disabled. However, this	mechanism  can	not  catch  monitoring
       processes that attach to	the process during its execution.

       The  user  compatibility	library	/usr/lib/0@0.so.1 provides a mechanism
       that establishes	a value	of 0 at	location 0.  Some  applications	 exist
       that  erroneously assume	a null character pointer should	be treated the
       same as a pointer to a null string. A segmentation violation occurs  in
       these  applications  when a null	character pointer is accessed. If this
       library is added	to such	an application at  runtime  using  LD_PRELOAD,
       the  library provides an	environment that is sympathetic	to this	errant
       behavior. However, the user compatibility library is  intended  neither
       to enable the generation	of such	applications, nor to endorse this par-
       ticular programming practice.

				  1 Aug	2005			    ld.so.1(1)

NAME | SYNOPSIS | SECURITY

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

home | help