DLOPEN(3) BSD Library Functions Manual DLOPEN(3)
NAME
dlopen -- load and link a dynamic library or bundle
SYNOPSIS
#include <dlfcn.h>
void*
dlopen(const char* path, int mode);
DESCRIPTION
dlopen() examines the mach-o file specified by path. If the file is compatible with the current process and has not already been loaded into
the current process, it is loaded and linked. After being linked, if it contains any initializer functions, they are called, before dlopen()
returns. dlopen() can load dynamic libraries and bundles. It returns a handle that can be used with dlsym() and dlclose(). A second call
to dlopen() with the same path will return the same handle, but the internal reference count for the handle will be incremented. Therefore
all dlopen() calls should be balanced with a dlclose() call.
If a null pointer is passed in path, dlopen() returns a handle equivalent to RTLD_DEFAULT.
mode contains options to dlopen(). It must contain one or more of the following values, possibly ORed together:
RTLD_LAZY Each external function reference is bound the first time the function is called.
RTLD_NOW All external function references are bound immediately during the call to dlopen().
RTLD_LAZY is normally preferred, for reasons of efficiency. However, RTLD_NOW is useful to ensure that any undefined symbols are discovered
during the call to dlopen(). If neither RTLD_LAZY nor RTLD_NOW is specified, the default is RTLD_LAZY.
One of the following flags may be ORed into the mode argument:
RTLD_GLOBAL Symbols exported from this image (dynamic library or bundle) will be available to any images build with -flat_namespace option
to ld(1) or to calls to dlsym() when using a special handle.
RTLD_LOCAL Symbols exported from this image (dynamic library or bundle) are generally hidden and only availble to dlsym() when directly
using the handle returned by this call to dlopen().
If neither RTLD_GLOBAL nor RTLD_LOCAL is specified, the default is RTLD_GLOBAL.
One of the following may be ORed into the mode argument:
RTLD_NOLOAD The specified image is not loaded. However, a valid handle is returned if the image already exists in the process. This pro-
vides a way to query if an image is already loaded. The handle returned is ref-counted, so you eventually need a correspond-
ing call to dlclose()
RTLD_NODELETE The specified image is tagged so that will never be removed from the address space, even after all clients have released it
via dlclose()
Additionally, the following may be ORed into the mode argument:
RTLD_FIRST The retuned handle is tagged so that any dlsym() calls on the handle will only search the image specified, and not subsequent
images. If path is NULL and the option RTLD_FIRST is used, the handle returned will only search the main executable.
SEARCHING
dlopen() searches for a compatible Mach-O file in the directories specified by a set of environment variables and the process's current work-
ing directory. When set, the environment variables contain a colon-separated list of directory paths, which can be absolute or relative to
the current working directory.
When path does not contain a slash character (i.e. it is just a leaf name), dlopen() searches the following until it finds a compatible Mach-
O file: $LD_LIBRARY_PATH, $DYLD_LIBRARY_PATH, current working directory, $DYLD_FALLBACK_LIBRARY_PATH.
When path looks like a framework path (e.g. /stuff/foo.framework/foo), dlopen() searches the following until it finds a compatible Mach-O
file: $DYLD_FRAMEWORK_PATH (with framework partial path from path ), then the supplied path (using current working directory for relative
paths), then $DYLD_FALLBACK_FRAMEWORK_PATH (with framework partial path from path ).
When path contains a slash but is not a framework path (i.e. a full path or a partial path to a dylib), dlopen() searches the following until
it finds a compatible Mach-O file: $DYLD_LIBRARY_PATH (with leaf name from path ), then the supplied path (using current working directory
for relative paths), then $DYLD_FALLBACK_LIBRARY_PATH (with leaf name from path ).
Note: If DYLD_FALLBACK_LIBRARY_PATH is not set, dlopen operates as if DYLD_FALLBACK_LIBRARY_PATH was set to
$HOME/lib:/usr/local/lib:/usr/lib.
Note: If DYLD_FALLBACK_FRAMEWORK_PATH is not set, dlopen operates as if DYLD_FALLBACK_FRAMEWORK_PATH was set to $HOME/Library/Frame-
works:/Library/Frameworks:/Network/Library/Frameworks:/System/Library/Frameworks.
Note: There are no configuration files to control dlopen searching.
Note: If the main executable is a set[ug]id binary or codesigned with entitlements, then all environment variables are ignored, and only a
full path can be used.
Note: Mac OS X uses "universal" files to combine 32-bit and 64-bit libraries. This means there are no separate 32-bit and 64-bit search
paths.
RETURN VALUES
If dlopen() fails, it returns a null pointer, and sets an error condition which may be interrogated with dlerror().
SEE ALSO
dlopen_preflight(3) dlclose(3) dlsym(3) dlerror(3) dyld(1) ld(1)
BSD
Aug 7, 2012 BSD