NAME
dyld debug - programmatic interface for debugging a task using the
dynamic link editorSYNOPSIS
#include
#include
extern enum dylddebugreturn dylddebugdefiningmodule( taskt targettask, unsigned long sendtimeout, unsigned long rcvtimeout, booleant inconsistentdataok, char *name, struct dylddebugmodule *module); extern enum dylddebugreturn dylddebugismodulebound( taskt targettask, unsigned long sendtimeout, unsigned long rcvtimeout, booleant inconsistentdataok, struct dylddebugmodule module, booleant *bound); extern enum dylddebugreturn dylddebugbindmodule( taskt targettask, unsigned long sendtimeout, unsigned long rcvtimeout, booleant inconsistentdataok, struct dylddebugmodule module); extern enum dylddebugreturn dylddebugmodulename( taskt targettask, unsigned long sendtimeout, unsigned long rcvtimeout, booleant inconsistentdataok, struct dylddebugmodule module, char **imagename, unsigned long *imagenameCnt, char **modulename, unsigned long *modulenameCnt); extern enum dylddebugreturn dylddebugsubscribetoevents( taskt targettask, unsigned long sendtimeout, unsigned long rcvtimeout, booleant inconsistentdataok, void (*dyldeventroutine)(struct dyldevent event)); extern enum dylddebugreturn dylddebugaddeventsubscriber( taskt targettask, unsigned long sendtimeout, unsigned long rcvtimeout, booleant inconsistentdataok, portt subscriber); extern booleant dyldeventserver( struct dyldeventmessagerequest *request, struct dyldeventmessagereply *reply); extern void dyldeventservercallback( portt subscriber, struct dyldevent event); extern void dylddebugseterrorfunc( void (*func)(struct dylddebugerrordata *e)); extern enum dylddebugreturn dylddebugmakerunnable( machportt targettask, struct dylddebugtaskstate *state); extern enum dylddebugreturn dylddebugrestorerunnable( machportt targettask, struct dylddebugtaskstate *state); extern enum dylddebugreturn dylddebugtaskfromcore( NSObjectFileImage coreFileImage, machportt *coretask);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 targettask being debugged with mach messages. The parameters targettask, sendtimeout, rcvtimeout and inconsistentdataok 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. targettask is the task port for the task which is being debugged. sendtimeout and rcvtimeout are the mach message send and receive time out values in milliseconds to be used with msgrpc(2). inconsistentdataok 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 targettask 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 inconsistentdataok was FALSE it is assured theresults are consistent. If the operation fails with inconsis-
tentdataok FALSE it can be retried with inconsistentdataok TRUE to possibly get the information. Even if inconsistentdataok is TRUE the operation may still fail with the return code DYLDINCONSISTENTDATA depending on the state of the dynamic linker in the target task and the operation to be performed. dylddebugdefiningmodule 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 targettask this returns DYLDINVALIDARGUMENTS. dylddebugismodulebound is passed a dylddebugmodule struct and sets bound to TRUE if the module is bound and FALSE otherwise. If the module does not refer to a valid module DYLDINVALIDARGUMENTS is returned.dylddebugbindmodule binds the modules specified by dylddebugmod-
ule into the target task. If the module does not refer to a valid mod-
ule DYLDINVALIDARGUMENTS is returned. This will return DYLDFAILURE 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. dylddebugbindmodule should be used with this in mind. dylddebugmodulename returns the image name and module name for the specified dylddebugmodule in the target task. If the module does not refer to a valid module DYLDINVALIDARGUMENTS is returned. This will return DYLDFAILURE if there is a dynamic linking operation in progress that could not be first completed without error. The names are returned as pointers to vmallocated memory. Their sizes are also returned so the memory can be vmdeallocated when no longer needed. Tempting as it might be, this can not be called from the function passed to dylddebugsubscribetoevents as the mach message queues will fill and the calls will time out. dylddebugsubscribetoevents creates a new thread that will call thespecified dyldeventroutine when dynamic link events occur in the tar-
get task. These events are described below. dylddebugaddeventsubscriber 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 dylddebugsubscribetoevents which creates a new thread. dyldeventserver is the mig generated routine to dispatch dyld event messages that can be used if the dylddebugaddeventsubscriber interface is used. This routine will call the routine dyldeventservercallback which must be provided if dyldeventserver is used. dylddebugseterrorfunc 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 DYLDFAILURE). The e argument is a pointer to a dylddebugerrordatastructure as defined by <
which information is placed concerning the error. struct dylddebugerrordata { enum dylddebugreturn dylddebugreturn; kernreturnt macherror; int dylddebugerrno; unsigned long localerror; char *filename; unsigned long linenumber; }> (shown below) and into The localerror field is a unique number for each possible error condi-
tion in the source code in that makes up the dyld debug APIs. The filename and linenumber fields are filled in with the the source file name and line number for the files in the Darwin cctools project in thelibdyld sub-directory which is where the dyld debug APIs are imple-
mented. The field dylddebugreturn is filled in with that would be returned by the API (usually DYLDFAILURE). 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. dylddebugmakerunnable is automaticly called before sending messagesto the dynamic link editor but when the dylddebugaddeventsub-
scriber API is used by the debugger, gdb(1) for example, it may have the task and threads suspended and may need to call dylddebugmakerunnable directly. dylddebugmakerunnable 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 dylddebugtaskstate structure and the state changed state is saved into that structure.dylddebugrestorerunnable 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 dylddebugmakerunnable 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. dylddebugtaskfromcore 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 coretask. The core file is represented as the parameter coreFileImage which is returned from a sucessfull to NSCreateCoreFileImageFromFile(3). DDYYLLDD EEVVEENNTTSS If dylddebugsubscribetoevents or dylddebugaddeventsubscriber is used dynamic link events will be sent to the dyldeventroutine or dyldeventservercallback respectively. The dyldevent structure parameter describes the dynamic link event that happened in the target task. The event field of the dyldevent structure specified the type of the event and the arg field describes the module(s) or image for theevent. The dylddebugmodule of the arg's for non-library modules
always have moduleindex field of 0. The possible event types are as follows: The DYLDIMAGEADDED event is sent when a new image is brought into thetarget 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 dyldevent structure is used for the image and the moduleindex has no meaning since this event is for the entire image. A DYLDMODULEBOUND event is sent for each module that is bound into the target task. For this event only the arg[0] field of the dyldevent structure is used to identify the module being bound. A DYLDMODULEREMOVED 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 dyldevent structure is used to identify the module being unlinked. A DYLDMODULEREPLACED 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 dyldevent structure is used to identify the module that was replaced and the arg[1] field identifies the new module that replaced it. A DYLDIMAGEREMOVED event is sent for each image that is removed inthe target task via an NSUnLinkModule call (without the NSUNLINKMOD-
ULEOPTIONKEEPMEMORYMAPPED option specified) done by the target
task. For this event only the arg[0] field of the dyldevent structure is used to identify the module being removed. RREETTUURRNN CCOODDEESS DYLDSUCCESS Indicates the operation and the communication with the target task was successful. DYLDINCONSISTENTDATA Indicates the operation was not attempted because the state of the dynamic linker was able to be brought into a consistent state. DYLDINVALIDARGUMENTS Indicates the operation failed because the arguments to the operation were invalid. DYLDFAILURE Indicates the operation or the communication with the target task was unsuccessful. Apple Computer, Inc. April 21, 2000 DYLDDEBUG(3)