dyld_debug man page on OpenDarwin

Man page or keyword search:  
man Server   3202 pages
apropos Keyword Search (all sections)
Output format
OpenDarwin logo
[printable version]

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)
[top]

List of man pages available for OpenDarwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
...................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net