doc/man/man1/dyld.1

   1 .TH DYLD 1 "December 14, 2009" "Apple Inc."
   2 .SH NAME
   3 dyld \- the dynamic link editor
   4 .SH SYNOPSIS
   5 DYLD_FRAMEWORK_PATH
   6 .br
   7 DYLD_FALLBACK_FRAMEWORK_PATH
   8 .br
   9 DYLD_VERSIONED_FRAMEWORK_PATH
  10 .br
  11 DYLD_LIBRARY_PATH
  12 .br
  13 DYLD_FALLBACK_LIBRARY_PATH
  14 .br
  15 DYLD_VERSIONED_LIBRARY_PATH
  16 .br
  17 DYLD_PRINT_TO_FILE
  18 .br
  19 DYLD_ROOT_PATH
  20 .br
  21 DYLD_SHARED_REGION
  22 .br
  23 DYLD_INSERT_LIBRARIES
  24 .br
  25 DYLD_FORCE_FLAT_NAMESPACE
  26 .br
  27 DYLD_IMAGE_SUFFIX
  28 .br
  29 DYLD_PRINT_OPTS
  30 .br
  31 DYLD_PRINT_ENV
  32 .br
  33 DYLD_PRINT_LIBRARIES
  34 .br
  35 DYLD_PRINT_LIBRARIES_POST_LAUNCH
  36 .br
  37 DYLD_BIND_AT_LAUNCH
  38 .br
  39 DYLD_DISABLE_DOFS
  40 .br
  41 DYLD_PRINT_APIS
  42 .br
  43 DYLD_PRINT_BINDINGS
  44 .br
  45 DYLD_PRINT_INITIALIZERS
  46 .br
  47 DYLD_PRINT_REBASINGS
  48 .br
  49 DYLD_PRINT_SEGMENTS
  50 .br
  51 DYLD_PRINT_STATISTICS
  52 .br
  53 DYLD_PRINT_DOFS
  54 .br
  55 DYLD_PRINT_RPATHS
  56 .br
  57 DYLD_SHARED_CACHE_DIR
  58 .br
  59 DYLD_SHARED_CACHE_DONT_VALIDATE
  60 .SH DESCRIPTION
  61 The dynamic linker uses the following environment variables.
  62 They affect any program that uses the dynamic linker.
  63 .TP
  64 .B DYLD_FRAMEWORK_PATH
  65 This is a colon separated list of directories that contain frameworks.
  66 The dynamic linker searches these directories before it searches for the
  67 framework by its install name.
  68 It allows you to test new versions of existing
  69 frameworks. (A framework is a library install name that ends in the form
  70 XXX.framework/Versions/YYY/XXX or XXX.framework/XXX, where XXX and YYY are any
  71 name.)
  72 .IP
  73 For each framework that a program uses, the dynamic linker looks for the
  74 framework in each directory in
  75 .SM DYLD_FRAMEWORK_PATH
  76 in turn. If it looks in all the directories and can't find the framework, it
  77 searches the directories in
  78 .SM DYLD_LIBRARY_PATH
  79 in turn. If it still can't find the framework, it then searches
  80 .SM DYLD_FALLBACK_FRAMEWORK_PATH
  81 and
  82 .SM DYLD_FALLBACK_LIBRARY_PATH
  83 in turn.
  84 .IP
  85 Use the
  86 .B \-L
  87 option to
  88 .IR otool (1).
  89 to discover the frameworks and shared libraries that the executable
  90 is linked against.
  91 .TP
  92 .B DYLD_FALLBACK_FRAMEWORK_PATH
  93 This is a colon separated list of directories that contain frameworks.
  94 It is used as the default location for frameworks not found in their install
  95 path.
  96
  97 By default, it is set to
  98 /Library/Frameworks:/Network/Library/Frameworks:/System/Library/Frameworks
  99 .TP
 100 .B DYLD_VERSIONED_FRAMEWORK_PATH
 101 This is a colon separated list of directories that contain potential override frameworks.
 102 The dynamic linker searches these directories for frameworks.  For
 103 each framework found dyld looks at its LC_ID_DYLIB and gets the current_version
 104 and install name.  Dyld then looks for the framework at the install name path.
 105 Whichever has the larger current_version value will be used in the process whenever
 106 a framework with that install name is required.  This is similar to DYLD_FRAMEWORK_PATH
 107 except instead of always overriding, it only overrides is the supplied framework is newer.
 108 Note: dyld does not check the framework's Info.plist to find its version.  Dyld only
 109 checks the -currrent_version number supplied when the framework was created.
 110 .TP
 111 .B DYLD_LIBRARY_PATH
 112 This is a colon separated list of directories that contain libraries. The
 113 dynamic linker searches these directories before it searches the default
 114 locations for libraries. It allows you to test new versions of existing
 115 libraries.
 116 .IP
 117 For each library that a program uses, the dynamic linker looks for it in each
 118 directory in
 119 .SM DYLD_LIBRARY_PATH
 120 in turn. If it still can't find the library, it then searches
 121 .SM DYLD_FALLBACK_FRAMEWORK_PATH
 122 and
 123 .SM DYLD_FALLBACK_LIBRARY_PATH
 124 in turn.
 125 .IP
 126 Use the
 127 .B \-L
 128 option to
 129 .IR otool (1).
 130 to discover the frameworks and shared libraries that the executable
 131 is linked against.
 132 .TP
 133 .B DYLD_FALLBACK_LIBRARY_PATH
 134 This is a colon separated list of directories that contain libraries.
 135 It is used as the default location for libraries not found in their install
 136 path.
 137 By default, it is set
 138 to $(HOME)/lib:/usr/local/lib:/lib:/usr/lib.
 139 .TP
 140 .B DYLD_VERSIONED_LIBRARY_PATH
 141 This is a colon separated list of directories that contain potential override libraries.
 142 The dynamic linker searches these directories for dynamic libraries.  For
 143 each library found dyld looks at its LC_ID_DYLIB and gets the current_version
 144 and install name.  Dyld then looks for the library at the install name path.
 145 Whichever has the larger current_version value will be used in the process whenever
 146 a dylib with that install name is required.  This is similar to DYLD_LIBRARY_PATH
 147 except instead of always overriding, it only overrides is the supplied library is newer.
 148 .TP
 149 .B DYLD_PRINT_TO_FILE
 150 This is a path to a (writable) file. Normally, the dynamic linker writes all
 151 logging output (triggered by DYLD_PRINT_* settings) to file descriptor 2
 152 (which is usually stderr).  But this setting causes the dynamic linker to
 153 write logging output to the specified file.
 154 .TP
 155 .B DYLD_ROOT_PATH
 156 This is a colon separated list of directories.  The dynamic linker will prepend each of
 157 this directory paths to every image access until a file is found.
 158 .TP
 159 .B DYLD_SHARED_REGION
 160 This can be "use" (the default), "avoid", or "private".  Setting it to
 161 "avoid" tells dyld to not use the shared cache.  All OS dylibs are loaded
 162 dynamically just like every other dylib.  Setting it to "private" tells
 163 dyld to remove the shared region from the process address space and mmap()
 164 back in a private copy of the dyld shared cache in the shared region address
 165 range. This is only useful if the shared cache on disk has been updated
 166 and is different than the shared cache in use.
 167 .TP
 168 .B DYLD_INSERT_LIBRARIES
 169 This is a colon separated list of dynamic libraries to load before the ones
 170 specified in the program.  This lets you test new modules of existing dynamic
 171 shared libraries that are used in flat-namespace images by loading a temporary
 172 dynamic shared library with just the new modules.  Note that this has no
 173 effect on images built a two-level namespace images using a dynamic shared
 174 library unless
 175 .SM DYLD_FORCE_FLAT_NAMESPACE
 176 is also used.
 177 .TP
 178 .B DYLD_FORCE_FLAT_NAMESPACE
 179 Force all images in the program to be linked as flat-namespace images and ignore
 180 any two-level namespace bindings.  This may cause programs to fail to execute
 181 with a multiply defined symbol error if two-level namespace images are used to
 182 allow the images to have multiply defined symbols.
 183 .TP
 184 .B DYLD_IMAGE_SUFFIX
 185 This is set to a string of a suffix to try to be used for all shared libraries
 186 used by the program.  For libraries ending in ".dylib" the suffix is applied
 187 just before the ".dylib".  For all other libraries the suffix is appended to the
 188 library name.  This is useful for using conventional "_profile" and "_debug"
 189 libraries and frameworks.
 190 .TP
 191 .B DYLD_PRINT_OPTS
 192 When this is set, the dynamic linker writes to file descriptor 2 (normally
 193 standard error) the command line options.
 194 .TP
 195 .B DYLD_PRINT_ENV
 196 When this is set, the dynamic linker writes to file descriptor 2 (normally
 197 standard error) the environment variables.
 198 .TP
 199 .B DYLD_PRINT_LIBRARIES
 200 When this is set, the dynamic linker writes to file descriptor 2 (normally
 201 standard error) the filenames of the libraries the program is using.
 202 This is useful to make sure that the use of
 203 .SM DYLD_LIBRARY_PATH
 204 is getting what you want.
 205 .TP
 206 .B DYLD_PRINT_LIBRARIES_POST_LAUNCH
 207 This does the same as
 208 .SM DYLD_PRINT_LIBRARIES
 209 but the printing starts after the program gets to its entry point.
 210 .TP
 211 .B DYLD_BIND_AT_LAUNCH
 212 When this is set, the dynamic linker binds all undefined symbols
 213 the program needs at launch time. This includes function symbols that can are normally
 214 lazily bound at the time of their first call.
 215 .TP
 216 .B DYLD_PRINT_STATISTICS
 217 Right before the process's main() is called, dyld prints out information about how
 218 dyld spent its time.  Useful for analyzing launch performance.
 219 .TP
 220 .B DYLD_PRINT_STATISTICS_DETAILS
 221 Right before the process's main() is called, dyld prints out detailed information about how
 222 dyld spent its time.  Useful for analyzing launch performance.
 223 .TP
 224 .B DYLD_DISABLE_DOFS
 225 Causes dyld not register dtrace static probes with the kernel.
 226 .TP
 227 .B DYLD_PRINT_INITIALIZERS
 228 Causes dyld to print out a line when running each initializers in every image.  Initializers
 229 run by dyld included constructors for C++ statically allocated objects, functions marked with
 230 __attribute__((constructor)), and -init functions.
 231 .TP
 232 .B DYLD_PRINT_APIS
 233 Causes dyld to print a line whenever a dyld API is called (e.g. NSAddImage()).
 234 .TP
 235 .B DYLD_PRINT_SEGMENTS
 236 Causes dyld to print out a line containing the name and address range of each mach-o segment
 237 that dyld maps.  In addition it prints information about if the image was from the dyld
 238 shared cache.
 239 .TP
 240 .B DYLD_PRINT_BINDINGS
 241 Causes dyld to print a line each time a symbolic name is bound.
 242 .TP
 243 .B DYLD_PRINT_DOFS
 244 Causes dyld to print out information about dtrace static probes registered with the kernel.
 245 .TP
 246 .B DYLD_PRINT_RPATHS
 247 Cause dyld  to print a line each time it expands an @rpath variable and whether
 248 that expansion was successful or not.
 249 .TP
 250 .B DYLD_SHARED_CACHE_DIR
 251 This is a directory containing dyld shared cache files.  This variable can be used in
 252 conjunction with DYLD_SHARED_REGION=private and DYLD_SHARED_CACHE_DONT_VALIDATE
 253 to run a process with an alternate shared cache.
 254 .TP
 255 .B DYLD_SHARED_CACHE_DONT_VALIDATE
 256 Causes dyld to not check that the inode and mod-time of files in the shared cache match
 257 the requested dylib on disk. Thus a program can be made to run with the dylib in the
 258 shared cache even though the real dylib has been updated on disk.
 259 .TP
 260 .SH DYNAMIC LIBRARY LOADING
 261 Unlike many other operating systems, Darwin does not locate dependent dynamic libraries
 262 via their leaf file name.  Instead the full path to each dylib is used (e.g. /usr/lib/libSystem.B.dylib).
 263 But there are times when a full path is not appropriate; for instance, may want your
 264 binaries to be installable in anywhere on the disk.
 265 To support that, there are three @xxx/ variables that can be used as a path prefix.  At runtime dyld
 266 substitutes a dynamically generated path for the @xxx/ prefix.
 267 .TP
 268 .B @executable_path/
 269 This variable is replaced with the path to the directory containing the main executable for
 270 the process.  This is useful for loading dylibs/frameworks embedded in a .app directory.
 271 If the main executable file is at /some/path/My.app/Contents/MacOS/My and a framework dylib
 272 file is at /some/path/My.app/Contents/Frameworks/Foo.framework/Versions/A/Foo, then
 273 the framework load path could be encoded as
 274 @executable_path/../Frameworks/Foo.framework/Versions/A/Foo and the .app directory could be
 275 moved around in the file system and dyld will still be able to load the embedded framework.
 276 .TP
 277 .B @loader_path/
 278 This variable is replaced with the path to the directory containing the mach-o binary which
 279 contains the load command using @loader_path. Thus, in every binary, @loader_path resolves to
 280 a different path, whereas @executable_path always resolves to the same path. @loader_path is
 281 useful as the load path for a framework/dylib embedded in a plug-in, if the final file
 282 system location of the plugin-in unknown (so absolute paths cannot be used) or if the plug-in
 283 is used by multiple applications (so @executable_path cannot be used). If the plug-in mach-o
 284 file is at /some/path/Myfilter.plugin/Contents/MacOS/Myfilter and a framework dylib
 285 file is at /some/path/Myfilter.plugin/Contents/Frameworks/Foo.framework/Versions/A/Foo, then
 286 the framework load path could be encoded as
 287 @loader_path/../Frameworks/Foo.framework/Versions/A/Foo and the Myfilter.plugin directory could
 288 be moved around in the file system and dyld will still be able to load the embedded framework.
 289 .TP
 290 .B @rpath/
 291 Dyld maintains a current stack of paths called the run path list.  When @rpath is encountered
 292 it is substituted with each path in the run path list until a loadable dylib if found.
 293 The run path stack is built from the LC_RPATH load commands in the depencency chain
 294 that lead to the current dylib load.
 295 You can add an LC_RPATH load command to an image with the -rpath option to ld(1).  You can
 296 even add a LC_RPATH load command path that starts with @loader_path/, and it will push a path
 297 on the run path stack that relative to the image containing the LC_RPATH.
 298 The use of @rpath is most useful when you have a complex directory structure of programs and
 299 dylibs which can be installed anywhere, but keep their relative positions.  This scenario
 300 could be implemented using @loader_path, but every client of a dylib could need a different
 301 load path because its relative position in the file system is different. The use of @rpath
 302 introduces a level of indirection that simplies things.  You pick a location in your directory
 303 structure as an anchor point.  Each dylib then gets an install path that starts with @rpath
 304 and is the path to the dylib relative to the anchor point. Each main executable is linked
 305 with -rpath @loader_path/zzz, where zzz is the path from the executable to the anchor point.
 306 At runtime dyld sets it run path to be the anchor point, then each dylib is found relative
 307 to the anchor point.
 308 .SH "SEE ALSO"
 309 libtool(1), ld(1), otool(1)