NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | ATTRIBUTES | CONFORMING TO | NOTES | EXAMPLE | BUGS | SEE ALSO | COLOPHON

DLOPEN(3)                 Linux Programmer's Manual                DLOPEN(3)

NAME         top

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

SYNOPSIS         top

       #include <dlfcn.h>

       void *dlopen(const char *filename, int flags);

       int dlclose(void *handle);

       #define _GNU_SOURCE
       #include <dlfcn.h>

       void *dlmopen (Lmid_t lmid, const char *filename, int flags);

       Link with -ldl.

DESCRIPTION         top

   dlopen()
       The function dlopen() loads the dynamic shared object (shared
       library) file named by the null-terminated string filename 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 filename is NULL, then the returned handle is for the main
       program.  If filename 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):

       o   (ELF only) If the executable file for the calling program
           contains a DT_RPATH tag, and does not contain a DT_RUNPATH tag,
           then the directories listed in the DT_RPATH tag are searched.

       o   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.)

       o   (ELF only) If the executable file for the calling program
           contains a DT_RUNPATH tag, then the directories listed in that
           tag are searched.

       o   The cache file /etc/ld.so.cache (maintained by ldconfig(8)) is
           checked to see whether it contains an entry for filename.

       o   The directories /lib and /usr/lib are searched (in that order).

       If the object specified by filename 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.  Only resolve symbols 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.)

       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 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 filename is NULL, then the returned handle is for the main
       program.  When given to dlsym(), 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.

       External references in the shared object are resolved using the
       shared objects in that object's dependency list and any other objects
       previously opened with the RTLD_GLOBAL flag.  If the executable was
       linked with the flag "-rdynamic" (or, synonymously,
       "--export-dynamic"), then the global symbols in the executable will
       also be used to resolve references in a dynamically loaded shared
       object.

       If the same shared object is loaded 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.  Any initialization returns (see
       below) are called just once.  However, 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.

       If dlopen() fails for any reason, it returns NULL.

   dlmopen()
       This function performs the same task as dlopen()—the filename 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 filename 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
       reference count drops to zero, then the object is unloaded.  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         top

       On success, dlopen() and dlmopen() return a non-NULL handle for the
       loaded library.  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).

VERSIONS         top

       dlopen() and dlclose() are present in glibc 2.0 and later.  dlmopen()
       first appeared in glibc 2.3.4.

ATTRIBUTES         top

       For an explanation of the terms used in this section, see
       attributes(7).

       ┌───────────────────────────────┬───────────────┬─────────┐
       │Interface                      Attribute     Value   │
       ├───────────────────────────────┼───────────────┼─────────┤
       │dlopen(), dlmopen(), dlclose() │ Thread safety │ MT-Safe │
       └───────────────────────────────┴───────────────┴─────────┘

CONFORMING TO         top

       POSIX.1-2001 describes dlclose() and dlopen().  The dlmopen()
       function is a GNU extension.

       The RTLD_NOLOAD, RTLD_NODELETE, and RTLD_DEEP_BIND flags are GNU
       extensions; the first two of these flags are also present on Solaris.

NOTES         top

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

EXAMPLE         top

       Load the math library, and print the cosine of 2.0:

       #include <stdio.h>
       #include <stdlib.h>
       #include <dlfcn.h>

       int
       main(int argc, char **argv)
       {
           void *handle;
           double (*cosine)(double);
           char *error;

           handle = dlopen("libm.so", RTLD_LAZY);
           if (!handle) {
               fprintf(stderr, "%s\n", dlerror());
               exit(EXIT_FAILURE);
           }

           dlerror();    /* Clear any existing error */

           cosine = (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-2003 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 to POSIX.1-2008 (a.k.a.
              POSIX.1-2013) 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);
       }

BUGS         top

       As at glibc 2.21, 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.

SEE ALSO         top

       ld(1), ldd(1), pldd(1), dl_iterate_phdr(3), dladdr(3), dlerror(3),
       dlinfo(3), dlsym(3), rtld-audit(7), ld.so(8), ldconfig(8)

       gcc info pages, ld info pages

COLOPHON         top

       This page is part of release 4.02 of the Linux man-pages project.  A
       description of the project, information about reporting bugs, and the
       latest version of this page, can be found at
       http://www.kernel.org/doc/man-pages/.

Linux                            2015-08-08                        DLOPEN(3)