dyld-433.5.tar.gz

[apple/dyld.git] / doc / man / man3 / dlsym.3

diff --git a/doc/man/man3/dlsym.3 b/doc/man/man3/dlsym.3
index 6072b92dc2f95c02e1b51a26639f578877bebbcc..5f7c4ed26207a6e36db2d5e3ff74ebc1d0654b4b 100644 (file)
--- a/doc/man/man3/dlsym.3
+++ b/doc/man/man3/dlsym.3
@@ -1,4 +1,4 @@
-.Dd Sept 25, 2004
+.Dd August 28, 2008
 .Dt DLSYM 3
 .Sh NAME
 .Nm dlsym
@@ -30,7 +30,8 @@ If
 is called with the special
 .Fa handle
 .Dv RTLD_DEFAULT ,
-then every mach-o image in the process is searched in the order they were loaded.
+then all mach-o images in the process (except those loaded with dlopen(xxx, RTLD_LOCAL))
+are searched in the order they were loaded.
 This can be a costly search and should be avoided.  
 .Pp
 If
@@ -38,9 +39,36 @@ If
 is called with the special
 .Fa handle
 .Dv RTLD_NEXT ,
-then the search for the symbol is limited to the images which were loaded
-after the one issuing the call to
+then dyld searches for the symbol in the dylibs the calling image 
+linked against when built. It is usually used when
+you intentionally have multiply defined symbol across images
+and want to find the "next" definition.  It searches other images 
+for the definition that the caller would be using if it did not
+have a definition.  The exact search algorithm depends on whether
+the caller's image was linked -flat_namespace or -twolevel_namespace.
+For flat linked images, the search starts in the load ordered list
+of all images, in the image right after the caller's image.  
+For two-level images, the search simulates how the static linker
+would have searched for the symbol when linking the caller's
+image.  
+.Pp
+If
+.Fn dlsym
+is called with the special
+.Fa handle
+.Dv RTLD_SELF ,
+then the search for the symbol starts with the image that called
 .Fn dlsym .
+If it is not found, the search continues as if RTLD_NEXT was used.
+.Pp
+If
+.Fn dlsym
+is called with the special
+.Fa handle
+.Dv RTLD_MAIN_ONLY ,
+then it only searches for 
+.Fa symbol
+in the main executable.
 .Pp
 .Sh RETURN VALUES
 The
@@ -51,15 +79,16 @@ condition which may be queried with
 .Fn dlerror .
 .Pp
 .Sh NOTES
-Unlike other dyld API's, the symbol name passed to
+The symbol name passed to
 .Fn dlsym
-must NOT be prepended with an underscore.  
+is the name used in C source code.  For example to find the address
+of function foo(), you would pass "foo" as the symbol name.  This
+is unlike the older dyld APIs which required a leading underscore.
+If you looking up a C++ symbol, you need to use the mangled C++ symbol
+name.  
 .Sh SEE ALSO
 .Xr dlopen 3
-.Xr dlsym 3
 .Xr dlerror 3
 .Xr dyld 3
-.Xr NSModule 3
-.Xr NSObjectFileImage 3
 .Xr ld 1
 .Xr cc 1