-.TH DYLD 1 "November 25, 2008" "Apple Inc."
+.TH DYLD 1 "June 1, 2020" "Apple Inc."
.SH NAME
-dyld \- the dynamic link editor
+dyld \- the dynamic linker
.SH SYNOPSIS
DYLD_FRAMEWORK_PATH
.br
DYLD_FALLBACK_FRAMEWORK_PATH
.br
+DYLD_VERSIONED_FRAMEWORK_PATH
+.br
DYLD_LIBRARY_PATH
.br
DYLD_FALLBACK_LIBRARY_PATH
.br
-DYLD_ROOT_PATH
+DYLD_VERSIONED_LIBRARY_PATH
+.br
+DYLD_PRINT_TO_FILE
.br
DYLD_SHARED_REGION
.br
.br
DYLD_PRINT_LIBRARIES
.br
-DYLD_PRINT_LIBRARIES_POST_LAUNCH
-.br
DYLD_BIND_AT_LAUNCH
.br
-DYLD_NO_FIX_PREBINDING
-.br
DYLD_DISABLE_DOFS
.br
DYLD_PRINT_APIS
.br
DYLD_PRINT_DOFS
.br
-DYLD_NO_PIE
+DYLD_PRINT_RPATHS
.br
DYLD_SHARED_CACHE_DIR
-.br
-DYLD_SHARED_CACHE_DONT_VALIDATE
.SH DESCRIPTION
-The dynamic linker uses the following environment variables.
-They affect any program that uses the dynamic linker.
+The dynamic linker checks the following environment variables during the launch
+of each process.
+.br
+.br
+Note: If System Integrity Protection is enabled, these environment variables are ignored
+when executing binaries protected by System Integrity Protection.
.TP
.B DYLD_FRAMEWORK_PATH
This is a colon separated list of directories that contain frameworks.
framework by its install name.
It allows you to test new versions of existing
frameworks. (A framework is a library install name that ends in the form
-XXX.framework/Versions/YYY/XXX or XXX.framework/XXX, where XXX and YYY are any
+XXX.framework/Versions/A/XXX or XXX.framework/XXX, where XXX and A are any
name.)
.IP
For each framework that a program uses, the dynamic linker looks for the
framework in each directory in
.SM DYLD_FRAMEWORK_PATH
-in turn. If it looks in all the directories and can't find the framework, it
-searches the directories in
-.SM DYLD_LIBRARY_PATH
-in turn. If it still can't find the framework, it then searches
-.SM DYLD_FALLBACK_FRAMEWORK_PATH
-and
-.SM DYLD_FALLBACK_LIBRARY_PATH
-in turn.
+in turn. If it looks in all those directories and can't find the framework, it
+uses whatever it would have loaded if DYLD_FRAMEWORK_PATH had not been set.
.IP
Use the
.B \-L
option to
-.IR otool (1).
+.IR otool (1)
to discover the frameworks and shared libraries that the executable
is linked against.
.TP
.B DYLD_FALLBACK_FRAMEWORK_PATH
This is a colon separated list of directories that contain frameworks.
-It is used as the default location for frameworks not found in their install
-path.
+If a framework is not found at its install path, dyld uses this
+as a list of directories to search for the framework.
By default, it is set to
-/Library/Frameworks:/Network/Library/Frameworks:/System/Library/Frameworks
+/Library/Frameworks:/System/Library/Frameworks
+.TP
+.B DYLD_VERSIONED_FRAMEWORK_PATH
+This is a colon separated list of directories that contain potential override frameworks.
+The dynamic linker searches these directories for frameworks. For
+each framework found dyld looks at its LC_ID_DYLIB and gets the current_version
+and install name. Dyld then looks for the framework at the install name path.
+Whichever has the larger current_version value will be used in the process whenever
+a framework with that install name is required. This is similar to DYLD_FRAMEWORK_PATH
+except instead of always overriding, it only overrides if the supplied framework is newer.
+Note: dyld does not check the framework's Info.plist to find its version. Dyld only
+checks the -currrent_version number supplied when the framework was created.
.TP
.B DYLD_LIBRARY_PATH
This is a colon separated list of directories that contain libraries. The
locations for libraries. It allows you to test new versions of existing
libraries.
.IP
-For each library that a program uses, the dynamic linker looks for it in each
-directory in
-.SM DYLD_LIBRARY_PATH
-in turn. If it still can't find the library, it then searches
-.SM DYLD_FALLBACK_FRAMEWORK_PATH
-and
-.SM DYLD_FALLBACK_LIBRARY_PATH
-in turn.
+For each dylib that a program uses, the dynamic linker looks for its
+leaf name in each directory in
+.SM DYLD_LIBRARY_PATH.
.IP
Use the
.B \-L
option to
-.IR otool (1).
+.IR otool (1)
to discover the frameworks and shared libraries that the executable
is linked against.
.TP
.B DYLD_FALLBACK_LIBRARY_PATH
This is a colon separated list of directories that contain libraries.
-It is used as the default location for libraries not found in their install
-path.
+If a dylib is not found at its install path,
+dyld uses this as a list of directories to search for the dylib.
By default, it is set
-to $(HOME)/lib:/usr/local/lib:/lib:/usr/lib.
+to /usr/local/lib:/usr/lib.
.TP
-.B DYLD_ROOT_PATH
-This is a colon separated list of directories. The dynamic linker will prepend each of
-this directory paths to every image access until a file is found.
+.B DYLD_VERSIONED_LIBRARY_PATH
+This is a colon separated list of directories that contain potential override libraries.
+The dynamic linker searches these directories for dynamic libraries. For
+each library found dyld looks at its LC_ID_DYLIB and gets the current_version
+and install name. Dyld then looks for the library at the install name path.
+Whichever has the larger current_version value will be used in the process whenever
+a dylib with that install name is required. This is similar to DYLD_LIBRARY_PATH
+except instead of always overriding, it only overrides is the supplied library is newer.
+.TP
+.B DYLD_PRINT_TO_FILE
+This is a path to a (writable) file. Normally, the dynamic linker writes all
+logging output (triggered by DYLD_PRINT_* settings) to file descriptor 2
+(which is usually stderr). But this setting causes the dynamic linker to
+write logging output to the specified file.
.TP
.B DYLD_SHARED_REGION
This can be "use" (the default), "avoid", or "private". Setting it to
.SM DYLD_LIBRARY_PATH
is getting what you want.
.TP
-.B DYLD_PRINT_LIBRARIES_POST_LAUNCH
-This does the same as
-.SM DYLD_PRINT_LIBRARIES
-but the printing starts after the program gets to its entry point.
-.TP
.B DYLD_BIND_AT_LAUNCH
When this is set, the dynamic linker binds all undefined symbols
-the program needs at launch time. This includes function symbols that can are normally
+the program needs at launch time. This includes function symbols that are normally
lazily bound at the time of their first call.
.TP
.B DYLD_PRINT_STATISTICS
Right before the process's main() is called, dyld prints out information about how
dyld spent its time. Useful for analyzing launch performance.
.TP
-.B DYLD_NO_FIX_PREBINDING
-Normally, dyld will trigger the dyld shared cache to be regenerated if it notices
-the cache is out of date while launching a process. If this environment variable
-is set, dyld will not trigger a cache rebuild. This is useful to set while installing
-a large set of OS dylibs, to ensure the cache is not regenerated until the install
-is complete.
+.B DYLD_PRINT_STATISTICS_DETAILS
+Right before the process's main() is called, dyld prints out detailed information about how
+dyld spent its time. Useful for analyzing launch performance.
.TP
-.B DYLD_DISABLE_DOFS
-Causes dyld not register dtrace static probes with the kernel.
+.B DYLD_DISABLE_DOFS
+Causes dyld to not register dtrace static probes with the kernel.
.TP
.B DYLD_PRINT_INITIALIZERS
-Causes dyld to print out a line when running each initializers in every image. Initializers
-run by dyld included constructors for C++ statically allocated objects, functions marked with
+Causes dyld to print out a line when running each initializer in every image. Initializers
+run by dyld include constructors for C++ statically allocated objects, functions marked with
__attribute__((constructor)), and -init functions.
.TP
.B DYLD_PRINT_APIS
.B DYLD_PRINT_DOFS
Causes dyld to print out information about dtrace static probes registered with the kernel.
.TP
-.B DYLD_NO_PIE
-Causes dyld to not randomize the load addresses of images in a process where the main
-executable was built position independent. This can be helpful when trying to reproduce
-and debug a problem in a PIE.
+.B DYLD_PRINT_RPATHS
+Cause dyld to print a line each time it expands an @rpath variable and whether
+that expansion was successful or not.
.TP
.B DYLD_SHARED_CACHE_DIR
This is a directory containing dyld shared cache files. This variable can be used in
-conjunction with DYLD_SHARED_REGION=private and DYLD_SHARED_CACHE_DONT_VALIDATE
-to run a process with an alternate shared cache.
+conjunction with DYLD_SHARED_REGION=private to run a process with an alternate shared cache.
.TP
-.B DYLD_SHARED_CACHE_DONT_VALIDATE
-Causes dyld to not check that the inode and mod-time of files in the shared cache match
-the requested dylib on disk. Thus a program can be made to run with the dylib in the
-shared cache even though the real dylib has been updated on disk.
.SH DYNAMIC LIBRARY LOADING
Unlike many other operating systems, Darwin does not locate dependent dynamic libraries
via their leaf file name. Instead the full path to each dylib is used (e.g. /usr/lib/libSystem.B.dylib).
.TP
.B @executable_path/
This variable is replaced with the path to the directory containing the main executable for
-the process. This is useful for .app directories where the main executable is in a well
-known location inside the .app directory. A typical load path for an embedded framework would
-look like @executable_path/../Frameworks/Foo.framework/Versions/A/Foo.
+the process. This is useful for loading dylibs/frameworks embedded in a .app directory.
+If the main executable file is at /some/path/My.app/Contents/MacOS/My and a framework dylib
+file is at /some/path/My.app/Contents/Frameworks/Foo.framework/Versions/A/Foo, then
+the framework load path could be encoded as
+@executable_path/../Frameworks/Foo.framework/Versions/A/Foo and the .app directory could be
+moved around in the file system and dyld will still be able to load the embedded framework.
.TP
.B @loader_path/
This variable is replaced with the path to the directory containing the mach-o binary which
-contains the load path. This is useful for a plug-in that has an embedded framework. @executable_path/
-is not helpful because you may not know where the plugin-in will be installed relative to the
-main executable, or there may be multiple applications that load the plug-in.
-A typical load path for an embedded framework for reference a sibling framework would
-look like @loader_path/../../../Frameworks/Foo.framework/Versions/A/Foo.
+contains the load command using @loader_path. Thus, in every binary, @loader_path resolves to
+a different path, whereas @executable_path always resolves to the same path. @loader_path is
+useful as the load path for a framework/dylib embedded in a plug-in, if the final file
+system location of the plugin-in unknown (so absolute paths cannot be used) or if the plug-in
+is used by multiple applications (so @executable_path cannot be used). If the plug-in mach-o
+file is at /some/path/Myfilter.plugin/Contents/MacOS/Myfilter and a framework dylib
+file is at /some/path/Myfilter.plugin/Contents/Frameworks/Foo.framework/Versions/A/Foo, then
+the framework load path could be encoded as
+@loader_path/../Frameworks/Foo.framework/Versions/A/Foo and the Myfilter.plugin directory could
+be moved around in the file system and dyld will still be able to load the embedded framework.
.TP
.B @rpath/
Dyld maintains a current stack of paths called the run path list. When @rpath is encountered
At runtime dyld sets it run path to be the anchor point, then each dylib is found relative
to the anchor point.
.SH "SEE ALSO"
-libtool(1), ld(1), otool(1)
+dyldinfo(1), ld(1), otool(1)
projects / apple / dyld.git / blobdiff