IDA SDK
Public Attributes | Public Member Functions | List of all members
debugger_t Struct Reference

Detailed Description

This structure describes a debugger API module.

(functions needed to debug a process on a specific operating system).

The address of this structure must be put into the dbg variable by the plugin_t::init() function of the debugger plugin.

Public Attributes

int version
 Expected kernel version, should be IDD_INTERFACE_VERSION.
 
const char * name
 Short debugger name like win32 or linux.
 
int id
 one of Debugger API module id
 
const char * processor
 Required processor name. More...
 
uint32 flags
 Debugger module features
 
const char ** register_classes
 Array of register class names.
 
int register_classes_default
 Mask of default printed register classes.
 
register_info_t_registers
 Array of registers. Use registers() to access it.
 
int registers_size
 Number of registers.
 
int memory_page_size
 Size of a memory page.
 
const ucharbpt_bytes
 Array of bytes for a breakpoint instruction.
 
uchar bpt_size
 Size of this array.
 
uchar filetype
 for miniidbs: use this value for the file type after attaching to a new process
 
ushort resume_modes
 Resume modes
 
bool(idaapiinit_debugger )(const char *hostname, int portnum, const char *password)
 Initialize debugger. More...
 
bool(idaapiterm_debugger )(void)
 Terminate debugger. More...
 
int(idaapiget_processes )(procinfo_vec_t *procs)
 Return information about the running processes. More...
 
int(idaapistart_process )(const char *path, const char *args, const char *startdir, int dbg_proc_flags, const char *input_path, uint32 input_file_crc32)
 Start an executable to debug. More...
 
int(idaapiattach_process )(pid_t pid, int event_id, int dbg_proc_flags)
 Attach to an existing running process. More...
 
int(idaapidetach_process )(void)
 Detach from the debugged process. More...
 
void(idaapirebase_if_required_to )(ea_t new_base)
 Rebase database if the debugged program has been rebased by the system. More...
 
int(idaapiprepare_to_pause_process )(void)
 Prepare to pause the process. More...
 
int(idaapiexit_process )(void)
 Stop the process. More...
 
gdecode_t(idaapiget_debug_event )(debug_event_t *event, int timeout_ms)
 Get a pending debug event and suspend the process. More...
 
int(idaapicontinue_after_event )(const debug_event_t *event)
 Continue after handling the event. More...
 
void(idaapiset_exception_info )(const exception_info_t *info, int qty)
 Set exception handling. More...
 
void(idaapistopped_at_debug_event )(bool dlls_added)
 This function will be called by the kernel each time it has stopped the debugger process and refreshed the database. More...
 
int(idaapiread_registers )(thid_t tid, int clsmask, regval_t *values)
 Read thread registers. More...
 
int(idaapiwrite_register )(thid_t tid, int regidx, const regval_t *value)
 Write one thread register. More...
 
int(idaapithread_get_sreg_base )(ea_t *answer, thid_t tid, int sreg_value)
 Get information about the base of a segment register. More...
 
int(idaapiis_ok_bpt )(bpttype_t type, ea_t ea, int len)
 Is it possible to set breakpoint?. More...
 
int(idaapiupdate_bpts )(update_bpt_info_t *bpts, int nadd, int ndel)
 Add/del breakpoints. More...
 
int(idaapiupdate_lowcnds )(const lowcnd_t *lowcnds, int nlowcnds)
 Update low-level (server side) breakpoint conditions. More...
 
ea_t(idaapimap_address )(ea_t off, const regval_t *regs, int regnum)
 Map process address. More...
 
const char *(idaapiset_dbg_options )(const char *keyword, int pri, int value_type, const void *value)
 Set debugger options (parameters that are specific to the debugger module). More...
 
const void *(idaapiget_debmod_extensions )(void)
 Get pointer to debugger specific functions. More...
 
