DYLD_DEBUG(3)DYLD_DEBUG(3)NAME
dyld debug - programmatic interface for debugging a task using the
dynamic link editor
SYNOPSIS
#include <mach-o/dyld_debug.h>
#include <mach-o/dyld.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);
extern void _dyld_debug_set_error_func(
void (*func)(struct dyld_debug_error_data *e));
extern enum dyld_debug_return _dyld_debug_make_runnable(
mach_port_t target_task,
struct _dyld_debug_task_state *state);
extern enum dyld_debug_return _dyld_debug_restore_runnable(
mach_port_t target_task,
struct _dyld_debug_task_state *state);
extern enum dyld_debug_return _dyld_debug_task_from_core(
NSObjectFileImage coreFileImage,
mach_port_t *core_task);
DESCRIPTION
These routines are the programmatic interface for debugging or examin‐
ing 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 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 fin‐
ish 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 inconsis‐
tent_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_mod‐
ule into the target task. If the module does not refer to a valid mod‐
ule 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 will call the
specified dyld_event_routine when dynamic link events occur in the tar‐
get 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.
_dyld_debug_set_error_func is called with a pointer to a function,
func, which will then be called if there are any errors in subsequent
calls to other dyld debug routines. This is to provide more detailed
information when the APIs of the dyld debug interfaces fail (return
DYLD_FAILURE). The e argument is a pointer to a dyld_debug_error_data
structure as defined by <mach-o/dyld_debug.h> (shown below) and into
which information is placed concerning the error.
struct dyld_debug_error_data {
enum dyld_debug_return dyld_debug_return;
kern_return_t mach_error;
int dyld_debug_errno;
unsigned long local_error;
char *file_name;
unsigned long line_number;
}
The local_error field is a unique number for each possible error condi‐
tion in the source code in that makes up the dyld debug APIs. The
file_name and line_number fields are filled in with the the source file
name and line number for the files in the Darwin cctools project in the
libdyld sub-directory which is where the dyld debug APIs are imple‐
mented. The field dyld_debug_return is filled in with that would be
returned by the API (usually DYLD_FAILURE). The other fields will be
zero or filled in by the error code from the mach system call, or UNIX
system call that failed. This is intended to help diagnose problems
with the kernel like not starting the dyld debug thread in the target
task.
_dyld_debug_make_runnable is automaticly called before sending messages
to the dynamic link editor but when the _dyld_debug_add_event_sub‐
scriber API is used by the debugger, gdb(1) for example, it may have
the task and threads suspended and may need to call
_dyld_debug_make_runnable directly. _dyld_debug_make_runnable assures
that the dyld debug thread is the only runnable thread in the task to
receive the message. It also assures that the debugging thread is
indeed runnable if it was suspended. To be able to restore the state
of the task this function changes, the parameter state, is passed in as
a pointer to _dyld_debug_task_state structure and the state changed
state is saved into that structure.
_dyld_debug_restore_runnable is automaticly called after sending mes‐
sages to the dynamic link editor but again a debugger like gdb(1) may
need to directly call it. It undoes what _dyld_debug_make_runnable did
to the task and puts it back the way it was. These functions will make
sure each thread in the remote task is suspended and resumed the same
number of times, so in the end the suspend count of each individual
thread is the same.
_dyld_debug_task_from_core is used to create a task from a core file in
which the dyld debug API can then be used with that task. The task
port is indirectly returned through the parameter core_task. The core
file is represented as the parameter coreFileImage which is returned
from a sucessfull to NSCreateCoreFileImageFromFile(3).
DYLD EVENTS
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 respectively. 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 image is brought into the
target task. These images include the dynamic linker itself, the exe‐
cutable image, dynamic shared libraries that get loaded and objects
loaded by NSLinkModule. For this event only the arg[0] field of the
dyld_event structure is used for the image and the module_index 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 NSUnLinkModule 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 unlinked.
A DYLD_MODULE_REPLACED event is sent for each module that is replaced
in the target task via an NSReplaceModule 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 module that replaced it.
A DYLD_IMAGE_REMOVED event is sent for each image that is removed in
the target task via an NSUnLinkModule call (without the NSUNLINKMOD‐
ULE_OPTION_KEEP_MEMORY_MAPPED option specified) 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 removed.
RETURN CODES
DYLD_SUCCESS
Indicates the operation and the communication with the target
task was successful.
DYLD_INCONSISTENT_DATA
Indicates the operation was not attempted because the state of
the dynamic linker was able to be brought into a consistent
state.
DYLD_INVALID_ARGUMENTS
Indicates the operation failed because the arguments to the
operation were invalid.
DYLD_FAILURE
Indicates the operation or the communication with the target
task was unsuccessful.
Apple Computer, Inc. April 21, 2000 DYLD_DEBUG(3)
