X-Git-Url: https://git.saurik.com/apple/dyld.git/blobdiff_plain/0959b6d4289bd106fddb7fe7d84a346159895fdd..refs/heads/master:/doc/man/man1/dyld.1 diff --git a/doc/man/man1/dyld.1 b/doc/man/man1/dyld.1 index 9e0b776..605f454 100644 --- a/doc/man/man1/dyld.1 +++ b/doc/man/man1/dyld.1 @@ -1,16 +1,22 @@ -.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 @@ -24,15 +30,9 @@ DYLD_PRINT_ENV .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 @@ -45,9 +45,19 @@ DYLD_PRINT_REBASINGS 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. @@ -55,35 +65,40 @@ The dynamic linker searches these directories before it searches for the 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 @@ -91,32 +106,47 @@ dynamic linker searches these directories before it searches the default 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 @@ -156,85 +186,25 @@ This is useful to make sure that the use of .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 @@ -242,12 +212,70 @@ Causes dyld to print a line whenever a dyld API is called (e.g. NSAddImage()). .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)