# dlopen

## NAME



           dlclose, dlopen, dlmopen - open and close a shared object
    


## LIBRARY



           Dynamic linking library (_libdl_ , _-ldl_)
    


## SYNOPSIS



           **#include <dlfcn.h>**
    
           **void *dlopen(const char ***_path_**, int** _flags_**);**
           **int dlclose(void ***_handle_**);**
    
           **#define _GNU_SOURCE**
           **#include <dlfcn.h>**
    
           **void *dlmopen(Lmid_t** _lmid_**, const char ***_path_**, int** _flags_**);**
    


## DESCRIPTION



       **dlopen()**
           The function **dlopen**() loads the dynamic shared object (shared
           library) file named by the null-terminated string _path_ and returns
           an opaque "handle" for the loaded object.  This handle is employed
           with other functions in the dlopen API, such as dlsym(3),
           dladdr(3), dlinfo(3), and **dlclose**().
    
           If _path_ is NULL, then the returned handle is for the main program.
           If _path_ contains a slash ("/"), then it is interpreted as a
           (relative or absolute) pathname.  Otherwise, the dynamic linker
           searches for the object as follows (see ld.so(8) for further
           details):
    
           •  (ELF only) If the calling object (i.e., the shared library or
              executable from which **dlopen**() is called) contains a DT_RPATH
              tag, and does not contain a DT_RUNPATH tag, then the
              directories listed in the DT_RPATH tag are searched.
    
           •  If, at the time that the program was started, the environment
              variable **LD_LIBRARY_PATH** was defined to contain a colon-
              separated list of directories, then these are searched.  (As a
              security measure, this variable is ignored for set-user-ID and
              set-group-ID programs.)
    
           •  (ELF only) If the calling object contains a DT_RUNPATH tag,
              then the directories listed in that tag are searched.
    
           •  The cache file _/etc/ld.so.cache_ (maintained by ldconfig(8)) is
              checked to see whether it contains an entry for _path_.
    
           •  The directories _/lib_ and _/usr/lib_ are searched (in that order).
    
           If the object specified by _path_ has dependencies on other shared
           objects, then these are also automatically loaded by the dynamic
           linker using the same rules.  (This process may occur recursively,
           if those objects in turn have dependencies, and so on.)
    
           One of the following two values must be included in _flags_ :
    
           **RTLD_LAZY**
                  Perform lazy binding.  Resolve symbols only as the code
                  that references them is executed.  If the symbol is never
                  referenced, then it is never resolved.  (Lazy binding is
                  performed only for function references; references to
                  variables are always immediately bound when the shared
                  object is loaded.)  Since glibc 2.1.1, this flag is
                  overridden by the effect of the **LD_BIND_NOW** environment
                  variable.
    
           **RTLD_NOW**
                  If this value is specified, or the environment variable
                  **LD_BIND_NOW** is set to a nonempty string, all undefined
                  symbols in the shared object are resolved before **dlopen**()
                  returns.  If this cannot be done, an error is returned.
    
           Zero or more of the following values may also be ORed in _flags_ :
    
           **RTLD_GLOBAL**
                  The symbols defined by this shared object will be made
                  available for symbol resolution of subsequently loaded
                  shared objects.
    
           **RTLD_LOCAL**
                  This is the converse of **RTLD_GLOBAL** , and the default if
                  neither flag is specified.  Symbols defined in this shared
                  object are not made available to resolve references in
                  subsequently loaded shared objects.
    
           **RTLD_NODELETE**(since glibc 2.2)
                  Do not unload the shared object during **dlclose**().
                  Consequently, the object's static and global variables are
                  not reinitialized if the object is reloaded with **dlopen**()
                  at a later time.
    
           **RTLD_NOLOAD**(since glibc 2.2)
                  Don't load the shared object.  This can be used to test if
                  the object is already resident (**dlopen**() returns NULL if it
                  is not, or the object's handle if it is resident).  This
                  flag can also be used to promote the flags on a shared
                  object that is already loaded.  For example, a shared
                  object that was previously loaded with **RTLD_LOCAL** can be
                  reopened with **RTLD_NOLOAD | RTLD_GLOBAL**.
    
           **RTLD_DEEPBIND**(since glibc 2.3.4)
                  Place the lookup scope of the symbols in this shared object
                  ahead of the global scope.  This means that a self-
                  contained object will use its own symbols in preference to
                  global symbols with the same name contained in objects that
                  have already been loaded.
    
           If _path_ is NULL, then the returned handle is for the main program.
           When given to dlsym(3), this handle causes a search for a symbol
           in the main program, followed by all shared objects loaded at
           program startup, and then all shared objects loaded by **dlopen**()
           with the flag **RTLD_GLOBAL**.
    
           Symbol references in the shared object are resolved using (in
           order): symbols in the link map of objects loaded for the main
           program and its dependencies; symbols in shared objects (and their
           dependencies) that were previously opened with **dlopen**() using the
           **RTLD_GLOBAL** flag; and definitions in the shared object itself (and
           any dependencies that were loaded for that object).
    
           Any global symbols in the executable that were placed into its
           dynamic symbol table by ld(1) can also be used to resolve
           references in a dynamically loaded shared object.  Symbols may be
           placed in the dynamic symbol table either because the executable
           was linked with the flag "-rdynamic" (or, synonymously,
           "--export-dynamic"), which causes all of the executable's global
           symbols to be placed in the dynamic symbol table, or because ld(1)
           noted a dependency on a symbol in another object during static
           linking.
    
           If the same shared object is opened again with **dlopen**(), the same
           object handle is returned.  The dynamic linker maintains reference
           counts for object handles, so a dynamically loaded shared object
           is not deallocated until **dlclose**() has been called on it as many
           times as **dlopen**() has succeeded on it.  Constructors (see below)
           are called only when the object is actually loaded into memory
           (i.e., when the reference count increases to 1).
    
           A subsequent **dlopen**() call that loads the same shared object with
           **RTLD_NOW** may force symbol resolution for a shared object earlier
           loaded with **RTLD_LAZY**.  Similarly, an object that was previously
           opened with **RTLD_LOCAL** can be promoted to **RTLD_GLOBAL** in a
           subsequent **dlopen**().
    
           If **dlopen**() fails for any reason, it returns NULL.
    
       **dlmopen()**
           This function performs the same task as **dlopen**()—the _path_ and
           _flags_ arguments, as well as the return value, are the same, except
           for the differences noted below.
    
           The **dlmopen**() function differs from **dlopen**() primarily in that it
           accepts an additional argument, _lmid_ , that specifies the link-map
           list (also referred to as a _namespace_) in which the shared object
           should be loaded.  (By comparison, **dlopen**() adds the dynamically
           loaded shared object to the same namespace as the shared object
           from which the **dlopen**() call is made.)  The _Lmid_t_ type is an
           opaque handle that refers to a namespace.
    
           The _lmid_ argument is either the ID of an existing namespace (which
           can be obtained using the dlinfo(3) **RTLD_DI_LMID** request) or one
           of the following special values:
    
           **LM_ID_BASE**
                  Load the shared object in the initial namespace (i.e., the
                  application's namespace).
    
           **LM_ID_NEWLM**
                  Create a new namespace and load the shared object in that
                  namespace.  The object must have been correctly linked to
                  reference all of the other shared objects that it requires,
                  since the new namespace is initially empty.
    
           If _path_ is NULL, then the only permitted value for _lmid_ is
           **LM_ID_BASE**.
    
       **dlclose()**
           The function **dlclose**() decrements the reference count on the
           dynamically loaded shared object referred to by _handle_.
    
           If the object's reference count drops to zero and no symbols in
           this object are required by other objects, then the object is
           unloaded after first calling any destructors defined for the
           object.  (Symbols in this object might be required in another
           object because this object was opened with the **RTLD_GLOBAL** flag
           and one of its symbols satisfied a relocation in another object.)
    
           All shared objects that were automatically loaded when **dlopen**()
           was invoked on the object referred to by _handle_ are recursively
           closed in the same manner.
    
           A successful return from **dlclose**() does not guarantee that the
           symbols associated with _handle_ are removed from the caller's
           address space.  In addition to references resulting from explicit
           **dlopen**() calls, a shared object may have been implicitly loaded
           (and reference counted) because of dependencies in other shared
           objects.  Only when all references have been released can the
           shared object be removed from the address space.
    


## RETURN VALUE



           On success, **dlopen**() and **dlmopen**() return a non-NULL handle for
           the loaded object.  On error (file could not be found, was not
           readable, had the wrong format, or caused errors during loading),
           these functions return NULL.
    
           On success, **dlclose**() returns 0; on error, it returns a nonzero
           value.
    
           Errors from these functions can be diagnosed using dlerror(3).
    


## ATTRIBUTES



           For an explanation of the terms used in this section, see
           attributes(7).
           ┌──────────────────────────────────────┬───────────────┬─────────┐
           │ **Interface** │ **Attribute** │ **Value** │
           ├──────────────────────────────────────┼───────────────┼─────────┤
           │ **dlopen**(), **dlmopen**(), **dlclose**()       │ Thread safety │ MT-Safe │
           └──────────────────────────────────────┴───────────────┴─────────┘
    


## STANDARDS



           **dlopen**()
           **dlclose**()
                  POSIX.1-2008.
    
           **dlmopen**()
           **RTLD_NOLOAD**
           **RTLD_NODELETE**
                  GNU.
    
           **RTLD_DEEPBIND**
                  Solaris.
    


## NOTES



       **dlmopen() and namespaces**
           A link-map list defines an isolated namespace for the resolution
           of symbols by the dynamic linker.  Within a namespace, dependent
           shared objects are implicitly loaded according to the usual rules,
           and symbol references are likewise resolved according to the usual
           rules, but such resolution is confined to the definitions provided
           by the objects that have been (explicitly and implicitly) loaded
           into the namespace.
    
           The **dlmopen**() function permits object-load isolation—the ability
           to load a shared object in a new namespace without exposing the
           rest of the application to the symbols made available by the new
           object.  Note that the use of the **RTLD_LOCAL** flag is not
           sufficient for this purpose, since it prevents a shared object's
           symbols from being available to _any_ other shared object.  In some
           cases, we may want to make the symbols provided by a dynamically
           loaded shared object available to (a subset of) other shared
           objects without exposing those symbols to the entire application.
           This can be achieved by using a separate namespace and the
           **RTLD_GLOBAL** flag.
    
           The **dlmopen**() function also can be used to provide better
           isolation than the **RTLD_LOCAL** flag.  In particular, shared objects
           loaded with **RTLD_LOCAL** may be promoted to **RTLD_GLOBAL** if they are
           dependencies of another shared object loaded with **RTLD_GLOBAL**.
           Thus, **RTLD_LOCAL** is insufficient to isolate a loaded shared object
           except in the (uncommon) case where one has explicit control over
           all shared object dependencies.
    
           Possible uses of **dlmopen**() are plugins where the author of the
           plugin-loading framework can't trust the plugin authors and does
           not wish any undefined symbols from the plugin framework to be
           resolved to plugin symbols.  Another use is to load the same
           object more than once.  Without the use of **dlmopen**(), this would
           require the creation of distinct copies of the shared object file.
           Using **dlmopen**(), this can be achieved by loading the same shared
           object file into different namespaces.
    
           The glibc implementation supports a maximum of 16 namespaces.
    
       **Initialization and finalization functions**
           Shared objects may export functions using the
           **__attribute__((constructor))** and **__attribute__((destructor))**
           function attributes.  Constructor functions are executed before
           **dlopen**() returns, and destructor functions are executed before
           **dlclose**() returns.  A shared object may export multiple
           constructors and destructors, and priorities can be associated
           with each function to determine the order in which they are
           executed.  See the **gcc** info pages (under "Function attributes")
           for further information.
    
           An older method of (partially) achieving the same result is via
           the use of two special symbols recognized by the linker: **_init** and
           **_fini**.  If a dynamically loaded shared object exports a routine
           named **_init**(), then that code is executed after loading a shared
           object, before **dlopen**() returns.  If the shared object exports a
           routine named **_fini**(), then that routine is called just before the
           object is unloaded.  In this case, one must avoid linking against
           the system startup files, which contain default versions of these
           files; this can be done by using the gcc(1) _-nostartfiles_ command-
           line option.
    
           Use of **_init** and **_fini** is now deprecated in favor of the
           aforementioned constructors and destructors, which among other
           advantages, permit multiple initialization and finalization
           functions to be defined.
    
           Since glibc 2.2.3, atexit(3) can be used to register an exit
           handler that is automatically called when a shared object is
           unloaded.
    
       **History**
           These functions are part of the dlopen API, derived from SunOS.
    


## BUGS



           As at glibc 2.24, specifying the **RTLD_GLOBAL** flag when calling
           **dlmopen**() generates an error.  Furthermore, specifying **RTLD_GLOBAL**
           when calling **dlopen**() results in a program crash (**SIGSEGV**) if the
           call is made from any object loaded in a namespace other than the
           initial namespace.
    


## EXAMPLES



           The program below loads the (glibc) math library, looks up the
           address of the cos(3) function, and prints the cosine of 2.0.  The
           following is an example of building and running the program:
    
               $ **cc dlopen_demo.c -ldl** ;
               $ **./a.out** ;
               -0.416147
    
       **Program source**
    
           #include <dlfcn.h>
           #include <stdio.h>
           #include <stdlib.h>
    
           #include <gnu/lib-names.h>  /* Defines LIBM_SO (which will be a
                                          string such as "libm.so.6") */
           int
           main(void)
           {
               void *handle;
               typeof(double (double)) *cosine;
               char *error;
    
               handle = dlopen(LIBM_SO, RTLD_LAZY);
               if (!handle) {
                   fprintf(stderr, "%s\n", dlerror());
                   exit(EXIT_FAILURE);
               }
    
               dlerror();    /* Clear any existing error */
    
               cosine = (typeof(double (double)) *) dlsym(handle, "cos");
    
               /* According to the ISO C standard, casting between function
                  pointers and 'void *', as done above, produces undefined results.
                  POSIX.1-2001 and POSIX.1-2008 accepted this state of affairs and
                  proposed the following workaround:
    
                      *(void **) &cosine = dlsym(handle, "cos");
    
                  This (clumsy) cast conforms with the ISO C standard and will
                  avoid any compiler warnings.
    
                  The 2013 Technical Corrigendum 1 to POSIX.1-2008 improved matters
                  by requiring that conforming implementations support casting
                  'void *' to a function pointer.  Nevertheless, some compilers
                  (e.g., gcc with the '-pedantic' option) may complain about the
                  cast used in this program. */
    
               error = dlerror();
               if (error != NULL) {
                   fprintf(stderr, "%s\n", error);
                   exit(EXIT_FAILURE);
               }
    
               printf("%f\n", (*cosine)(2.0));
               dlclose(handle);
               exit(EXIT_SUCCESS);
           }
    


* * *