IDA SDK
Classes | Functions | Macros | Typedefs | Enumerations | Variables
dbg.hpp File Reference

Detailed Description

Contains functions to control the debugging of a process.

See Debugger functions for a complete explanation of these functions.

These functions are inlined for the kernel. They are not inlined for the user-interfaces.

Classes

struct  bpt_location_t
 Describes a breakpoint location. More...
 
struct  bpt_t
 Characteristics of a breakpoint. More...
 
struct  movbpt_info_t
 
struct  bpt_visitor_t
 Visit all breakpoints. More...
 
struct  tev_info_t
 Common information for all trace events. More...
 
struct  memreg_info_t
 Required typedef for get_insn_tev_reg_mem() More...
 
struct  tev_reg_value_t
 Structure used for dbg_add_many_tevs() More...
 
struct  tev_info_reg_t
 Structure used for dbg_add_many_tevs() More...
 
class  eval_ctx_t
 Execution context. More...
 
class  source_file_t
 Describes a source file. More...
 
class  source_item_t
 Describes a subdivision of source information. More...
 
class  srcinfo_provider_t
 Describes the mechanism used to retrieve source file information. More...
 

Functions

bool idaapi run_requests (void)
 Execute requests until all requests are processed or an asynchronous function is called. More...
 
ui_notification_t idaapi get_running_request (void)
 Get the current running request. More...
 
bool is_request_running (void)
 Is a request currently running?
 
dbg_notification_t idaapi get_running_notification (void)
 Get the notification associated (if any) with the current running request. More...
 
void idaapi clear_requests_queue (void)
 Clear the queue of waiting requests. More...
 
int idaapi get_process_state (void)
 Return the state of the currently debugged process. More...
 
int idaapi set_process_state (int newstate, thid_t *p_thid, int dbginv)
 Set new state for the debugged process. More...
 
int idaapi invalidate_dbg_state (int dbginv)
 Invalidate cached debugger information. More...
 
int idaapi start_process (const char *path=NULL, const char *args=NULL, const char *sdir=NULL)
 Start a process in the debugger. More...
 
int idaapi request_start_process (const char *path=NULL, const char *args=NULL, const char *sdir=NULL)
 Post a start_process() request.
 
bool idaapi suspend_process (void)
 Suspend the process in the debugger. More...
 
bool idaapi request_suspend_process (void)
 Post a suspend_process() request.
 
bool idaapi continue_process (void)
 Continue the execution of the process in the debugger. More...
 
bool idaapi request_continue_process (void)
 Post a continue_process() request. More...
 
bool idaapi exit_process (void)
 Terminate the debugging of the current process. More...
 
bool idaapi request_exit_process (void)
 Post an exit_process() request.
 
ssize_t idaapi get_processes (procinfo_vec_t *proclist)
 Take a snapshot of running processes and return their description. More...
 
int idaapi attach_process (pid_t pid=NO_PROCESS, int event_id=-1)
 Attach the debugger to a running process. More...
 
int idaapi request_attach_process (pid_t pid, int event_id)
 Post an attach_process() request.
 
bool idaapi detach_process (void)
 Detach the debugger from the debugged process. More...
 
bool idaapi request_detach_process (void)
 Post a detach_process() request.
 
bool idaapi is_debugger_busy (void)
 Is the debugger busy?. More...
 
int idaapi get_thread_qty (void)
 Get number of threads. More...
 
thid_t idaapi getn_thread (int n)
 Get the ID of a thread. More...
 
thid_t idaapi get_current_thread (void)
 Get current thread ID. More...
 
bool idaapi select_thread (thid_t tid)
 Select the given thread as the current debugged thread. More...
 
bool idaapi request_select_thread (thid_t tid)
 Post a select_thread() request.
 
int idaapi suspend_thread (thid_t tid)
 Suspend thread. More...
 
int idaapi request_suspend_thread (thid_t tid)
 Post a suspend_thread() request.
 
int idaapi resume_thread (thid_t tid)
 Resume thread. More...
 
int idaapi request_resume_thread (thid_t tid)
 Post a resume_thread() request.
 
bool idaapi get_first_module (module_info_t *modinfo)
 See Modules.
 
bool idaapi get_next_module (module_info_t *modinfo)
 See Modules.
 
bool idaapi step_into (void)
 Execute one instruction in the current thread. More...
 
bool idaapi request_step_into (void)
 Post a step_into() request.
 
bool idaapi step_over (void)
 Execute one instruction in the current thread, but without entering into functions. More...
 
bool idaapi request_step_over (void)
 Post a step_over() request.
 
bool idaapi run_to (ea_t ea)
 Execute the process until the given address is reached. More...
 
