Unix/Linux Go Back    


OpenDarwin 7.2.1 - man page for dyld_debug (opendarwin section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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 examining a task that is
       using the dynamic link editor.  Using these routines allows one to get  accurate  informa-
       tion 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 mil-
       liseconds 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
       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	inconsis-
       tent_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 possi-
       bly  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 mem-
       ory 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 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.

       _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 condition 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_subscriber 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 messages 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  func-
       tions will make sure each thread in the remote task is suspended and resumed the same num-
       ber 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  respec-
       tively.	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  executable  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  mod-
       ule 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 NSUNLINKMODULE_OPTION_KEEP_MEMORY_MAPPED option speci-
       fied) 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)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 09:02 AM.