*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Linux man pages -> dlopen (3)              



NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

       #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    [Toc]    [Back]

       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

       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.  Optionally, 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 handle is returned.  The dl  library  maintains
       link counts for dynamic file handles, so a dynamic library is not deallocated
 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 consecutively, will
       always result in the second call returning 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    [Toc]    [Back]

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

EXAMPLE    [Toc]    [Back]

       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);

		  cosine = dlsym(handle, "cos");
		  if ((error = dlerror()) != NULL)  {
		      fprintf (stderr, "%s\n", error);

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

       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


       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    [Toc]    [Back]

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

Linux				  2000-11-28			     DLOPEN(3)
[ Back ]
 Similar pages
Name OS Title
link OpenBSD dynamic loader and link editor interface
link FreeBSD dynamic loader and link editor interface
dld.sl HP-UX dynamic loader
dld.so HP-UX dynamic loader
ld.so Linux dynamic linker/loader
sane-dll Linux SANE dynamic backend loader
gssapi HP-UX Generic Security Service Application Programming Interface
dmapi Tru64 Describes the contents of the Data Management Applications Programming Interface (DMAPI)
libgss HP-UX shared library for GSSAPI (Generic Security Service Application Programming Interface)
dlfcn NetBSD dynamic link interface
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service