DynamoRIO API
dr_app.h File Reference

DR's application interface for running portions of a program under its control. More...

Functions

DR_APP_API int dr_app_setup (void)
 
DR_APP_API int dr_app_cleanup (void)
 
DR_APP_API void dr_app_start (void)
 
DR_APP_API void dr_app_stop (void)
 
DR_APP_API void dr_app_take_over (void)
 
DR_APP_API int dr_app_setup_and_start (void)
 
DR_APP_API void dr_app_stop_and_cleanup (void)
 
DR_APP_API bool dr_app_running_under_dynamorio (void)
 
DR_APP_API void * dr_app_handle_mbr_target (void *target)
 

Detailed Description

DR's application interface for running portions of a program under its control.

Function Documentation

DR_APP_API int dr_app_cleanup ( void  )

Application-wide cleanup. Prints statistics. Returns zero on success. Once this is invoked, calling dr_app_start() or dr_app_setup() is not supported. This should be invoked at application exit, after joining with application threads. If the application wants to continue executing significant code or executing additional threads after cleanup, it should use dr_app_stop_and_cleanup() instead.

DR_APP_API void* dr_app_handle_mbr_target ( void *  target)

DynamoRIO's (experimental) native execution mode supports running some modules natively while the others run under DynamoRIO. When a module is running natively, it may jump to a module that should be executed under DynamoRIO directly without going through DynamoRIO. To handle this situation, the application code should call this routine and use the returned stub pc as the branch target instead.

Note
Linux only.
Native execution mode only.
Experimental support.
DR_APP_API bool dr_app_running_under_dynamorio ( void  )

Indicates whether the current thread is running within the DynamoRIO code cache. Returns true only if the current thread is running within the DynamoRIO code cache and returns false othrewise.

Note
This routines returns false if the current thread is running within the DynamoRIO probe mode.
DR_APP_API int dr_app_setup ( void  )

Application-wide initialization. Must be called before any other API function. Returns zero on success.

DR_APP_API int dr_app_setup_and_start ( void  )

Calls dr_app_setup() and, if it succeeds, calls dr_app_start(). Returns the result of dr_app_setup(), which returns zero on success. This routine is intended as a convenient single point of entry for callers who are using dlsym() or GetProcAddress() to access the app API.

DR_APP_API void dr_app_start ( void  )

Causes the application to run under DR control upon return from this call. Attempts to take over any existing threads in the application.

Warning
On Linux, DR detects threads by listing thread ids in the current process's thread group. This, and other queries about the current process may fail if the main thread has quit. DR also assumes the threads all share signal handlers, as is the case for pthreads. Violating these assumptions will lead to unpredictable behavior.
DR_APP_API void dr_app_stop ( void  )

Causes all of the application's threads to run directly on the machine upon return from this call; no effect if the application is not currently running under DR control.

DR_APP_API void dr_app_stop_and_cleanup ( void  )

Causes all of the application's threads to run directly on the machine upon return from this call, and additionally frees the resources used by DR. Once this is invoked, calling dr_app_start() or dr_app_setup() is not supported. This call has no effect if the application is not currently running under DR control.

DR_APP_API void dr_app_take_over ( void  )

Causes application to run under DR control upon return from this call. DR never releases control. Useful for overriding dr_app_start/dr_app_stop calls in the rest of a program.