Man Pages

dlopen(3) - phpMan dlopen(3) - phpMan

Command: man perldoc info search(apropos)  


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



NAME
       dladdr, dlclose, dlerror, dlopen, dlsym, dlvsym - programming interface to dynamic linking loader

SYNOPSIS
       #include <dlfcn.h>

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

       char *dlerror(void);

       void *dlsym(void *handle, const char *symbol);

       int dlclose(void *handle);

       Link with -ldl.

DESCRIPTION
       The  four  functions  dlopen(),  dlsym(),  dlclose(),  dlerror() implement the interface to the dynamic linking
       loader.

   dlerror()
       The function dlerror() returns a human readable string describing the most  recent  error  that  occurred  from
       dlopen(),  dlsym()  or  dlclose() since the last call to dlerror().  It returns NULL if no errors have occurred
       since initialization or since it was last called.

   dlopen()
       The function dlopen() loads the dynamic library file named by the null-terminated string filename  and  returns
       an opaque "handle" for the dynamic library.  If filename is NULL, then the returned handle is for the main pro-
       gram.  If filename contains a slash ("/"), then it is interpreted as a (relative or absolute) pathname.  Other-
       wise, the dynamic linker searches for the library 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  con-
           tain  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 library has dependencies on other shared libraries, then these are  also  automatically  loaded  by  the
       dynamic  linker  using  the  same  rules.  (This process may occur recursively, if those libraries in turn have
       dependencies, and so on.)

       One of the following two values must be included in flag:

       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 only performed for function refer-
              ences; references to variables are always immediately bound when the library is loaded.)

       RTLD_NOW
              If this value is specified, or the environment variable LD_BIND_NOW is set to a  non-empty  string,  all
              undefined symbols in the library are resolved before dlopen() returns.  If this cannot be done, an error
              is returned.

       Zero of more of the following values may also be ORed in flag:

       RTLD_GLOBAL
              The symbols defined by this library will be made available for symbol resolution of subsequently  loaded
              libraries.

       RTLD_LOCAL
              This  is  the converse of RTLD_GLOBAL, and the default if neither flag is specified.  Symbols defined in
              this library are not made available to resolve references in subsequently loaded libraries.

       RTLD_NODELETE (since glibc 2.2)
              Do not unload the library during dlclose().  Consequently, the library's static variables are not reini-
              tialized  if  the  library  is  reloaded  with  dlopen() at a later time.  This flag is not specified in
              POSIX.1-2001.

       RTLD_NOLOAD (since glibc 2.2)
              Don't load the library.  This can be used to test if the library is already resident  (dlopen()  returns
              NULL  if  it  is not, or the library's handle if it is resident).  This flag can also be used to promote
              the flags on a library that is already loaded.  For example, a library that was previously  loaded  with
              RTLD_LOCAL can be re-opened with RTLD_NOLOAD | RTLD_GLOBAL.  This flag is not specified in POSIX.1-2001.

       RTLD_DEEPBIND (since glibc 2.3.4)
              Place the lookup scope of the symbols in this library ahead of the global  scope.   This  means  that  a
              self-contained  library will use its own symbols in preference to global symbols with the same name con-
              tained in libraries that have already been loaded.  This flag is not specified in POSIX.1-2001.

       If filename is a NULL pointer, 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 libraries loaded at program
       startup, and then all shared libraries loaded by dlopen() with the flag RTLD_GLOBAL.

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

       If  the same library is loaded again with dlopen(), the same file handle is returned.  The dl library maintains
       reference counts for library handles, so a dynamic library is not deallocated until dlclose() has  been  called
       on  it  as  many  times as dlopen() has succeeded on it.  The _init() routine, if present, is only called once.
       But a subsequent call with RTLD_NOW may force symbol resolution for a library earlier loaded with RTLD_LAZY.

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

   dlsym()
       The function dlsym() takes a "handle" of a dynamic library returned by dlopen() and the null-terminated  symbol
       name, returning the address where that symbol is loaded into memory.  If the symbol is not found, in the speci-
       fied library or any of the libraries that were automatically loaded by dlopen() when that library  was  loaded,
       dlsym()  returns  NULL.  (The search performed by dlsym() is breadth first through the dependency tree of these
       libraries.)  Since the value of the symbol could actually be NULL (so that a NULL return from dlsym() need  not
       indicate  an  error),  the  correct way to test for an error is to call dlerror() to clear any old error condi-
       tions, then call dlsym(), and then call dlerror() again, saving its return value into  a  variable,  and  check
       whether this saved value is not NULL.

       There are two special pseudo-handles, RTLD_DEFAULT and RTLD_NEXT.  The former will find the first occurrence of
       the desired symbol using the default library search order.  The latter will find the next occurrence of a func-
       tion  in the search order after the current library.  This allows one to provide a wrapper around a function in
       another shared library.

   dlclose()
       The function dlclose() decrements the reference count on the dynamic library handle handle.  If  the  reference
       count drops to zero and no other loaded libraries use symbols in it, then the dynamic library is unloaded.

       The function dlclose() returns 0 on success, and non-zero on error.

   The obsolete symbols _init() and _fini()
       The  linker  recognizes special symbols _init and _fini.  If a dynamic library exports a routine named _init(),
       then that code is executed after the loading, before dlopen()  returns.   If  the  dynamic  library  exports  a
       routine  named  _fini(),  then that routine is called just before the library is unloaded.  In case you need to
       avoid linking against the system startup files, this can be done by using the gcc(1) -nostartfiles command-line
       option.

       Using  these routines, or the gcc -nostartfiles or -nostdlib options, is not recommended.  Their use may result
       in undesired behavior, since the constructor/destructor routines will not be executed (unless special  measures
       are taken).

       Instead,  libraries  should  export routines using the __attribute__((constructor)) and __attribute__((destruc-
       tor)) function attributes.  See the gcc info pages for information on these.  Constructor routines are executed
       before dlopen() returns, and destructor routines are executed before dlclose() returns.

   Glibc extensions: dladdr() and dlvsym()
       Glibc adds two functions not described by POSIX, with prototypes

       #define _GNU_SOURCE
       #include <dlfcn.h>

       int dladdr(void *addr, Dl_info *info);

       void *dlvsym(void *handle, char *symbol, char *version);

       The  function dladdr() takes a function pointer and tries to resolve name and file where it is located.  Infor-
       mation is stored in the Dl_info structure:

           typedef struct {
               const char *dli_fname;  /* Pathname of shared object that
                                          contains address */
               void       *dli_fbase;  /* Address at which shared object
                                          is loaded */
               const char *dli_sname;  /* Name of nearest symbol with address
                                          lower than addr */
               void       *dli_saddr;  /* Exact address of symbol named
                                          in dli_sname */
           } Dl_info;

       If no symbol matching addr could be found, then dli_sname and dli_saddr are set to NULL.

       dladdr() returns 0 on error, and non-zero on success.

       The function dlvsym(), provided by glibc since version 2.1, does the same as dlsym() but takes a version string
       as an additional argument.

