DLOPEN(3)                BSD Library Functions Manual                DLOPEN(3)

NAME
     dlopen -- load and link a dynamic library or bundle

SYNOPSIS
     ##include <>

     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 RTLDEFAULT.

     mode contains options to dlopen().  It must contain one or more of the
     following values, possibly ORed together:

     RTLDLAZY   Each external function reference is bound the first time the
                 function is called.

     RTLDNOW    All external function references are bound immediately during
                 the call to dlopen().

     RTLDLAZY is normally preferred, for reasons of efficiency.  However,
     RTLDNOW is useful to ensure that any undefined symbols are discovered
     during the call to dlopen().  If neither RTLDLAZY nor RTLDNOW is speci-
     fied, the default is RTLDLAZY.

     One of the following flags may be ORed into the mode argument:

     RTLDGLOBAL   Symbols exported from this image (dynamic library or bun-
                   dle) will be available to any images build with
                   -flatnamespace option to ld(1) or to calls to dlsym() when
                   using a special handle.

     RTLDLOCAL    Symbols exported from this image (dynamic library or bun-
                   dle) are generally hidden and only availble to dlsym() when
                   directly using the handle returned by this call to
                   dlopen().  If neither RTLDGLOBAL nor RTLDLOCAL is speci-
                   fied, the default is RTLDGLOBAL.

SEARCHING
     dlopen() uses a series of steps to find a compatible mach-o file.  The
     first compatible file found is used.

     1) If the directory specified by path does not contain a slash '/' (i.e.
     it is a leaf name) then the environment variable LDLIBRARYPATH is used.
     LDLIBRARYPATH should be a colon seperated list of directories.
     dlopen() searches each directory, in the order specified, for the leaf
     name path.

     2) If DYLDLIBRARYPATH is set, then those directories are searched, in
     order, with the leaf name of path.

     3) If DYLDFALBACKLIBRARYPATH is set, then those directories are
     searched, in order with the leaf name of path.  If DYLDFAL-
     BACKLIBRARYPATH is not set, then the following directories are
     searched: $HOME/lib, /usr/local/lib, /usr/lib

     4) Lastly, path is tried as-is as a regular file path.  That means it
     might resolve relative to the current working directory.

     Note: There are no configuration files to control dlopen searching.

     Note: Mac OS X uses "fat" 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().

AUTHORS
     Mac OS X 10.3 incorporated the dlcompat package written by Jorge Acereda
      and Peter O'Gorman .

     In Mac OS X 10.4, dlopen was rewritten to be a native part of dyld.

SEE ALSO
     dlclose(3) dlsym(3) dlerror(3) dyld(3) ld(1)

BSD                            February 8, 2005                            BSD