RTLD(1)                    OpenBSD Reference Manual                    RTLD(1)

NAME
     ld.so - run-time link-editor



DESCRIPTION
     ld.so is a self-contained, position independent program image providing
     run-time support for loading and link-editing shared objects into a pro-
     cess's address space. It uses the data structures (see link(5)) contained
     within dynamically linked programs to determine which shared libraries
     are needed and loads them at a convenient virtual address using the
     mmap(2) system call.

     After all shared libraries have been successfully loaded, ld.so proceeds
     to resolve external references from both the main program and all objects
     loaded. A mechanism is provided for initialization routines to be called,
     on a per-object basis, giving a shared object an opportunity to perform
     any extra set-up, before execution of the program proper begins.  ld.so
     looks for a symbol named .init in each object's symbol table. If present,
     this symbol is assumed to represent a C-function declared as void
     .init(void), which is then called. Similarly, a void .fini(void) function
     is called just before an object is unloaded from the process address
     space as a result of calling dlclose(3).  Note that while an object's
     .init is always called, whether the object is loaded automatically at
     program startup or programatically by using dlopen(3),  the .fini func-
     tion is called only on `last dlclose(3)'.

     This mechanism is exploited by the system-supplied C++ constructor ini-
     tialization code located in /usr/lib/c++rt.o. This file should be includ-
     ed in the list of object-code files passed to ld(1) when building a
     shared C++ library.

     ld.so is itself a shared object that is initially loaded by the startup
     module crt0. Since a.out(5) formats do not provide easy access to the
     file header from within a running process, crt0 uses the special symbol
     _DYNAMIC to determine whether a program is in fact dynamically linked or
     not. Whenever the linker ld(1) has relocated this symbol to a location
     other than 0, crt0 assumes the services of ld.so are needed (see link(5)
     for details) . crt0 passes control to rtld's entry point before the pro-
     gram's main() routine is called. Thus, ld.so can complete the link-edit-
     ing process before the dynamic program calls upon services of any dynamic
     library.

     To quickly locate the required shared objects in the filesystem, ld.so
     may use a ``hints'' file, prepared by the ldconfig(8) utility, in which
     the full path specification of the shared objects can be looked up by
     hashing on the 3-tuple <library-name, major-version-number,
     minor-version-number>.

     ld.so recognises a number of environment variables that can be used to
     modify its behaviour as follows:

     LD_LIBRARY_PATH                   A colon separated list of directories,
                                       overriding the default search path for
                                       shared libraries.  This variable is ig-
                                       nored for set-user-ID and set-group-ID
                                       executables.

     LD_PRELOAD                        A colon seperate list of library names
                                       to load before any of the regular li-
                                       braries are loaded.  This variable is
                                       ignored for set-user-ID and set-group-
                                       ID executables.

     LD_WARN_NON_PURE_CODE             When set, issue a warning whenever a
                                       link-editing operation requires modifi-
                                       cation of the text segment of some
                                       loaded object. This is usually indica-
                                       tive of an incorrectly built library.

     LD_SUPPRESS_WARNINGS              When set, no warning messages of any
                                       kind are issued. Normally, a warning is
                                       given if satisfactorily versioned li-
                                       brary could not be found.

     LD_TRACE_LOADED_OBJECTS           When set, causes ld.so to exit after
                                       loading the shared objects and printing
                                       a summary which includes the absolute
                                       pathnames of all objects, to standard
                                       output.

     LD_TRACE_LOADED_OBJECTS_FMT1

     LD_TRACE_LOADED_OBJECTS_FMT2      When set, these variables are inter-
                                       preted as format strings a la printf(3)
                                       to customize the trace output and are
                                       used by ldd(1)'s  -f option and allows
                                       ldd(1) to be operated as a filter more
                                       conveniently.  The following conver-
                                       sions can be used:

                                       %a    The main program's name  (also
                                             known as``__progname'').

                                       %A    The value of the environment
                                             variable
                                             LD_TRACE_LOADED_OBJECTS_PROGNAME

                                       %o    The library name.

                                       %m    The library's major version num-
                                             ber.

                                       %n    The library's minor version num-
                                             ber.

                                       %p    The full pathname as determined
                                             by rtld's library search rules.

                                       %x    The library's load address.

                                       Additionally, \n and \t are recognised
                                       and have their usual meaning.

     LD_NO_INTERN_SEARCH               When set, ld.so does not process any
                                       internal search paths that were record-
                                       ed in the executable.

     LD_NOSTD_PATH                     When set, do not include a set of
                                       built-in standard directory paths for
                                       searching. This might be useful when
                                       running on a system with a completely
                                       non-standard filesystem layout.

FILES
     /var/run/ld.so.hints     library location hints built by ldconfig(8)

SEE ALSO
     ld(1),  link(5),  ldconfig(8)

HISTORY
     The shared library model employed first appeared in SunOS 4.0.


OpenBSD 2.6                      June 27, 1995                               3