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 cached 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.

       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.


RETURN VALUE

       dlclose returns 0 on success, and non-zero on error.


EXAMPLE

       Load the math library, and print the cosine of 2.0:
              #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)  {
                      fprintf (stderr, "%s\n", error);
                      exit(1);
                  }

                  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


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


Man(1) output converted with man2html