IDA SDK
Modules | Functions
Process commands

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...
 
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...
 

Function Documentation

int idaapi get_process_state ( void  )
inline

Return the state of the currently debugged process.

TypeSynchronous function
Notificationnone (synchronous function)
Returns
one of Debugged process states
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.

TypeSynchronous function
Notificationnone (synchronous function)
Parameters
newstatenew process state (one of Debugged process states) if DSTATE_NOTASK is passed then the state is not changed
p_thidptr to new thread id. may be NULL or pointer to NO_THREAD. the pointed variable will contain the old thread id upon return
dbginvDebugged process invalidation options
Returns
old debugger state (one of Debugged process states)
int idaapi invalidate_dbg_state ( int  dbginv)
inline

Invalidate cached debugger information.

TypeSynchronous function
Notificationnone (synchronous function)
Parameters
dbginvDebugged process invalidation options
Returns
current debugger state (one of Debugged process states)
int idaapi start_process ( const char *  path = NULL,
const char *  args = NULL,
const char *  sdir = NULL 
)
inline

Start a process in the debugger.

TypeAsynchronous function - available as Request
Notificationdbg_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 NULL value indicates the debugger will take the value from the defined Process Options.
Parameters
pathpath to the executable to start
argsarguments to pass to process
sdirstarting directory for the process
Return values
-1impossible to create the process
0the starting of the process was cancelled by the user
1the process was properly started
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
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.
bool idaapi continue_process ( void  )
inline

Continue the execution of the process in the debugger.

TypeSynchronous function - available as Request
Notificationnone (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.
bool idaapi request_continue_process ( void  )
inline

Post a continue_process() request.

Note
This requires an explicit call to run_requests()
bool idaapi exit_process ( void  )
inline

Terminate the debugging of the current process.

TypeAsynchronous function - available as Request
Notificationdbg_process_exit
ssize_t idaapi get_processes ( procinfo_vec_t proclist)
inline

Take a snapshot of running processes and return their description.

TypeSynchronous function
Notificationnone (synchronous function)
Parameters
[out]arraywith information about each running process
Returns
number of processes or -1 on error
int idaapi attach_process ( pid_t  pid = NO_PROCESS,
int  event_id = -1 
)
inline

Attach the debugger to a running process.

TypeAsynchronous function - available as Request
Notificationdbg_process_attach
Note
This function shouldn't be called as a request if NO_PROCESS is used.
Parameters
pidPID of the process to attach to. If NO_PROCESS, a dialog box will interactively ask the user for the process to attach to.
Return values
-2impossible to find a compatible process
-1impossible to attach to the given process (process died, privilege needed, not supported by the debugger plugin, ...)
0the user cancelled the attaching to the process
1the debugger properly attached to the process
bool idaapi detach_process ( void  )
inline

Detach the debugger from the debugged process.

TypeAsynchronous function - available as Request
Notificationdbg_process_detach
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