bool(idaapiupdate_call_stack )(thid_t tid, call_stack_t *trace)
 Calculate the call stack trace. More...
 
ea_t(idaapiappcall )(ea_t func_ea, thid_t tid, const struct func_type_data_t *fti, int nargs, const struct regobjs_t *regargs, struct relobj_t *stkargs, struct regobjs_t *retregs, qstring *errbuf, debug_event_t *event, int options)
 Call application function. More...
 
int(idaapicleanup_appcall )(thid_t tid)
 Cleanup after appcall(). More...
 
int(idaapieval_lowcnd )(thid_t tid, ea_t ea)
 Evaluate a low level breakpoint condition at 'ea'. More...
 
ssize_t(idaapiwrite_file )(int fn, qoff64_t off, const void *buf, size_t size)
 This function is called from main thread.
 
int(idaapisend_ioctl )(int fn, const void *buf, size_t size, void **poutbuf, ssize_t *poutsize)
 Perform a debugger-specific function. More...
 
bool(idaapidbg_enable_trace )(thid_t tid, bool enable, int trace_flags)
 Enable/Disable tracing. More...
 
bool(idaapiis_tracing_enabled )(thid_t tid, int tracebit)
 Is tracing enabled? ONLY used for tracers. More...
 
int(idaapirexec )(const char *cmdline)
 Execute a command on the remote computer. More...
 
void(idaapiget_debapp_attrs )(debapp_attrs_t *out_pattrs)
 Get (store to out_pattrs) process/debugger-specific runtime attributes. More...
 
bool(idaapiget_srcinfo_path )(qstring *path, ea_t base)
 Get the path to a file containing source debug info for the given module. More...
 
Memory manipulation

The following functions manipulate bytes in the memory.

int(idaapiget_memory_info )(meminfo_vec_t &ranges)
 Get information on the memory ranges. More...
 
ssize_t(idaapiread_memory )(ea_t ea, void *buffer, size_t size)
 Read process memory. More...
 
ssize_t(idaapiwrite_memory )(ea_t ea, const void *buffer, size_t size)
 Write process memory. More...
 
Remote file

Open/close/read a remote file.

These functions are called from the main thread

int(idaapiopen_file )(const char *file, uint64 *fsize, bool readonly)
 
void(idaapiclose_file )(int fn)
 
ssize_t(idaapiread_file )(int fn, qoff64_t off, void *buf, size_t size)
 

Public Member Functions

bool is_remote (void) const
 
bool must_have_hostname (void) const
 
bool can_continue_from_bpt (void) const
 
bool may_disturb (void) const
 
bool is_safe (void) const
 
bool use_sregs (void) const
 
size_t cache_block_size (void) const
 
bool use_memregs (void) const
 
bool may_take_exit_snapshot (void) const
 
bool virtual_threads (void) const
 
bool supports_lowcnds (void) const
 
bool supports_debthread (void) const
 
bool can_debug_standalone_dlls (void) const
 
bool fake_memory (void) const
 
bool is_resmod_avail (int resmod) const
 
register_info_tregisters (int idx)
 

Threads

The following functions manipulate threads.

These functions are called from debthread.

Return values
1ok
0failed
-1network error
int(idaapithread_continue )(thid_t tid)
 Resume a suspended thread.
 
int(idaapiset_resume_mode )(thid_t tid, resume_mode_t resmod)
 Specify resume action.
 
 int (idaapi *thread_suspend)(thid_t tid)
 Suspend a running thread.
 

Member Data Documentation

const char* debugger_t::processor

Required processor name.

Used for instant debugging to load the correct processor module

bool(idaapi * debugger_t::init_debugger) (const char *hostname, int portnum, const char *password)

Initialize debugger.

This function is called from the main thread.

Returns
success
bool(idaapi * debugger_t::term_debugger) (void)

Terminate debugger.

This function is called from the main thread.

Returns
success
int(idaapi * debugger_t::get_processes) (procinfo_vec_t *procs)

