DynamoRIO API
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

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

#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_EXPORT char* dr_inject_get_image_name ( void *  data)

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

Parameters
[in]dataThe 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_EXPORT HANDLE dr_inject_get_process_handle ( void *  data)

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

Parameters
[in]dataThe 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_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]dataThe pointer returned by dr_inject_process_create()
Returns
Returns the pid of the process.
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]dataThe pointer returned by dr_inject_process_create()
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_nameThe path to the target executable. The caller must ensure this data is valid until the inject data is disposed.
[in]app_cmdlineA 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]dataAn 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_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]dataThe pointer returned by dr_inject_process_create()
Returns
Whether successful.
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]dataThe pointer returned by dr_inject_process_create()
[in]elapsed_secsElapsed time recorded by the caller that will be printed by this routine if showstats is true.
[in]showstatsIf true, elapsed_secs and resource usage is printed.
[in]showmemIf true, memory usage statistics are printed.
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_nameThe path to the target executable. The caller must ensure this data is valid until the inject data is disposed.
[in]app_cmdlineA 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]dataAn 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_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]dataThe pointer returned by dr_inject_process_create()
[in]terminateIf 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_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]dataThe pointer returned by dr_inject_process_create()
[in]force_injectionRequests injection even if the process is configured to not be run under DynamoRIO.
[in]library_pathThe 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_EXPORT bool dr_inject_process_run ( void *  data)

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

Parameters
[in]dataThe pointer returned by dr_inject_process_create()
Returns
Whether successful.
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]dataThe pointer returned by dr_inject_process_create()
[in]timeout_millisThe 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.