dr_inject.h File Reference

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

Macros
#define	ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE   720L
#define	WARN_IMAGE_MACHINE_TYPE_MISMATCH_EXE   ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE

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

Detailed Description

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

Macro Definition Documentation

ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE

#define ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE   720L

Special error code that is returned by dr_inject_prepare_to_exec or dr_inject_process_create when the target application image does not match the bitwidth of the injection front-end. The target process is still created: it is up to the caller to decide whether to abort (and if so, it should call dr_inject_process_exit()), although on Windows this is generally a fatal error with the current implementation. We use ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE in both Windows and Unix assuming no error code conflict on Unix.

WARN_IMAGE_MACHINE_TYPE_MISMATCH_EXE

#define WARN_IMAGE_MACHINE_TYPE_MISMATCH_EXE   ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE

Alias of ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE to indicate it is not a fatal error on Unix.

Function Documentation

dr_inject_get_image_name()

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

dr_inject_get_process_handle()

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

Note

Windows only.

Returns

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

dr_inject_get_process_id()

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

dr_inject_prepare_new_process_group()

bool dr_inject_prepare_new_process_group

(

void *

data

)

Put the child in a new process group. If termination is requested with dr_inject_process_exit(), the entire child process group is killed. Using this option creates a new process group, so if the process group of the injector is killed, the child will survive, which may not be desirable. This routine only operates on child process, and will fail if dr_inject_prepare_to_exec() has been called instead of dr_inject_process_create().

Note

Only available on Linux.

Parameters

[in]

data

The pointer returned by dr_inject_process_create()

dr_inject_prepare_to_exec()

DR_EXPORT int dr_inject_prepare_to_exec	(	const char *	app_name,
		const char **	app_cmdline,
		void **	data
	)

Prepare to exec() the provided command from the current process. Use dr_inject_process_inject() to perform the exec() under DR.

Note

Only available on Linux.

Parameters

[in]	app_name	The path to the target executable. The caller must ensure this data is valid until the inject data is disposed.
[in]	app_cmdline	A NULL-terminated array of strings representing the app's command line. This should match what the app will receive as argv in main(). The caller must ensure this data is valid until the inject data is disposed.
[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 system error code. For a mismatched bitwidth, the code is ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE. On returning ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE on Unix, data will be initialized: i.e., it is merely a warning, and the caller may continue with cross arch injection. Regardless of success, caller must call dr_inject_process_exit() when finished to clean up internally-allocated resources.

dr_inject_prepare_to_ptrace()

DR_EXPORT bool dr_inject_prepare_to_ptrace

(

void *

data

)

Use the ptrace system call to inject into the targetted process. Must be called before dr_inject_process_inject(). Does not work with dr_inject_prepare_to_exec().

Newer Linux distributions restrict which processes can be ptraced. If DR fails to attach, make sure that gdb can attach to the process in question.

Once in the injectee, DynamoRIO searches the $HOME directory of the user of the injector, not the user of the injectee. Normal usage of drconfig and drinjectlib will ensure that DynamoRIO finds the right config files, however users that wish to examine config files need to check the home directory of the injector's user.

Warning

ptrace injection is still experimental and subject to change.

Parameters

[in]

data

The pointer returned by dr_inject_process_create()

Returns

Whether successful.

dr_inject_print_stats()

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

dr_inject_process_create()

DR_EXPORT 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. The caller must ensure this data is valid until the inject data is disposed.
[in]	app_cmdline	A NULL-terminated array of strings representing the app's command line. This should match what the app will receive as argv in main(). The caller must ensure this data is valid until the inject data is disposed.
[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 system error code. For a mismatched bitwidth, the code is ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE. On returning ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE on Unix, data will be initialized and child process created: i.e., it is merely a warning, and the caller may continue with cross arch injection. Regardless of success, caller must call dr_inject_process_exit() when finished to clean up internally-allocated resources.

dr_inject_process_exit()

DR_EXPORT int dr_inject_process_exit	(	void *	data,
		bool	terminate
	)

Frees resources used by dr_inject_process_create(). Does not wait for the child to exit, unless terminate is true.

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.

dr_inject_process_inject()

DR_EXPORT 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(), or the current process if using dr_inject_prepare_to_exec() on Linux.

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.

dr_inject_process_run()

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

dr_inject_wait_for_child()

DR_EXPORT bool dr_inject_wait_for_child	(	void *	data,
		uint64	timeout_millis
	)

Waits for the child process to exit with the given timeout.

Parameters

[in]	data	The pointer returned by dr_inject_process_create()
[in]	timeout_millis	The timeout in milliseconds. Zero means wait forever.

Returns

Return true if the child exited, and false if we timed out.

Note

On Linux, this sets a signal handler for SIGALRM.