doc/man/man3/dyld.3

   1 .Dd November 29, 2010
   2 .Dt dyld 3
   3 .Sh NAME
   4 .Nm _dyld_image_count,
   5 .Nm _dyld_get_image_header,
   6 .Nm _dyld_get_image_vmaddr_slide,
   7 .Nm _dyld_get_image_name,
   8 .Nm _dyld_register_func_for_add_image,
   9 .Nm _dyld_register_func_for_remove_image,
  10 .Nm NSVersionOfRunTimeLibrary,
  11 .Nm NSVersionOfLinkTimeLibrary
  12 .Nm _NSGetExecutablePath
  13 .Sh SYNOPSIS
  14 .In mach-o/dyld.h
  15 .Ft uint32_t
  16 .Fo _dyld_image_count
  17 .Fa "void"
  18 .Fc
  19 .Ft const struct mach_header*
  20 .Fo _dyld_get_image_header
  21 .Fa "uint32_t image_index"
  22 .Fc
  23 .Ft intptr_t
  24 .Fo _dyld_get_image_vmaddr_slide
  25 .Fa "uint32_t image_index"
  26 .Fc
  27 .Ft const char*
  28 .Fo _dyld_get_image_name
  29 .Fa "uint32_t image_index"
  30 .Fc
  31 .Ft void
  32 .Fo _dyld_register_func_for_add_image
  33 .Fa "void \*[lp]*func\*[rp]\*[lp]const struct mach_header* mh, intptr_t vmaddr_slide\*[rp]"
  34 .Fc
  35 .Ft void
  36 .Fo _dyld_register_func_for_remove_image
  37 .Fa "void \*[lp]*func\*[rp]\*[lp]const struct mach_header* mh, intptr_t vmaddr_slide\*[rp]"
  38 .Fc
  39 .Ft int32_t
  40 .Fo NSVersionOfRunTimeLibrary
  41 .Fa "const char* libraryName"
  42 .Fc
  43 .Ft int32_t
  44 .Fo NSVersionOfLinkTimeLibrary
  45 .Fa "const char* libraryName"
  46 .Fc
  47 .Ft int
  48 .Fo _NSGetExecutablePath
  49 .Fa "char* buf"
  50 .Fa "uint32_t* bufsize"
  51 .Fc
  52 .Sh DESCRIPTION
  53 These routines provide additional introspection of dyld beyond that provided by
  54 .Fn dlopen
  55 and
  56 .Fn dladdr
  57 .
  58 .Pp
  59 .Fn _dyld_image_count
  60 returns the current number of images mapped in by dyld. Note that using this
  61 count to iterate all images is not thread safe, because another thread
  62 may be adding or removing images during the iteration.
  63 .Pp
  64 .Fn _dyld_get_image_header
  65 returns a pointer to the mach header of the image indexed by image_index.  If
  66 .Fa image_index
  67 is out of range, NULL is returned.
  68 .Pp
  69 .Fn _dyld_get_image_vmaddr_slide
  70 returns the virtural memory address slide amount of the image indexed by
  71 .Fa image_index.
  72 If
  73 .Fa image_index
  74 is out of range zero is returned.
  75 .Pp
  76 .Fn _dyld_get_image_name
  77 returns the name of the image indexed by
  78 .Fa image_index.
  79 The C-string continues to be owned by dyld and should not deleted.
  80 If
  81 .Fa image_index
  82 is out of range NULL is returned.
  83 .Pp
  84 .Fn _dyld_register_func_for_add_image
  85 registers the specified function to be called when a new image is added
  86 (a bundle or a dynamic shared library) to the program.  When this function is
  87 first registered it is called for once for each image that is currently part of
  88 the process.
  89 .Pp
  90 .Fn _dyld_register_func_for_remove_image
  91 registers the specified function to be called when an image is removed
  92 (a bundle or a dynamic shared library) from the process.
  93 .Pp
  94 .Fn NSVersionOfRunTimeLibrary
  95 returns the current_version number of the currently loaded dylib
  96 specifed by the libraryName.  The libraryName parameter would be "bar" for /path/libbar.3.dylib and
  97 "Foo" for /path/Foo.framework/Versions/A/Foo.  This function returns -1 if no such library is loaded.
  98 .Pp
  99 .Fn NSVersionOfLinkTimeLibrary
 100 returns the current_version number that the main executable was linked
 101 against at build time.  The libraryName parameter would be "bar" for /path/libbar.3.dylib and
 102 "Foo" for /path/Foo.framework/Versions/A/Foo.  This function returns -1 if the main executable did not link
 103 against the specified library.
 104 .Pp
 105 .Fn _NSGetExecutablePath
 106 copies the path of the main executable into the buffer
 107 .Fa buf .
 108 The
 109 .Fa bufsize
 110 parameter should initially be the size of the buffer.  This function returns 0 if the path was successfully copied,
 111 and  *
 112 .Fa bufsize
 113 is left unchanged.
 114 It returns -1 if the buffer is not large enough, and *
 115 .Fa bufsize
 116 is set to the size required.
 117 Note that
 118 .Fn _NSGetExecutablePath
 119 will return "a path" to the executable not a "real path" to the executable.
 120 That is, the path may be a symbolic link and not the real file. With deep directories the total bufsize
 121 needed could be more than MAXPATHLEN.
 122 .Sh SEE ALSO
 123 .Xr dlopen 3
 124 .Xr dladdr 3
 125 .Xr dyld 1
 126 http://developer.apple.com/documentation/DeveloperTools/Conceptual/MachOTopics/index.html