bool idaapi request_run_to (ea_t ea)
 Post a run_to() request.
 
bool idaapi step_until_ret (void)
 Execute instructions in the current thread until a function return instruction is executed (aka "step out"). More...
 
bool idaapi request_step_until_ret (void)
 Post a step_until_ret() request.
 
bool idaapi set_resume_mode (thid_t tid, resume_mode_t mode)
 How to resume the application. More...
 
bool idaapi request_set_resume_mode (thid_t tid, resume_mode_t mode)
 Post a set_resume_mode() request.
 
bool idaapi get_reg_val (const char *regname, regval_t *regval)
 Read a register value from the current thread. More...
 
bool get_reg_val (const char *regname, uint64 *ival)
 Get register value as an unsigned 64-bit int.
 
bool idaapi get_sp_val (ea_t *out_spval)
 Get value of the SP register for the current thread. More...
 
bool idaapi get_ip_val (ea_t *out_ipval)
 Get value of the IP (program counter) register for the current thread. More...
 
bool idaapi set_reg_val (const char *regname, const regval_t *regval)
 Write a register value to the current thread. More...
 
bool idaapi request_set_reg_val (const char *regname, const regval_t *regval)
 Post a set_reg_val() request.
 
bool set_reg_val (const char *regname, uint64 ival)
 Write a register value to the current thread.
 
bool idaapi is_reg_integer (const char *regname)
 Does a register contain an integer value? More...
 
bool idaapi is_reg_float (const char *regname)
 Does a register contain a floating point value? More...
 
bool idaapi is_reg_custom (const char *regname)
 Does a register contain a value of a custom data type? More...
 
int idaapi set_bptloc_string (const char *s)
 Helper function for bpt_location_t.
 
const char *idaapi get_bptloc_string (int i)
 Helper function for bpt_location_t. More...
 
int idaapi get_bpt_qty (void)
 Get number of breakpoints. More...
 
bool idaapi getn_bpt (int n, bpt_t *bpt)
 Get the characteristics of a breakpoint. More...
 
bool idaapi get_bpt (ea_t ea, bpt_t *bpt)
 Get the characteristics of a breakpoint. More...
 
bool exist_bpt (ea_t ea)
 Does a breakpoint exist at the given location?
 
bool idaapi add_bpt (ea_t ea, asize_t size=0, bpttype_t type=BPT_DEFAULT)
 Add a new breakpoint in the debugged process. More...
 
bool idaapi request_add_bpt (ea_t ea, asize_t size=0, bpttype_t type=BPT_DEFAULT)
 Post an add_bpt(ea_t, asize_t, bpttype_t) request.
 
bool idaapi add_bpt (const bpt_t &bpt)
 Add a new breakpoint in the debugged process. More...
 
bool idaapi request_add_bpt (const bpt_t &bpt)
 Post an add_bpt(const bpt_t &) request.
 
bool idaapi del_bpt (ea_t ea)
 Delete an existing breakpoint in the debugged process. More...
 
bool idaapi request_del_bpt (ea_t ea)
 Post a del_bpt(ea_t) request.
 
bool idaapi del_bpt (const bpt_location_t &bptloc)
 Delete an existing breakpoint in the debugged process. More...
 
bool idaapi request_del_bpt (const bpt_location_t &bptloc)
 Post a del_bpt(const bpt_location_t &) request.
 
bool idaapi update_bpt (const bpt_t *bpt)
 Update modifiable characteristics of an existing breakpoint. More...
 
bool idaapi find_bpt (const bpt_location_t &bptloc, bpt_t *bpt)
 Find a breakpoint by location. More...
 
int idaapi change_bptlocs (const movbpt_infos_t &movinfo, movbpt_codes_t *codes=NULL, bool del_hindering_bpts=true)
 Move breakpoint(s) from one location to another. More...
 
int idaapi check_bpt (ea_t ea)
 Check the breakpoint at the specified address. More...
 
bool idaapi set_trace_size (int size)
 Specify the new size of the circular buffer. More...
 
void idaapi clear_trace (void)
 Clear all events in the trace buffer. More...
 
void idaapi request_clear_trace (void)
 Post a clear_trace() request.
 
bool idaapi is_step_trace_enabled (void)
 Get current state of step tracing. More...
 
int idaapi get_step_trace_options (void)
 Get current step tracing options. More...
 
void idaapi set_step_trace_options (int options)
 Modify step tracing options. More...
 
void idaapi request_set_step_trace_options (int options)
 Post a set_step_trace_options() request.
 
bool idaapi is_insn_trace_enabled (void)
 Get current state of instructions tracing. More...
 
int idaapi get_insn_trace_options (void)
 Get current instruction tracing options. More...
 
