dr_inject.h File Reference

Injection API for Windows. Use these functions to launch processes under the control of under DynamoRIO. More...

Functions
int	dr_inject_process_create (const char *app_name, const char *app_cmdline, void **data)
bool	dr_inject_process_inject (void *data, bool force_injection, const char *library_path)
bool	dr_inject_process_run (void *data)
int	dr_inject_process_exit (void *data, bool terminate)
char *	dr_inject_get_image_name (void *data)
HANDLE	dr_inject_get_process_handle (void *data)
process_id_t	dr_inject_get_process_id (void *data)
void	dr_inject_print_stats (void *data, int elapsed_secs, bool showstats, bool showmem)

---

Detailed Description

Injection API for Windows. Use these functions to launch processes under the control of under DynamoRIO.

---

Function Documentation

char* dr_inject_get_image_name

(

void *

data

)

Returns the process name of a process created by dr_inject_process_create().

Parameters:

[in]

data

The pointer returned by dr_inject_process_create()

Returns:

Returns the process name of the process. This is the file name without the path, suitable for passing to dr_register_process().

HANDLE dr_inject_get_process_handle

(

void *

data

)

Returns a handle to a process created by dr_inject_process_create().

Parameters:

[in]

data

The pointer returned by dr_inject_process_create()

Returns:

Returns the handle used by drinjectlib. Do not close the handle: it will be closed in dr_inject_process_exit().

process_id_t dr_inject_get_process_id

(

void *

data

)

Returns the pid of a process created by dr_inject_process_create().

Parameters:

[in]

data

The pointer returned by dr_inject_process_create()

Returns:

Returns the pid of the process.

void dr_inject_print_stats	(	void *	data,
		int	elapsed_secs,
		bool	showstats,
		bool	showmem
	)

Prints statistics for a process created by dr_inject_process_create().

Parameters:

[in]	data	The pointer returned by dr_inject_process_create()
[in]	elapsed_secs	Elapsed time recorded by the caller that will be printed by this routine if showstats is true.
[in]	showstats	If true, elapsed_secs and resource usage is printed.
[in]	showmem	If true, memory usage statistics are printed.

int dr_inject_process_create	(	const char *	app_name,
		const char *	app_cmdline,
		void **	data
	)

Creates a new process for the executable and command line specified. The initial thread in the process is suspended. Use dr_inject_process_inject() to inject DynamoRIO into the process (first calling dr_register_process() to configure the process, for one-time targeted configuration), dr_inject_process_run() to resume the thread, and dr_inject_process_exit() to finish and free resources.

Parameters:

[in]	app_name	The path to the target executable.
[in]	app_cmdline	The target executable and its arguments.
[out]	data	An opaque pointer that should be passed to subsequent dr_inject_* routines to refer to this process.

Returns:

Returns 0 on success. On failure, returns a Windows API error code. Regardless of success, caller must call dr_inject_process_exit() when finished to clean up internally-allocated resources.

int dr_inject_process_exit	(	void *	data,
		bool	terminate
	)

Frees resources used by dr_inject_process_create().

Parameters:

[in]	data	The pointer returned by dr_inject_process_create()
[in]	terminate	If true, the process is forcibly terminated.

Returns:

Returns the exit code of the process. If the caller did not wait for the process to finish before calling this, the code will be STILL_ACTIVE.

bool dr_inject_process_inject	(	void *	data,
		bool	force_injection,
		const char *	library_path
	)

Injects DynamoRIO into a process created by dr_inject_process_create().

Parameters:

[in]	data	The pointer returned by dr_inject_process_create()
[in]	force_injection	Requests injection even if the process is configured to not be run under DynamoRIO.
[in]	library_path	The path to the DynamoRIO library to use. If NULL, the library that the target process is configured for will be used.

Returns:

Whether successful.

bool dr_inject_process_run

(

void *

data

)

Resumes the suspended thread in a process created by dr_inject_process_create().

Parameters:

[in]

data

The pointer returned by dr_inject_process_create()

Returns:

Whether successful.