1/*
2 * Copyright (c) 1999-2008 Apple 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#include <stddef.h>
27#include <stdint.h>
28#include <stdbool.h>
29
30#include <mach-o/loader.h>
31#include <Availability.h>
32#include <TargetConditionals.h>
33
34#if __cplusplus
35extern "C" {
36#endif
37
38#ifdef __DRIVERKIT_19_0
39 #define DYLD_DRIVERKIT_UNAVAILABLE __API_UNAVAILABLE(driverkit)
40#else
41 #define DYLD_DRIVERKIT_UNAVAILABLE
42#endif
43
44#ifndef __OPEN_SOURCE__
45
46
47 #define DYLD_EXCLAVEKIT_UNAVAILABLE
48
49#endif //__OPEN_SOURCE__
50
51/*
52 * The following functions allow you to iterate through all loaded images.
53 * This is not a thread safe operation. Another thread can add or remove
54 * an image during the iteration.
55 *
56 * Many uses of these routines can be replace by a call to dladdr() which
57 * will return the mach_header and name of an image, given an address in
58 * the image. dladdr() is thread safe.
59 */
60extern uint32_t _dyld_image_count(void) __API_AVAILABLE(macos(10.1), ios(2.0));
61extern const struct mach_header* _dyld_get_image_header(uint32_t image_index) __API_AVAILABLE(macos(10.1), ios(2.0));
62extern intptr_t _dyld_get_image_vmaddr_slide(uint32_t image_index) __API_AVAILABLE(macos(10.1), ios(2.0));
63extern const char* _dyld_get_image_name(uint32_t image_index) __API_AVAILABLE(macos(10.1), ios(2.0));
64
65
66/*
67 * The following functions allow you to install callbacks which will be called
68 * by dyld whenever an image is loaded or unloaded. During a call to _dyld_register_func_for_add_image()
69 * the callback func is called for every existing image. Later, it is called as each new image
70 * is loaded and bound (but initializers not yet run). The callback registered with
71 * _dyld_register_func_for_remove_image() is called after any terminators in an image are run
72 * and before the image is un-memory-mapped.
73 */
74extern void _dyld_register_func_for_add_image(void (*func)(const struct mach_header* mh, intptr_t vmaddr_slide)) __API_AVAILABLE(macos(10.1), ios(2.0));
75extern void _dyld_register_func_for_remove_image(void (*func)(const struct mach_header* mh, intptr_t vmaddr_slide)) __API_AVAILABLE(macos(10.1), ios(2.0));
76
77
78/*
79 * NSVersionOfRunTimeLibrary() returns the current_version number of the currently dylib
80 * specifed by the libraryName. The libraryName parameter would be "bar" for /path/libbar.3.dylib and
81 * "Foo" for /path/Foo.framework/Versions/A/Foo. It returns -1 if no such library is loaded.
82 */
83extern int32_t NSVersionOfRunTimeLibrary(const char* libraryName) __API_AVAILABLE(macos(10.1), ios(2.0));
84
85
86/*
87 * NSVersionOfLinkTimeLibrary() returns the current_version number that the main executable was linked
88 * against at build time. The libraryName parameter would be "bar" for /path/libbar.3.dylib and
89 * "Foo" for /path/Foo.framework/Versions/A/Foo. It returns -1 if the main executable did not link
90 * against the specified library.
91 */
92extern int32_t NSVersionOfLinkTimeLibrary(const char* libraryName) __API_AVAILABLE(macos(10.1), ios(2.0));
93
94
95/*
96 * _NSGetExecutablePath() copies the path of the main executable into the buffer. The bufsize parameter
97 * should initially be the size of the buffer. The function returns 0 if the path was successfully copied,
98 * and *bufsize is left unchanged. It returns -1 if the buffer is not large enough, and *bufsize is set
99 * to the size required.
100 *
101 * Note that _NSGetExecutablePath will return "a path" to the executable not a "real path" to the executable.
102 * That is the path may be a symbolic link and not the real file. With deep directories the total bufsize
103 * needed could be more than MAXPATHLEN.
104 */
105extern int _NSGetExecutablePath(char* buf, uint32_t* bufsize) __API_AVAILABLE(macos(10.2), ios(2.0));
106
107
108
109/*
110 * Registers a function to be called when the current thread terminates.
111 * Called by c++ compiler to implement destructors on thread_local object variables.
112 */
113extern void _tlv_atexit(void (*termFunc)(void* objAddr), void* objAddr) __API_AVAILABLE(macos(10.10), ios(8.0));
114
115
116/*
117 * Never called. On-disk thread local variables contain a pointer to this. Once
118 * the thread local is prepared, the pointer changes to a real handler such as tlv_get_addr.
119 */
120extern void _tlv_bootstrap(void) __API_AVAILABLE(macos(10.10), ios(8.0)) DYLD_DRIVERKIT_UNAVAILABLE ;
121
122
123/*
124 * Dylibs that are incorporated into the dyld cache are removed from disk. That means code
125 * cannot stat() the file to see if it "exists". This function is like a stat() call that checks if a
126 * path is to a dylib that was removed from disk and is incorporated into the active dyld cache.
127 */
128extern bool _dyld_shared_cache_contains_path(const char* path) __API_AVAILABLE(macos(11.0), ios(14.0), watchos(7.0), tvos(14.0)) DYLD_DRIVERKIT_UNAVAILABLE;
129
130
131/*
132 * The following dyld API's are deprecated as of Mac OS X 10.5. They are either
133 * no longer necessary or are superceeded by dlopen and friends in <dlfcn.h>.
134 * dlopen/dlsym/dlclose have been available since Mac OS X 10.3 and work with
135 * dylibs and bundles.
136 *
137 * NSAddImage -> dlopen
138 * NSLookupSymbolInImage -> dlsym
139 * NSCreateObjectFileImageFromFile -> dlopen
140 * NSDestroyObjectFileImage -> dlclose
141 * NSLinkModule -> not needed when dlopen used
142 * NSUnLinkModule -> not needed when dlclose used
143 * NSLookupSymbolInModule -> dlsym
144 * _dyld_image_containing_address -> dladdr
145 * NSLinkEditError -> dlerror
146 *
147 */
148
149#ifndef ENUM_DYLD_BOOL
150#define ENUM_DYLD_BOOL
151 #undef FALSE
152 #undef TRUE
153 enum DYLD_BOOL { FALSE, TRUE };
154#endif /* ENUM_DYLD_BOOL */
155
156
157/* Object file image API */
158typedef enum {
159 NSObjectFileImageFailure, /* for this a message is printed on stderr */
160 NSObjectFileImageSuccess,
161 NSObjectFileImageInappropriateFile,
162 NSObjectFileImageArch,
163 NSObjectFileImageFormat, /* for this a message is printed on stderr */
164 NSObjectFileImageAccess
165} NSObjectFileImageReturnCode;
166
167typedef struct __NSObjectFileImage* NSObjectFileImage;
168
169
170
171/* NSObjectFileImage can only be used with MH_BUNDLE files */
172extern NSObjectFileImageReturnCode NSCreateObjectFileImageFromFile(const char* pathName, NSObjectFileImage *objectFileImage) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "dlopen()");
173extern NSObjectFileImageReturnCode NSCreateObjectFileImageFromMemory(const void *address, size_t size, NSObjectFileImage *objectFileImage) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "");
174extern bool NSDestroyObjectFileImage(NSObjectFileImage objectFileImage) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "dlclose()");
175
176extern uint32_t NSSymbolDefinitionCountInObjectFileImage(NSObjectFileImage objectFileImage) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "");
177extern const char* NSSymbolDefinitionNameInObjectFileImage(NSObjectFileImage objectFileImage, uint32_t ordinal) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "");
178extern uint32_t NSSymbolReferenceCountInObjectFileImage(NSObjectFileImage objectFileImage) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "");
179extern const char* NSSymbolReferenceNameInObjectFileImage(NSObjectFileImage objectFileImage, uint32_t ordinal, bool *tentative_definition) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "");
180extern bool NSIsSymbolDefinedInObjectFileImage(NSObjectFileImage objectFileImage, const char* symbolName) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.4, "dlsym()");
181extern void* NSGetSectionDataInObjectFileImage(NSObjectFileImage objectFileImage, const char* segmentName, const char* sectionName, size_t *size) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "getsectiondata()");
182
183typedef struct __NSModule* NSModule;
184extern const char* NSNameOfModule(NSModule m) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "");
185extern const char* NSLibraryNameForModule(NSModule m) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "");
186
187extern NSModule NSLinkModule(NSObjectFileImage objectFileImage, const char* moduleName, uint32_t options) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "dlopen()");
188#define NSLINKMODULE_OPTION_NONE 0x0
189#define NSLINKMODULE_OPTION_BINDNOW 0x1
190#define NSLINKMODULE_OPTION_PRIVATE 0x2
191#define NSLINKMODULE_OPTION_RETURN_ON_ERROR 0x4
192#define NSLINKMODULE_OPTION_DONT_CALL_MOD_INIT_ROUTINES 0x8
193#define NSLINKMODULE_OPTION_TRAILING_PHYS_NAME 0x10
194
195extern bool NSUnLinkModule(NSModule module, uint32_t options) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "");
196#define NSUNLINKMODULE_OPTION_NONE 0x0
197#define NSUNLINKMODULE_OPTION_KEEP_MEMORY_MAPPED 0x1
198#define NSUNLINKMODULE_OPTION_RESET_LAZY_REFERENCES 0x2
199
200/* symbol API */
201typedef struct __NSSymbol* NSSymbol;
202extern bool NSIsSymbolNameDefined(const char* symbolName) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.4, "dlsym()");
203extern bool NSIsSymbolNameDefinedWithHint(const char* symbolName, const char* libraryNameHint) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.4, "dlsym()");
204extern bool NSIsSymbolNameDefinedInImage(const struct mach_header* image, const char* symbolName) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.4, "dlsym()");
205extern NSSymbol NSLookupAndBindSymbol(const char* symbolName) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.4, "dlsym()");
206extern NSSymbol NSLookupAndBindSymbolWithHint(const char* symbolName, const char* libraryNameHint) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.4, "dlsym()");
207extern NSSymbol NSLookupSymbolInModule(NSModule module, const char* symbolName) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "dlsym()");
208extern NSSymbol NSLookupSymbolInImage(const struct mach_header* image, const char* symbolName, uint32_t options) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "dlsym()");
209#define NSLOOKUPSYMBOLINIMAGE_OPTION_BIND 0x0
210#define NSLOOKUPSYMBOLINIMAGE_OPTION_BIND_NOW 0x1
211#define NSLOOKUPSYMBOLINIMAGE_OPTION_BIND_FULLY 0x2
212#define NSLOOKUPSYMBOLINIMAGE_OPTION_RETURN_ON_ERROR 0x4
213extern const char* NSNameOfSymbol(NSSymbol symbol) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "");
214extern void * NSAddressOfSymbol(NSSymbol symbol) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "dlsym()");
215extern NSModule NSModuleForSymbol(NSSymbol symbol) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "dladdr()");
216
217/* error handling API */
218typedef enum {
219 NSLinkEditFileAccessError,
220 NSLinkEditFileFormatError,
221 NSLinkEditMachResourceError,
222 NSLinkEditUnixResourceError,
223 NSLinkEditOtherError,
224 NSLinkEditWarningError,
225 NSLinkEditMultiplyDefinedError,
226 NSLinkEditUndefinedError
227} NSLinkEditErrors;
228
229/*
230 * For the NSLinkEditErrors value NSLinkEditOtherError these are the values
231 * passed to the link edit error handler as the errorNumber (what would be an
232 * errno value for NSLinkEditUnixResourceError or a kern_return_t value for
233 * NSLinkEditMachResourceError).
234 */
235typedef enum {
236 NSOtherErrorRelocation,
237 NSOtherErrorLazyBind,
238 NSOtherErrorIndrLoop,
239 NSOtherErrorLazyInit,
240 NSOtherErrorInvalidArgs
241} NSOtherErrorNumbers;
242
243extern void NSLinkEditError(NSLinkEditErrors *c, int *errorNumber, const char** fileName, const char** errorString) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "dlerror()");
244
245typedef struct {
246 void (*undefined)(const char* symbolName);
247 NSModule (*multiple)(NSSymbol s, NSModule oldModule, NSModule newModule);
248 void (*linkEdit)(NSLinkEditErrors errorClass, int errorNumber,
249 const char* fileName, const char* errorString);
250} NSLinkEditErrorHandlers;
251
252extern void NSInstallLinkEditErrorHandlers(const NSLinkEditErrorHandlers *handlers) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "");
253
254extern bool NSAddLibrary(const char* pathName) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.4, "dlopen()");
255extern bool NSAddLibraryWithSearching(const char* pathName) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.4, "dlopen()");
256extern const struct mach_header* NSAddImage(const char* image_name, uint32_t options) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "dlopen()");
257#define NSADDIMAGE_OPTION_NONE 0x0
258#define NSADDIMAGE_OPTION_RETURN_ON_ERROR 0x1
259#define NSADDIMAGE_OPTION_WITH_SEARCHING 0x2
260#define NSADDIMAGE_OPTION_RETURN_ONLY_IF_LOADED 0x4
261#define NSADDIMAGE_OPTION_MATCH_FILENAME_BY_INSTALLNAME 0x8
262
263extern bool _dyld_present(void) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "always true");
264extern bool _dyld_launched_prebound(void) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "moot");
265extern bool _dyld_all_twolevel_modules_prebound(void) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.3, 10.5, "moot");
266extern bool _dyld_bind_fully_image_containing_address(const void* address) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "dlopen(RTLD_NOW)");
267extern bool _dyld_image_containing_address(const void* address) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.3, 10.5, "dladdr()");
268extern void _dyld_lookup_and_bind(const char* symbol_name, void **address, NSModule* module) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.4, "dlsym()");
269extern void _dyld_lookup_and_bind_with_hint(const char* symbol_name, const char* library_name_hint, void** address, NSModule* module) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.4, "dlsym()");
270extern void _dyld_lookup_and_bind_fully(const char* symbol_name, void** address, NSModule* module) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.1, 10.5, "dlsym()");
271
272extern const struct mach_header* _dyld_get_image_header_containing_address(const void* address) __API_UNAVAILABLE(ios, tvos, watchos) DYLD_DRIVERKIT_UNAVAILABLE DYLD_EXCLAVEKIT_UNAVAILABLE __OSX_DEPRECATED(10.3, 10.5, "dladdr()");
273
274
275#if __cplusplus
276}
277#endif
278
279#endif /* _MACH_O_DYLD_H_ */