1 .TH DYLD 1 "June 1, 2020" "Apple Inc."
3 dyld \- the dynamic linker
7 DYLD_FALLBACK_FRAMEWORK_PATH
9 DYLD_VERSIONED_FRAMEWORK_PATH
13 DYLD_FALLBACK_LIBRARY_PATH
15 DYLD_VERSIONED_LIBRARY_PATH
23 DYLD_FORCE_FLAT_NAMESPACE
41 DYLD_PRINT_INITIALIZERS
55 The dynamic linker checks the following environment variables during the launch
59 Note: If System Integrity Protection is enabled, these environment variables are ignored
60 when executing binaries protected by System Integrity Protection.
62 .B DYLD_FRAMEWORK_PATH
63 This is a colon separated list of directories that contain frameworks.
64 The dynamic linker searches these directories before it searches for the
65 framework by its install name.
66 It allows you to test new versions of existing
67 frameworks. (A framework is a library install name that ends in the form
68 XXX.framework/Versions/A/XXX or XXX.framework/XXX, where XXX and A are any
71 For each framework that a program uses, the dynamic linker looks for the
72 framework in each directory in
73 .SM DYLD_FRAMEWORK_PATH
74 in turn. If it looks in all those directories and can't find the framework, it
75 uses whatever it would have loaded if DYLD_FRAMEWORK_PATH had not been set.
81 to discover the frameworks and shared libraries that the executable
84 .B DYLD_FALLBACK_FRAMEWORK_PATH
85 This is a colon separated list of directories that contain frameworks.
86 If a framework is not found at its install path, dyld uses this
87 as a list of directories to search for the framework.
89 By default, it is set to
90 /Library/Frameworks:/System/Library/Frameworks
92 .B DYLD_VERSIONED_FRAMEWORK_PATH
93 This is a colon separated list of directories that contain potential override frameworks.
94 The dynamic linker searches these directories for frameworks. For
95 each framework found dyld looks at its LC_ID_DYLIB and gets the current_version
96 and install name. Dyld then looks for the framework at the install name path.
97 Whichever has the larger current_version value will be used in the process whenever
98 a framework with that install name is required. This is similar to DYLD_FRAMEWORK_PATH
99 except instead of always overriding, it only overrides if the supplied framework is newer.
100 Note: dyld does not check the framework's Info.plist to find its version. Dyld only
101 checks the -currrent_version number supplied when the framework was created.
104 This is a colon separated list of directories that contain libraries. The
105 dynamic linker searches these directories before it searches the default
106 locations for libraries. It allows you to test new versions of existing
109 For each dylib that a program uses, the dynamic linker looks for its
110 leaf name in each directory in
111 .SM DYLD_LIBRARY_PATH.
117 to discover the frameworks and shared libraries that the executable
120 .B DYLD_FALLBACK_LIBRARY_PATH
121 This is a colon separated list of directories that contain libraries.
122 If a dylib is not found at its install path,
123 dyld uses this as a list of directories to search for the dylib.
124 By default, it is set
125 to /usr/local/lib:/usr/lib.
127 .B DYLD_VERSIONED_LIBRARY_PATH
128 This is a colon separated list of directories that contain potential override libraries.
129 The dynamic linker searches these directories for dynamic libraries. For
130 each library found dyld looks at its LC_ID_DYLIB and gets the current_version
131 and install name. Dyld then looks for the library at the install name path.
132 Whichever has the larger current_version value will be used in the process whenever
133 a dylib with that install name is required. This is similar to DYLD_LIBRARY_PATH
134 except instead of always overriding, it only overrides is the supplied library is newer.
136 .B DYLD_PRINT_TO_FILE
137 This is a path to a (writable) file. Normally, the dynamic linker writes all
138 logging output (triggered by DYLD_PRINT_* settings) to file descriptor 2
139 (which is usually stderr). But this setting causes the dynamic linker to
140 write logging output to the specified file.
142 .B DYLD_SHARED_REGION
143 This can be "use" (the default), "avoid", or "private". Setting it to
144 "avoid" tells dyld to not use the shared cache. All OS dylibs are loaded
145 dynamically just like every other dylib. Setting it to "private" tells
146 dyld to remove the shared region from the process address space and mmap()
147 back in a private copy of the dyld shared cache in the shared region address
148 range. This is only useful if the shared cache on disk has been updated
149 and is different than the shared cache in use.
151 .B DYLD_INSERT_LIBRARIES
152 This is a colon separated list of dynamic libraries to load before the ones
153 specified in the program. This lets you test new modules of existing dynamic
154 shared libraries that are used in flat-namespace images by loading a temporary
155 dynamic shared library with just the new modules. Note that this has no
156 effect on images built a two-level namespace images using a dynamic shared
158 .SM DYLD_FORCE_FLAT_NAMESPACE
161 .B DYLD_FORCE_FLAT_NAMESPACE
162 Force all images in the program to be linked as flat-namespace images and ignore
163 any two-level namespace bindings. This may cause programs to fail to execute
164 with a multiply defined symbol error if two-level namespace images are used to
165 allow the images to have multiply defined symbols.
168 This is set to a string of a suffix to try to be used for all shared libraries
169 used by the program. For libraries ending in ".dylib" the suffix is applied
170 just before the ".dylib". For all other libraries the suffix is appended to the
171 library name. This is useful for using conventional "_profile" and "_debug"
172 libraries and frameworks.
175 When this is set, the dynamic linker writes to file descriptor 2 (normally
176 standard error) the command line options.
179 When this is set, the dynamic linker writes to file descriptor 2 (normally
180 standard error) the environment variables.
182 .B DYLD_PRINT_LIBRARIES
183 When this is set, the dynamic linker writes to file descriptor 2 (normally
184 standard error) the filenames of the libraries the program is using.
185 This is useful to make sure that the use of
186 .SM DYLD_LIBRARY_PATH
187 is getting what you want.
189 .B DYLD_BIND_AT_LAUNCH
190 When this is set, the dynamic linker binds all undefined symbols
191 the program needs at launch time. This includes function symbols that are normally
192 lazily bound at the time of their first call.
194 .B DYLD_PRINT_STATISTICS
195 Right before the process's main() is called, dyld prints out information about how
196 dyld spent its time. Useful for analyzing launch performance.
198 .B DYLD_PRINT_STATISTICS_DETAILS
199 Right before the process's main() is called, dyld prints out detailed information about how
200 dyld spent its time. Useful for analyzing launch performance.
203 Causes dyld to not register dtrace static probes with the kernel.
205 .B DYLD_PRINT_INITIALIZERS
206 Causes dyld to print out a line when running each initializer in every image. Initializers
207 run by dyld include constructors for C++ statically allocated objects, functions marked with
208 __attribute__((constructor)), and -init functions.
211 Causes dyld to print a line whenever a dyld API is called (e.g. NSAddImage()).
213 .B DYLD_PRINT_SEGMENTS
214 Causes dyld to print out a line containing the name and address range of each mach-o segment
215 that dyld maps. In addition it prints information about if the image was from the dyld
218 .B DYLD_PRINT_BINDINGS
219 Causes dyld to print a line each time a symbolic name is bound.
222 Causes dyld to print out information about dtrace static probes registered with the kernel.
225 Cause dyld to print a line each time it expands an @rpath variable and whether
226 that expansion was successful or not.
228 .B DYLD_SHARED_CACHE_DIR
229 This is a directory containing dyld shared cache files. This variable can be used in
230 conjunction with DYLD_SHARED_REGION=private to run a process with an alternate shared cache.
232 .SH DYNAMIC LIBRARY LOADING
233 Unlike many other operating systems, Darwin does not locate dependent dynamic libraries
234 via their leaf file name. Instead the full path to each dylib is used (e.g. /usr/lib/libSystem.B.dylib).
235 But there are times when a full path is not appropriate; for instance, may want your
236 binaries to be installable in anywhere on the disk.
237 To support that, there are three @xxx/ variables that can be used as a path prefix. At runtime dyld
238 substitutes a dynamically generated path for the @xxx/ prefix.
241 This variable is replaced with the path to the directory containing the main executable for
242 the process. This is useful for loading dylibs/frameworks embedded in a .app directory.
243 If the main executable file is at /some/path/My.app/Contents/MacOS/My and a framework dylib
244 file is at /some/path/My.app/Contents/Frameworks/Foo.framework/Versions/A/Foo, then
245 the framework load path could be encoded as
246 @executable_path/../Frameworks/Foo.framework/Versions/A/Foo and the .app directory could be
247 moved around in the file system and dyld will still be able to load the embedded framework.
250 This variable is replaced with the path to the directory containing the mach-o binary which
251 contains the load command using @loader_path. Thus, in every binary, @loader_path resolves to
252 a different path, whereas @executable_path always resolves to the same path. @loader_path is
253 useful as the load path for a framework/dylib embedded in a plug-in, if the final file
254 system location of the plugin-in unknown (so absolute paths cannot be used) or if the plug-in
255 is used by multiple applications (so @executable_path cannot be used). If the plug-in mach-o
256 file is at /some/path/Myfilter.plugin/Contents/MacOS/Myfilter and a framework dylib
257 file is at /some/path/Myfilter.plugin/Contents/Frameworks/Foo.framework/Versions/A/Foo, then
258 the framework load path could be encoded as
259 @loader_path/../Frameworks/Foo.framework/Versions/A/Foo and the Myfilter.plugin directory could
260 be moved around in the file system and dyld will still be able to load the embedded framework.
263 Dyld maintains a current stack of paths called the run path list. When @rpath is encountered
264 it is substituted with each path in the run path list until a loadable dylib if found.
265 The run path stack is built from the LC_RPATH load commands in the depencency chain
266 that lead to the current dylib load.
267 You can add an LC_RPATH load command to an image with the -rpath option to ld(1). You can
268 even add a LC_RPATH load command path that starts with @loader_path/, and it will push a path
269 on the run path stack that relative to the image containing the LC_RPATH.
270 The use of @rpath is most useful when you have a complex directory structure of programs and
271 dylibs which can be installed anywhere, but keep their relative positions. This scenario
272 could be implemented using @loader_path, but every client of a dylib could need a different
273 load path because its relative position in the file system is different. The use of @rpath
274 introduces a level of indirection that simplies things. You pick a location in your directory
275 structure as an anchor point. Each dylib then gets an install path that starts with @rpath
276 and is the path to the dylib relative to the anchor point. Each main executable is linked
277 with -rpath @loader_path/zzz, where zzz is the path from the executable to the anchor point.
278 At runtime dyld sets it run path to be the anchor point, then each dylib is found relative
281 dyldinfo(1), ld(1), otool(1)
projects / apple / dyld.git / blob