include/mach-o/dyld.h

   1 /*
   2  * Copyright (c) 1999-2005 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23 #ifndef _MACH_O_DYLD_H_
  24 #define _MACH_O_DYLD_H_
  25
  26 #if __cplusplus
  27 extern "C" {
  28 #endif /* __cplusplus */
  29
  30 #include <stddef.h>
  31 #include <stdint.h>
  32 #if __cplusplus
  33   /* C++ has bool type built in */
  34 #else
  35  #include <stdbool.h>
  36 #endif
  37 #include <mach-o/loader.h>
  38 #include <AvailabilityMacros.h>
  39
  40 #ifndef ENUM_DYLD_BOOL
  41 #define ENUM_DYLD_BOOL
  42 #undef FALSE
  43 #undef TRUE
  44 enum DYLD_BOOL {
  45     FALSE,
  46     TRUE
  47 };
  48 #endif /* ENUM_DYLD_BOOL */
  49
  50 /*
  51  * The high level NS... API.
  52  */
  53
  54 /* Object file image API */
  55 typedef enum {
  56     NSObjectFileImageFailure, /* for this a message is printed on stderr */
  57     NSObjectFileImageSuccess,
  58     NSObjectFileImageInappropriateFile,
  59     NSObjectFileImageArch,
  60     NSObjectFileImageFormat, /* for this a message is printed on stderr */
  61     NSObjectFileImageAccess
  62 } NSObjectFileImageReturnCode;
  63
  64 typedef struct __NSObjectFileImage*  NSObjectFileImage;
  65
  66 /* limited implementation, only MH_BUNDLE files can be used */
  67 extern NSObjectFileImageReturnCode NSCreateObjectFileImageFromFile(
  68     const char *pathName,
  69     NSObjectFileImage *objectFileImage);
  70 extern NSObjectFileImageReturnCode NSCreateCoreFileImageFromFile(
  71     const char *pathName,
  72     NSObjectFileImage *objectFileImage);
  73 extern NSObjectFileImageReturnCode NSCreateObjectFileImageFromMemory(
  74     const void *address,
  75     size_t size,
  76     NSObjectFileImage *objectFileImage);
  77 extern bool NSDestroyObjectFileImage(
  78     NSObjectFileImage objectFileImage);
  79 /*
  80  * API on NSObjectFileImage's for:
  81  *   "for Each Symbol Definition In Object File Image" (for Dynamic Bundles)
  82  *   and the same thing for references
  83  */
  84 extern uint32_t NSSymbolDefinitionCountInObjectFileImage(
  85     NSObjectFileImage objectFileImage);
  86 extern const char * NSSymbolDefinitionNameInObjectFileImage(
  87     NSObjectFileImage objectFileImage,
  88     uint32_t ordinal);
  89 extern uint32_t NSSymbolReferenceCountInObjectFileImage(
  90     NSObjectFileImage objectFileImage);
  91 extern const char * NSSymbolReferenceNameInObjectFileImage(
  92     NSObjectFileImage objectFileImage,
  93     uint32_t ordinal,
  94     bool *tentative_definition); /* can be NULL */
  95 /*
  96  * API on NSObjectFileImage:
  97  *   "does Object File Image define symbol name X" (using sorted symbol table)
  98  *   and a way to get the named objective-C section
  99  */
 100 extern bool NSIsSymbolDefinedInObjectFileImage(
 101     NSObjectFileImage objectFileImage,
 102     const char *symbolName) AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4;
 103 extern void * NSGetSectionDataInObjectFileImage(
 104     NSObjectFileImage objectFileImage,
 105     const char *segmentName,
 106     const char *sectionName,
 107     size_t *size); /* can be NULL */
 108 /* SPI first appeared in Mac OS X 10.3 */
 109 extern bool NSHasModInitObjectFileImage(
 110     NSObjectFileImage objectFileImage)
 111     AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 112
 113 /* module API */
 114 typedef struct __NSModule* NSModule;
 115 extern const char * NSNameOfModule(
 116     NSModule m);
 117 extern const char * NSLibraryNameForModule(
 118     NSModule m);
 119
 120 /* limited implementation, only MH_BUNDLE files can be linked */
 121 extern NSModule NSLinkModule(
 122     NSObjectFileImage objectFileImage,
 123     const char *moduleName,
 124     uint32_t options);
 125 #define NSLINKMODULE_OPTION_NONE                0x0
 126 #define NSLINKMODULE_OPTION_BINDNOW             0x1
 127 #define NSLINKMODULE_OPTION_PRIVATE             0x2
 128 #define NSLINKMODULE_OPTION_RETURN_ON_ERROR     0x4
 129 #define NSLINKMODULE_OPTION_DONT_CALL_MOD_INIT_ROUTINES 0x8
 130 #define NSLINKMODULE_OPTION_TRAILING_PHYS_NAME  0x10
 131
 132 /* limited implementation, only modules loaded with NSLinkModule() can be
 133    unlinked */
 134 extern bool NSUnLinkModule(
 135     NSModule module,
 136     uint32_t options);
 137 #define NSUNLINKMODULE_OPTION_NONE                      0x0
 138 #define NSUNLINKMODULE_OPTION_KEEP_MEMORY_MAPPED        0x1
 139 #define NSUNLINKMODULE_OPTION_RESET_LAZY_REFERENCES     0x2
 140
 141 /* not yet implemented */
 142 extern NSModule NSReplaceModule(
 143     NSModule moduleToReplace,
 144     NSObjectFileImage newObjectFileImage,
 145     uint32_t options);
 146
 147 /* symbol API */
 148 typedef struct __NSSymbol* NSSymbol;
 149 extern bool NSIsSymbolNameDefined(
 150     const char *symbolName) AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4;
 151 extern bool NSIsSymbolNameDefinedWithHint(
 152     const char *symbolName,
 153     const char *libraryNameHint) AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4;
 154 extern bool NSIsSymbolNameDefinedInImage(
 155     const struct mach_header *image,
 156     const char *symbolName) AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4;
 157 extern NSSymbol NSLookupAndBindSymbol(
 158     const char *symbolName) AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4;
 159 extern NSSymbol NSLookupAndBindSymbolWithHint(
 160     const char *symbolName,
 161     const char *libraryNameHint) AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4;
 162 extern NSSymbol NSLookupSymbolInModule(
 163     NSModule module,
 164     const char *symbolName);
 165 extern NSSymbol NSLookupSymbolInImage(
 166     const struct mach_header *image,
 167     const char *symbolName,
 168     uint32_t options);
 169 #define NSLOOKUPSYMBOLINIMAGE_OPTION_BIND            0x0
 170 #define NSLOOKUPSYMBOLINIMAGE_OPTION_BIND_NOW        0x1
 171 #define NSLOOKUPSYMBOLINIMAGE_OPTION_BIND_FULLY      0x2
 172 #define NSLOOKUPSYMBOLINIMAGE_OPTION_RETURN_ON_ERROR 0x4
 173 extern const char * NSNameOfSymbol(
 174     NSSymbol symbol);
 175 extern void * NSAddressOfSymbol(
 176     NSSymbol symbol);
 177 extern NSModule NSModuleForSymbol(
 178     NSSymbol symbol);
 179
 180 /* error handling API */
 181 typedef enum {
 182     NSLinkEditFileAccessError,
 183     NSLinkEditFileFormatError,
 184     NSLinkEditMachResourceError,
 185     NSLinkEditUnixResourceError,
 186     NSLinkEditOtherError,
 187     NSLinkEditWarningError,
 188     NSLinkEditMultiplyDefinedError,
 189     NSLinkEditUndefinedError
 190 } NSLinkEditErrors;
 191
 192 /*
 193  * For the NSLinkEditErrors value NSLinkEditOtherError these are the values
 194  * passed to the link edit error handler as the errorNumber (what would be an
 195  * errno value for NSLinkEditUnixResourceError or a kern_return_t value for
 196  * NSLinkEditMachResourceError).
 197  */
 198 typedef enum {
 199     NSOtherErrorRelocation,
 200     NSOtherErrorLazyBind,
 201     NSOtherErrorIndrLoop,
 202     NSOtherErrorLazyInit,
 203     NSOtherErrorInvalidArgs
 204 } NSOtherErrorNumbers;
 205
 206 extern void NSLinkEditError(
 207     NSLinkEditErrors *c,
 208     int *errorNumber,
 209     const char **fileName,
 210     const char **errorString);
 211
 212 typedef struct {
 213      void     (*undefined)(const char *symbolName);
 214      NSModule (*multiple)(NSSymbol s, NSModule oldModule, NSModule newModule);
 215      void     (*linkEdit)(NSLinkEditErrors errorClass, int errorNumber,
 216                           const char *fileName, const char *errorString);
 217 } NSLinkEditErrorHandlers;
 218
 219 extern void NSInstallLinkEditErrorHandlers(
 220     const NSLinkEditErrorHandlers *handlers);
 221
 222 /* other API */
 223 extern bool NSAddLibrary(
 224     const char *pathName) AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4;
 225 extern bool NSAddLibraryWithSearching(
 226     const char *pathName) AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4;
 227 extern const struct mach_header * NSAddImage(
 228     const char *image_name,
 229     uint32_t options);
 230 #define NSADDIMAGE_OPTION_NONE                          0x0
 231 #define NSADDIMAGE_OPTION_RETURN_ON_ERROR               0x1
 232 #define NSADDIMAGE_OPTION_WITH_SEARCHING                0x2
 233 #define NSADDIMAGE_OPTION_RETURN_ONLY_IF_LOADED         0x4
 234 #define NSADDIMAGE_OPTION_MATCH_FILENAME_BY_INSTALLNAME 0x8
 235 extern int32_t NSVersionOfRunTimeLibrary(
 236     const char *libraryName);
 237 extern int32_t NSVersionOfLinkTimeLibrary(
 238     const char *libraryName);
 239 extern int _NSGetExecutablePath( /* SPI first appeared in Mac OS X 10.2 */
 240     char *buf,
 241     uint32_t *bufsize);
 242
 243 /*
 244  * The low level _dyld_... API.
 245  * (used by the objective-C runtime primarily)
 246  */
 247 extern bool _dyld_present(
 248     void);
 249
 250 extern uint32_t _dyld_image_count(
 251     void);
 252 extern const struct mach_header * _dyld_get_image_header(
 253     uint32_t image_index);
 254 extern intptr_t _dyld_get_image_vmaddr_slide(
 255     uint32_t image_index);
 256 extern const char * _dyld_get_image_name(
 257     uint32_t image_index);
 258
 259 extern void _dyld_register_func_for_add_image(
 260     void (*func)(const struct mach_header *mh, intptr_t vmaddr_slide));
 261 extern void _dyld_register_func_for_remove_image(
 262     void (*func)(const struct mach_header *mh, intptr_t vmaddr_slide));
 263 extern void _dyld_register_func_for_link_module(
 264     void (*func)(NSModule module));
 265 /* not yet implemented */
 266 extern void _dyld_register_func_for_unlink_module(
 267     void (*func)(NSModule module));
 268 /* not yet implemented */
 269 extern void _dyld_register_func_for_replace_module(
 270     void (*func)(NSModule oldmodule, NSModule newmodule));
 271 extern void _dyld_get_objc_module_sect_for_module(
 272     NSModule module,
 273     void **objc_module,
 274     size_t *size);
 275 extern void _dyld_bind_objc_module(
 276     const void *objc_module);
 277 extern bool _dyld_bind_fully_image_containing_address(
 278     const void *address);
 279 extern bool _dyld_image_containing_address(
 280     const void* address);
 281 /* SPI first appeared in Mac OS X 10.3 */
 282 extern const struct mach_header * _dyld_get_image_header_containing_address(
 283     const void* address)
 284     AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 285
 286 extern void _dyld_moninit(
 287     void (*monaddition)(char *lowpc, char *highpc));
 288 extern bool _dyld_launched_prebound(
 289     void);
 290 /* SPI first appeared in Mac OS X 10.3 */
 291 extern bool _dyld_all_twolevel_modules_prebound(
 292     void)
 293     AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 294
 295 extern void _dyld_lookup_and_bind(
 296     const char *symbol_name,
 297     void **address,
 298     NSModule* module) AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4;
 299 extern void _dyld_lookup_and_bind_with_hint(
 300     const char *symbol_name,
 301     const char *library_name_hint,
 302     void **address,
 303     NSModule* module) AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4;
 304 extern void _dyld_lookup_and_bind_objc(
 305     const char *symbol_name,
 306     void **address,
 307     NSModule* module);
 308 extern void _dyld_lookup_and_bind_fully(
 309     const char *symbol_name,
 310     void **address,
 311     NSModule* module);
 312
 313 extern int _dyld_func_lookup(
 314     const char *dyld_func_name,
 315     void **address);
 316
 317 #if __cplusplus
 318 }
 319 #endif /* __cplusplus */
 320
 321 #endif /* _MACH_O_DYLD_H_ */