dyld-43.tar.gz
[apple/dyld.git] / include / mach-o / dyld_debug.h
1 /*
2 * Copyright (c) 1999 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 _DYLD_DEBUG_
24 #define _DYLD_DEBUG_
25
26 #include <mach/mach.h>
27 #ifndef DYLD_BUILD /* do not include this when building dyld itself */
28 #include <mach-o/dyld.h>
29 #endif /* !defined(DYLD_BUILD) */
30
31 #include <AvailabilityMacros.h>
32
33 /*
34 * The dyld debugging API is deprecated as of Mac OS X 10.4
35 */
36 enum dyld_debug_return {
37 DYLD_SUCCESS,
38 DYLD_INCONSISTENT_DATA,
39 DYLD_INVALID_ARGUMENTS,
40 DYLD_FAILURE
41 };
42
43 struct dyld_debug_module {
44 struct mach_header *header;
45 unsigned long vmaddr_slide;
46 unsigned long module_index;
47 };
48
49 enum dyld_event_type {
50 DYLD_IMAGE_ADDED,
51 DYLD_MODULE_BOUND,
52 DYLD_MODULE_REMOVED,
53 DYLD_MODULE_REPLACED,
54 DYLD_PAST_EVENTS_END,
55 DYLD_IMAGE_REMOVED
56 };
57
58 struct dyld_event {
59 enum dyld_event_type type;
60 struct dyld_debug_module arg[2];
61 };
62
63 extern enum dyld_debug_return _dyld_debug_defining_module(
64 mach_port_t target_task,
65 unsigned long send_timeout,
66 unsigned long rcv_timeout,
67 boolean_t inconsistent_data_ok,
68 char *name,
69 struct dyld_debug_module *module) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4;
70
71 extern enum dyld_debug_return _dyld_debug_is_module_bound(
72 mach_port_t target_task,
73 unsigned long send_timeout,
74 unsigned long rcv_timeout,
75 boolean_t inconsistent_data_ok,
76 struct dyld_debug_module module,
77 boolean_t *bound) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4;
78
79 extern enum dyld_debug_return _dyld_debug_bind_module(
80 mach_port_t target_task,
81 unsigned long send_timeout,
82 unsigned long rcv_timeout,
83 boolean_t inconsistent_data_ok,
84 struct dyld_debug_module module) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4;
85
86 extern enum dyld_debug_return _dyld_debug_module_name(
87 mach_port_t target_task,
88 unsigned long send_timeout,
89 unsigned long rcv_timeout,
90 boolean_t inconsistent_data_ok,
91 struct dyld_debug_module module,
92 char **image_name,
93 unsigned long *image_nameCnt,
94 char **module_name,
95 unsigned long *module_nameCnt) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4;
96
97 extern enum dyld_debug_return _dyld_debug_subscribe_to_events(
98 mach_port_t target_task,
99 unsigned long send_timeout,
100 unsigned long rcv_timeout,
101 boolean_t inconsistent_data_ok,
102 void (*dyld_event_routine)(struct dyld_event event)) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4;
103
104 /*
105 * _dyld_debug_add_event_subscriber() uses the mig interface functions below
106 * to dispatch the dyld event messages from the subscriber port specified.
107 */
108 extern enum dyld_debug_return _dyld_debug_add_event_subscriber(
109 mach_port_t target_task,
110 unsigned long send_timeout,
111 unsigned long rcv_timeout,
112 boolean_t inconsistent_data_ok,
113 mach_port_t subscriber) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4;
114
115 /*
116 * These structures should be produced by mig(1) from the mig generated files
117 * but they are not. These are really only needed so the correct size of the
118 * request and reply messages can be allocated.
119 */
120 struct _dyld_event_message_request {
121 #ifdef __MACH30__
122 mach_msg_header_t head;
123 NDR_record_t NDR;
124 struct dyld_event event;
125 mach_msg_trailer_t trailer;
126 #else
127 msg_header_t head;
128 msg_type_t eventType;
129 struct dyld_event event;
130 #endif
131 };
132 struct _dyld_event_message_reply {
133 #ifdef __MACH30__
134 mach_msg_header_t head;
135 NDR_record_t NDR;
136 struct dyld_event event;
137 #else
138 msg_header_t head;
139 msg_type_t RetCodeType;
140 kern_return_t RetCode;
141 #endif
142 };
143 #ifndef mig_internal
144 /*
145 * _dyld_event_server() is the mig generated routine to dispatch dyld event
146 * messages.
147 */
148 extern boolean_t _dyld_event_server(
149 #ifdef __MACH30__
150 mach_msg_header_t *request,
151 mach_msg_header_t *reply);
152 #else
153 struct _dyld_event_message_request *request,
154 struct _dyld_event_message_reply *reply);
155 #endif
156 #endif /* mig_internal */
157
158 #ifndef SHLIB
159 /*
160 * _dyld_event_server_callback() is the routine called by _dyld_event_server()
161 * that must be written by users of _dyld_event_server().
162 */
163 extern
164 #ifdef __MACH30__
165 kern_return_t
166 #else
167 void
168 #endif
169 _dyld_event_server_callback(
170 #ifdef __MACH30__
171 mach_port_t subscriber,
172 #else
173 port_t subscriber,
174 #endif
175 struct dyld_event event);
176 #endif /* SHLIB */
177
178 /*
179 * This is the state of the target task while we are sending a message to it.
180 */
181 struct _dyld_debug_task_state {
182 mach_port_t debug_port;
183 mach_port_t debug_thread;
184 unsigned int debug_thread_resume_count;
185 unsigned int task_resume_count;
186 mach_port_t *threads;
187 unsigned int thread_count;
188 };
189
190 /*
191 * _dyld_debug_make_runnable() is called before sending messages to the
192 * dynamic link editor. Basically it assures that the debugging
193 * thread is the only runnable thread in the task to receive the
194 * message. It also assures that the debugging thread is indeed
195 * runnable if it was suspended. The function will make sure each
196 * thread in the remote task is suspended and resumed the same number
197 * of times, so in the end the suspend count of each individual thread
198 * is the same.
199 */
200 extern enum dyld_debug_return _dyld_debug_make_runnable(
201 mach_port_t target_task,
202 struct _dyld_debug_task_state *state) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4;
203
204 /*
205 * _dyld_debug_restore_runnable() is called after sending messages to the
206 * dynamic link editor. It undoes what _dyld_debug_make_runnable() did to the
207 * task and put it back the way it was.
208 */
209 extern enum dyld_debug_return _dyld_debug_restore_runnable(
210 mach_port_t target_task,
211 struct _dyld_debug_task_state *state) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4;
212
213 /*
214 * To provide more detailed information when the APIs of the dyld debug
215 * interfaces fail (return DYLD_FAILURE) the following structure is filled in.
216 * After it is filled in the function registered with
217 * set_dyld_debug_error_func() is called with a pointer to that struct.
218 *
219 * The local_error field is a unique number for each possible error condition
220 * in the source code in that makes up the dyld debug APIs. The source file
221 * and line number in the cctools libdyld directory where the dyld debug APIs
222 * are implemented are set into the file_name and line_number fields. The
223 * field dyld_debug_return is filled in with that would be returned by the
224 * API (usually DYLD_FAILURE). The other fields will be zero or filled in by
225 * the error code from the mach system call, or UNIX system call that failed.
226 */
227 struct dyld_debug_error_data {
228 enum dyld_debug_return dyld_debug_return;
229 kern_return_t mach_error;
230 int dyld_debug_errno;
231 unsigned long local_error;
232 char *file_name;
233 unsigned long line_number;
234 };
235
236 extern void _dyld_debug_set_error_func(
237 void (*func)(struct dyld_debug_error_data *e)) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4;
238
239 #ifndef DYLD_BUILD /* do not include this when building dyld itself */
240
241 extern enum dyld_debug_return _dyld_debug_task_from_core(
242 NSObjectFileImage coreFileImage,
243 mach_port_t *core_task) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4;
244
245 #endif /* !defined(DYLD_BUILD) */
246
247 #endif /* _DYLD_DEBUG_ */