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

NAME
     ddllooppeenn - load and link a dynamic library or bundle

SYNOPSIS
     ##iinncclluuddee <>

     void*
     ddllooppeenn(const char* path, int mode);

DESCRIPTION
     ddllooppeenn() 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 ddllooppeenn()
     returns.  ddllooppeenn() can load dynamic libraries and bundles.  It returns a
     handle that can be used with ddllssyymm() and ddllcclloossee().  A second call to
     ddllooppeenn() with the same path will return the same handle, but the internal
     reference count for the handle will be incremented.  Therefore all
     ddllooppeenn() calls should be balanced with a ddllcclloossee() call.

     If a null pointer is passed in path, ddllooppeenn() returns a handle equivalent
     to RTLDDEFAULT.

     mode contains options to ddllooppeenn().  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 ddllooppeenn().

     RTLDLAZY is normally preferred, for reasons of efficiency.  However,
     RTLDNOW is useful to ensure that any undefined symbols are discovered
     during the call to ddllooppeenn().  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 bundle)
                  will be available to any images build with -flatnamespace
                  option to ld(1) or to calls to ddllssyymm() when using a special
                  handle.

     RTLDLOCAL   Symbols exported from this image (dynamic library or bundle)
                  are generally hidden and only availble to ddllssyymm() when
                  directly using the handle returned by this call to ddllooppeenn().

     If neither RTLDGLOBAL nor RTLDLOCAL is specified, the default is
     RTLDGLOBAL.

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

     RTLDNOLOAD     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 ddllcclloossee()

     RTLDNODELETE   The specified image is tagged so that will never be
                     removed from the address space, even after all clients
                     have released it via ddllcclloossee()

     Additionally, the following may be ORed into the mode argument:

     RTLDFIRST   The retuned handle is tagged so that any ddllssyymm() calls on
                  the handle will only search the image specified, and not
                  subsequent images.  If path is NULL and the option
                  RTLDFIRST is used, the handle returned will only search the
                  main executable.

SSEEAARRCCHHIINNGG
     ddllooppeenn() 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 must contain a colon-sep-
     arated list of directory paths, which can be absolute or relative to the
     current working directory. The environment variables are LDLIBRARYPATH,
     DYLDLIBRARYPATH, and DYLDFALLBACKLIBRARYPATH.  The first two vari-
     ables have no default value. The default value of DYLDFALL-
     BACKLIBRARYPATH is $HOME/lib;/usr/local/lib;/usr/lib.  ddllooppeenn()
     searches the directories specified in the environment variables in the
     order they are listed.

     When path doesn't contain a slash character (i.e. it is just a leaf
     name), ddllooppeenn() searches the following the following until it finds a
     compatible Mach-O file: $LDLIBRARYPATH, $DYLDLIBRARYPATH, current
     working directory, $DYLDFALLBACKLIBRARYPATH.

     When path contains a slash (i.e. a full path or a partial path) ddllooppeenn()
     searches the following the following until it finds a compatible Mach-O
     file: $DYLDLIBRARYPATH (with leaf name from path ), current working
     directory (for partial paths), $DYLDFALLBACKLIBRARYPATH (with leaf
     name from path ).

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

     Note: If the main executable is a set[ug]id binary, 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 ddllooppeenn() fails, it returns a null pointer, and sets an error condition
     which may be interrogated with ddlleerrrroorr().

AUTHORS     Mac OS X 10.3 incorporated the dlcompat package written by Jorge Acereda
      and Peter O'Gorman      man@users.sourceforge.net>.

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

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

BSD                               Nov 6, 2006                              BSD