doc/man/man3/dlsym.3

   1 .Dd Jan 16, 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 the search for the symbol is limited to the images which were loaded
  43 by the image issuing the call to
  44 .Fn dlsym .
  45 In other words, search the dylib symbols that the calling image linked against when it was built.
  46 .Pp
  47 If
  48 .Fn dlsym
  49 is called with the special
  50 .Fa handle
  51 .Dv RTLD_SELF ,
  52 then the search for the symbol starts with the image that called
  53 .Fn dlsym .
  54 If it is not found, the search continues as if RTLD_NEXT was used.
  55 .Pp
  56 .Sh RETURN VALUES
  57 The
  58 .Fn dlsym
  59 function
  60 returns a null pointer if the symbol cannot be found, and sets an error
  61 condition which may be queried with
  62 .Fn dlerror .
  63 .Pp
  64 .Sh NOTES
  65 Unlike other dyld API's, the symbol name passed to
  66 .Fn dlsym
  67 must NOT be prepended with an underscore.
  68 .Sh SEE ALSO
  69 .Xr dlopen 3
  70 .Xr dlsym 3
  71 .Xr dlerror 3
  72 .Xr dyld 3
  73 .Xr ld 1
  74 .Xr cc 1