void idaapi set_insn_trace_options (int options)
 Modify instruction tracing options. More...
 
void idaapi request_set_insn_trace_options (int options)
 Post a set_insn_trace_options() request.
 
bool idaapi is_func_trace_enabled (void)
 Get current state of functions tracing. More...
 
int idaapi get_func_trace_options (void)
 Get current function tracing options. More...
 
void idaapi set_func_trace_options (int options)
 Modify function tracing options. More...
 
void idaapi request_set_func_trace_options (int options)
 Post a set_func_trace_options() request.
 
int idaapi get_bblk_trace_options (void)
 Get current basic block tracing options. More...
 
void idaapi set_bblk_trace_options (int options)
 Modify basic block tracing options (see BT_LOG_INSTS)
 
void idaapi request_set_bblk_trace_options (int options)
 Post a set_bblk_trace_options() request.
 
int idaapi get_tev_qty (void)
 Get number of trace events available in trace buffer. More...
 
bool idaapi get_tev_info (int n, tev_info_t *tev_info)
 Get main information about a trace event. More...
 
bool idaapi get_insn_tev_reg_val (int n, const char *regname, regval_t *regval)
 Read a register value from an instruction trace event. More...
 
bool idaapi get_insn_tev_reg_mem (int n, memreg_infos_t *memmap)
 Read the memory pointed by register values from an instruction trace event. More...
 
bool get_insn_tev_reg_val (int n, const char *regname, uint64 *ival)
 
bool idaapi get_insn_tev_reg_result (int n, const char *regname, regval_t *regval)
 Read the resulting register value from an instruction trace event. More...
 
bool get_insn_tev_reg_result (int n, const char *regname, uint64 *ival)
 
ea_t idaapi get_call_tev_callee (int n)
 Get the called function from a function call trace event. More...
 
ea_t idaapi get_ret_tev_return (int n)
 Get the return address from a function return trace event. More...
 
ea_t idaapi get_bpt_tev_ea (int n)
 Get the address associated to a read, read/write or execution trace event. More...
 
bool idaapi get_tev_memory_info (int n, meminfo_vec_t *mi)
 Get the memory layout, if any, for the specified tev object. More...
 
bool idaapi get_tev_event (int n, debug_event_t *d)
 Get the corresponding debug event, if any, for the specified tev object. More...
 
ea_t idaapi get_trace_base_address (void)
 Get the base address of the current trace. More...
 
void idaapi set_trace_base_address (ea_t ea)
 Set the base address of the current trace. More...
 
void idaapi dbg_add_thread (thid_t tid)
 Add a thread to the current trace. More...
 
void idaapi dbg_del_thread (thid_t tid)
 Delete a thread from the current trace. More...
 
void idaapi dbg_add_tev (tev_type_t type, thid_t tid, ea_t address)
 Add a new trace element to the current trace. More...
 
bool idaapi dbg_add_many_tevs (tevinforeg_vec_t *new_tevs)
 Add many new trace elements to the current trace. More...
 
bool idaapi dbg_add_insn_tev (thid_t tid, ea_t ea, save_reg_values_t save=SAVE_DIFF)
 Add a new instruction trace element to the current trace. More...
 
bool idaapi dbg_add_bpt_tev (thid_t tid, ea_t ea, ea_t bp)
 Add a new breakpoint trace element to the current trace. More...
 
void idaapi dbg_add_call_tev (thid_t tid, ea_t caller, ea_t callee)
 Add a new call trace element to the current trace. More...
 
void idaapi dbg_add_ret_tev (thid_t tid, ea_t ret_insn, ea_t return_to)
 Add a new return trace element to the current trace. More...
 
void idaapi dbg_add_debug_event (debug_event_t *event)
 Add a new debug event to the current trace. More...
 
bool idaapi load_trace_file (qstring *buf, const char *filename)
 Load a recorded trace file in the trace window. More...
 
bool idaapi save_trace_file (const char *filename, const char *description)
 Save the current trace in the specified file.
 
bool idaapi is_valid_trace_file (const char *filename)
 Is the specified file a valid trace file for the current database?
 
bool idaapi set_trace_file_desc (const char *filename, const char *description)
 Change the description of the specified trace file.
 
bool idaapi get_trace_file_desc (qstring *buf, const char *filename)
 Get the file header of the specified trace file.
 
bool idaapi choose_trace_file (qstring *buf)
 Show the choose trace dialog.
 
bool idaapi diff_trace_file (const char *filename)
 Show difference between the current trace and the one from 'filename'.
 
bool idaapi graph_trace (void)
 Show the trace callgraph.
 
void idaapi set_highlight_trace_options (bool highlight, bgcolor_t color, bgcolor_t diff)
 Set highlight trace parameters.
 
