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 are looking up a C++ symbol, you need to use the mangled C++ symbol name.
  88 .Sh SEE ALSO
  89 .Xr dlopen 3
  90 .Xr dlerror 3
  91 .Xr dyld 3
  92 .Xr ld 1
  93 .Xr cc 1