dyld-43.tar.gz
[apple/dyld.git] / 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_ */