|
|
|
#include <mach-o/dyld_debug.h>
extern enum dyld_debug_return _dyld_debug_defining_module(
task_t target_task,
unsigned long send_timeout,
unsigned long rcv_timeout,
boolean_t inconsistent_data_ok,
char *name,
struct dyld_debug_module *module);
extern enum dyld_debug_return _dyld_debug_is_module_bound(
task_t target_task,
unsigned long send_timeout,
unsigned long rcv_timeout,
boolean_t inconsistent_data_ok,
struct dyld_debug_module module,
boolean_t *bound);
extern enum dyld_debug_return _dyld_debug_bind_module(
task_t target_task,
unsigned long send_timeout,
unsigned long rcv_timeout,
boolean_t inconsistent_data_ok,
struct dyld_debug_module module);
extern enum dyld_debug_return _dyld_debug_module_name(
task_t target_task,
unsigned long send_timeout,
unsigned long rcv_timeout,
boolean_t inconsistent_data_ok,
struct dyld_debug_module module,
char **image_name,
unsigned long *image_nameCnt,
char **module_name,
unsigned long *module_nameCnt);
extern enum dyld_debug_return _dyld_debug_subscribe_to_events(
task_t target_task,
unsigned long send_timeout,
unsigned long rcv_timeout,
boolean_t inconsistent_data_ok,
void (*dyld_event_routine)(struct dyld_event event));
extern enum dyld_debug_return _dyld_debug_add_event_subscriber(
task_t target_task,
unsigned long send_timeout,
unsigned long rcv_timeout,
boolean_t inconsistent_data_ok,
port_t subscriber);
extern boolean_t _dyld_event_server(
struct _dyld_event_message_request *request,
struct _dyld_event_message_reply *reply);
extern void _dyld_event_server_callback(
port_t subscriber,
struct dyld_event event);
These routines are the programmatic interface for debugging or examining a task that is using the dynamic link editor. Using these routines allows one to get accurate information on which symbols (and from which library or image they come from) are being used by a target task.
These routines communicate with the target_task being debugged with mach messages. The parameters target_task, send_timeout, rcv_timeout and inconsistent_data_ok have the same meaning for all the routines. All the routines return the same return code type which is interpreted the same for all routines.
target_task is the task port for the task which is being debugged.
send_timeout and rcv_timeout are the mach message send and receive time out values in milliseconds to be used with msg_rpc(2).
inconsistent_data_ok indicates if it is ok to attempt to the operation even though the state of the dynamic linker in the target task is inconsistent. All of these calls suspend all threads in the target task during the duration of the calls. Then they first attempt to finish any current dynamic linking operation in process, there by getting the dynamic linker into a consistent state. If the operation is done successfully and inconsistent_data_ok was FALSE it is assured the results are consistent. If the operation fails with inconsistent_data_ok FALSE it can be retried with inconsistent_data_ok TRUE to possibly get the information. Even if inconsistent_data_ok is TRUE the operation may still fail with the return code DYLD_INCONSISTENT_DATA depending on the state of the dynamic linker in the target task and the operation to be performed.
_dyld_debug_defining_module is passed a symbol name and returns which module the symbol name is being or would be used from. If the symbol does not exist in the target_task this returns DYLD_INVALID_ARGUMENTS.
_dyld_debug_is_module_bound is passed a dyld_debug_module struct and sets bound to TRUE if the module is bound and FALSE otherwise. If the module does not refer to a valid module DYLD_INVALID_ARGUMENTS is returned.
_dyld_debug_bind_module binds the modules specified by dyld_debug_module into the target task. If the module does not refer to a valid module DYLD_INVALID_ARGUMENTS is returned. This will return DYLD_FAILURE if there is a dynamic linking operation in progress that could not be first completed without error. This routine can cause the task to exit if when binding the specified module it results in an undefined symbol, a multiply defined symbol or other link edit error and the target task does not handle the error. _dyld_debug_bind_module should be used with this in mind.
_dyld_debug_module_name returns the image name and module name for the specified dyld_debug_module in the target task. If the module does not refer to a valid module DYLD_INVALID_ARGUMENTS is returned. This will return DYLD_FAILURE if there is a dynamic linking operation in progress that could not be first completed without error. The names are returned as pointers to vm_allocated memory. Their sizes are also returned so the memory can be vm_deallocated when no longer needed. Tempting as it might be, this can not be called from the function passed to _dyld_debug_subscribe_to_events as the mach message queues will fill and the calls will time out.
_dyld_debug_subscribe_to_events creates a new thread that is will call the specified dyld_event_routine when dynamic link events occur in the target task. These events are described below.
_dyld_debug_add_event_subscriber adds the subscriber port to the list of event ports that dyld event messages are sent to. This is just a different interface to get dynamic link events on a mach port rather than using _dyld_debug_subscribe_to_events which creates a new thread.
_dyld_event_server is the mig generated routine to dispatch dyld event messages that can be used if the _dyld_debug_add_event_subscriber interface is used. This routine will call the routine _dyld_event_server_callback which must be provided if _dyld_event_server is used.
If _dyld_debug_subscribe_to_events or _dyld_debug_add_event_subscriber is used dynamic link events will be sent to the dyld_event_routine or _dyld_event_server_callback respectfully. The dyld_event structure parameter describes the dynamic link event that happened in the target task. The event field of the dyld_event structure specified the type of the event and the arg field describes the module(s) or image for the event. The dyld_debug_module of the arg's for non-library modules always have module_index field of 0. The possible event types are as follows:
The DYLD_IMAGE_ADDED event is sent when a new images is brought into the target task. These images include the dynamic linker itself, the executable image, dynamic shared libraries that get loaded and objects loaded by NXLoadModule. For this event only the arg[0] field of the dyld_event structure is used for the image and the module_index is has no meaning since this event is for the entire image.
A DYLD_MODULE_BOUND event is sent for each module that is bound into the target task. For this event only the arg[0] field of the dyld_event structure is used to identify the module being bound.
A DYLD_MODULE_REMOVED event is sent for each module that is removed in the target task via an NXUnloadModule call done by the target task. For this event only the arg[0] field of the dyld_event structure is used to identify the module being unloaded.
A DYLD_MODULE_REPLACED event is sent for each module that is replaced in the target task via an NXReplaceModule call done by the target task. For this event the arg[0] field of the dyld_event structure is used to identify the module that was replaced and the arg[1] field identifies the new moduled that replaced it.
|
|
|
Created by unroff & hp-tools. © somebody (See intro for details). All Rights Reserved. Last modified 11/5/97