GENWiki

Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools


man:dlopen

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

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  (rela-
     tive 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 vari-
         able  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 pro-
         grams.)
     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 immedi-
            ately 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  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  previ-
     ously  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 ref-
     erences 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 names-
            pace.   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  dynami-
     cally  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

     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

     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).
     +-------------------------------+---------------+---------+
     |Interface                      | Attribute     | Value   |
     +-------------------------------+---------------+---------+
     |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  exten-
     sions; 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  dependen-
     cies.
     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.  With-
     out  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 names-
     paces.
     The glibc implementation supports a maximum of 16 namespaces.
 Initialization and finalization functions
     Shared objects may export functions using the  __attribute__((construc-
     tor)) and __attribute__((destructor)) function attributes.  Constructor
     functions are executed before dlopen() returns,  and  destructor  func-
     tions  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 mul-
     tiple 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 4.16 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 2017-09-15 DLOPEN(3)

/data/webs/external/dokuwiki/data/pages/man/dlopen.txt · Last modified: 2019/05/17 09:47 by 127.0.0.1

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki