Home Man
Today's Posts

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

RedHat 9 (Linux i386) - man page for dlopen (redhat section 3)

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

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

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

       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

	      A colon-separated list of directories in	the  user's  LD_LIBRARY_PATH  environment

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

	      /lib, followed by /usr/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 exe-
       cutable 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 subse-
       quently 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  ini-
       tialization  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.

       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, which is usable only from within a dynamic library, 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 decrements the reference count on the dynamic library handle handle.  If the  ref-
       erence  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.

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

       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 ("libm.so", RTLD_LAZY);
		  if (!handle) {
		      fprintf (stderr, "%s\n", dlerror());

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

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

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

	      gcc -rdynamic -o foo foo.c -ldl

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

       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.

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

Linux					    2001-12-14					DLOPEN(3)

All times are GMT -4. The time now is 08:40 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
Show Password