void idaapi set_trace_platform (const char *platform)
 Set platform name of current trace.
 
const char *idaapi get_trace_platform ()
 Get platform name of current trace.
 
dbg_event_code_t idaapi wait_for_next_event (int wfne, int timeout_in_secs)
 If the returned value > 0, then it is the event id (see event_id_t)
 
const debug_event_t *idaapi get_debug_event (void)
 Get the current debugger event.
 
uint idaapi set_debugger_options (uint options)
 Set debugger options. More...
 
void idaapi set_remote_debugger (const char *host, const char *pass, int port=-1)
 Set remote debugging options. More...
 
void idaapi get_process_options (qstring *path, qstring *args, qstring *sdir, qstring *host, qstring *pass, int *port)
 Get process options. More...
 
void idaapi set_process_options (const char *path, const char *args, const char *sdir, const char *host, const char *pass, int port)
 Set process options. More...
 
excvec_t *idaapi retrieve_exceptions (void)
 Retrieve the exception information. More...
 
bool idaapi store_exceptions (void)
 Update the exception information stored in the debugger module by invoking its dbg->set_exception_info callback.
 
const char *idaapi define_exception (uint code, const char *name, const char *desc, int flags)
 Convenience function: define new exception code. More...
 
bool have_set_options (const debugger_t *_dbg)
 Is set_dbg_options() present in debugger_t?
 
const char *idaapi set_dbg_options (debugger_t *_dbg, const char *keyword, int pri, int value_type, const void *value)
 Convenience function to set debugger specific options. More...
 
const char *idaapi set_dbg_options (const char *keyword, int pri, int value_type, const void *value)
 Set options for dbg.
 
const char *idaapi set_dbg_default_options (const char *keyword, int value_type, const void *value)
 Set dbg options with #IDPOPT_PRI_DEFAULT.
 
const char *idaapi set_int_dbg_options (const char *keyword, int32 value)
 Set an integer value option for dbg.
 
bool idaapi register_srcinfo_provider (srcinfo_provider_t *sp)
 Register a source information provider. More...
 
bool idaapi unregister_srcinfo_provider (srcinfo_provider_t *sp)
 Unregister a source information provider. More...
 
source_view_t * create_source_viewer (TWidget **out_ccv, TWidget *parent, TWidget *custview, source_file_ptr sf, strvec_t *lines, int lnnum, int colnum, int flags)
 Create a source code view.
 
idaman bool ida_export get_dbg_byte (uint32 *x, ea_t ea)
 Get one byte of the debugged process memory. More...
 
idaman bool ida_export put_dbg_byte (ea_t ea, uint32 x)
 Change one byte of the debugged process memory. More...
 
idaman void ida_export set_dbgmem_source (range_t *(idaapi *dbg_get_memory_config)(int *n), int(idaapi *memory_read)(ea_t ea, void *buffer, int size), int(idaapi *memory_write)(ea_t ea, const void *buffer, int size))
 Set the memory information source for IDA kernel. More...
 
idaman void ida_export invalidate_dbgmem_config (void)
 Invalidate the debugged process memory configuration. More...
 
idaman void ida_export invalidate_dbgmem_contents (ea_t ea, asize_t size)
 Invalidate the debugged process memory contents. More...
 
idaman bool ida_export is_debugger_on (void)
 Is the debugger currently running?
 
idaman bool ida_export is_debugger_memory (ea_t ea)
 Is the address mapped to debugger memory?
 
bool idaapi is_bblk_trace_enabled (void)
 
ea_t idaapi get_tev_ea (int n)
 
int idaapi get_tev_type (int n)
 
int idaapi get_tev_tid (int n)
 
void idaapi bring_debugger_to_front (void)
 
const char *idaapi get_debugger_event_cond (void)
 
void idaapi set_debugger_event_cond (const char *cond)
 
bool idaapi load_debugger (const char *dbgname, bool use_remote)
 
void idaapi get_manual_regions (meminfo_vec_t *ranges)
 
void idaapi set_manual_regions (const meminfo_vec_t *ranges)
 
void idaapi edit_manual_regions ()
 
void idaapi enable_manual_regions (bool enable)
 
int idaapi hide_all_bpts (void)
 
int idaapi handle_debug_event (const debug_event_t *ev, int rqflags)
 
bool idaapi add_virt_module (const module_info_t *mod)
 
bool idaapi del_virt_module (const ea_t base)
 
int idaapi internal_cleanup_appcall (thid_t tid)
 
int idaapi internal_get_sreg_base (ea_t *answer, thid_t tid, int sreg_value)
 
int idaapi internal_ioctl (int fn, const void *buf, size_t size, void **poutbuf, ssize_t *poutsize)
 
