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

NAME
       dlclose, dlerror, dlopen, dlsym - Programming interface to
       dynamic linking loader.

SYNOPSIS
       #include <dlfcn.h>

       void *dlopen (const char *filename, int flag);
       const char *dlerror(void);
       void *dlsym(void *handle, char *symbol);
       int dlclose (void *handle);

       Special symbols: _init, _fini.

DESCRIPTION
       dlopen loads a dynamic library from the file named by  the
       null  terminated  string  filename  and  returns an opaque
       "handle" for the dynamic library.  If filename is  not  an
       absolute  path  (i.e., it does not begin with a "/"), then
       the file is searched for in the following locations:

              A colon-separated list of directories in the user's
              LD_LIBRARY path environment variable.

              The     list     of    libraries    specified    in
              /etc/ld.so.cache.

              /usr/lib, followed by /lib.

       If filename is a NULL pointer, then the returned handle is
       for the main program.

       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",  then
       the  global symbols in the executable will also be used to
       resolve references in a dynamically loaded library.

       flag must be either RTLD_LAZY, meaning  resolve  undefined
       symbols  as  code from the dynamic library is executed, or
       RTLD_NOW, meaning resolve  all  undefined  symbols  before
       dlopen  returns, and fail if this cannot be done.  Option-
       ally, RTLD_GLOBAL may be or'ed with flag,  in  which  case
       the  external  symbols defined in the library will be made
       available to subsequently loaded libraries.

       If the library exports a routine named  _init,  then  that
       code  is  executed  before  dlopen  returns.   If the same
       library is loaded twice with dlopen(), the same file  han-
       dle is returned.  The dl library maintains link counts for
       dynamic file handles, so a dynamic library is not  deallo-
       cated until dlclose has been called on it as many times as
       dlopen has succeeded on it.

       If dlopen fails for any reason, it returns NULL.  A  human
       readable  string  describing  the  most  recent error that
       occurred from any of the dl  routines  (dlopen,  dlsym  or
       dlclose) can be extracted with dlerror().  dlerror returns
       NULL if no errors have occurred  since  initialization  or
       since  it  was last called.  (Calling dlerror() twice con-
       secutively, will always result in the second call  return-
       ing NULL.)

       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.  If the symbol is not
       found, dlsym returns NULL; however,  the  correct  way  to
       test  for  an  error  from  dlsym is to save the result of
       dlerror into a variable, and then check if saved value  is
       not  NULL.   This is because the value of the symbol could
       actually be NULL.   It  is  also  necessary  to  save  the
       results  of  dlerror into a variable because if dlerror is
       called again, it will return NULL.

       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.  If the dynamic library
       exports a routine named _fini, then that routine is called
       just before the library is unloaded.

EXAMPLES
       Load the math library, and print the cosine of 2.0:
              #include <dlfcn.h>

              int main(int argc, char **argv) {
                  void *handle = dlopen ("/lib/libm.so", RTLD_LAZY);
                  double (*cosine)(double) = dlsym(handle, "cos");
                  printf ("%f\n", (*cosine)(2.0));
                  dlclose(handle);
              }

              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

       Do the same thing, but check for errors at every step:
              #include <stdio.h>
              #include <dlfcn.h>

              int main(int argc, char **argv) {
                  void *handle;
                  double (*cosine)(double);
                  char *error;

                  handle = dlopen ("/lib/libm.so", RTLD_LAZY);
                  if (!handle) {
                      fputs (dlerror(), stderr);
                      exit(1);
                  }

                  cosine = dlsym(handle, "cos");
                  if ((error = dlerror()) != NULL)  {
                      fputs(error, stderr);
                      exit(1);
                  }

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

ACKNOWLEDGEMENTS
       The  dlopen  interface  standard  comes from Solaris.  The
       Linux dlopen implementation was primarily written by  Eric
       Youngdale  with  help  from  Mitch  D'Souza,  David Engel,
       Hongjiu Lu, Andreas Schwab and others.   The  manual  page
       was written by Adam Richter.

SEE ALSO
       ld(1), ld.so(8), ldconfig(8), ldd(1), ld.so.info.

Linux                      16 May 1995                          1