Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Apropos / Subsearch:
optional field

ld.so.1(1)                       User Commands                      ld.so.1(1)

       ld.so.1 - runtime linker for dynamic objects


       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

       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,

       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
       Linker and Libraries Guide.

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

       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

       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
           Linker  and  Libraries  Guide.  Also,  see the -p and -P options of

       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 during
           process initialization, before transferring control to the applica-
           tion. Also, see the -z now option of ld(1).

       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.


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


           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


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


           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.


           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.


           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.


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


           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.


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


           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.


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


           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-


           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.


           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  NOTES.  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 Linker and Libraries Guide for  more  informa-
           tion 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

       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

       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-

       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-

       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-

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


           Default runtime linker.


           Alternate interpreter for SVID ABI compatibility.


           AOUT (BCP) runtime linker.


           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.


           Default runtime linker for 64-bit applications.


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


           Default configuration file for 32-bit applications.


           Default configuration file for 64-bit applications.

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

       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).  ATTRIBUTE TYPEATTRIBUTE VALUE AvailabilitySUNWcsu

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

       Linker and Libraries Guide

       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.

SunOS 5.10                        14 Apr 2004                       ld.so.1(1)