ssize_t idaapi read_dbg_memory (ea_t ea, void *buffer, size_t size)
 
ssize_t idaapi write_dbg_memory (ea_t ea, const void *buffer, size_t size)
 
int idaapi get_reg_vals (thid_t tid, int clsmask, regval_t *values)
 
int idaapi set_reg_val (thid_t tid, int regidx, const regval_t *value)
 
int idaapi get_dbg_memory_info (meminfo_vec_t *ranges)
 
void idaapi set_bpt_group (bpt_t &bpt, const char *grp_name)
 
bool idaapi set_bptloc_group (const bpt_location_t &bptloc, const char *grp_name)
 
bool idaapi get_bpt_group (qstring *grp_name, const bpt_location_t &bptloc)
 
size_t idaapi list_bptgrps (qstrvec_t *bptgrps)
 
bool idaapi rename_bptgrp (const char *old_name, const char *new_name)
 
bool idaapi del_bptgrp (const char *name)
 
ssize_t idaapi get_grp_bpts (bpt_vec_t *bpts, const char *grp_name)
 
idaman void ida_export lock_dbgmem_config (void)
 
idaman void ida_export unlock_dbgmem_config (void)
 
enable/disable breakpoints
TypeSynchronous function - available as request
Notificationnone (synchronous function)

Enable or disable an existing breakpoint. A disabled breakpoint isn't available anymore in the process.

bool idaapi enable_bpt (ea_t ea, bool enable=true)
 
bool idaapi enable_bpt (const bpt_location_t &bptloc, bool enable=true)
 
bool disable_bpt (ea_t ea)
 
bool disable_bpt (const bpt_location_t &bptloc)
 
bool idaapi request_enable_bpt (ea_t ea, bool enable=true)
 
bool idaapi request_enable_bpt (const bpt_location_t &bptloc, bool enable=true)
 
bool request_disable_bpt (ea_t ea)
 
bool request_disable_bpt (const bpt_location_t &bptloc)
 
Enable/Disable tracing

Enable or disable the step tracing

TypeSynchronous function - available as request
Notificationnone (synchronous function)
Parameters
enable
  • true : enable step tracing
  • false : disable step tracing
  • -1 : temporarily disable step tracing (trace-over breakpoints are conserved: these could re-enable step tracing later)
bool idaapi enable_step_trace (int enable=true)
 
bool disable_step_trace (void)
 
bool idaapi request_enable_step_trace (int enable=true)
 
bool request_disable_step_trace (void)
 
Enable/Disable instruction tracing
TypeSynchronous function - available as request
Notificationnone (synchronous function)
bool idaapi enable_insn_trace (bool enable=true)
 
bool disable_insn_trace (void)
 
bool idaapi request_enable_insn_trace (bool enable=true)
 
bool request_disable_insn_trace (void)
 
Enable/Disable functions tracing
TypeSynchronous function - available as request
Notificationnone (synchronous function)
bool idaapi enable_func_trace (bool enable=true)
 
bool disable_func_trace (void)
 
bool idaapi request_enable_func_trace (bool enable=true)
 
bool request_disable_func_trace (void)
 
Enable/Disable basic blocks tracing
TypeSynchronous function - available as request
Notificationnone (synchronous function)
bool idaapi enable_bblk_trace (bool enable=true)
 
bool disable_bblk_trace (void)
 
bool idaapi request_enable_bblk_trace (bool enable=true)
 
bool request_disable_bblk_trace (void)
 

Macros

#define BPTEV_ADDED   0
 Breakpoint has been added.
 
#define BPTEV_REMOVED   1
 Breakpoint has been removed.
 
#define BPTEV_CHANGED   2
 Breakpoint has been modified.
 
#define DSTATE_SUSP   -1
 process is suspended and will not continue
 
#define DSTATE_NOTASK   0
 no process is currently debugged
 
#define DSTATE_RUN   1
 process is running
 
#define DBGINV_MEMORY   0x0001
 invalidate cached memory contents
 
#define DBGINV_MEMCFG   0x0002
 invalidate cached process segmentation
 
#define DBGINV_REGS   0x0004
 invalidate cached register values
 
#define DBGINV_ALL   0x7FFF
 invalidate everything
 
#define DBGINV_REDRAW   0x8000
 refresh the screen
 
#define DBGINV_NONE   0
 invalidate nothing
 
#define BPT_BRK   0x001
 suspend execution upon hit
 
#define BPT_TRACE   0x002
 add trace information upon hit
 
#define BPT_UPDMEM   0x004
 refresh the memory layout and contents before evaluating bpt condition
 
#define BPT_ENABLED   0x008
 enabled?
 