Return information about the running processes.

This function is called from the main thread.

Return values
1ok
0failed
-1network error
int(idaapi * debugger_t::start_process) (const char *path, const char *args, const char *startdir, int dbg_proc_flags, const char *input_path, uint32 input_file_crc32)

Start an executable to debug.

This function is called from debthread.

Parameters
pathpath to executable
argsarguments to pass to executable
startdircurrent directory of new process
dbg_proc_flagsDebug process flags
input_pathpath to database input file. (not always the same as 'path' - e.g. if you're analyzing a dll and want to launch an executable that loads it)
input_file_crc32CRC value for 'input_path'
Return values
1ok
0failed
-2file not found (ask for process options)
1| CRC32_MISMATCH ok, but the input file crc does not match
-1network error
int(idaapi * debugger_t::attach_process) (pid_t pid, int event_id, int dbg_proc_flags)

Attach to an existing running process.

event_id should be equal to -1 if not attaching to a crashed process. This function is called from debthread.

Parameters
pidprocess id to attach
event_idevent to trigger upon attaching
dbg_proc_flagsDebug process flags
Return values
1ok
0failed
-1network error
int(idaapi * debugger_t::detach_process) (void)

Detach from the debugged process.

May be called while the process is running or suspended. Must detach from the process in any case. The kernel will repeatedly call get_debug_event() and until PROCESS_DETACH. In this mode, all other events will be automatically handled and process will be resumed. This function is called from debthread.

Return values
1ok
0failed
-1network error
void(idaapi * debugger_t::rebase_if_required_to) (ea_t new_base)

Rebase database if the debugged program has been rebased by the system.

This function is called from the main thread.

int(idaapi * debugger_t::prepare_to_pause_process) (void)

Prepare to pause the process.

Normally the next get_debug_event() will pause the process If the process is sleeping then the pause will not occur until the process wakes up. The interface should take care of this situation. If this function is absent, then it won't be possible to pause the program. This function is called from debthread.

Return values
1ok
0failed
-1network error
int(idaapi * debugger_t::exit_process) (void)

Stop the process.

May be called while the process is running or suspended. Must terminate the process in any case. The kernel will repeatedly call get_debug_event() and until PROCESS_EXIT. In this mode, all other events will be automatically handled and process will be resumed. This function is called from debthread.

Return values
1ok
0failed
-1network error
gdecode_t(idaapi * debugger_t::get_debug_event) (debug_event_t *event, int timeout_ms)

Get a pending debug event and suspend the process.

This function will be called regularly by IDA. This function is called from debthread. IMPORTANT: commdbg does not expect immediately after a BPT-related event any other event with the same thread/IP - this can cause erroneous restoring of a breakpoint before resume (the bug was encountered 24.02.2015 in pc_linux_upx.elf)

int(idaapi * debugger_t::continue_after_event) (const debug_event_t *event)

Continue after handling the event.

This function is called from debthread.

Return values
1ok
0failed
-1network error
void(idaapi * debugger_t::set_exception_info) (const exception_info_t *info, int qty)

Set exception handling.

This function is called from debthread or the main thread.

void(idaapi * debugger_t::stopped_at_debug_event) (bool dlls_added)

This function will be called by the kernel each time it has stopped the debugger process and refreshed the database.

The debugger module may add information to the database if it wants.

The reason for introducing this function is that when an event line LOAD_DLL happens, the database does not reflect the memory state yet and therefore we can't add information about the dll into the database in the get_debug_event() function. Only when the kernel has adjusted the database we can do it. Example: for imported PE DLLs we will add the exported function names to the database.

This function pointer may be absent, i.e. NULL. This function is called from the main thread.

int(idaapi * debugger_t::read_registers) (thid_t tid, int clsmask, regval_t *values)

Read thread registers.

This function is called from debthread.

Parameters
tidthread id
clsmaskbitmask of register classes to read
valuespointer to vector of regvals for all registers. regval is assumed to have debugger_t::registers_size elements
Return values
1ok
0failed
-1network error
int(idaapi * debugger_t::write_register) (thid_t tid, int regidx, const regval_t *value)

Write one thread register.

This function is called from debthread.

Parameters
tidthread id
regidxregister index
valuenew value of the register
Return values
1ok
0failed
-1network error
int(idaapi * debugger_t::thread_get_sreg_base) (ea_t *answer, thid_t tid, int sreg_value)

Get information about the base of a segment register.

Currently used by the IBM PC module to resolve references like fs:0. This function is called from debthread.

Parameters
answerpointer to the answer. can't be NULL.
tidthread id
sreg_valuevalue of the segment register (returned by get_reg_val())
Return values
1ok
0failed
-1network error
int(idaapi * debugger_t::get_memory_info) (meminfo_vec_t &ranges)

Get information on the memory ranges.

The debugger module fills 'ranges'. The returned vector MUST be sorted. This function is called from debthread.

Return values
-3use idb segmentation
-2no changes
-1the process does not exist anymore
0failed
1new memory layout is returned
ssize_t(idaapi * debugger_t::read_memory) (ea_t ea, void *buffer, size_t size)

Read process memory.

Returns number of read bytes. This function is called from debthread.

Return values
0read error
-1process does not exist anymore
ssize_t(idaapi * debugger_t::write_memory) (ea_t ea, const void *buffer, size_t size)

Write process memory.

This function is called from debthread.

Returns
number of written bytes, -1 if fatal error
int(idaapi * debugger_t::is_ok_bpt) (bpttype_t type, ea_t ea, int len)

Is it possible to set breakpoint?.

This function is called from debthread or from the main thread if debthread is not running yet. It is called to verify hardware breakpoints.

Returns
ref BPT_
int(idaapi * debugger_t::update_bpts) (update_bpt_info_t *bpts, int nadd, int ndel)

Add/del breakpoints.

bpts array contains nadd bpts to add, followed by ndel bpts to del. This function is called from debthread.

Returns
number of successfully modified bpts, -1 if network error
int(idaapi * debugger_t::update_lowcnds) (const lowcnd_t *lowcnds, int nlowcnds)

Update low-level (server side) breakpoint conditions.

This function is called from debthread.

Returns
nlowcnds. -1-network error
ea_t(idaapi * debugger_t::map_address) (ea_t off, const regval_t *regs, int regnum)

Map process address.

This function may be absent. This function is called from debthread.

Parameters
offoffset to map
regscurrent register values. if regs == NULL, then perform global mapping, which is independent on used registers usually such a mapping is a trivial identity mapping
regnumrequired mapping. maybe specified as a segment register number or a regular register number if the required mapping can be deduced from it. for example, esp implies that ss should be used.
Returns
mapped address or BADADDR
const char*(idaapi * debugger_t::set_dbg_options) (const char *keyword, int pri, int value_type, const void *value)

Set debugger options (parameters that are specific to the debugger module).

See the definition of ::set_options_t for arguments. See the convenience function in dbg.hpp if you need to call it. The kernel will call this function after reading the debugger specific config file (arguments are: keyword="", type=#IDPOPT_STR, value="") This function is optional. This function is called from the main thread

const void*(idaapi * debugger_t::get_debmod_extensions) (void)

Get pointer to debugger specific functions.

This function returns a pointer to a structure that holds pointers to debugger module specific functions. For information on the structure layout, please check the corresponding debugger module. Most debugger modules return NULL because they do not have any extensions. Available extensions may be called from plugins. This function is called from the main thread.

bool(idaapi * debugger_t::update_call_stack) (thid_t tid, call_stack_t *trace)

Calculate the call stack trace.

This function is called when the process is suspended and should fill the 'trace' object with the information about the current call stack. If this function is missing or returns false, IDA will use the standard mechanism (based on the frame pointer chain) to calculate the stack trace This function is called from the main thread.

Returns
success
ea_t(idaapi * debugger_t::appcall) (ea_t func_ea, thid_t tid, const struct func_type_data_t *fti, int nargs, const struct regobjs_t *regargs, struct relobj_t *stkargs, struct regobjs_t *retregs, qstring *errbuf, debug_event_t *event, int options)

Call application function.

This function calls a function from the debugged application. This function is called from debthread

Parameters
func_eaaddress to call
tidthread to use
ftitype information for the called function
nargsnumber of actual arguments
regargsinformation about register arguments
stkargsmemory blob to pass as stack arguments (usually contains pointed data) it must be relocated by the callback but not changed otherwise
retregsfunction return registers.
[out]errbufthe error message. if empty on failure, see 'event'. should not be filled if an appcall exception happened but APPCALL_DEBEV is set
[out]eventthe last debug event that occurred during appcall execution filled only if the appcall execution fails and APPCALL_DEBEV is set
optionsappcall options, usually taken from idainfo::appcall_options. possible values: combination of Appcall options or 0
Returns
ea of stkargs blob, BADADDR if failed and errbuf is filled
int(idaapi * debugger_t::cleanup_appcall) (thid_t tid)

Cleanup after appcall().

The debugger module must keep the stack blob in the memory until this function is called. It will be called by the kernel for each successful appcall(). There is an exception: if APPCALL_MANUAL, IDA may not call cleanup_appcall. If the user selects to terminate a manual appcall, then cleanup_appcall will be called. Otherwise, the debugger module should terminate the appcall when the called function returns. This function is called from debthread.

Return values
2ok, there are pending events
1ok
0failed
-1network error
int(idaapi * debugger_t::eval_lowcnd) (thid_t tid, ea_t ea)

Evaluate a low level breakpoint condition at 'ea'.

Other evaluation errors are displayed in a dialog box. This call is rarely used by IDA when the process has already been suspended for some reason and it has to decide whether the process should be resumed or definitely suspended because of a breakpoint with a low level condition. This function is called from debthread.

Return values
1condition is satisfied
0not satisfied
-1network error
int(idaapi * debugger_t::send_ioctl) (int fn, const void *buf, size_t size, void **poutbuf, ssize_t *poutsize)

Perform a debugger-specific function.

This function is called from debthread

bool(idaapi * debugger_t::dbg_enable_trace) (thid_t tid, bool enable, int trace_flags)

Enable/Disable tracing.

"trace_flags" can be a set of STEP_TRACE, INSN_TRACE, BBLK_TRACE or FUNC_TRACE. See thread_t::trace_mode in debugger.h. This function is called from the main thread.

bool(idaapi * debugger_t::is_tracing_enabled) (thid_t tid, int tracebit)

Is tracing enabled? ONLY used for tracers.

"trace_bit" can be one of the following: STEP_TRACE, INSN_TRACE, BBLK_TRACE or FUNC_TRACE

int(idaapi * debugger_t::rexec) (const char *cmdline)

Execute a command on the remote computer.

Returns
exit code
void(idaapi * debugger_t::get_debapp_attrs) (debapp_attrs_t *out_pattrs)

Get (store to out_pattrs) process/debugger-specific runtime attributes.

This function is called from main thread.

bool(idaapi * debugger_t::get_srcinfo_path) (qstring *path, ea_t base)

Get the path to a file containing source debug info for the given module.

This allows srcinfo providers to call into the debugger when looking for debug info. It is useful in certain cases like the iOS debugger, which is a remote debugger but the remote debugserver does not provide dwarf info. So, we allow the debugger client to decide where to look for debug info locally.

Parameters
pathoutput path (file might not exist)
basebase address of a module in the target process
Returns
success, result stored in 'path'

The documentation for this struct was generated from the following file: