doc/man/man1/dyld.1

   1 .TH DYLD 1 "March 23, 2007" "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_LIBRARY_PATH
  10 .br
  11 DYLD_FALLBACK_LIBRARY_PATH
  12 .br
  13 DYLD_ROOT_PATH
  14 .br
  15 DYLD_SHARED_REGION
  16 .br
  17 DYLD_INSERT_LIBRARIES
  18 .br
  19 DYLD_FORCE_FLAT_NAMESPACE
  20 .br
  21 DYLD_IMAGE_SUFFIX
  22 .br
  23 DYLD_PRINT_OPTS
  24 .br
  25 DYLD_PRINT_ENV
  26 .br
  27 DYLD_PRINT_LIBRARIES
  28 .br
  29 DYLD_PRINT_LIBRARIES_POST_LAUNCH
  30 .br
  31 DYLD_BIND_AT_LAUNCH
  32 .br
  33 DYLD_NO_FIX_PREBINDING
  34 .br
  35 DYLD_DISABLE_DOFS
  36 .br
  37 DYLD_PRINT_APIS
  38 .br
  39 DYLD_PRINT_BINDINGS
  40 .br
  41 DYLD_PRINT_INITIALIZERS
  42 .br
  43 DYLD_PRINT_REBASINGS
  44 .br
  45 DYLD_PRINT_SEGMENTS
  46 .br
  47 DYLD_PRINT_STATISTICS
  48 .br
  49 DYLD_PRINT_DOFS
  50 .SH DESCRIPTION
  51 The dynamic linker uses the following environment variables.
  52 They affect any program that uses the dynamic linker.
  53 .TP
  54 .B DYLD_FRAMEWORK_PATH
  55 This is a colon separated list of directories that contain frameworks.
  56 The dynamic linker searches these directories before it searches for the
  57 framework by its install name.
  58 It allows you to test new versions of existing
  59 frameworks. (A framework is a library install name that ends in the form
  60 XXX.framework/Versions/YYY/XXX or XXX.framework/XXX, where XXX and YYY are any
  61 name.)
  62 .IP
  63 For each framework that a program uses, the dynamic linker looks for the
  64 framework in each directory in
  65 .SM DYLD_FRAMEWORK_PATH
  66 in turn. If it looks in all the directories and can't find the framework, it
  67 searches the directories in
  68 .SM DYLD_LIBRARY_PATH
  69 in turn. If it still can't find the framework, it then searches
  70 .SM DYLD_FALLBACK_FRAMEWORK_PATH
  71 and
  72 .SM DYLD_FALLBACK_LIBRARY_PATH
  73 in turn.
  74 .IP
  75 Use the
  76 .B \-L
  77 option to
  78 .IR otool (1).
  79 to discover the frameworks and shared libraries that the executable
  80 is linked against.
  81 .TP
  82 .B DYLD_FALLBACK_FRAMEWORK_PATH
  83 This is a colon separated list of directories that contain frameworks.
  84 It is used as the default location for frameworks not found in their install
  85 path.
  86
  87 By default, it is set to
  88 /Library/Frameworks:/Network/Library/Frameworks:/System/Library/Frameworks
  89 .TP
  90 .B DYLD_LIBRARY_PATH
  91 This is a colon separated list of directories that contain libraries. The
  92 dynamic linker searches these directories before it searches the default
  93 locations for libraries. It allows you to test new versions of existing
  94 libraries.
  95 .IP
  96 For each library that a program uses, the dynamic linker looks for it in each
  97 directory in
  98 .SM DYLD_LIBRARY_PATH
  99 in turn. If it still can't find the library, it then searches
 100 .SM DYLD_FALLBACK_FRAMEWORK_PATH
 101 and
 102 .SM DYLD_FALLBACK_LIBRARY_PATH
 103 in turn.
 104 .IP
 105 Use the
 106 .B \-L
 107 option to
 108 .IR otool (1).
 109 to discover the frameworks and shared libraries that the executable
 110 is linked against.
 111 .TP
 112 .B DYLD_FALLBACK_LIBRARY_PATH
 113 This is a colon separated list of directories that contain libraries.
 114 It is used as the default location for libraries not found in their install
 115 path.
 116 By default, it is set
 117 to $(HOME)/lib:/usr/local/lib:/lib:/usr/lib.
 118 .TP
 119 .B DYLD_ROOT_PATH
 120 This is a colon separated list of directories.  The dynamic linker will prepend each of
 121 this directory paths to every image access until a file is found.
 122 .TP
 123 .B DYLD_SHARED_REGION
 124 This can be "use" (the default), "avoid", or "private".  Settting it to
 125 "avoid" tells dyld to not use the shared cache.  All OS dylibs are loaded
 126 dynamically just like every other dylib.  Setting it to "private" tells
 127 dyld to remove the shared region from the process address space and mmap()
 128 back in a private copy of the dyld shared cache in the shared region address
 129 range. This is only useful if the shared cache on disk has been updated
 130 and is different than the shared cache in use.
 131 .TP
 132 .B DYLD_INSERT_LIBRARIES
 133 This is a colon separated list of dynamic libraries to load before the ones
 134 specified in the program.  This lets you test new modules of existing dynamic
 135 shared libraries that are used in flat-namespace images by loading a temporary
 136 dynamic shared library with just the new modules.  Note that this has no
 137 effect on images built a two-level namespace images using a dynamic shared
 138 library unless
 139 .SM DYLD_FORCE_FLAT_NAMESPACE
 140 is also used.
 141 .TP
 142 .B DYLD_FORCE_FLAT_NAMESPACE
 143 Force all images in the program to be linked as flat-namespace images and ignore
 144 any two-level namespace bindings.  This may cause programs to fail to execute
 145 with a multiply defined symbol error if two-level namespace images are used to
 146 allow the images to have multiply defined symbols.
 147 .TP
 148 .B DYLD_IMAGE_SUFFIX
 149 This is set to a string of a suffix to try to be used for all shared libraries
 150 used by the program.  For libraries ending in ".dylib" the suffix is applied
 151 just before the ".dylib".  For all other libraries the suffix is appended to the
 152 library name.  This is useful for using conventional "_profile" and "_debug"
 153 libraries and frameworks.
 154 .TP
 155 .B DYLD_PRINT_OPTS
 156 When this is set, the dynamic linker writes to file descriptor 2 (normally
 157 standard error) the command line options.
 158 .TP
 159 .B DYLD_PRINT_ENV
 160 When this is set, the dynamic linker writes to file descriptor 2 (normally
 161 standard error) the environment variables.
 162 .TP
 163 .B DYLD_PRINT_LIBRARIES
 164 When this is set, the dynamic linker writes to file descriptor 2 (normally
 165 standard error) the filenames of the libraries the program is using.
 166 This is useful to make sure that the use of
 167 .SM DYLD_LIBRARY_PATH
 168 is getting what you want.
 169 .TP
 170 .B DYLD_PRINT_LIBRARIES_POST_LAUNCH
 171 This does the same as
 172 .SM DYLD_PRINT_LIBRARIES
 173 but the printing starts after the program gets to its entry point.
 174 .TP
 175 .B DYLD_BIND_AT_LAUNCH
 176 When this is set, the dynamic linker binds all undefined symbols
 177 the program needs at launch time. This includes function symbols that can are normally
 178 lazily bound at the time of their first call.
 179 .TP
 180 .B DYLD_PRINT_STATISTICS
 181 Right before the process's main() is called, dyld prints out information about how
 182 dyld spent its time.  Useful for analyzing launch performance.
 183 .TP
 184 .B DYLD_NO_FIX_PREBINDING
 185 Normally, dyld will trigger the dyld shared cache to be regenerated if it notices
 186 the cache is out of date while launching a process.  If this environment variable
 187 is set, dyld will not trigger a cache rebuild.  This is useful to set while installing
 188 a large set of OS dylibs, to ensure the cache is not regenerated until the install
 189 is complete.
 190 .TP
 191 .B DYLD_DISABLE_DOFS
 192 Causes dyld not register dtrace static probes with the kernel.
 193 .TP
 194 .B DYLD_PRINT_INITIALIZERS
 195 Causes dyld to print out a line when running each initializers in every image.  Initializers
 196 run by dyld included constructors for C++ statically allocated objects, functions marked with
 197 __attribute__((constructor)), and -init functions.
 198 .TP
 199 .B DYLD_PRINT_APIS
 200 Causes dyld to print a line whenever a dyld API is called (e.g. NSAddImage()).
 201 .TP
 202 .B DYLD_PRINT_SEGMENTS
 203 Causes dyld to print out a line containing the name and address range of each mach-o segment
 204 that dyld maps.  In addition it prints information about if the image was from the dyld
 205 shared cache.
 206 .TP
 207 .B DYLD_PRINT_BINDINGS
 208 Causes dyld to print a line each time a symbolic name is bound.
 209 .TP
 210 .B DYLD_PRINT_DOFS
 211 Causes dyld to print out information about dtrace static probes registered with the kernel.
 212
 213 .SH "SEE ALSO"
 214 libtool(1), ld(1), otool(1)