manpagez: man pages & more
man dlopen(3)
Home | html | info | man
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 com-
     patible with the current process and has not already been loaded into the
     current process, it is loaded and linked.  After being linked, if it con-
     tains 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 speci-
     fied, 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 provides a way to query if an image is
                     already loaded.  The handle returned is ref-counted, so
                     you eventually need a corresponding 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 speci-
     fied by a set of environment variables and the process's current working
     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 rela-
     tive 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:/Sys-
     tem/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

Mac OS X 10.9.1 - Generated Tue Jan 7 19:08:18 CST 2014
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.