libexec/ld.aout_so/ld.aout_so.1

   1 .\"     $NetBSD: ld.aout_so.1,v 1.8 2008/04/30 13:10:52 martin Exp $
   2 .\"
   3 .\" Copyright (c) 1998 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Paul Kranenburg.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd March 24, 2000
  31 .Dt LD.AOUT_SO 1
  32 .Os
  33 .Sh NAME
  34 .Nm ld.so
  35 .Nd run-time link-editor
  36 .Sh DESCRIPTION
  37 .Nm
  38 is a self-contained, position independent program image
  39 providing run-time support for loading and link-editing
  40 shared objects into a process' address space.
  41 It uses the data structures
  42 .Po
  43 see
  44 .Xr link 5
  45 .Pc
  46 contained within dynamically linked programs to determine which shared
  47 libraries are needed and loads them at a convenient virtual address
  48 using the
  49 .Xr mmap 2
  50 system call.
  51 .Pp
  52 After all shared libraries have been successfully loaded,
  53 .Nm
  54 proceeds to resolve external references from both the main program and
  55 all objects loaded.
  56 A mechanism is provided for initialization routines to be called,
  57 on a per-object basis, giving a shared object an opportunity
  58 to perform any extra set-up, before execution of the program proper begins.
  59 .Nm
  60 looks for a symbol named
  61 .Em .init
  62 in each object's symbol table.
  63 If present, this symbol is assumed to represent a C-function declared as
  64 .Ft void
  65 .Fn .init "void" ,
  66 which is then called.
  67 Similarly, a
  68 .Ft void
  69 .Fn .fini "void"
  70 function is called just before an object is unloaded from the process
  71 address space as a result of calling
  72 .Xr dlclose 3 .
  73 Note that while an object's
  74 .Em .init
  75 is always called, whether the object is loaded automatically at program
  76 startup or programmatically by using
  77 .Xr dlopen 3 ,
  78 the
  79 .Em .fini
  80 function is called only on
  81 .Sq last Xr dlclose 3 .
  82 .Pp
  83 This mechanism is exploited by the system-supplied C++ constructor
  84 initialization code located in
  85 .Pa /usr/lib/c++rt.o .
  86 This file should be included in the list of object-code files passed to
  87 .Xr ld 1
  88 when building a shared C++ library.
  89 .Pp
  90 .Nm
  91 is itself a shared object that is initially loaded by the startup module
  92 .Em crt0 .
  93 Since
  94 .Xr a.out 5
  95 formats do not provide easy access to the file header from within a running
  96 process,
  97 .Em crt0
  98 uses the special symbol
  99 .Va _DYNAMIC
 100 to determine whether a program is in fact dynamically linked or not.
 101 Whenever the linker
 102 .Xr ld 1
 103 has relocated this symbol to a location other than 0,
 104 .Em crt0
 105 assumes the services of
 106 .Nm
 107 are needed
 108 .Po
 109 see
 110 .Xr link 5
 111 for details
 112 .Pc .
 113 .Em crt0
 114 passes control to
 115 .Nm rtld Ns 's
 116 entry point before the program's
 117 .Fn main
 118 routine is called.
 119 Thus,
 120 .Nm
 121 can complete the link-editing process before the dynamic program calls upon
 122 services of any dynamic library.
 123 .Pp
 124 To quickly locate the required shared objects in the filesystem,
 125 .Nm
 126 may use a
 127 .Dq hints
 128 file, prepared by the
 129 .Xr ldconfig 8
 130 utility, in which the full path specification of the shared objects can be
 131 looked up by hashing on the 3-tuple
 132 .Ao
 133 library-name, major-version-number, minor-version-number
 134 .Ac Ns \&.
 135 .Pp
 136 .Nm
 137 recognizes a number of environment variables that can be used to modify
 138 its behavior as follows:
 139 .Pp
 140 .\" intentionally not the longest
 141 .Bl -tag -width LD_TRACE_LOADED_OBJECTS
 142 .It Ev LD_LIBRARY_PATH
 143 A colon separated list of directories, overriding the default search path
 144 for shared libraries.
 145 .It Ev LD_PRELOAD
 146 A colon separated list of shared object filenames to be loaded
 147 .Em after
 148 the main program but
 149 .Em before
 150 its shared object dependencies.
 151 .It Ev LD_WARN_NON_PURE_CODE
 152 When set, issue a warning whenever a link-editing operation requires
 153 modification of the text segment of some loaded object.
 154 This is usually indicative of an incorrectly built library.
 155 .It Ev LD_SUPPRESS_WARNINGS
 156 When set, no warning messages of any kind are issued.
 157 Normally, a warning is given if satisfactorily versioned
 158 library could not be found.
 159 .It Ev LD_TRACE_LOADED_OBJECTS
 160 When set, causes
 161 .Nm
 162 to exit after loading the shared objects and printing a summary which includes
 163 the absolute pathnames of all objects, to standard output.
 164 .It Ev LD_TRACE_LOADED_OBJECTS_FMT1
 165 .It Ev LD_TRACE_LOADED_OBJECTS_FMT2
 166 When set, these variables are interpreted as format strings a la
 167 .Xr printf 3
 168 to customize the trace output and are used by
 169 .Xr ldd 1 Ns 's
 170 .Fl f
 171 option and allows
 172 .Xr ldd 1
 173 to be operated as a filter more conveniently.
 174 The following conversions can be used:
 175 .Bl -tag -width xxxx
 176 .It \&%a
 177 The main program's name
 178 .Po also known as
 179 .Dq __progname
 180 .Pc .
 181 .It \&%A
 182 The value of the environment variable
 183 .Ev LD_TRACE_LOADED_OBJECTS_PROGNAME
 184 .It \&%o
 185 The library name.
 186 .It \&%m
 187 The library's major version number.
 188 .It \&%n
 189 The library's minor version number.
 190 .It \&%p
 191 The full pathname as determined by
 192 .Nm rtld Ns 's
 193 library search rules.
 194 .It \&%x
 195 The library's load address.
 196 .El
 197 .Pp
 198 Additionally,
 199 .Sy \en
 200 and
 201 .Sy \et
 202 are recognized and have their usual meaning.
 203 .It Ev LD_NO_INTERN_SEARCH
 204 When set,
 205 .Nm
 206 does not process any internal search paths that were recorded in the
 207 executable.
 208 .It Ev LD_NOSTD_PATH
 209 When set, do not include a set of built-in standard directory paths for
 210 searching.
 211 This might be useful when running on a system with a completely
 212 non-standard filesystem layout.
 213 .El
 214 .Sh FILES
 215 .Bl -tag -width /var/run/ld.so.hintsXXX -compact
 216 .It Pa /var/run/ld.so.hints
 217 library location hints built by
 218 .Xr ldconfig 8
 219 .El
 220 .Sh SEE ALSO
 221 .Xr ld 1 ,
 222 .Xr ld.elf_so 1 ,
 223 .Xr ld.so 1 ,
 224 .Xr link 5 ,
 225 .Xr ldconfig 8
 226 .Sh HISTORY
 227 The shared library model employed first appeared in SunOS 4.0.
 228 .Sh SECURITY CONSIDERATIONS
 229 The environment variables
 230 .Ev LD_LIBRARY_PATH
 231 and
 232 .Ev LD_PRELOAD
 233 are not honored when executing in a set-user-ID or set-group-ID environment.
 234 This action is taken to prevent malicious substitution of shared object
 235 dependencies or interposition of symbols.