Penguin

Differences between current version and predecessor to the previous major change of dlsym(3).

Other diffs: Previous Revision, Previous Author, or view the Annotated Edit History

Newer page: version 4 Last edited on Tuesday, September 30, 2003 8:42:51 pm by JohnMcPherson
Older page: version 2 Last edited on Tuesday, June 4, 2002 12:24:16 am by perry Revert
@@ -1,53 +1,43 @@
-DLOPEN  
 !!!DLOPEN 
-NAME  
-SYNOPSIS  
-DESCRIPTION  
-RETURN VALUE  
-EXAMPLE  
-ACKNOWLEDGEMENTS  
-SEE ALSO  
+  
 ---- 
 !!NAME 
  
  
 dlclose, dlerror, dlopen, dlsym - Programming interface to dynamic linking loader. 
 !!SYNOPSIS 
  
  
-__#include __ 
+__#include __ <dlfcn.h>  
  
  
-__ void *dlopen (const char *__''filename''__, int__  
- ''flag''__); 
+void *dlopen (const char *__''filename''__, int__ ''flag''__);  
+  
 const char *dlerror(void); 
-void *dlsym(void *__''handle''__, char  
- *__''symbol''__);  
-int dlclose (void *__''handle''__);__  
+  
+ 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 
+opaque "handle" for the dynamic library. If  
 ''filename'' is not an absolute path (i.e., it does not 
-begin with a  
-''  
+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.  
  
-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''.  
  
-The list of libraries cached in  
-''/etc/ld.so.cache''.  
  
-  
- ''/usr/lib'', followed by ''/lib''. 
+;: ''/usr/lib'', followed by ''/lib''. 
  
  
 If ''filename'' is a NULL pointer, then the returned 
 handle is for the main program. 
@@ -55,10 +45,12 @@
  
 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  
-__  
+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 
@@ -89,9 +81,9 @@
 __dlerror()__ twice consecutively, will always result in 
 the second call returning NULL.) 
  
  
-__dlsym__ takes a 
+__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 
@@ -99,44 +91,71 @@
 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 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  
  
+  
+!!RETURN VALUE  
  
 __dlclose__ returns 0 on success, and non-zero on 
 error. 
+  
 !!EXAMPLE 
  
+__Load the math library, and print the cosine of 2.0:__  
  
-__Load the math library, and print the cosine of  
-2.0:__  
  
+ #include <stdio.h>  
+ #include <dlfcn.h>  
  
-#include  
+ 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);  
+ }  
  
-If this program were in a file named  
+ 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  
  
-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__ 
+ld(1), ld.so(8), ldconfig(8), ldd(1), __ld.so.info__, dladdr(3)  
 ---- 
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.