dyld-43.tar.gz
[apple/dyld.git] / doc / man / man3 / dlsym.3
1 .Dd Sept 25, 2004
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 every mach-o image in the process is searched in the order they were loaded.
34 This can be a costly search and should be avoided.  
35 .Pp
36 If
37 .Fn dlsym
38 is called with the special
39 .Fa handle
40 .Dv RTLD_NEXT ,
41 then the search for the symbol is limited to the images which were loaded
42 after the one issuing the call to
43 .Fn dlsym .
44 .Pp
45 .Sh RETURN VALUES
46 The
47 .Fn dlsym
48 function
49 returns a null pointer if the symbol cannot be found, and sets an error
50 condition which may be queried with
51 .Fn dlerror .
52 .Pp
53 .Sh NOTES
54 Unlike other dyld API's, the symbol name passed to
55 .Fn dlsym
56 must NOT be prepended with an underscore.  
57 .Sh SEE ALSO
58 .Xr dlopen 3
59 .Xr dlsym 3
60 .Xr dlerror 3
61 .Xr dyld 3
62 .Xr NSModule 3
63 .Xr NSObjectFileImage 3
64 .Xr ld 1
65 .Xr cc 1