IDA SDK

- Main Page
- Header Files
- Classes
- Modules

- Class List
- Class Index
- Class Hierarchy
- Class Members

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 uchar * | bpt_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(idaapi * | init_debugger )(const char *hostname, int portnum, const char *password)
| Initialize debugger. More...
bool(idaapi * | term_debugger )(void)
| Terminate debugger. More...
int(idaapi * | process_get_info )(int n, process_info_t *info)
| Return information about the n-th "compatible" running process. More...
int(idaapi * | 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. More...
int(idaapi * | attach_process )(pid_t pid, int event_id, int dbg_proc_flags)
| Attach to an existing running process. More...
int(idaapi * | detach_process )(void)
| Detach from the debugged process. More...
void(idaapi * | rebase_if_required_to )(ea_t new_base)
| Rebase database if the debugged program has been rebased by the system. More...
int(idaapi * | prepare_to_pause_process )(void)
| Prepare to pause the process. More...
int(idaapi * | exit_process )(void)
| Stop the process. More...
gdecode_t(idaapi * | get_debug_event )(debug_event_t *event, int timeout_ms)
| Get a pending debug event and suspend the process. More...
int(idaapi * | continue_after_event )(const debug_event_t *event)
| Continue after handling the event. More...
void(idaapi * | set_exception_info )(const exception_info_t *info, int qty)
| Set exception handling. More...
void(idaapi * | 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. More...
int(idaapi * | read_registers )(thid_t tid, int clsmask, regval_t *values)
| Read thread registers. More...
int(idaapi * | write_register )(thid_t tid, int regidx, const regval_t *value)
| Write one thread register. More...
int(idaapi * | thread_get_sreg_base )(thid_t tid, int sreg_value, ea_t *answer)
| Get information about the base of a segment register. More...
int(idaapi * | is_ok_bpt )(bpttype_t type, ea_t ea, int len)
| Is it possible to set breakpoint?. More...
int(idaapi * | update_bpts )(update_bpt_info_t *bpts, int nadd, int ndel)
| Add/del breakpoints. More...
int(idaapi * | update_lowcnds )(const lowcnd_t *lowcnds, int nlowcnds)
| Update low-level (server side) breakpoint conditions. More...
ea_t(idaapi * | map_address )(ea_t off, const regval_t *regs, int regnum)
| Map process address. More...
const char *(idaapi * | 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). More...
const void *(idaapi * | get_debmod_extensions )(void)
| Get pointer to debugger specific functions. More...
bool(idaapi * | update_call_stack )(thid_t tid, call_stack_t *trace)
| Calculate the call stack trace. More...
ea_t(idaapi * | 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. More...
int(idaapi * | cleanup_appcall )(thid_t tid)
| Cleanup after appcall(). More...
int(idaapi * | eval_lowcnd )(thid_t tid, ea_t ea)
| Evaluate a low level breakpoint condition at 'ea'. More...
ssize_t(idaapi * | write_file )(int fn, uint32 off, const void *buf, size_t size)
| This function is called from main thread.
int(idaapi * | send_ioctl )(int fn, const void *buf, size_t size, void **poutbuf, ssize_t *poutsize)
| Perform a debugger-specific function. More...
bool(idaapi * | dbg_enable_trace )(thid_t tid, bool enable, int trace_flags)
| Enable/Disable tracing. More...
bool(idaapi * | is_tracing_enabled )(thid_t tid, int tracebit)
| Is tracing enabled? ONLY used for tracers. More...
int(idaapi * | rexec )(const char *cmdline)
| Execute a command on the remote computer. More...
void(idaapi * | get_debapp_attrs )(debapp_attrs_t *out_pattrs)
| Get (store to out_pattrs) process/debugger-specific runtime attributes. More...
Memory manipulation
The following functions manipulate bytes in the memory.
int(idaapi * | get_memory_info )(meminfo_vec_t &areas)
| Get information on the memory areas. More...
ssize_t(idaapi * | read_memory )(ea_t ea, void *buffer, size_t size)
| Read process memory. More...
ssize_t(idaapi * | write_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(idaapi * | open_file )(const char *file, uint32 *fsize, bool readonly)
void(idaapi * | close_file )(int fn)
ssize_t(idaapi * | read_file )(int fn, uint32 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_t & | registers (int idx)

## Threads
  The following functions manipulate threads. These functions are called from debthread. Return values
  1 | ok
  0 | failed
  -1 | network error
int(idaapi * | thread_continue )(thid_t tid)
| Resume a suspended thread.
int(idaapi * | set_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::process_get_info) (int n, process_info_t *info)

Return information about the n-th "compatible" running process.

If n is 0, the processes list is reinitialized. This function is called from the main thread.

Return values

  1 | ok
  0 | failed
  -1 | network 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

  path | path to executable
  args | arguments to pass to executable
  startdir | current directory of new process
  dbg_proc_flags | Debug process flags
  input_path | path 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_crc32 | CRC value for 'input_path'

Return values

  1 | ok
  0 | failed
  -2 | file not found (ask for process options)
  1 | | CRC32_MISMATCH ok, but the input file crc does not match
  -1 | network 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

  pid | process id to attach
  event_id | event to trigger upon attaching
  dbg_proc_flags | Debug process flags

Return values

  1 | ok
  0 | failed
  -1 | network 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

  1 | ok
  0 | failed
  -1 | network 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

  1 | ok
  0 | failed
  -1 | network 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

  1 | ok
  0 | failed
  -1 | network 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

  1 | ok
  0 | failed
  -1 | network 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

  tid | thread id
  clsmask | bitmask of register classes to read
  regval | pointer to vector of regvals for all registers. regval is assumed to have debugger_t::registers_size elements

Return values

  1 | ok
  0 | failed
  -1 | network 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

  tid | thread id
  regidx | register index
  regval | new value of the register

Return values

  1 | ok
  0 | failed
  -1 | network error

int(idaapi * debugger_t::thread_get_sreg_base) (thid_t tid, int sreg_value, ea_t *answer)

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

  tid | thread id
  sreg_value | value of the segment register (returned by get_reg_val())
  answer | pointer to the answer. can't be NULL.

Return values

  1 | ok
  0 | failed
  -1 | network error

int(idaapi * debugger_t::get_memory_info) (meminfo_vec_t &areas)

Get information on the memory areas.

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

Return values

  -3 | use idb segmentation
  -2 | no changes
  -1 | the process does not exist anymore
  0 | failed
  1 | new 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

  0 | read error
  -1 | process 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

  off | offset to map
  regs | current register values. if regs == NULL, then perform global mapping, which is independent on used registers usually such a mapping is a trivial identity mapping
  regnum | required 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_ea | address to call
  | tid | thread to use
  | fti | type information for the called function
  | nargs | number of actual arguments
  | regargs | information about register arguments
  | stkargs | memory blob to pass as stack arguments (usually contains pointed data) it must be relocated by the callback but not changed otherwise
  | retregs | function return registers.
  [out] | errbuf | the error message. if empty on failure, see 'event'. should not be filled if an appcall exception happened but APPCALL_DEBEV is set
  [out] | event | the last debug event that occurred during appcall execution filled only if the appcall execution fails and APPCALL_DEBEV is set
  | options | appcall 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

  2 | ok, there are pending events
  1 | ok
  0 | failed
  -1 | network 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

  1 | condition is satisfied
  0 | not satisfied
  -1 | network 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.

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

- idd.hpp