| IDA SDK

Modules | Functions
Process commands
Debugger functions

## Detailed Description

Use these functions to manipulate the debugged process.

## Modules
| Debugged process states
| See get_process_state(), set_process_state(), invalidate_dbg_state()
| Debugged process invalidation options
| See set_process_state() and invalidate_dbg_state()

## Functions
int idaapi | get_process_state (void)
| Return the state of the currently debugged process. More...
bool idaapi | is_valid_dstate (int state)
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=nullptr, const char *args=nullptr, const char *sdir=nullptr)
| Start a process in the debugger. More...
int idaapi | request_start_process (const char *path=nullptr, const char *args=nullptr, const char *sdir=nullptr)
| 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 | continue_backwards (void)
| Continue the execution of the process in the debugger backwards. More...
bool idaapi | request_continue_backwards (void)
| Post a continue_backwards() 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...

## Function Documentation

## ◆ get_process_state()

int idaapi get_process_state | ( | void |  | ) |
| inline

Return the state of the currently debugged process.

Type | Synchronous function
Notification | none (synchronous function)

Returns
  one of Debugged process states

## ◆ set_process_state()

int idaapi set_process_state | ( | int | newstate,
|  | thid_t * | p_thid,
|  | int | dbginv
| ) |  |
| inline

Set new state for the debugged process.

Notifies the IDA kernel about the change of the debugged process state. For example, a debugger module could call this function when it knows that the process is suspended for a short period of time. Some IDA API calls can be made only when the process is suspended. The process state is usually restored before returning control to the caller. You must know that it is ok to change the process state, doing it at arbitrary moments may crash the application or IDA.

Type | Synchronous function
Notification | none (synchronous function)

Parameters

  newstate | new process state (one of Debugged process states) if DSTATE_NOTASK is passed then the state is not changed
  p_thid | ptr to new thread id. may be nullptr or pointer to NO_THREAD. the pointed variable will contain the old thread id upon return
  dbginv | Debugged process invalidation options

Returns
  old debugger state (one of Debugged process states)

## ◆ invalidate_dbg_state()

int idaapi invalidate_dbg_state | ( | int | dbginv | ) |
| inline

Invalidate cached debugger information.

Type | Synchronous function
Notification | none (synchronous function)

Parameters

  dbginv | Debugged process invalidation options

Returns
  current debugger state (one of Debugged process states)

## ◆ start_process()

int idaapi start_process | ( | const char * | path = `nullptr`,
|  | const char * | args = `nullptr`,
|  | const char * | sdir = `nullptr`
| ) |  |
| inline

Start a process in the debugger.

Type | Asynchronous function - available as Request
Notification | dbg_process_start

Note
  You can also use the run_to() function to easily start the execution of a process until a given address is reached.
  For all parameters, a nullptr value indicates the debugger will take the value from the defined Process Options.

Parameters

  path | path to the executable to start
  args | arguments to pass to process
  sdir | starting directory for the process

Return values

  -1 | impossible to create the process
  0 | the starting of the process was cancelled by the user
  1 | the process was properly started

## ◆ suspend_process()

bool idaapi suspend_process | ( | void |  | ) |
| inline

Suspend the process in the debugger.

Type | Synchronous function (if in a notification handler) Asynchronous function (everywhere else) available as Request
Notification | none (if in a notification handler) dbg_suspend_process (everywhere else)

Note
  The suspend_process() function can be called from a notification handler to force the stopping of the process. In this case, no notification will be generated. When you suspend a process, the running command is always aborted.

## ◆ continue_process()

bool idaapi continue_process | ( | void |  | ) |
| inline

Continue the execution of the process in the debugger.

Type | Synchronous function - available as Request
Notification | none (synchronous function)

Note
  The continue_process() function can be called from a notification handler to force the continuation of the process. In this case the request queue will not be examined, IDA will simply resume execution. Usually it makes sense to call request_continue_process() followed by run_requests(), so that IDA will first start a queued request (if any) and then resume the application.

## ◆ request_continue_process()

bool idaapi request_continue_process | ( | void |  | ) |
| inline

Post a continue_process() request.

Note
  This requires an explicit call to run_requests()

## ◆ continue_backwards()

bool idaapi continue_backwards | ( | void |  | ) |
| inline

Continue the execution of the process in the debugger backwards.

Can only be used with debuggers that support time-travel debugging.

Type | Synchronous function - available as Request
Notification | none (synchronous function)

Note
  The continue_backwards() function can be called from a notification handler to force the continuation of the process. In this case the request queue will not be examined, IDA will simply resume execution. Usually it makes sense to call request_continue_process() followed by run_requests(), so that IDA will first start a queued request (if any) and then resume the application.

## ◆ request_continue_backwards()

bool idaapi request_continue_backwards | ( | void |  | ) |
| inline

Post a continue_backwards() request.

Note
  This requires an explicit call to run_requests()

## ◆ exit_process()

bool idaapi exit_process | ( | void |  | ) |
| inline

Terminate the debugging of the current process.

Type | Asynchronous function - available as Request
Notification | dbg_process_exit

## ◆ get_processes()

ssize_t idaapi get_processes | ( | procinfo_vec_t * | proclist | ) |
| inline

Take a snapshot of running processes and return their description.

Type | Synchronous function
Notification | none (synchronous function)

Parameters

  [out] | proclist | array with information about each running process

Returns
  number of processes or -1 on error

## ◆ attach_process()

int idaapi attach_process | ( | pid_t | pid = `NO_PROCESS`,
|  | int | event_id = `-1`
| ) |  |
| inline

Attach the debugger to a running process.

Type | Asynchronous function - available as Request
Notification | dbg_process_attach

Note
  This function shouldn't be called as a request if NO_PROCESS is used.

Parameters

  pid | PID of the process to attach to. If NO_PROCESS, a dialog box will interactively ask the user for the process to attach to.
  event_id | event to trigger upon attaching

Return values

  -4 | debugger was not inited
  -3 | the attaching is not supported
  -2 | impossible to find a compatible process
  -1 | impossible to attach to the given process (process died, privilege needed, not supported by the debugger plugin, ...)
  0 | the user cancelled the attaching to the process
  1 | the debugger properly attached to the process

## ◆ detach_process()

bool idaapi detach_process | ( | void |  | ) |
| inline

Detach the debugger from the debugged process.

Type | Asynchronous function - available as Request
Notification | dbg_process_detach

## ◆ is_debugger_busy()

bool idaapi is_debugger_busy | ( | void |  | ) |
| inline

Is the debugger busy?.

Some debuggers do not accept any commands while the debugged application is running. For such a debugger, it is unsafe to do anything with the database (even simple queries like get_byte may lead to undesired consequences). Returns: true if the debugged application is running under such a debugger