-.TH DYLD 1 "January 15, 2005" "Apple Computer, 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
DYLD_INSERT_LIBRARIES
.br
.br
DYLD_PRINT_LIBRARIES
.br
-DYLD_PRINT_LIBRARIES_POST_LAUNCH
-.br
DYLD_BIND_AT_LAUNCH
.br
-DYLD_PREBIND_DEBUG
-.br
-DYLD_NEW_LOCAL_SHARED_REGIONS
-.br
-DYLD_IGNORE_PREBINDING
+DYLD_DISABLE_DOFS
.br
DYLD_PRINT_APIS
.br
DYLD_PRINT_SEGMENTS
.br
DYLD_PRINT_STATISTICS
+.br
+DYLD_PRINT_DOFS
+.br
+DYLD_PRINT_RPATHS
+.br
+DYLD_SHARED_CACHE_DIR
.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_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_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_SHARED_REGION
+This can be "use" (the default), "avoid", or "private". Setting it to
+"avoid" tells dyld to not use the shared cache. All OS dylibs are loaded
+dynamically just like every other dylib. Setting it to "private" tells
+dyld to remove the shared region from the process address space and mmap()
+back in a private copy of the dyld shared cache in the shared region address
+range. This is only useful if the shared cache on disk has been updated
+and is different than the shared cache in use.
.TP
.B DYLD_INSERT_LIBRARIES
This is a colon separated list of dynamic libraries to load before the ones
.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 lazily bound at the time of their first call.
-.TP
-.B DYLD_PREBIND_DEBUG
-When this is set, the dynamic linker prints diagnostics about
-launching prebound programs and libraries. This lets you determine why a
-program is not being launched prebound.
-You can view the recorded library time stamps with the
-.B \-Lv
-option to
-.IR otool (1).
-.TP
-.PP
-For secure programs that are UNIX set uid or set gid, the dynamic linker will
-not use the dyld environment variables for path searching and library insertion,
-unless the program is run as the real user. For secure programs, the dynamic
-linker clears out the value of the dyld path and insertion environment
-variables. This is so that if a program is
-.IR exec (2)'ed
-from a secure program too will not have it's libraries searched for, as well.
-For statically linked secure programs that
-.IR exec (2)
-other programs that might use the dynamic linker, they too should clear out the
-values of the dyld path and insertion environment variables.
-.TP
-.B DYLD_NEW_LOCAL_SHARED_REGIONS
-When set, the dynamic linker directs the system to provide a new set of shared
-regions as the repository for library load requests for dynamic libraries
-built with
-.SM MH_SPLIT_SEGS
-(split shared libraries).
-
-Split shared libraries reside in a defined contiguous region of address space
-in all dynamic linker runtime processes. This space is backed by named regions
-or sub-maps. These sub-maps are owned by the system and items which are to
-mapped into them must be mapped via the
-.IR load_shared_file (2)
-call. The use of
-sub-maps promotes a high degree of system resource sharing between the
-processes which incorporate and use them. However, some processes require
-either additional or different libraries to be loaded into the shared region.
-While there is some space available within the shared region for alternate and
-new shared libraries, it is inappropriate to use that area for temporary or
-private libraries. Setting the
-.SM DYLD_NEW_LOCAL_SHARED_REGIONS
-flag will cause
-all children of the current process to have their own set of sub-maps. In this
-way the libraries found in the children's submaps will not be caused to be
-present in the submaps shared by the rest of the system.
-
-.SM DYLD_NEW_LOCAL_SHARED_REGIONS
-should be set by anyone wishing to run
-non-standard or temporary split shared libraries by setting an explicit path to
-point to them. i.e. by using the DYLD_LIBRARY_PATH environment variable
-instead of changing the root by executing a
-.IR chroot (2)
-call.
+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_IGNORE_PREBINDING { app | all }
-Valid values are "app", "all", and "" (empty). The variable is useful for testing
-how various mixes of prebound and unprebound libraries perform. When set to "all",
-all prebinding is ignored. That is, dyld fixes up any prebound images as if the prebinding
-in it was invalid. When set to "all", just the prebinding information in main
-executables is ignored. When set the nothing, the prebinding in split-seg libraries
-is used, by all other prebinding is ignored.
+.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 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
.TP
.B DYLD_PRINT_SEGMENTS
Causes dyld to print out a line containing the name and address range of each mach-o segment
-that dyld maps in.
+that dyld maps. In addition it prints information about if the image was from the dyld
+shared cache.
.TP
.B DYLD_PRINT_BINDINGS
Causes dyld to print a line each time a symbolic name is bound.
-
-
-
+.TP
+.B DYLD_PRINT_DOFS
+Causes dyld to print out information about dtrace static probes registered with the kernel.
+.TP
+.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 to run a process with an alternate shared cache.
+.TP
+.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).
+But there are times when a full path is not appropriate; for instance, may want your
+binaries to be installable in anywhere on the disk.
+To support that, there are three @xxx/ variables that can be used as a path prefix. At runtime dyld
+substitutes a dynamically generated path for the @xxx/ prefix.
+.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 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 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
+it is substituted with each path in the run path list until a loadable dylib if found.
+The run path stack is built from the LC_RPATH load commands in the depencency chain
+that lead to the current dylib load.
+You can add an LC_RPATH load command to an image with the -rpath option to ld(1). You can
+even add a LC_RPATH load command path that starts with @loader_path/, and it will push a path
+on the run path stack that relative to the image containing the LC_RPATH.
+The use of @rpath is most useful when you have a complex directory structure of programs and
+dylibs which can be installed anywhere, but keep their relative positions. This scenario
+could be implemented using @loader_path, but every client of a dylib could need a different
+load path because its relative position in the file system is different. The use of @rpath
+introduces a level of indirection that simplies things. You pick a location in your directory
+structure as an anchor point. Each dylib then gets an install path that starts with @rpath
+and is the path to the dylib relative to the anchor point. Each main executable is linked
+with -rpath @loader_path/zzz, where zzz is the path from the executable to the anchor point.
+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