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