DYLD
Section: User Commands (1)
Updated: March 12, 2001
Index
Return to Main Contents
NAME
dyld - the dynamic link editor
SYNOPSIS
DYLD_FRAMEWORK_PATH
DYLD_FALLBACK_FRAMEWORK_PATH
DYLD_LIBRARY_PATH
DYLD_FALLBACK_LIBRARY_PATH
DYLD_INSERT_LIBRARIES
DYLD_FORCE_FLAT_NAMESPACE
DYLD_IMAGE_SUFFIX
DYLD_PRINT_LIBRARIES
DYLD_MEM_PROTECT
DYLD_EBADEXEC_ONLY
DYLD_BIND_AT_LAUNCH
DYLD_DEAD_LOCK_HANG
DYLD_PREBIND_DEBUG
DYLD_ABORT_MULTIPLE_INITS
DYLD_NEW_LOCAL_SHARED_REGIONS
DESCRIPTION
The dynamic linker uses the following environment variables.
They affect any program that uses the dynamic linker.
- DYLD_FRAMEWORK_PATH
-
This is a colon separated list of directories that contain frameworks.
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
name.)
-
For each framework that a program uses, the dynamic linker looks for the
framework in each directory in
DYLD_FRAMEWORK_PATH
in turn. If it looks in all the directories and can't find the framework, it
searches the directories in
DYLD_LIBRARY_PATH
in turn. If it still can't find the framework, it then searches
DYLD_FALLBACK_FRAMEWORK_PATH
and
DYLD_FALLBACK_LIBRARY_PATH
in turn.
-
You can view which version of the framework that the dyld uses with the
-L
option to
otool(1).
- 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.
By default, it is set to
$(HOME)/Library/Frameworks:/Library/Frameworks:/Network/Library/Frameworks:/System/Library/Frameworks
- 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
locations for libraries. It allows you to test new versions of existing
libraries.
-
For each library that a program uses, the dynamic linker looks for it in each
directory in
DYLD_LIBRARY_PATH
in turn. If it still can't find the library, it then searches
DYLD_FALLBACK_FRAMEWORK_PATH
and
DYLD_FALLBACK_LIBRARY_PATH
in turn.
-
You can view which version of the library that the dyld uses with the
-L
option to
otool(1).
- 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.
By default, it is set
to $(HOME)/lib:/usr/local/lib:/lib:/usr/lib.
- DYLD_INSERT_LIBRARIES
-
This is a colon separated list of dynamic libraries to load before the ones
specified in the program. This lets you test new modules of existing dynamic
shared libraries that are used in flat-namespace images by loading a temporary
dynamic shared library with just the new modules. Note that this has no
effect on images built a two-level namespace images using a dynamic shared
library unless
DYLD_FORCE_FLAT_NAMESPACE
is also used.
- DYLD_FORCE_FLAT_NAMESPACE
-
Force all images in the program to be linked as flat-namespace images and ignore
any two-level namespace bindings. This may cause programs to fail to execute
with a multiply defined symbol error if two-level namespace images are used to
allow the images to have multiply defined symbols.
- DYLD_IMAGE_SUFFIX
-
This is set to a string of a suffix to try to be used for all shared libraries
used by the program. For libraries ending in ".dylib" the suffix is applied
just before the ".dylib". For all other libraries the suffix is appended to the
library name. This is useful for using conventional "_profile" and "_debug"
libraries and frameworks.
- DYLD_PRINT_LIBRARIES
-
When this is set, the dynamic linker writes to file descriptor 2 (normally
standard error) the filenames of the libraries the program is using.
This is useful to make sure that the use of
DYLD_LIBRARY_PATH
is getting what you want.
- DYLD_MEM_PROTECT
-
When this is set, the dynamic linker changes the protection of
the memory it uses for its data structures when it is not operating on them.
This helps track down the point where a program does an inappropriate write.
It is possible for an errant program to mistakenly write on the data structures
of dynamic linker. This variable causes the program to crash at the first
occurrence of the write making the error easier to track down. Unfortunately,
this can't be done in the debugger as the debugger's interface to the dynamic
linker will cause the dynamic link editor's memory to remain writable. But
setting this variable can produce a very useful core file, which you can debug
later.
- DYLD_EBADEXEC_ONLY
-
When this is set, the dynamic linker does all of the work needed
to launch a program without launching it.
This either prints the cause why the program could not be launched or prints
a message saying the program could be launched.
This variable can be used a supplement to the program
ebadexec(1)
to determine why a program can't be launched.
For programs that should not have any undefined symbols when launched the
DYLD_BIND_AT_LAUNCH
can also be set to check this.
- 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.
- DYLD_DEAD_LOCK_HANG
-
When this is set, the dynamic linker enters a loop that hangs
the program if a thread doing a dynamic linker operation attempts to start
another dynamic linker operation before completing the first.
This lets you attach a debugger to the process instead of letting the process
exit.
- 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
-Lv
option to
otool(1).
- DYLD_ABORT_MULTIPLE_INITS
-
When this is set, the dynamic linker causes the program to abort when multiple
library initialization routines are being run which can happen if code called
via a library initialization routine makes a call to a dyld API. Then under the
debugger it is easy to do a back trace and find the code that is making the
call to a dyld API via code called from a library initialization routine
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
exec(2)'ed
from a secure program too will not have it's libraries searched for, as well.
For staticly linked secure programs that
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.
- 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
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
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
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 childrens' submaps will not be caused to be
present in the submaps shared by the rest of the system.
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
chroot(2)
call.
SEE ALSO
libtool(1), ld(1), otool(1), redo_prebinding(1)
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- SEE ALSO
-
This document was created by
man2html,
using the manual pages.
Time: 04:29:57 GMT, April 24, 2025