#define BPT_LOWCND   0x010
 condition is calculated at low level (on the server side)
 
#define BPT_TRACEON   0x020
 enable tracing when the breakpoint is reached
 
#define BPT_TRACE_INSN   0x040
 instruction tracing
 
#define BPT_TRACE_FUNC   0x080
 function tracing
 
#define BPT_TRACE_BBLK   0x100
 basic block tracing
 
#define BPT_TRACE_TYPES   (BPT_TRACE_INSN|BPT_TRACE_FUNC|BPT_TRACE_BBLK)
 trace insns, functions, and basic blocks. More...
 
#define BPT_ELANG_MASK   0xF0000000u
 
#define BPT_ELANG_SHIFT   28
 index of the extlang (scripting language) of the condition
 
#define BKPT_BADBPT   0x01
 failed to write the bpt to the process memory (at least one location)
 
#define BKPT_LISTBPT   0x02
 include in bpt list (user-defined bpt)
 
#define BKPT_TRACE   0x04
 trace bpt; should not be deleted when the process gets suspended
 
#define BKPT_ACTIVE   0x08
 active?
 
#define BKPT_PARTIAL   0x10
 partially active? (some locations were not written yet)
 
#define BKPT_CNDREADY   0x20
 condition has been compiled
 
#define BKPT_FAKEPEND   0x40
 fake pending bpt: it is inactive but another More...
 
#define BKPT_PAGE   0x80
 written to the process as a page bpt. More...
 
#define BPTCK_NONE   -1
 breakpoint does not exist
 
#define BPTCK_NO   0
 breakpoint is disabled
 
#define BPTCK_YES   1
 breakpoint is enabled
 
#define BPTCK_ACT   2
 breakpoint is active (written to the process)
 
#define BVF_ABS   0x0001
 include absolute bpts
 
#define BVF_REL   0x0002
 include relative bpts
 
#define BVF_SYM   0x0004
 include symbolic bpts
 
#define BVF_SRC   0x0008
 include source bpts
 
#define BVF_ALL   0x000F
 include all bpt location types
 
#define BVF_STATE   0x0030
 bpt state mask
 
#define BVFS_ANY   0x0000
 any state
 
#define BVFS_INPROC   0x0010
 written to process memory
 
#define BVFS_PENDING   0x0020
 pending
 
#define BVFS_DISABLED   0x0030
 disabled.
 
#define ST_OVER_DEBUG_SEG   0x01
 step tracing will be disabled when IP is in a debugger segment
 
#define ST_OVER_LIB_FUNC   0x02
 step tracing will be disabled when IP is in a library function
 
#define ST_ALREADY_LOGGED   0x04
 step tracing will be disabled when IP is already logged
 
#define ST_SKIP_LOOPS   0x08
 step tracing will try to skip loops already recorded
 
#define ST_DIFFERENTIAL   0x10
 tracing: log only new instructions
 
#define ST_OPTIONS_MASK   (ST_OVER_DEBUG_SEG|ST_OVER_LIB_FUNC|ST_ALREADY_LOGGED|ST_SKIP_LOOPS|ST_DIFFERENTIAL)
 mask of available options, to ensure compatibility with newer IDA versions
 
#define ST_OPTIONS_DEFAULT   (ST_OVER_DEBUG_SEG|ST_OVER_LIB_FUNC)
 
#define IT_LOG_SAME_IP   0x01
 instruction tracing will log instructions whose IP doesn't change
 
#define FT_LOG_RET   0x01
 function tracing will log returning instructions
 
#define BT_LOG_INSTS   0x0001
 log all instructions in the current basic block
 
