dlopen(3) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | ATTRIBUTES | CONFORMING TO | NOTES | BUGS | EXAMPLES | 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 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.

       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 calling object 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.  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 filename 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 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 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         top

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

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_DEEPBIND 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 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         top

       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         top

       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 <stdio.h>
       #include <stdlib.h>
       #include <dlfcn.h>
       #include <gnu/lib-names.h>  /* Defines LIBM_SO (which will be a
                                      string such as "libm.so.6") */
       int
       main(void)
       {
           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-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);
       }

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 5.12 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
       https://www.kernel.org/doc/man-pages/.

Linux                          2021-03-22                      DLOPEN(3)

Pages that refer to this page: dbpmda(1)pldd(1)pmcd(1)mmap(2)uselib(2)vfork(2)atexit(3)backtrace(3)dladdr(3)dlerror(3)dlinfo(3)dl_iterate_phdr(3)dlsym(3)lttng-ust(3)lttng-ust-dl(3)pmda(3)rtld-audit(7)ld.so(8)mount(8)