-.TH DYLD 1 "March 23, 2007" "Apple Inc."
+.TH DYLD 1 "December 14, 2009" "Apple Inc."
.SH NAME
dyld \- the dynamic link editor
.SH SYNOPSIS
.br
DYLD_FALLBACK_FRAMEWORK_PATH
.br
+DYLD_VERSIONED_FRAMEWORK_PATH
+.br
DYLD_LIBRARY_PATH
.br
DYLD_FALLBACK_LIBRARY_PATH
.br
+DYLD_VERSIONED_LIBRARY_PATH
+.br
DYLD_ROOT_PATH
.br
DYLD_SHARED_REGION
DYLD_PRINT_STATISTICS
.br
DYLD_PRINT_DOFS
+.br
+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.
By default, it is set to
/Library/Frameworks:/Network/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 is 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
dynamic linker searches these directories before it searches the default
By default, it is set
to $(HOME)/lib:/usr/local/lib:/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_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.
.TP
.B DYLD_SHARED_REGION
-This can be "use" (the default), "avoid", or "private". Settting it to
+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()
.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 and DYLD_SHARED_CACHE_DONT_VALIDATE
+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.
+.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)
projects / apple / dyld.git / blobdiff