unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

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



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

SYNOPSIS
       #include <&lt;dlfcn.h>&gt;

       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  program.   If  filename  contains  a slash ("/"), then it is
       interpreted as a  (relative  or  absolute)  pathname.   Otherwise,  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 the environment variable LD_LIBRARY_PATH is 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 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 references; references to variables are always  immedi-
              ately 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 reinitialized 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 contained 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 sym-
       bol  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 "-rdynamic" (or, synonymously, "--export-dynamic"),  then  the
       global  symbols  in  the executable will also be used to resolve refer-
       ences 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  specified  library or any of the libraries that were automati-
       cally 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 conditions, 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 function 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__((con-
       structor))  and  __attribute__((destructor))  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 <&lt;dlfcn.h>&gt;

       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.   Information 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  &lt;dlfcn.h&gt;  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().

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 pro-
       gram 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), ld.so(8),
       ldconfig(8), ld.so info pages, gcc info pages, ld info pages

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



Linux                             2008-06-14                         DLOPEN(3)