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_ */