Process commands

Use these functions to manipulate the debugged process. More...

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

Detailed Description

Use these functions to manipulate the debugged process.

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()

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