focal (3) dlopen.3.gz

Provided by: manpages-dev_5.05-1_all bug

NAME

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

SYNOPSIS

       #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

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

       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

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

ATTRIBUTES

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

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

CONFORMING TO

       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

   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.

EXAMPLE

       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-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);
       }

SEE ALSO

       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

       This  page  is  part  of  release  5.05  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/.