CONFORMING TO
       POSIX.1-2001 describes dlclose(), dlerror(), dlopen(), and dlsym().

NOTES
       The  symbols  RTLD_DEFAULT  and  RTLD_NEXT  are  defined  by <dlfcn.h> only when _GNU_SOURCE was defined before
       including it.

       Since glibc 2.2.3, atexit(3) can be used to register an exit  handler  that  is  automatically  called  when  a
       library is unloaded.

   History
       The dlopen interface standard comes from SunOS.  That system also has dladdr(), but not dlvsym().

BUGS
       Sometimes,  the  function  pointers you pass to dladdr() may surprise you.  On some architectures (notably i386
       and x86_64), dli_fname and dli_fbase may end up pointing back at the object from  which  you  called  dladdr(),
       even if the function used as an argument should come from a dynamically linked library.

       The  problem  is  that the function pointer will still be resolved at compile time, but merely point to the plt
       (Procedure Linkage Table) section of the original object (which dispatches the call after  asking  the  dynamic
       linker  to  resolve  the symbol).  To work around this, you can try to compile the code to be position-indepen-
       dent: then, the compiler cannot prepare the pointer at compile time anymore and today's  gcc(1)  will  generate
       code  that just loads the final symbol address from the got (Global Offset Table) at run time before passing it
       to dladdr().

EXAMPLE
       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 */

           /* Writing: cosine = (double (*)(double)) dlsym(handle, "cos");
              would seem more natural, but the C99 standard leaves
              casting from "void *" to a function pointer undefined.
              The assignment used below is the POSIX.1-2003 (Technical
              Corrigendum 1) workaround; see the Rationale for the
              POSIX specification of dlsym(). */

           *(void **) (&cosine) = dlsym(handle, "cos");

           if ((error = dlerror()) != NULL)  {
               fprintf(stderr, "%s\n", error);
               exit(EXIT_FAILURE);
           }

           printf("%f\n", (*cosine)(2.0));
           dlclose(handle);
           exit(EXIT_SUCCESS);
       }

       If this program were in a file named "foo.c", you would build the program with the following command:

           gcc -rdynamic -o foo foo.c -ldl

       Libraries exporting _init() and _fini() will want to be compiled as follows, using bar.c as the example name:

           gcc -shared -nostartfiles -o bar bar.c

SEE ALSO
       ld(1), ldd(1), dl_iterate_phdr(3), feature_test_macros(7), rtld-audit(7),  ld.so(8),  ldconfig(8),  ld.so  info
       pages, gcc info pages, ld info pages

COLOPHON
       This  page  is part of release 3.22 of the Linux man-pages project.  A description of the project, and informa-
       tion about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.



Linux                             2008-12-06                         DLOPEN(3)