dyld-635.2.tar.gz
[apple/dyld.git] / doc / man / man3 / dlsym.3
1 .Dd August 28, 2008
2 .Dt DLSYM 3
3 .Sh NAME
4 .Nm dlsym
5 .Nd get address of a symbol
6 .Sh SYNOPSIS
7 .In dlfcn.h
8 .Ft void*
9 .Fn dlsym "void* handle" "const char* symbol"
10 .Sh DESCRIPTION
11 .Fn dlsym
12 returns the address of the code or data location 
13 specified by the null-terminated character string
14 .Fa symbol .
15 Which libraries and bundles are searched depends on the  
16 .Fa handle 
17 parameter. 
18 .Pp
19 If
20 .Fn dlsym
21 is called with a
22 .Fa handle ,
23 returned by
24 .Fn dlopen
25 then only that image and any libraries it depends on are searched for
26 .Fa symbol .
27 .Pp
28 If
29 .Fn dlsym
30 is called with the special
31 .Fa handle
32 .Dv RTLD_DEFAULT ,
33 then all mach-o images in the process (except those loaded with dlopen(xxx, RTLD_LOCAL))
34 are searched in the order they were loaded.
35 This can be a costly search and should be avoided.  
36 .Pp
37 If
38 .Fn dlsym
39 is called with the special
40 .Fa handle
41 .Dv RTLD_NEXT ,
42 then dyld searches for the symbol in the dylibs the calling image 
43 linked against when built. It is usually used when
44 you intentionally have multiply defined symbol across images
45 and want to find the "next" definition.  It searches other images 
46 for the definition that the caller would be using if it did not
47 have a definition.  The exact search algorithm depends on whether
48 the caller's image was linked -flat_namespace or -twolevel_namespace.
49 For flat linked images, the search starts in the load ordered list
50 of all images, in the image right after the caller's image.  
51 For two-level images, the search simulates how the static linker
52 would have searched for the symbol when linking the caller's
53 image.  
54 .Pp
55 If
56 .Fn dlsym
57 is called with the special
58 .Fa handle
59 .Dv RTLD_SELF ,
60 then the search for the symbol starts with the image that called
61 .Fn dlsym .
62 If it is not found, the search continues as if RTLD_NEXT was used.
63 .Pp
64 If
65 .Fn dlsym
66 is called with the special
67 .Fa handle
68 .Dv RTLD_MAIN_ONLY ,
69 then it only searches for 
70 .Fa symbol
71 in the main executable.
72 .Pp
73 .Sh RETURN VALUES
74 The
75 .Fn dlsym
76 function
77 returns a null pointer if the symbol cannot be found, and sets an error
78 condition which may be queried with
79 .Fn dlerror .
80 .Pp
81 .Sh NOTES
82 The symbol name passed to
83 .Fn dlsym
84 is the name used in C source code.  For example to find the address
85 of function foo(), you would pass "foo" as the symbol name.  This
86 is unlike the older dyld APIs which required a leading underscore.
87 If you looking up a C++ symbol, you need to use the mangled C++ symbol
88 name.  
89 .Sh SEE ALSO
90 .Xr dlopen 3
91 .Xr dlerror 3
92 .Xr dyld 3
93 .Xr ld 1
94 .Xr cc 1