#define WFNE_ANY   0x0001
 return the first event (even if it doesn't suspend the process)
 
#define WFNE_SUSP   0x0002
 wait until the process gets suspended
 
#define WFNE_SILENT   0x0004
 1: be slient, 0:display modal boxes if necessary
 
#define WFNE_CONT   0x0008
 continue from the suspended state
 
#define WFNE_NOWAIT   0x0010
 do not wait for any event, immediately return DEC_TIMEOUT More...
 
#define WFNE_USEC   0x0020
 timeout is specified in microseconds More...
 
#define DOPT_SEGM_MSGS   0x00000001
 log debugger segments modifications
 
#define DOPT_START_BPT   0x00000002
 break on process start
 
#define DOPT_THREAD_MSGS   0x00000004
 log thread starts/exits
 
#define DOPT_THREAD_BPT   0x00000008
 break on thread start/exit
 
#define DOPT_BPT_MSGS   0x00000010
 log breakpoints
 
#define DOPT_LIB_MSGS   0x00000040
 log library loads/unloads
 
#define DOPT_LIB_BPT   0x00000080
 break on library load/unload
 
#define DOPT_INFO_MSGS   0x00000100
 log debugging info events
 
#define DOPT_INFO_BPT   0x00000200
 break on debugging information
 
#define DOPT_REAL_MEMORY   0x00000400
 do not hide breakpoint instructions
 
#define DOPT_REDO_STACK   0x00000800
 reconstruct the stack
 
#define DOPT_ENTRY_BPT   0x00001000
 break on program entry point
 
#define DOPT_EXCDLG   0x00006000
 exception dialogs:
 
#define EXCDLG_NEVER   0x00000000
 never display exception dialogs
 
#define EXCDLG_UNKNOWN   0x00002000
 display for unknown exceptions
 
#define EXCDLG_ALWAYS   0x00006000
 always display
 
#define DOPT_LOAD_DINFO   0x00008000
 automatically load debug files (pdb)
 
#define DOPT_END_BPT   0x00010000
 evaluate event condition on process end
 
#define DOPT_TEMP_HWBPT   0x00020000
 when possible use hardware bpts for temp bpts
 
#define ENABLE_SRCDBG
 
#define SRCDBG_PROV_VERSION   4
 
#define SPF_DECOMPILER   0x0001
 is a decompiler?
 
#define SPF_ENABLED   0x0002
 enabled by the user More...
 
#define SPF_ACTIVE   0x0004
 is willing to work with the current idb More...
 
#define SPF_VERSION_MASK   0xFF000000
 Version mask, in the flags. More...
 
#define SPCH_NONE   0x0000
 nothing has changed
 
#define SPCH_FILES   0x0001
 source files have changed
 
#define SPCH_ITEMS   0x0002
 source items have changed
 
#define SPCH_LINES   0x0004
 source line numbers have changed
 

Typedefs

typedef qvector< bpt_tbpt_vec_t
 vector of breakpoints
 
typedef qvector< movbpt_code_t > movbpt_codes_t
 
typedef qvector< movbpt_info_tmovbpt_infos_t
 
typedef qvector< debug_event_tdbgevt_vec_t
 vector of debug events
 
typedef qvector< tev_info_ttevinfo_vec_t
 vector of trace event info objects
 
typedef qvector< memreg_info_tmemreg_infos_t
 
typedef qvector< tev_reg_value_ttev_reg_values_t
 vector of trace event reg values
 
typedef qvector< tev_info_reg_ttevinforeg_vec_t
 vector of trace elements
 
typedef qrefcnt_t< source_item_tsource_item_ptr
 Maintain a reference count for source items.
 
typedef qiterator< source_item_ptr_source_item_iterator
 Iterator for source items.
 
typedef qrefcnt_t< _source_item_iteratorsource_item_iterator
 Maintain a reference count for source item iterators.
 
typedef qrefcnt_t< source_file_tsource_file_ptr
 Maintain a reference count for source file objects.
 
typedef qiterator< source_file_ptr_source_file_iterator
 Iterator for source files.
 
typedef qrefcnt_t< _source_file_iteratorsource_file_iterator
 Maintain a reference count for source file iterators.
 

Enumerations

enum  dbg_notification_t {
  dbg_null = 0, dbg_process_start, dbg_process_exit, dbg_process_attach,
  dbg_process_detach, dbg_thread_start, dbg_thread_exit, dbg_library_load,
  dbg_library_unload, dbg_information, dbg_exception, dbg_suspend_process,
  dbg_bpt, dbg_trace, dbg_request_error, dbg_step_into,
  dbg_step_over, dbg_run_to, dbg_step_until_ret, dbg_bpt_changed,
  dbg_last
}
 Debugger notification codes. More...
 
enum  bpt_loctype_t { BPLT_ABS, BPLT_REL, BPLT_SYM, BPLT_SRC }
 Breakpoint location types. More...
 
enum  movbpt_code_t { MOVBPT_OK, MOVBPT_NOT_FOUND, MOVBPT_DEST_BUSY, MOVBPT_BAD_TYPE }
 
enum  tev_type_t {
  tev_none = 0, tev_insn, tev_call, tev_ret,
  tev_bpt, tev_mem, tev_event, tev_max
}
 Trace event types. More...
 
enum  save_reg_values_t { SAVE_ALL_VALUES = 0, SAVE_DIFF, SAVE_NONE }
 Se dbg_add_insn_tev()
 
enum  dbg_event_code_t { DEC_NOTASK = -2, DEC_ERROR = -1, DEC_TIMEOUT = 0 }
 Wait for the next debugger event. More...
 
enum  src_item_kind_t {
  SRCIT_NONE, SRCIT_MODULE, SRCIT_FUNC, SRCIT_STMT,
  SRCIT_EXPR, SRCIT_STTVAR, SRCIT_LOCVAR
}
 Kinds of source items. More...
 

Variables

idaman debugger_t ida_export_datadbg
 This structure contains information about the current debugger. More...
 

Enumeration Type Documentation

Debugger notification codes.

A plugin can receive notifications of all major events in the debugger, by calling the hook_to_notification_point() function with HT_DBG as hook_type_t (see loader.hpp for details about installing and removing such callbacks).

IDA generates two major different types of debugger notifications:

  • debugger event notification: this notification monitors usual events occurring during the execution of a process. These event notifications are always generated for any process. Some of these event notifications are interpreted by IDA (high-level events), while others are directly generated by the debugger module (low-level events). Low-level events always return a debug_event_t structure as an argument.
  • debugger asynchronous function result notification: such a notification occurs only when a debugger properly terminated the execution of an asynchronous function (see Debugger functions)

How to control the process execution (after the execution of all notification handlers) from the notification handler:

  • to force the process to STOP: call suspend_process(). In this case, the current debugger command will be aborted and no new request will be started.
  • to force the process to CONTINUE: call continue_process(). In this case, no new request will be started.
  • to start new debugger command(s): call as many request_COMMAND() as needed, then call run_requests(). In this case, the current debugger command (if any) will be aborted. (see Debugger functions in this file for more details about requests)
  • else, the process execution will depend on the current debugger options or object settings. Some examples:
    • a new loaded library will stop the process depending on the associated debugger option.
    • a breakpoint will stop the process depending on its properties.

A plugin must not call asynchronous debugger functions from the notification handler! Use the REQUEST QUEUE mechanism instead (request_...()).

If the plugin wants to access the process memory from a notification point, it should call invalidate_dbgmem_config() and/or invalidate_dbgmem_contents() functions. The invalidate_dbgmem_config() is really slow, so do not call it unless the process memory config have changed after the last time the process was suspended. The invalidate_dbgmem_contents() is fast and flushes the memory cache in the ida kernel. Without it, functions like get_byte() would return stale values!

Enumerator
dbg_process_start 
Parameters
event(const debug_event_t *)
Note
This event notification is also an asynchronous function result notification for start_process() !
dbg_process_exit 
Parameters
event(const debug_event_t *)
Note
This event notification is also an asynchronous function result notification for start_process() !
dbg_process_attach 
Parameters
event(const debug_event_t *)
Note
This event notification is also an asynchronous function result notification for start_process() !
dbg_process_detach 
Parameters
event(const debug_event_t *)
Note
This event notification is also an asynchronous function result notification for start_process() !
dbg_thread_start 
Parameters
event(const debug_event_t *)
dbg_thread_exit 
Parameters
event(const debug_event_t *)
dbg_library_load 
Parameters
event(const debug_event_t *)
dbg_library_unload 
Parameters
event(const debug_event_t *)
dbg_information 
Parameters
event(const debug_event_t *)
dbg_exception 
Parameters
event(const debug_event_t *)
[out]warn(int *) filled with:
  • -1: display an exception warning dialog if the process is suspended.
  • 0: never display an exception warning dialog.
  • 1: always display an exception warning dialog.
dbg_suspend_process 

The process is now suspended.

Parameters
event(const debug_event_t *)
Note
This event notification is also an asynchronous function result notification for suspend_process() !
dbg_bpt 

A user defined breakpoint was reached.

Parameters
tid(thid_t)
bptea(ea_t)
[out]warn(int *) filled with:
  • -1: display an exception warning dialog if the process is suspended.
  • 0: never display an exception warning dialog.
  • 1: always display an exception warning dialog.
dbg_trace 

A step occurred (one instruction was executed).

This event notification is only generated if step tracing is enabled.

Parameters
tid(thid_t)
ip(ea_t)
Return values
1do not log this trace event
0log it
dbg_request_error 

An error occurred during the processing of a request.

Parameters
failed_command(ui_notification_t)
failed_dbg_notification(dbg_notification_t)
dbg_step_into 
Parameters
event(const debug_event_t *)
dbg_step_over 
Parameters
event(const debug_event_t *)
dbg_run_to 
Parameters
event(const debug_event_t *)
dbg_step_until_ret 
Parameters
event(const debug_event_t *)
dbg_bpt_changed 

Breakpoint has been changed.

Parameters
bptev_code(int) Breakpoint modification events
bpt(bpt_t *)
dbg_last 

The last debugger notification code.

Variable Documentation

This structure contains information about the current debugger.

(NULL if no debugger was loaded) - see idd.hpp for details about this structure.

All functions defined in this structure should only be called by the kernel !!!