doc/man/man1/dyld.1

   1 .TH DYLD 1 "January 15, 2005" "Apple Computer, 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_INSERT_LIBRARIES
  16 .br
  17 DYLD_FORCE_FLAT_NAMESPACE
  18 .br
  19 DYLD_IMAGE_SUFFIX
  20 .br
  21 DYLD_PRINT_OPTS
  22 .br
  23 DYLD_PRINT_ENV
  24 .br
  25 DYLD_PRINT_LIBRARIES
  26 .br
  27 DYLD_PRINT_LIBRARIES_POST_LAUNCH
  28 .br
  29 DYLD_BIND_AT_LAUNCH
  30 .br
  31 DYLD_PREBIND_DEBUG
  32 .br
  33 DYLD_NEW_LOCAL_SHARED_REGIONS
  34 .br
  35 DYLD_IGNORE_PREBINDING
  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 .SH DESCRIPTION
  49 The dynamic linker uses the following environment variables.
  50 They affect any program that uses the dynamic linker.
  51 .TP
  52 .B DYLD_FRAMEWORK_PATH
  53 This is a colon separated list of directories that contain frameworks.
  54 The dynamic linker searches these directories before it searches for the
  55 framework by its install name.
  56 It allows you to test new versions of existing
  57 frameworks. (A framework is a library install name that ends in the form
  58 XXX.framework/Versions/YYY/XXX or XXX.framework/XXX, where XXX and YYY are any
  59 name.)
  60 .IP
  61 For each framework that a program uses, the dynamic linker looks for the
  62 framework in each directory in
  63 .SM DYLD_FRAMEWORK_PATH
  64 in turn. If it looks in all the directories and can't find the framework, it
  65 searches the directories in
  66 .SM DYLD_LIBRARY_PATH
  67 in turn. If it still can't find the framework, it then searches
  68 .SM DYLD_FALLBACK_FRAMEWORK_PATH
  69 and
  70 .SM DYLD_FALLBACK_LIBRARY_PATH
  71 in turn.
  72 .IP
  73 Use the
  74 .B \-L
  75 option to
  76 .IR otool (1).
  77 to discover the frameworks and shared libraries that the executable
  78 is linked against.
  79 .TP
  80 .B DYLD_FALLBACK_FRAMEWORK_PATH
  81 This is a colon separated list of directories that contain frameworks.
  82 It is used as the default location for frameworks not found in their install
  83 path.
  84
  85 By default, it is set to
  86 /Library/Frameworks:/Network/Library/Frameworks:/System/Library/Frameworks
  87 .TP
  88 .B DYLD_LIBRARY_PATH
  89 This is a colon separated list of directories that contain libraries. The
  90 dynamic linker searches these directories before it searches the default
  91 locations for libraries. It allows you to test new versions of existing
  92 libraries.
  93 .IP
  94 For each library that a program uses, the dynamic linker looks for it in each
  95 directory in
  96 .SM DYLD_LIBRARY_PATH
  97 in turn. If it still can't find the library, it then searches
  98 .SM DYLD_FALLBACK_FRAMEWORK_PATH
  99 and
 100 .SM DYLD_FALLBACK_LIBRARY_PATH
 101 in turn.
 102 .IP
 103 Use the
 104 .B \-L
 105 option to
 106 .IR otool (1).
 107 to discover the frameworks and shared libraries that the executable
 108 is linked against.
 109 .TP
 110 .B DYLD_FALLBACK_LIBRARY_PATH
 111 This is a colon separated list of directories that contain libraries.
 112 It is used as the default location for libraries not found in their install
 113 path.
 114 By default, it is set
 115 to $(HOME)/lib:/usr/local/lib:/lib:/usr/lib.
 116 .TP
 117 .B DYLD_ROOT_PATH
 118 This is a colon separated list of directories.  The dynamic linker will prepend each of
 119 this directory paths to every image access until a file is found.
 120 .TP
 121 .B DYLD_INSERT_LIBRARIES
 122 This is a colon separated list of dynamic libraries to load before the ones
 123 specified in the program.  This lets you test new modules of existing dynamic
 124 shared libraries that are used in flat-namespace images by loading a temporary
 125 dynamic shared library with just the new modules.  Note that this has no
 126 effect on images built a two-level namespace images using a dynamic shared
 127 library unless
 128 .SM DYLD_FORCE_FLAT_NAMESPACE
 129 is also used.
 130 .TP
 131 .B DYLD_FORCE_FLAT_NAMESPACE
 132 Force all images in the program to be linked as flat-namespace images and ignore
 133 any two-level namespace bindings.  This may cause programs to fail to execute
 134 with a multiply defined symbol error if two-level namespace images are used to
 135 allow the images to have multiply defined symbols.
 136 .TP
 137 .B DYLD_IMAGE_SUFFIX
 138 This is set to a string of a suffix to try to be used for all shared libraries
 139 used by the program.  For libraries ending in ".dylib" the suffix is applied
 140 just before the ".dylib".  For all other libraries the suffix is appended to the
 141 library name.  This is useful for using conventional "_profile" and "_debug"
 142 libraries and frameworks.
 143 .TP
 144 .B DYLD_PRINT_OPTS
 145 When this is set, the dynamic linker writes to file descriptor 2 (normally
 146 standard error) the command line options.
 147 .TP
 148 .B DYLD_PRINT_ENV
 149 When this is set, the dynamic linker writes to file descriptor 2 (normally
 150 standard error) the environment variables.
 151 .TP
 152 .B DYLD_PRINT_LIBRARIES
 153 When this is set, the dynamic linker writes to file descriptor 2 (normally
 154 standard error) the filenames of the libraries the program is using.
 155 This is useful to make sure that the use of
 156 .SM DYLD_LIBRARY_PATH
 157 is getting what you want.
 158 .TP
 159 .B DYLD_PRINT_LIBRARIES_POST_LAUNCH
 160 This does the same as
 161 .SM DYLD_PRINT_LIBRARIES
 162 but the printing starts after the program gets to its entry point.
 163 .TP
 164 .B DYLD_BIND_AT_LAUNCH
 165 When this is set, the dynamic linker binds all undefined symbols
 166 the program needs at launch time. This includes function symbols that can are normally lazily bound at the time of their first call.
 167 .TP
 168 .B DYLD_PREBIND_DEBUG
 169 When this is set, the dynamic linker prints diagnostics about
 170 launching prebound programs and libraries. This lets you determine why a
 171 program is not being launched prebound.
 172 You can view the recorded library time stamps with the
 173 .B \-Lv
 174 option to
 175 .IR otool (1).
 176 .TP
 177 .PP
 178 For secure programs that are UNIX set uid or set gid, the dynamic linker will
 179 not use the dyld environment variables for path searching and library insertion,
 180 unless the program is run as the real user.  For secure programs, the dynamic
 181 linker clears out the value of the dyld path and insertion environment
 182 variables.  This is so that if a program is
 183 .IR exec (2)'ed
 184 from a secure program too will not have it's libraries searched for, as well.
 185 For statically linked secure programs that
 186 .IR exec (2)
 187 other programs that might use the dynamic linker, they too should clear out the
 188 values of the dyld path and insertion environment variables.
 189 .TP
 190 .B DYLD_NEW_LOCAL_SHARED_REGIONS
 191 When set, the dynamic linker directs the system to provide a new set of shared
 192 regions as the repository for library load requests for dynamic libraries
 193 built with
 194 .SM MH_SPLIT_SEGS
 195 (split shared libraries).
 196
 197 Split shared libraries reside in a defined contiguous region of address space
 198 in all dynamic linker runtime processes.  This space is backed by named regions
 199 or sub-maps.  These sub-maps are owned by the system and items which are to
 200 mapped into them must be mapped via the
 201 .IR load_shared_file (2)
 202 call.  The use of
 203 sub-maps promotes a high degree of system resource sharing between the
 204 processes which incorporate and use them.  However, some processes require
 205 either additional or different libraries to be loaded into the shared region.
 206 While there is some space available within the shared region for alternate and
 207 new shared libraries, it is inappropriate to use that area for temporary or
 208 private libraries.  Setting the
 209 .SM DYLD_NEW_LOCAL_SHARED_REGIONS
 210 flag will cause
 211 all children of the current process to have their own set of sub-maps.  In this
 212 way the libraries found in the children's submaps will not be caused to be
 213 present in the submaps shared by the rest of the system.
 214
 215 .SM DYLD_NEW_LOCAL_SHARED_REGIONS
 216 should be set by anyone wishing to run
 217 non-standard or temporary split shared libraries by setting an explicit path to
 218 point to them.  i.e. by using the DYLD_LIBRARY_PATH environment variable
 219 instead of changing the root by executing a
 220 .IR chroot (2)
 221 call.
 222 .TP
 223 .B DYLD_PRINT_STATISTICS
 224 Right before the process's main() is called, dyld prints out information about how
 225 dyld spent its time.  Useful for analyzing launch performance.
 226 .TP
 227 .B DYLD_IGNORE_PREBINDING { app | all }
 228 Valid values are "app", "all", and "" (empty).  The variable is useful for testing
 229 how various mixes of prebound and unprebound libraries perform.  When set to "all",
 230 all prebinding is ignored.  That is, dyld fixes up any prebound images as if the prebinding
 231 in it was invalid.  When set to "all", just the prebinding information in main
 232 executables is ignored. When set the nothing, the prebinding in split-seg libraries
 233 is used, by all other prebinding is ignored.
 234 .TP
 235 .B DYLD_PRINT_INITIALIZERS
 236 Causes dyld to print out a line when running each initializers in every image.  Initializers
 237 run by dyld included constructors for C++ statically allocated objects, functions marked with
 238 __attribute__((constructor)), and -init functions.
 239 .TP
 240 .B DYLD_PRINT_APIS
 241 Causes dyld to print a line whenever a dyld API is called (e.g. NSAddImage()).
 242 .TP
 243 .B DYLD_PRINT_SEGMENTS
 244 Causes dyld to print out a line containing the name and address range of each mach-o segment
 245 that dyld maps in.
 246 .TP
 247 .B DYLD_PRINT_BINDINGS
 248 Causes dyld to print a line each time a symbolic name is bound.
 249
 250
 251
 252 .SH "SEE ALSO"
 253 libtool(1), ld(1), otool(1)