doc/man/man3/dyld.3

   1 .TH DYLD 3 "January 15, 2005" "Apple Computer, Inc."
   2 .SH NAME
   3 dyld \- low level programatic interface to the dynamic link editor
   4 .SH SYNOPSIS
   5 .nf
   6 .PP
   7 #include <mach-o/dyld.h>
   8 bool _dyld_present(void);
   9 .sp .5
  10 uint32_t _dyld_image_count(void);
  11 .sp .5
  12 const struct mach_header *_dyld_get_image_header(
  13         uint32_t image_index);
  14 .sp .5
  15 intptr_t _dyld_get_image_vmaddr_slide(
  16         uint32_t image_index);
  17 .sp .5
  18 const char *_dyld_get_image_name(
  19         uint32_t image_index);
  20 .sp .5
  21 void _dyld_lookup_and_bind(
  22         const char *symbol_name,
  23         void **address,
  24         NSModule *module);
  25 .sp .5
  26 void _dyld_lookup_and_bind_with_hint(
  27         const char *symbol_name,
  28         const char *library_name_hint,
  29         void **address,
  30         NSModule *module);
  31 .sp .5
  32 void _dyld_lookup_and_bind_fully(
  33         const char *symbol_name,
  34         void **address,
  35         NSModule *module);
  36 .sp .5
  37 bool _dyld_bind_fully_image_containing_address(
  38         const void *address);
  39 .sp .5
  40 bool _dyld_image_containing_address(
  41         const void* address);
  42 .sp .5
  43 const struct mach_header * _dyld_get_image_header_containing_address(
  44         const void* address);
  45 .sp .5
  46 bool _dyld_launched_prebound(void);
  47 .sp .5
  48 bool _dyld_all_twolevel_modules_prebound(void);
  49 .sp .5
  50 int _dyld_func_lookup(
  51         const char *dyld_func_name,
  52         void **address);
  53 .sp .5
  54 extern void _dyld_bind_objc_module(
  55         const void *objc_module);
  56 .sp .5
  57 extern void _dyld_get_objc_module_sect_for_module(
  58         NSModule module,
  59         void **objc_module,
  60         size_t *size);
  61 .sp .5
  62 extern void _dyld_lookup_and_bind_objc(
  63         const char *symbol_name,
  64         void **address,
  65         NSModule *module);
  66 .sp .5
  67 extern void _dyld_moninit(
  68         void (*monaddition)(char *lowpc, char *highpc));
  69 .sp .5
  70
  71 extern void _dyld_register_func_for_add_image(
  72         void (*func)(const struct mach_header *mh, intptr_t vmaddr_slide));
  73 .sp .5
  74 extern void _dyld_register_func_for_remove_image(
  75         void (*func)(const struct mach_header *mh, intptr_t vmaddr_slide));
  76 .sp .5
  77 extern void _dyld_register_func_for_link_module(
  78         void (*func)(NSModule module));
  79 .fi
  80 .SH DESCRIPTION
  81 These routines are the low level programatic interface to the dynamic link
  82 editor.
  83 .PP
  84 .I _dyld_present returns non-zero if the dynamic linker is being used in the
  85 program and zero otherwise.  If this returns zero this rest of these functions
  86 should not be called and most likely crash the program if called.
  87 .PP
  88 .I _dyld_image_count
  89 returns the current number of images mapped in by the dynamic link editor.
  90 .PP
  91 .I _dyld_get_image_header
  92 returns the mach header of the image indexed by image_index.  If image_index is
  93 out of range NULL is returned.
  94 .PP
  95 .I _dyld_get_image_vmaddr_slide
  96 returns the virtural memory address slide amount of the image indexed by
  97 .I image_index.
  98 If image_index is out of range zero is returned.
  99 .PP
 100 .I _dyld_get_image_name
 101 returns the name of the image indexed by
 102 .I image_index.
 103 If image_index is out of range NULL is returned.
 104 .PP
 105 .I _dyld_lookup_and_bind
 106 looks up the
 107 .I symbol_name
 108 and binds it into the program.  It indirectly returns the
 109 .I address
 110 and and a pointer to the
 111 .I module
 112 that defined the symbol.
 113 .PP
 114 .I _dyld_lookup_and_bind_with_hint
 115 is the same as
 116 .I _dyld_lookup_and_bind
 117 but the
 118 .I library_name_hint
 119 parameter provides a hint as to where to start the lookup in a prebound
 120 program.  The
 121 .I library_name_hint
 122 parameter is matched up with the actual library install names with
 123 .IR strstr (3).
 124 .PP
 125 .I _dyld_lookup_and_bind_fully
 126 looks up the
 127 .I symbol_name
 128 and binds it and all of its references into the program.  It indirectly returns
 129 the
 130 .I address
 131 and and a pointer to the
 132 .I module
 133 that defined the symbol.
 134 .PP
 135 .I _dyld_bind_fully_image_containing_address
 136 fully binds the image containing the specified address.  It returns TRUE if the
 137 address is contained in a loaded image and FALSE otherwise.
 138 .PP
 139 .I _dyld_image_containing_address
 140 It returns TRUE if the address is contained in an image dyld loaded and FALSE
 141 otherwise.
 142 .PP
 143 .I _dyld_get_image_header_containing_address
 144 It returns a pointer to the mach header of the image if the address is contained
 145 in an image dyld loaded and NULL otherwise.
 146 .PP
 147 .I _dyld_launched_prebound
 148 returns TRUE if the program was launched using the prebound state and FALSE
 149 otherwise.
 150 .PP
 151 .I_dyld_all_twolevel_modules_prebound(void);
 152 returns TRUE if all the libraries currently in use by the program are being used
 153 as two-level namespace libraries, are prebound and have all their modules bound.
 154 Otherwise it returns FALSE.
 155 .PP
 156 .I _dyld_func_lookup
 157 is passed a name,
 158 .I dyld_func_name,
 159 of a dynamic link editor function and returns the
 160 .I address
 161 of the function indirectly.  It returns non-zero if the function is found
 162 and zero otherwise.
 163 .PP
 164 .I _dyld_bind_objc_module
 165 is passed a pointer to something in an (__OBJC,__module) section and causes the
 166 module that is associated with that address to be bound.
 167 .PP
 168 .I _dyld_get_objc_module_sect_for_module
 169 is passed a module and sets a pointer to the (__OBJC,__module) section and its
 170 size for the specified module.
 171 .PP
 172 .I _dyld_lookup_and_bind_objc()
 173 is the same as _dyld_lookup_and_bind() but does not update the symbol pointers
 174 if the symbol is in a bound module.  The reason for this is that an objc symbol
 175 like
 176 .I .objc_class_name_Object
 177 is never used by a symbol pointer.  Since this is done a lot by the objc
 178 runtime and updating symbol pointers is not cheep it should not be done.
 179 .PP
 180 .I _dyld_moninit
 181 is called from the profiling runtime routine
 182 .IR moninit(3)
 183 to cause the dyld loaded code to be profiled.  It is passed a pointer to the
 184 the profiling runtime routine
 185 .IR monaddtion(3)
 186 to be called after an image had been mapped in.
 187 .PP
 188 .I _dyld_register_func_for_add_image
 189 registers the specified function to be called when a new image is added
 190 (a bundle or a dynamic shared library) to the program.  When this function is
 191 first registered it is called for once for each image that is currently part of
 192 the program.
 193 .PP
 194 .I _dyld_register_func_for_remove_image
 195 registers the specified function to be called when an image is removed
 196 (a bundle or a dynamic shared library) from the program.
 197 .I _dyld_register_func_for_link_module
 198 registers the specified function to be called when a module is bound into the
 199 program.  When this function is first registered it is called for once for each
 200 module that is currently bound into the program.