dr_tools.h File Reference

Main API routines, including transparency support. More...

Data Structures
struct	_dr_memory_dump_spec_t
struct	_dr_syscall_result_info_t

Macros
#define	GLOBAL_DCONTEXT   ((void *)-1)
#define	DR_ASSERT_MSG(x, msg)
#define	DR_ASSERT(x)   DR_ASSERT_MSG(x, "")
#define	DR_FILE_READ   0x1
#define	DR_FILE_WRITE_REQUIRE_NEW   0x2
#define	DR_FILE_WRITE_APPEND   0x4
#define	DR_FILE_WRITE_OVERWRITE   0x8
#define	DR_FILE_ALLOW_LARGE   0x10
#define	DR_FILE_CLOSE_ON_FORK   0x20
#define	DR_FILE_WRITE_ONLY   0x40
#define	DR_SEEK_SET   0
#define	DR_SEEK_CUR   1
#define	DR_SEEK_END   2
#define	DR_LOG_NONE   0x00000000
#define	DR_LOG_STATS   0x00000001
#define	DR_LOG_TOP   0x00000002
#define	DR_LOG_THREADS   0x00000004
#define	DR_LOG_SYSCALLS   0x00000008
#define	DR_LOG_ASYNCH   0x00000010
#define	DR_LOG_INTERP   0x00000020
#define	DR_LOG_EMIT   0x00000040
#define	DR_LOG_LINKS   0x00000080
#define	DR_LOG_CACHE   0x00000100
#define	DR_LOG_FRAGMENT   0x00000200
#define	DR_LOG_DISPATCH   0x00000400
#define	DR_LOG_MONITOR   0x00000800
#define	DR_LOG_HEAP   0x00001000
#define	DR_LOG_VMAREAS   0x00002000
#define	DR_LOG_SYNCH   0x00004000
#define	DR_LOG_MEMSTATS   0x00008000
#define	DR_LOG_OPTS   0x00010000
#define	DR_LOG_SIDELINE   0x00020000
#define	DR_LOG_SYMBOLS   0x00040000
#define	DR_LOG_RCT   0x00080000
#define	DR_LOG_NT   0x00100000
#define	DR_LOG_HOT_PATCHING   0x00200000
#define	DR_LOG_HTABLE   0x00400000
#define	DR_LOG_MODULEDB   0x00800000
#define	DR_LOG_ALL   0x00ffffff
#define	LOG_NONE   DR_LOG_NONE
#define	LOG_STATS   DR_LOG_STATS
#define	LOG_TOP   DR_LOG_TOP
#define	LOG_THREADS   DR_LOG_THREADS
#define	LOG_SYSCALLS   DR_LOG_SYSCALLS
#define	LOG_ASYNCH   DR_LOG_ASYNCH
#define	LOG_INTERP   DR_LOG_INTERP
#define	LOG_EMIT   DR_LOG_EMIT
#define	LOG_LINKS   DR_LOG_LINKS
#define	LOG_CACHE   DR_LOG_CACHE
#define	LOG_FRAGMENT   DR_LOG_FRAGMENT
#define	LOG_DISPATCH   DR_LOG_DISPATCH
#define	LOG_MONITOR   DR_LOG_MONITOR
#define	LOG_HEAP   DR_LOG_HEAP
#define	LOG_VMAREAS   DR_LOG_VMAREAS
#define	LOG_SYNCH   DR_LOG_SYNCH
#define	LOG_MEMSTATS   DR_LOG_MEMSTATS
#define	LOG_OPTS   DR_LOG_OPTS
#define	LOG_SIDELINE   DR_LOG_SIDELINE
#define	LOG_SYMBOLS   DR_LOG_SYMBOLS
#define	LOG_RCT   DR_LOG_RCT
#define	LOG_NT   DR_LOG_NT
#define	LOG_HOT_PATCHING   DR_LOG_HOT_PATCHING
#define	LOG_HTABLE   DR_LOG_HTABLE
#define	LOG_MODULEDB   DR_LOG_MODULEDB
#define	LOG_ALL   DR_LOG_ALL

Typedefs
typedef struct _dr_memory_dump_spec_t	dr_memory_dump_spec_t
typedef struct _dr_syscall_result_info_t	dr_syscall_result_info_t

Enumerations
enum	dr_memory_dump_flags_t {   DR_MEMORY_DUMP_LDMP = 0x0001,   DR_MEMORY_DUMP_ELF = 0x0002 }
enum	dr_alloc_flags_t {   DR_ALLOC_NON_HEAP = 0x0001,   DR_ALLOC_THREAD_PRIVATE = 0x0002,   DR_ALLOC_CACHE_REACHABLE = 0x0004,   DR_ALLOC_FIXED_LOCATION = 0x0008,   DR_ALLOC_LOW_2GB = 0x0010,   DR_ALLOC_NON_DR = 0x0020,   DR_ALLOC_RESERVE_ONLY = 0x0040,   DR_ALLOC_COMMIT_ONLY = 0x0080 }
enum	dr_map_executable_flags_t { DR_MAPEXE_SKIP_WRITABLE = 0x0002 }
enum	{   DR_MAP_PRIVATE = 0x0001,   DR_MAP_FIXED = 0x0002,   DR_MAP_IMAGE = 0x0004,   DR_MAP_CACHE_REACHABLE = 0x0008 }
enum	dr_suspend_flags_t { DR_SUSPEND_NATIVE = 0x0001 }
enum	dr_indirect_branch_type_t {   DR_INDIRECT_RETURN,   DR_INDIRECT_CALL,   DR_INDIRECT_JUMP }

Functions
DR_API void *	dr_standalone_init (void)
DR_API void	dr_standalone_exit (void)
DR_API bool	dr_using_all_private_caches (void)
DR_API bool	dr_running_under_dynamorio (void)
DR_API void	dr_request_synchronized_exit (void)
const DR_API char *	dr_get_options (client_id_t client_id)
DR_API bool	dr_get_option_array (client_id_t client_id, int *argc DR_PARAM_OUT, const char ***argv DR_PARAM_OUT)
DR_API bool	dr_get_string_option (const char *option_name, char *buf DR_PARAM_OUT, size_t len)
DR_API bool	dr_get_integer_option (const char *option_name, uint64 *val DR_PARAM_OUT)
const DR_API char *	dr_get_client_path (client_id_t client_id)
DR_API byte *	dr_get_client_base (client_id_t client_id)
DR_API bool	dr_set_client_name (const char *name, const char *report_URL)
DR_API bool	dr_set_client_version_string (const char *version)
DR_API dr_error_code_t	dr_get_error_code (void *drcontext)
DR_API void	dr_get_time (dr_time_t *time)
DR_API uint64	dr_get_milliseconds (void)
DR_API uint64	dr_get_microseconds (void)
DR_API uint	dr_get_random_value (uint max)
DR_API void	dr_set_random_seed (uint seed)
DR_API uint	dr_get_random_seed (void)
DR_API void	dr_abort (void)
DR_API void	dr_abort_with_code (int exit_code)
DR_API void	dr_exit_process (int exit_code)
DR_API bool	dr_create_memory_dump (dr_memory_dump_spec_t *spec)
DR_API void *	dr_thread_alloc (void *drcontext, size_t size)
DR_API void	dr_thread_free (void *drcontext, void *mem, size_t size)
DR_API void *	dr_global_alloc (size_t size)
DR_API void	dr_global_free (void *mem, size_t size)
DR_API void *	dr_custom_alloc (void *drcontext, dr_alloc_flags_t flags, size_t size, uint prot, void *addr)
DR_API bool	dr_custom_free (void *drcontext, dr_alloc_flags_t flags, void *addr, size_t size)
DR_API void *	dr_nonheap_alloc (size_t size, uint prot)
DR_API void	dr_nonheap_free (void *mem, size_t size)
DR_API void *	dr_raw_mem_alloc (size_t size, uint prot, void *addr)
DR_API bool	dr_raw_mem_free (void *addr, size_t size)
DR_API void *	dr_raw_mremap (void *old_address, size_t old_size, size_t new_size, int flags, void *new_address)
DR_API void *	dr_raw_brk (void *new_address)
DR_API void *	__wrap_malloc (size_t size)
DR_API void *	__wrap_realloc (void *mem, size_t size)
DR_API void *	__wrap_calloc (size_t nmemb, size_t size)
DR_API void	__wrap_free (void *mem)
DR_API char *	__wrap_strdup (const char *str)
DR_API void *	dr_mutex_create (void)
DR_API void	dr_mutex_destroy (void *mutex)
DR_API void	dr_mutex_lock (void *mutex)
DR_API void	dr_mutex_unlock (void *mutex)
DR_API bool	dr_mutex_trylock (void *mutex)
DR_API bool	dr_mutex_self_owns (void *mutex)
DR_API bool	dr_mutex_mark_as_app (void *mutex)
DR_API void *	dr_rwlock_create (void)
DR_API void	dr_rwlock_destroy (void *rwlock)
DR_API void	dr_rwlock_read_lock (void *rwlock)
DR_API void	dr_rwlock_read_unlock (void *rwlock)
DR_API void	dr_rwlock_write_lock (void *rwlock)
DR_API void	dr_rwlock_write_unlock (void *rwlock)
DR_API bool	dr_rwlock_write_trylock (void *rwlock)
DR_API bool	dr_rwlock_self_owns_write_lock (void *rwlock)
DR_API bool	dr_rwlock_mark_as_app (void *rwlock)
DR_API void *	dr_recurlock_create (void)
DR_API void	dr_recurlock_destroy (void *reclock)
DR_API void	dr_recurlock_lock (void *reclock)
DR_API void	dr_app_recurlock_lock (void *reclock, dr_mcontext_t *mc)
DR_API void	dr_recurlock_unlock (void *reclock)
DR_API bool	dr_recurlock_trylock (void *reclock)
DR_API bool	dr_recurlock_self_owns (void *reclock)
DR_API bool	dr_recurlock_mark_as_app (void *reclock)
DR_API void *	dr_event_create (void)
DR_API bool	dr_event_destroy (void *event)
DR_API bool	dr_event_wait (void *event)
DR_API bool	dr_event_signal (void *event)
DR_API bool	dr_event_reset (void *event)
DR_API bool	dr_mark_safe_to_suspend (void *drcontext, bool enter)
DR_API int	dr_atomic_add32_return_sum (volatile int *dest, int val)
DR_API int64	dr_atomic_add64_return_sum (volatile int64 *dest, int64 val)
DR_API int	dr_atomic_load32 (volatile int *src)
DR_API void	dr_atomic_store32 (volatile int *dest, int val)
DR_API int64	dr_atomic_load64 (volatile int64 *src)
DR_API void	dr_atomic_store64 (volatile int64 *dest, int64 val)
DR_API byte *	dr_map_executable_file (const char *filename, dr_map_executable_flags_t flags, size_t *size DR_PARAM_OUT)
DR_API bool	dr_unmap_executable_file (byte *base, size_t size)
DR_API reg_t	dr_syscall_get_param (void *drcontext, int param_num)
DR_API void	dr_syscall_set_param (void *drcontext, int param_num, reg_t new_value)
DR_API reg_t	dr_syscall_get_result (void *drcontext)
DR_API bool	dr_syscall_get_result_ex (void *drcontext, dr_syscall_result_info_t *info DR_PARAM_OUT)
DR_API void	dr_syscall_set_result (void *drcontext, reg_t value)
DR_API bool	dr_syscall_set_result_ex (void *drcontext, dr_syscall_result_info_t *info)
DR_API void	dr_syscall_set_sysnum (void *drcontext, int new_num)
DR_API void	dr_syscall_invoke_another (void *drcontext)
DR_API bool	dr_syscall_intercept_natively (const char *name, int sysnum, int num_args, int wow64_index)
DR_API bool	dr_create_dir (const char *fname)
DR_API bool	dr_delete_dir (const char *fname)
DR_API bool	dr_get_current_directory (char *buf, size_t bufsz)
DR_API bool	dr_directory_exists (const char *fname)
DR_API bool	dr_file_exists (const char *fname)
DR_API file_t	dr_open_file (const char *fname, uint mode_flags)
DR_API void	dr_close_file (file_t f)
DR_API bool	dr_rename_file (const char *src, const char *dst, bool replace)
DR_API bool	dr_delete_file (const char *filename)
DR_API void	dr_flush_file (file_t f)
DR_API ssize_t	dr_write_file (file_t f, const void *buf, size_t count)
DR_API ssize_t	dr_read_file (file_t f, void *buf, size_t count)
DR_API bool	dr_file_seek (file_t f, int64 offset, int origin)
DR_API int64	dr_file_tell (file_t f)
DR_API file_t	dr_dup_file_handle (file_t f)
DR_API bool	dr_file_size (file_t fd, DR_PARAM_OUT uint64 *size)
DR_API void *	dr_map_file (file_t f, DR_PARAM_INOUT size_t *size, uint64 offs, app_pc addr, uint prot, uint flags)
DR_API bool	dr_unmap_file (void *map, size_t size)
DR_API void	dr_log (void *drcontext, uint mask, uint level, const char *fmt,...)
DR_API file_t	dr_get_logfile (void *drcontext)
DR_API bool	dr_is_notify_on (void)
DR_API file_t	dr_get_stdout_file (void)
DR_API file_t	dr_get_stderr_file (void)
DR_API file_t	dr_get_stdin_file (void)
DR_API void	dr_messagebox (const char *fmt,...)
DR_API void	dr_printf (const char *fmt,...)
DR_API ssize_t	dr_fprintf (file_t f, const char *fmt,...)
DR_API ssize_t	dr_vfprintf (file_t f, const char *fmt, va_list ap)
DR_API bool	dr_enable_console_printing (void)
DR_API bool	dr_using_console (void)
DR_API int	dr_snprintf (char *buf, size_t max, const char *fmt,...)
DR_API int	dr_snwprintf (wchar_t *buf, size_t max, const wchar_t *fmt,...)
DR_API int	dr_vsnprintf (char *buf, size_t max, const char *fmt, va_list ap)
DR_API int	dr_vsnwprintf (wchar_t *buf, size_t max, const wchar_t *fmt, va_list ap)
DR_API int	dr_sscanf (const char *str, const char *fmt,...)
const DR_API char *	dr_get_token (const char *str, char *buf, size_t buflen)
DR_API void	dr_print_instr (void *drcontext, file_t f, instr_t *instr, const char *msg)
DR_API void	dr_print_opnd (void *drcontext, file_t f, opnd_t opnd, const char *msg)
DR_API void *	dr_get_current_drcontext (void)
DR_API thread_id_t	dr_get_thread_id (void *drcontext)
DR_API HANDLE	dr_get_dr_thread_handle (void *drcontext)
DR_API void *	dr_get_tls_field (void *drcontext)
DR_API void	dr_set_tls_field (void *drcontext, void *value)
DR_API void *	dr_get_dr_segment_base (DR_PARAM_IN reg_id_t tls_register)
DR_API bool	dr_raw_tls_calloc (DR_PARAM_OUT reg_id_t *tls_register, DR_PARAM_OUT uint *offset, DR_PARAM_IN uint num_slots, DR_PARAM_IN uint alignment)
DR_API bool	dr_raw_tls_cfree (uint offset, uint num_slots)
DR_API opnd_t	dr_raw_tls_opnd (void *drcontext, reg_id_t tls_register, uint tls_offs)
DR_API void	dr_insert_read_raw_tls (void *drcontext, instrlist_t *ilist, instr_t *where, reg_id_t tls_register, uint tls_offs, reg_id_t reg)
DR_API void	dr_insert_write_raw_tls (void *drcontext, instrlist_t *ilist, instr_t *where, reg_id_t tls_register, uint tls_offs, reg_id_t reg)
DR_API bool	dr_create_client_thread (void(*func)(void *param), void *arg)
DR_API bool	dr_client_thread_set_suspendable (bool suspendable)
DR_API void	dr_sleep (int time_ms)
DR_API void	dr_thread_yield (void)
DR_API bool	dr_suspend_all_other_threads_ex (DR_PARAM_OUT void ***drcontexts, DR_PARAM_OUT uint *num_suspended, DR_PARAM_OUT uint *num_unsuspended, dr_suspend_flags_t flags)
DR_API bool	dr_suspend_all_other_threads (DR_PARAM_OUT void ***drcontexts, DR_PARAM_OUT uint *num_suspended, DR_PARAM_OUT uint *num_unsuspended)
DR_API bool	dr_resume_all_other_threads (DR_PARAM_IN void **drcontexts, DR_PARAM_IN uint num_suspended)
DR_API bool	dr_is_thread_native (void *drcontext)
DR_API bool	dr_retakeover_suspended_native_thread (void *drcontext)
DR_API bool	dr_set_itimer (int which, uint millisec, void(*func)(void *drcontext, dr_mcontext_t *mcontext))
DR_API uint	dr_get_itimer (int which)
DR_API void	dr_track_where_am_i (void)
DR_API bool	dr_is_tracking_where_am_i (void)
DR_API dr_where_am_i_t	dr_where_am_i (void *drcontext, app_pc pc, DR_PARAM_OUT void **tag)
DR_API bool	dr_replace_fragment (void *drcontext, void *tag, instrlist_t *ilist)
DR_API bool	dr_delete_fragment (void *drcontext, void *tag)
DR_API bool	dr_flush_region_ex (app_pc start, size_t size, void(*flush_completion_callback)(void *user_data), void *user_data)
DR_API bool	dr_flush_region (app_pc start, size_t size)
DR_API bool	dr_unlink_flush_region (app_pc start, size_t size)
DR_API bool	dr_delay_flush_region (app_pc start, size_t size, uint flush_id, void(*flush_completion_callback)(int flush_id))
DR_API bool	dr_fragment_exists_at (void *drcontext, void *tag)
DR_API bool	dr_bb_exists_at (void *drcontext, void *tag)
DR_API uint	dr_fragment_size (void *drcontext, void *tag)
DR_API app_pc	dr_fragment_app_pc (void *tag)
DR_API app_pc	dr_app_pc_for_decoding (app_pc pc)
DR_API app_pc	dr_app_pc_from_cache_pc (byte *cache_pc)
DR_API bool	dr_prepopulate_cache (app_pc *tags, size_t tags_count)
DR_API bool	dr_prepopulate_indirect_targets (dr_indirect_branch_type_t branch_type, app_pc *tags, size_t tags_count)
DR_API bool	dr_get_stats (dr_stats_t *drstats)
DR_API bool	dr_mark_trace_head (void *drcontext, void *tag)
DR_API bool	dr_trace_head_at (void *drcontext, void *tag)
DR_API bool	dr_trace_exists_at (void *drcontext, void *tag)
DR_API void *	dr_hashtable_create (void *drcontext, uint bits, uint load_factor_percent, bool synch, void(*free_payload_func)(void *, void *))
DR_API void	dr_hashtable_destroy (void *drcontext, void *htable)
DR_API void	dr_hashtable_clear (void *drcontext, void *htable)
DR_API void *	dr_hashtable_lookup (void *drcontext, void *htable, ptr_uint_t key)
DR_API void	dr_hashtable_add (void *drcontext, void *htable, ptr_uint_t key, void *payload)
DR_API bool	dr_hashtable_remove (void *drcontext, void *htable, ptr_uint_t key)

Detailed Description

Main API routines, including transparency support.

Macro Definition Documentation

DR_ASSERT

#define DR_ASSERT

(

x

)

DR_ASSERT_MSG(x, "")

If x is false, displays a message about an assertion failure and then calls dr_abort()

DR_ASSERT_MSG

#define DR_ASSERT_MSG	(		x,
			msg
	)

Value:

        ((void)((!(x)) ? (dr_messagebox("ASSERT FAILURE: %s:%d: %s (%s)", __FILE__, \
                                        __LINE__, #x, msg),                         \
                          dr_abort(), 0)                                            \
                       : 0))

If x is false, displays a message about an assertion failure (appending msg to the message) and then calls dr_abort()

DR_FILE_ALLOW_LARGE

#define DR_FILE_ALLOW_LARGE   0x10

Open with large (>2GB) file support. Only applicable on 32-bit Linux.

Note

DR's log files and tracedump files are all created with this flag.

DR_FILE_CLOSE_ON_FORK

#define DR_FILE_CLOSE_ON_FORK   0x20

Linux-only. This file will be closed in the child of a fork.

DR_FILE_READ

#define DR_FILE_READ   0x1

Open with read access.

DR_FILE_WRITE_APPEND

#define DR_FILE_WRITE_APPEND   0x4

Open with write access. If the file already exists, set the file position to the end of the file.

DR_FILE_WRITE_ONLY

#define DR_FILE_WRITE_ONLY   0x40

Open with write-only access. Meant for use with pipes. Linux-only. Mutually exclusive with DR_FILE_WRITE_REQUIRE_NEW, DR_FILE_WRITE_APPEND, and DR_FILE_WRITE_OVERWRITE.

DR_FILE_WRITE_OVERWRITE

#define DR_FILE_WRITE_OVERWRITE   0x8

Open with write access. If the file already exists, truncate the file to zero length.

DR_FILE_WRITE_REQUIRE_NEW

#define DR_FILE_WRITE_REQUIRE_NEW   0x2

Open with write access, but do not open if the file already exists.

DR_LOG_ALL

#define DR_LOG_ALL   0x00ffffff

Log all data.

DR_LOG_ASYNCH

#define DR_LOG_ASYNCH   0x00000010

Log data related to signals/callbacks/etc.

DR_LOG_CACHE

#define DR_LOG_CACHE   0x00000100

Log data related to code cache management. \

DR_LOG_DISPATCH

#define DR_LOG_DISPATCH   0x00000400

Log data on every context switch dispatch. \

DR_LOG_EMIT

#define DR_LOG_EMIT   0x00000040

Log data related to emitting code.

DR_LOG_FRAGMENT

#define DR_LOG_FRAGMENT   0x00000200

Log data related to app code fragments. \

DR_LOG_HEAP

#define DR_LOG_HEAP   0x00001000

Log data related to memory management.

DR_LOG_HOT_PATCHING

#define DR_LOG_HOT_PATCHING   0x00200000

Log data related to hot patching.

DR_LOG_HTABLE

#define DR_LOG_HTABLE   0x00400000

Log data related to hash tables.

DR_LOG_INTERP

#define DR_LOG_INTERP   0x00000020

Log data related to app interpretation.

DR_LOG_LINKS

#define DR_LOG_LINKS   0x00000080

Log data related to linking code.

DR_LOG_MEMSTATS

#define DR_LOG_MEMSTATS   0x00008000

Log data related to memory statistics. \

DR_LOG_MODULEDB

#define DR_LOG_MODULEDB   0x00800000

Log data related to the module database.

DR_LOG_MONITOR

#define DR_LOG_MONITOR   0x00000800

Log data related to trace building.

DR_LOG_NONE

#define DR_LOG_NONE   0x00000000

Log no data.

DR_LOG_NT

#define DR_LOG_NT   0x00100000

Log data related to Windows Native API.

DR_LOG_OPTS

#define DR_LOG_OPTS   0x00010000

Log data related to optimizations.

DR_LOG_RCT

#define DR_LOG_RCT   0x00080000

Log data related to indirect transfers.

DR_LOG_SIDELINE

#define DR_LOG_SIDELINE   0x00020000

Log data related to sideline threads.

DR_LOG_STATS

#define DR_LOG_STATS   0x00000001

Log per-thread and global statistics.

DR_LOG_SYMBOLS

#define DR_LOG_SYMBOLS   0x00040000

Log data related to app symbols.

DR_LOG_SYNCH

#define DR_LOG_SYNCH   0x00004000

Log data related to synchronization.

DR_LOG_SYSCALLS

#define DR_LOG_SYSCALLS   0x00000008

Log data related to system calls.

DR_LOG_THREADS

#define DR_LOG_THREADS   0x00000004

Log data related to threads.

DR_LOG_TOP

#define DR_LOG_TOP   0x00000002

Log top-level information.

DR_LOG_VMAREAS

#define DR_LOG_VMAREAS   0x00002000

Log data related to address space regions.

DR_SEEK_CUR

#define DR_SEEK_CUR   1

current file position

DR_SEEK_END

#define DR_SEEK_END   2

end of file

DR_SEEK_SET

#define DR_SEEK_SET   0

start of file

GLOBAL_DCONTEXT

#define GLOBAL_DCONTEXT   ((void *)-1)

Use this dcontext for use with the standalone static decoder library. Pass it whenever a decoding-related API routine asks for a context. Note that this GLOBAL_DCONTEXT is returned by dr_standalone_init(); beware of its limitations (especially about thread-safety) described there.

LOG_ALL

#define LOG_ALL   DR_LOG_ALL

Identical to DR_LOG_ALL.

LOG_ASYNCH

#define LOG_ASYNCH   DR_LOG_ASYNCH

Identical to DR_LOG_ASYNCH.

LOG_CACHE

#define LOG_CACHE   DR_LOG_CACHE

Identical to DR_LOG_CACHE.

LOG_DISPATCH

#define LOG_DISPATCH   DR_LOG_DISPATCH

Identical to DR_LOG_DISPATCH.

LOG_EMIT

#define LOG_EMIT   DR_LOG_EMIT

Identical to DR_LOG_EMIT.

LOG_FRAGMENT

#define LOG_FRAGMENT   DR_LOG_FRAGMENT

Identical to DR_LOG_FRAGMENT.

LOG_HEAP

#define LOG_HEAP   DR_LOG_HEAP

Identical to DR_LOG_HEAP.

LOG_HOT_PATCHING

#define LOG_HOT_PATCHING   DR_LOG_HOT_PATCHING

Identical to DR_LOG_HOT_PATCHING.

LOG_HTABLE

#define LOG_HTABLE   DR_LOG_HTABLE

Identical to DR_LOG_HTABLE.

LOG_INTERP

#define LOG_INTERP   DR_LOG_INTERP

Identical to DR_LOG_INTERP.

LOG_LINKS

#define LOG_LINKS   DR_LOG_LINKS

Identical to DR_LOG_LINKS.

LOG_MEMSTATS

#define LOG_MEMSTATS   DR_LOG_MEMSTATS

Identical to DR_LOG_MEMSTATS.

LOG_MODULEDB

#define LOG_MODULEDB   DR_LOG_MODULEDB

Identical to DR_LOG_MODULEDB.

LOG_MONITOR

#define LOG_MONITOR   DR_LOG_MONITOR

Identical to DR_LOG_MONITOR.

LOG_NONE

#define LOG_NONE   DR_LOG_NONE

Identical to DR_LOG_NONE.

LOG_NT

#define LOG_NT   DR_LOG_NT

Identical to DR_LOG_NT.

LOG_OPTS

#define LOG_OPTS   DR_LOG_OPTS

Identical to DR_LOG_OPTS.

LOG_RCT

#define LOG_RCT   DR_LOG_RCT

Identical to DR_LOG_RCT.

LOG_SIDELINE

#define LOG_SIDELINE   DR_LOG_SIDELINE

Identical to DR_LOG_SIDELINE.

LOG_STATS

#define LOG_STATS   DR_LOG_STATS

Identical to DR_LOG_STATS.

LOG_SYMBOLS

#define LOG_SYMBOLS   DR_LOG_SYMBOLS

Identical to DR_LOG_SYMBOLS.

LOG_SYNCH

#define LOG_SYNCH   DR_LOG_SYNCH

Identical to DR_LOG_SYNCH.

LOG_SYSCALLS

#define LOG_SYSCALLS   DR_LOG_SYSCALLS

Identical to DR_LOG_SYSCALLS.

LOG_THREADS

#define LOG_THREADS   DR_LOG_THREADS

Identical to DR_LOG_THREADS.

LOG_TOP

#define LOG_TOP   DR_LOG_TOP

Identical to DR_LOG_TOP.

LOG_VMAREAS

#define LOG_VMAREAS   DR_LOG_VMAREAS

Identical to DR_LOG_VMAREAS.

Typedef Documentation

dr_memory_dump_spec_t

typedef struct _dr_memory_dump_spec_t dr_memory_dump_spec_t

Indicates the type of memory dump for dr_create_memory_dump().

dr_syscall_result_info_t

typedef struct _dr_syscall_result_info_t dr_syscall_result_info_t

Data structure used to obtain or modify the result of an application system call by dr_syscall_get_result_ex() and dr_syscall_set_result_ex().

Enumeration Type Documentation

anonymous enum

anonymous enum

Flags for use with dr_map_file().

Enumerator
DR_MAP_PRIVATE	If set, changes to mapped memory are private to the mapping process and are not reflected in the underlying file. If not set, changes are visible to other processes that map the same file, and will be propagated to the file itself.
DR_MAP_FIXED	If set, indicates that the passed-in start address is required rather than a hint. On Linux, this has the same semantics as mmap with MAP_FIXED: i.e., any existing mapping in [addr,addr+size) will be unmapped. This flag is not supported on Windows.
DR_MAP_IMAGE	If set, loads the specified file as an executable image, rather than a data file. This flag is not supported on Linux.
DR_MAP_CACHE_REACHABLE	If set, loads the specified file at a location that is reachable from the code cache and client libraries by a 32-bit displacement. If not set, the mapped file is not guaranteed to be reachable from the cache.

dr_alloc_flags_t

enum dr_alloc_flags_t

Flags used with dr_custom_alloc()

Enumerator
DR_ALLOC_NON_HEAP	If this flag is not specified, dr_custom_alloc() uses a managed heap to allocate the memory, just like dr_thread_alloc() or dr_global_alloc(). In that case, it ignores any requested protection bits (prot parameter), and the location (addr parameter) must be NULL. If this flag is specified, a page-aligned, separate block of memory is allocated, in a similar fashion to dr_nonheap_alloc().
DR_ALLOC_THREAD_PRIVATE	This flag only applies to heap memory (i.e., when DR_ALLOC_NON_HEAP is not specified). If this flag is not specified, global heap is used (just like dr_global_alloc()) and the drcontext parameter is ignored. If it is specified, thread-private heap specific to drcontext is used, just like dr_thread_alloc().
DR_ALLOC_CACHE_REACHABLE	Allocate memory that is 32-bit-displacement reachable from the code caches and from the client library. Memory allocated through dr_thread_alloc(), dr_global_alloc(), and dr_nonheap_alloc() is also reachable, but for dr_custom_alloc(), the resulting memory is not reachable unless this flag is specified. If this flag is passed, the requested location (addr parameter) must be NULL. This flag is not compatible with DR_ALLOC_LOW_2GB, DR_ALLOC_FIXED_LOCATION, or DR_ALLOC_NON_DR.
DR_ALLOC_FIXED_LOCATION	This flag only applies to non-heap memory (i.e., when DR_ALLOC_NON_HEAP is specified). The flag requests that memory be allocated at a specific address, given in the addr parameter. Without this flag, the addr parameter is not honored. This flag is not compatible with DR_ALLOC_LOW_2GB or DR_ALLOC_CACHE_REACHABLE.
DR_ALLOC_LOW_2GB	This flag only applies to non-heap memory (i.e., when DR_ALLOC_NON_HEAP is specified) in 64-bit mode. The flag requests that memory be allocated in the low 2GB of the address space. If this flag is passed, the requested location (addr parameter) must be NULL. This flag is not compatible with DR_ALLOC_FIXED_LOCATION.
DR_ALLOC_NON_DR	This flag only applies to non-heap memory (i.e., when DR_ALLOC_NON_HEAP is specified). When this flag is specified, the allocated memory is not considered to be DynamoRIO or tool memory and thus is not kept separate from the application. This is similar to dr_raw_mem_alloc(). Use of this memory is at the client's own risk. This flag is not compatible with DR_ALLOC_CACHE_REACHABLE.
DR_ALLOC_RESERVE_ONLY	This flag only applies to non-heap, non-DR memory (i.e., when both DR_ALLOC_NON_HEAP and DR_ALLOC_NON_DR are specified) on Windows. When this flag is specified, the allocated memory is reserved but not committed, just like the MEM_RESERVE Windows API flag (the default is MEM_RESERVE|MEM_COMMIT).
DR_ALLOC_COMMIT_ONLY	This flag only applies to non-heap, non-DR memory (i.e., when both DR_ALLOC_NON_HEAP and DR_ALLOC_NON_DR are specified) on Windows. This flag must be combined with DR_ALLOC_FIXED_LOCATION. When this flag is specified, previously allocated memory is committed, just like the MEM_COMMIT Windows API flag (when this flag is not passed, the effect is MEM_RESERVE|MEM_COMMIT). When passed to dr_custom_free(), this flag causes a de-commit, just like the MEM_DECOMMIT Windows API flag. This flag cannot be combined with DR_ALLOC_LOW_2GB and must include a non-NULL requested location (addr parameter).

dr_indirect_branch_type_t

enum dr_indirect_branch_type_t

Specifies the type of indirect branch for use with dr_prepopulate_indirect_targets().

Enumerator
DR_INDIRECT_RETURN	Return instruction type.
DR_INDIRECT_CALL	Indirect call instruction type.
DR_INDIRECT_JUMP	Indirect jump instruction type.

dr_map_executable_flags_t

enum dr_map_executable_flags_t

Flags for use with dr_map_executable_file().

Enumerator
DR_MAPEXE_SKIP_WRITABLE	Requests that writable segments are not mapped, to save address space. This may be ignored on some platforms and may only be honored for a writable segment that is at the very end of the loaded module.

dr_memory_dump_flags_t

enum dr_memory_dump_flags_t

Indicates the type of memory dump for dr_create_memory_dump().

Enumerator
DR_MEMORY_DUMP_LDMP	A "livedump", or "ldmp", DynamoRIO's own custom memory dump format. The ldmp format does not currently support specifying a context for the calling thread, so it will always include the call frames to dr_create_memory_dump(). The ldmp.exe tool can be used to create a dummy process (using the dummy.exe executable) which can then be attached to by the debugger (use a non-invasive attach) in order to view the memory dump contents. Note Windows only.
DR_MEMORY_DUMP_ELF	Memory dump in Executable and Linkable Format. This API has the same restrictions in where it can be called from as dr_suspend_all_other_threads_ex(). Note X64 Linux only.

dr_suspend_flags_t

enum dr_suspend_flags_t

Flags controlling the behavior of dr_suspend_all_other_threads_ex().

Enumerator
DR_SUSPEND_NATIVE	By default, native threads are not suspended by dr_suspend_all_other_threads_ex(). This flag requests that native threads (including those temporarily-native due to actions such as DR_EMIT_GO_NATIVE) be suspended as well.

Function Documentation

__wrap_calloc()

DR_API void* __wrap_calloc	(	size_t	nmemb,
		size_t	size
	)

Allocates memory from DR's global memory pool, but mimics the behavior of calloc. Memory must be freed with __wrap_free(). The __wrap routines are intended to be used with ld's -wrap option; see __wrap_malloc() for more information. The returned address is guaranteed to be double-pointer-aligned: aligned to 16 bytes for 64-bit; aligned to 8 bytes for 32-bit.

__wrap_free()

DR_API void __wrap_free

(

void *

mem

)

Frees memory from DR's global memory pool. Memory must have been allocated with __wrap_malloc(). The __wrap routines are intended to be used with ld's -wrap option; see __wrap_malloc() for more information.

__wrap_malloc()

DR_API void* __wrap_malloc

(

size_t

size

)

Allocates memory from DR's global memory pool, but mimics the behavior of malloc. Memory must be freed with __wrap_free(). The __wrap routines are intended to be used with ld's -wrap option to replace a client's use of malloc, realloc, and free with internal versions that allocate memory from DR's private pool. With -wrap, clients can link to libraries that allocate heap memory without interfering with application allocations. The returned address is guaranteed to be double-pointer-aligned: aligned to 16 bytes for 64-bit; aligned to 8 bytes for 32-bit.

__wrap_realloc()

DR_API void* __wrap_realloc	(	void *	mem,
		size_t	size
	)

Reallocates memory from DR's global memory pool, but mimics the behavior of realloc. Memory must be freed with __wrap_free(). The __wrap routines are intended to be used with ld's -wrap option; see __wrap_malloc() for more information. The returned address is guaranteed to be double-pointer-aligned: aligned to 16 bytes for 64-bit; aligned to 8 bytes for 32-bit.

__wrap_strdup()

DR_API char* __wrap_strdup

(

const char *

str

)

Allocates memory for a new string identical to 'str' and copies the contents of 'str' into the new string, including a terminating null. Memory must be freed with __wrap_free(). The __wrap routines are intended to be used with ld's -wrap option; see __wrap_malloc() for more information. The returned address is guaranteed to be double-pointer-aligned: aligned to 16 bytes for 64-bit; aligned to 8 bytes for 32-bit.

dr_abort()

DR_API void dr_abort

(

void

)

Aborts the process immediately without any cleanup (i.e., the exit event will not be called).

dr_abort_with_code()

DR_API void dr_abort_with_code

(

int

exit_code

)

Aborts the process immediately without any cleanup (i.e., the exit event will not be called) with the exit code exit_code.

On Linux, only the bottom 8 bits of exit_code will be honored for a normal exit. If bits 9..16 are not all zero, DR will send an unhandled signal of that signal number instead of performing a normal exit.

dr_app_pc_for_decoding()

DR_API app_pc dr_app_pc_for_decoding

(

app_pc

pc

)

Given an application PC, returns a PC that contains the application code corresponding to the original PC. In some circumstances on Windows DR inserts a jump on top of the original code, which the client will not see in the bb and trace hooks due to DR replacing it there with the displaced original application code in order to present the client with an unmodified view of the application code. A client should use this routine when attempting to decode the original application instruction that caused a fault from the translated fault address, as the translated address may actually point in the middle of DR's jump.

Note

Other applications on the system sometimes insert their own hooks, which will not be hidden by DR and will appear to the client as jumps and subsequent displaced code.

dr_app_pc_from_cache_pc()

DR_API app_pc dr_app_pc_from_cache_pc

(

byte *

cache_pc

)

Given a code cache pc, returns the corresponding application pc. This involves translating the state and thus may incur calls to the basic block and trace events (see dr_register_bb_event()). If translation fails, returns NULL. This routine may not be called from a thread exit event.

dr_app_recurlock_lock()

DR_API void dr_app_recurlock_lock	(	void *	reclock,
		dr_mcontext_t *	mc
	)

Acquires reclock, or increments the ownership count if already owned. Calls to this method which block (i.e. when the lock is already held) are marked safe to suspend AND transfer; in that case the provided mcontext mc will overwrite the current thread's mcontext. mc must have a valid PC and its flags must be DR_MC_ALL.

This routine must be used in clients holding application locks to prevent deadlocks in a way similar to dr_mark_safe_to_suspend(), but this routine is intended to be called by a clean call and may return execution to the provided mcontext rather than returning normally.

If this routine is called from a clean call, callers should not return normally. Instead, dr_redirect_execution() or dr_redirect_native_target() should be called to to prevent a return into a flushed code page.

dr_atomic_add32_return_sum()

DR_API int dr_atomic_add32_return_sum	(	volatile int *	dest,
		int	val
	)

Atomically adds val to *dest and returns the sum. dest must not straddle two cache lines.

dr_atomic_add64_return_sum()

DR_API int64 dr_atomic_add64_return_sum	(	volatile int64 *	dest,
		int64	val
	)

Atomically adds val to *dest and returns the sum. dest must not straddle two cache lines. Currently 64-bit-build only.

dr_atomic_load32()

DR_API int dr_atomic_load32

(

volatile int *

src

)

Atomically and visibly loads the value at src and returns it.

dr_atomic_load64()

DR_API int64 dr_atomic_load64

(

volatile int64 *

src

)

Atomically and visibly loads the value at src and returns it. Currently 64-bit-build only.

dr_atomic_store32()

DR_API void dr_atomic_store32	(	volatile int *	dest,
		int	val
	)

Atomically and visibly stores val to dest.

dr_atomic_store64()

DR_API void dr_atomic_store64	(	volatile int64 *	dest,
		int64	val
	)

Atomically and visibly stores val to dest. Currently 64-bit-build only.

dr_bb_exists_at()

DR_API bool dr_bb_exists_at	(	void *	drcontext,
		void *	tag
	)

Returns true if a basic block with tag tag exists in the code cache.

dr_client_thread_set_suspendable()

DR_API bool dr_client_thread_set_suspendable

(

bool

suspendable

)

Can only be called from a client thread: returns false if called from a non-client thread.

Controls whether a client thread created with dr_create_client_thread() will be suspended by DR for synchronization operations such as flushing or client requests like dr_suspend_all_other_threads(). A client thread that spends a lot of time holding locks can gain greater performance by not being suspended.

A client thread will be suspended for a thread termination operation, including at process exit, regardless of its suspendable requests.

dr_close_file()

DR_API void dr_close_file

(

file_t

f

)

Closes file f.

dr_create_client_thread()

DR_API bool dr_create_client_thread	(	void(*)(void *param)	func,
		void *	arg
	)

Creates a new thread that is marked as a non-application thread (i.e., DR will let it run natively and not execute its code from the code cache). The thread will terminate automatically simply by returning from func; if running when the application terminates its last thread, the client thread will also terminate when DR shuts the process down.

Init and exit events will not be raised for this thread (instead simply place init and exit code in func).

The new client thread has a drcontext that can be used for thread-private heap allocations. It has a stack of the same size as the DR stack used by application threads.

On Linux, this thread is guaranteed to have its own private itimer if dr_set_itimer() is called from it. However this does mean it will have its own process id.

A client thread should refrain from spending most of its time in calls to other libraries or making blocking or long-running system calls as such actions may incur performance or correctness problems with DR's synchronization engine, which needs to be able to suspend client threads at safe points and cannot determine whether the aforementioned actions are safe for suspension. Calling dr_sleep(), dr_thread_yield(), dr_messagebox(), or using DR's locks are safe. If a client thread spends a lot of time holding locks, consider marking it as un-suspendable by calling dr_client_thread_set_suspendable() for better performance.

Client threads, whether suspendable or not, must never execute from the code cache as the underlying fragments might be removed by another thread.

Client threads are suspended while DR is not executing the application. This includes initialization time: the client thread's func code will not execute until DR starts executing the application.

Note

Thread creation via this routine is not yet fully transparent: on Windows, the thread will show up in the list of application threads if the operating system is queried about threads. The thread will not trigger a DLL_THREAD_ATTACH message. On Linux, the thread will not receive signals meant for the application, and is guaranteed to have a private itimer.

dr_create_dir()

DR_API bool dr_create_dir

(

const char *

fname

)

Creates a new directory. Fails if the directory already exists or if it can't be created. Relative path support on Windows is identical to that described in dr_open_file().

dr_create_memory_dump()

DR_API bool dr_create_memory_dump

(

dr_memory_dump_spec_t *

spec

)

Requests that DR create a memory dump file of the current process. The type of dump is specified by spec.

Returns

whether successful.

Note

this function is only supported on Windows and X64 Linux only. For X64 Linux, this API has the same restriction as dr_suspend_all_other_threads_ex(). For X86_64 platform, fast FP save and restore (fxsave64) support is required. And mixed mode (a process mixing 64-bit and 32-bit code) is not supported.

dr_custom_alloc()

DR_API void* dr_custom_alloc	(	void *	drcontext,
		dr_alloc_flags_t	flags,
		size_t	size,
		uint	prot,
		void *	addr
	)

Allocates memory with the properties requested by flags.

If addr is non-NULL (only allowed with certain flags), it must be page-aligned.

To make more space available for the code caches when running larger applications, or for clients that use a lot of heap memory that is not directly referenced from the cache, we recommend that dr_custom_alloc() be called to obtain memory that is not guaranteed to be reachable from the code cache (by not passing DR_ALLOC_CACHE_REACHABLE). This frees up space in the reachable region.

Returns NULL on failure.

dr_custom_free()

DR_API bool dr_custom_free	(	void *	drcontext,
		dr_alloc_flags_t	flags,
		void *	addr,
		size_t	size
	)

Frees memory allocated by dr_custom_alloc(). The same flags and size must be passed here as were passed to dr_custom_alloc().

dr_delay_flush_region()

DR_API bool dr_delay_flush_region	(	app_pc	start,
		size_t	size,
		uint	flush_id,
		void(*)(int flush_id)	flush_completion_callback
	)

Request a flush of all fragments containing code from the region [start, start + size). The flush will be performed at the next safe point in time (usually before any new code is added to the cache after this routine is called). If flush_completion_callback is non-NULL, it will be called with the flush_id provided to this routine when the flush completes, after which no execution will occur out of the fragments flushed. Returns true if the flush was successfully queued.

Note

dr_flush_region() and dr_unlink_flush_region() can give stronger guarantees on when the flush will occur, but have more restrictions on use.

Use size == 1 to flush fragments containing the instruction at address start. A flush of size == 0 is not allowed.

As currently implemented there may be a performance penalty for requesting a flush_completion_callback; for most performant usage set flush_completion_callback to NULL.

dr_delete_dir()

DR_API bool dr_delete_dir

(

const char *

fname

)

Deletes the given directory. Fails if the directory is not empty. Relative path support on Windows is identical to that described in dr_open_file().

dr_delete_file()

DR_API bool dr_delete_file

(

const char *

filename

)

Deletes the file referred to by filename. Returns true if successful. On both Linux and Windows, if filename refers to a symlink, the symlink will be deleted and not the target of the symlink. On Windows, this will fail to delete any file that was not opened with FILE_SHARE_DELETE and is still open. Relative path support on Windows is identical to that described in dr_open_file().

dr_delete_fragment()

DR_API bool dr_delete_fragment	(	void *	drcontext,
		void *	tag
	)

Deletes the fragment with tag tag. This routine is only valid with the -thread_private option; it deletes the fragment in the current thread only. After deletion, the existing fragment is allowed to complete execution. For example, a clean call deleting the currently executing fragment will safely return to the existing code. Subsequent executions will cause DynamoRIO to reconstruct the fragment, and therefore call the appropriate fragment-creation event hook, if registered.

Note

This routine supports deletion for the current thread only. drcontext must be from the current thread and must be the drcontext used to create the instruction list. This routine may not be called from the thread exit event.

Other options of removing the code fragments from code cache include dr_flush_region(), dr_unlink_flush_region(), and dr_delay_flush_region().

Returns

false if the fragment does not exist and true otherwise.

dr_directory_exists()

DR_API bool dr_directory_exists

(

const char *

fname

)

Checks for the existence of a directory. Relative path support on Windows is identical to that described in dr_open_file().

dr_dup_file_handle()

DR_API file_t dr_dup_file_handle

(

file_t

f

)

Returns a new copy of the file handle f. Returns INVALID_FILE on error.

dr_enable_console_printing()

DR_API bool dr_enable_console_printing

(

void

)

Enables dr_printf() and dr_fprintf() to work with a legacy console window (viz., cmd on Windows 7 or earlier). Loads a private copy of kernel32.dll (if not already loaded) in order to accomplish this. To keep the default DR lean and mean, loading kernel32.dll is not performed by default.

This routine must be called during client initialization (dr_client_main()). If called later, it will fail.

Without calling this routine, dr_printf() and dr_fprintf() will not print anything in a console window on Windows 7 or earlier, nor will they print anything when running a graphical application.

Even after calling this routine, there are significant limitations to console printing support in DR:

• On Windows versions prior to Vista, and for WOW64 applications on Vista, it does not work from the exit event. Once the application terminates its state with csrss (toward the very end of ExitProcess), no output will show up on the console. We have no good solution here yet as exiting early is not ideal.
• In the future, with earliest injection (Issue 234), writing to the console may not work from the client init event on Windows 7 and earlier (it will work on Windows 8).

These limitations stem from the complex arrangement of the console window in Windows (prior to Windows 8), where printing to it involves sending a message in an undocumented format to the csrss process, rather than a simple write to a file handle. We recommend using a terminal window such as cygwin's rxvt rather than the cmd window, or alternatively redirecting all output to a file, which will solve all of the above limitations.

Returns whether successful.

Note

Windows only.

dr_event_create()

DR_API void* dr_event_create

(

void

)

Creates an event object on which threads can wait and be signaled.

dr_event_destroy()

DR_API bool dr_event_destroy

(

void *

event

)

Destroys an event object.

dr_event_reset()

DR_API bool dr_event_reset

(

void *

event

)

Resets event to no longer be in a signaled state.

dr_event_signal()

DR_API bool dr_event_signal

(

void *

event

)

Wakes up at most one thread waiting on event.

dr_event_wait()

DR_API bool dr_event_wait

(

void *

event

)

Suspends the current thread until event is signaled.

dr_exit_process()

DR_API void dr_exit_process

(

int

exit_code

)

Exits the process, first performing a full cleanup that will trigger the exit event (dr_register_exit_event()). The process exit code is set to exit_code.

On Linux, only the bottom 8 bits of exit_code will be honored for a normal exit. If bits 9..16 are not all zero, DR will send an unhandled signal of that signal number instead of performing a normal exit.

Note

Calling this from dr_client_main or from the primary thread's initialization event is not guaranteed to always work, as DR may invoke a thread exit event where a thread init event was never called. We recommend using dr_abort_with_code() or waiting for full initialization prior to use of this routine.

dr_file_exists()

DR_API bool dr_file_exists

(

const char *

fname

)

Checks the existence of a file. Relative path support on Windows is identical to that described in dr_open_file().

dr_file_seek()

DR_API bool dr_file_seek	(	file_t	f,
		int64	offset,
		int	origin
	)

Sets the current file position for file f to offset bytes from the specified origin, where origin is one of the DR_SEEK_* values. Returns true if successful.

dr_file_size()

DR_API bool dr_file_size	(	file_t	fd,
		DR_PARAM_OUT uint64 *	size
	)

Determines the size of the file fd. On success, returns the size in size.

Returns

whether successful.

dr_file_tell()

DR_API int64 dr_file_tell

(

file_t

f

)

Returns the current position for the file f in bytes from the start of the file. Returns -1 on an error.

dr_flush_file()

DR_API void dr_flush_file

(

file_t

f

)

Flushes any buffers for file f.

dr_flush_region()

DR_API bool dr_flush_region	(	app_pc	start,
		size_t	size
	)

Equivalent to dr_flush_region_ex(start, size, NULL).

dr_flush_region_ex()

DR_API bool dr_flush_region_ex	(	app_pc	start,
		size_t	size,
		void(*)(void *user_data)	flush_completion_callback,
		void *	user_data
	)

Flush all fragments containing any code from the region [start, start + size). Once this routine returns no execution will occur out of the fragments flushed. This routine may only be called during a clean call from the cache, from a nudge event handler, or from a pre- or post-system call event handler. It may not be called from any other event callback. No locks can held when calling this routine. If called from a clean call, caller can NOT return to the cache (the fragment that was called out of may have been flushed even if it doesn't apparently overlap the flushed region). Instead the caller must redirect execution via dr_redirect_execution() (or DR_SIGNAL_REDIRECT from a signal callback) after this routine to continue execution. Returns true if successful.

Note

This routine may not be called from any registered event callback other than the nudge event, the pre- or post-system call events, the exception event, or the signal event; clean calls out of the cache may call this routine.

If called from a clean call, caller must continue execution by calling dr_redirect_execution() after this routine, as the fragment containing the callout may have been flushed. The context to use can be obtained via dr_get_mcontext() with the exception of the pc to continue at which must be passed as an argument to the callout (see instr_get_app_pc()) or otherwise determined.

This routine may not be called while any locks are held that could block a thread processing a registered event callback or cache callout.

dr_delay_flush_region() has fewer restrictions on use, but is less synchronous.

Use size == 1 to flush fragments containing the instruction at address start. A flush of size == 0 is not allowed.

Use flush_completion_callback to specify logic to be executed after the flush and before the threads are resumed. Use NULL if not needed.

As currently implemented, dr_delay_flush_region() with no completion callback routine specified can be substantially more performant.

dr_fprintf()

DR_API ssize_t dr_fprintf	(	file_t	f,
		const char *	fmt,
			...
	)

Printing to a file that won't interfere with the application's own printing. It is not buffered, which means that it should not be used for very frequent, small print amounts: for that the client should either do its own buffering or it should use printf from the C library via DR's private loader.

Note

On Windows 7 and earlier, this routine is not able to print to STDOUT or STDERR in the cmd window unless dr_enable_console_printing() is called ahead of time, and even then there are limitations: see dr_enable_console_printing().

This routine supports printing wide characters via the ls or S format specifiers. On Windows, they are assumed to be UTF-16, and are converted to UTF-8. On Linux, they are converted by simply dropping the high-order bytes.

If the data to be printed is large it will be truncated to an internal buffer size. Use dr_snprintf() and dr_write_file() for large output.

On Linux this routine does not check for errors like EINTR. Use dr_write_file() if that is a concern.

When printing floating-point values, the caller's code should use proc_save_fpstate() or be inside a clean call that has requested to preserve the floating-point state, unless it can prove that its compiler will not use x87 operations. On success, the number of bytes written is returned. On error, -1 is returned.

dr_fragment_app_pc()

DR_API app_pc dr_fragment_app_pc

(

void *

tag

)

Retrieves the application PC of a fragment with tag tag.

dr_fragment_exists_at()

DR_API bool dr_fragment_exists_at	(	void *	drcontext,
		void *	tag
	)

Returns whether or not there is a fragment in code cache with tag tag.

dr_fragment_size()

DR_API uint dr_fragment_size	(	void *	drcontext,
		void *	tag
	)

Looks up the fragment with tag tag. If not found, returns 0. If found, returns the total size occupied in the cache by the fragment.

dr_get_client_base()

DR_API byte* dr_get_client_base

(

client_id_t

client_id

)

Returns the base address of the client library. client_id is the client ID passed to a client's dr_client_main() function.

dr_get_client_path()

const DR_API char* dr_get_client_path

(

client_id_t

client_id

)

Returns the client library name and path that were originally specified to load the library. If the resulting string is longer than MAXIMUM_PATH it will be truncated. client_id is the client ID passed to a client's dr_client_main() function.

dr_get_current_directory()

DR_API bool dr_get_current_directory	(	char *	buf,
		size_t	bufsz
	)

Returns the current directory for this process in buf. On Windows, reading the current directory is considered unsafe except during initialization, as it is stored in user memory and access is not controlled via any standard synchronization.

dr_get_current_drcontext()

DR_API void* dr_get_current_drcontext

(

void

)

Returns the DR context of the current thread.

dr_get_dr_segment_base()

DR_API void* dr_get_dr_segment_base

(

DR_PARAM_IN reg_id_t

tls_register

)

Get DR's thread local storage segment base pointed at by tls_register. It can be used to get the base of the thread-local storage segment used by dr_raw_tls_calloc.

Note

It should not be called on thread exit event, as the thread exit event may be invoked from other threads. See dr_register_thread_exit_event for details.

dr_get_dr_thread_handle()

DR_API HANDLE dr_get_dr_thread_handle

(

void *

drcontext

)

Returns a Windows handle to the thread with drcontext drcontext. This handle is DR's handle to this thread (it is not a separate copy) and as such it should not be closed by the caller; nor should it be used beyond the thread's exit, as DR's handle will be closed at that point.

The handle should have THREAD_ALL_ACCESS privileges.

Note

Windows only.

dr_get_error_code()

DR_API dr_error_code_t dr_get_error_code

(

void *

drcontext

)

Returns the error code of the last failed API routine. Users should check whether or not the API routine that they just called has failed prior to calling this function.

Warning

Not all API routines currently support the registering of an error code upon their failure. Therefore, check the routine's documentation to see whether it supports setting error codes.

dr_get_integer_option()

DR_API bool dr_get_integer_option	(	const char *	option_name,
		uint64 *val	DR_PARAM_OUT
	)

Read the value of an integer DynamoRIO runtime option named option_name into val. This includes boolean options. Options are listed in DynamoRIO Runtime Options. DynamoRIO has many other undocumented options which may be queried through this API, but they are not officially supported.

Warning

Always pass a full uint64 for val even if the option is a smaller integer to avoid overwriting nearby data.

Returns

false if no option named option_name exists, and true otherwise.

dr_get_itimer()

DR_API uint dr_get_itimer

(

int

which

)

If an interval timer is already installed in the itimer sharing group that contains the calling thread, returns its frequency. Else returns 0.

Parameters

[in]

which

Must be one of ITIMER_REAL, ITIMER_VIRTUAL, or ITIMER_PROF

Note

Linux-only.

dr_get_logfile()

DR_API file_t dr_get_logfile

(

void *

drcontext

)

Returns the log file for the thread with drcontext drcontext. If drcontext is NULL, returns the main log file.

dr_get_microseconds()

DR_API uint64 dr_get_microseconds

(

void

)

Returns the number of microseconds since Jan 1, 1601 (this is the current UTC time).

Note

This is the Windows standard. UNIX time functions typically count from the Epoch (Jan 1, 1970). The Epoch is 11644473600*1000*1000 microseconds after Jan 1, 1601.

dr_get_milliseconds()

DR_API uint64 dr_get_milliseconds

(

void

)

Returns the number of milliseconds since Jan 1, 1601 (this is the current UTC time).

Note

This is the Windows standard. UNIX time functions typically count from the Epoch (Jan 1, 1970). The Epoch is 11644473600*1000 milliseconds after Jan 1, 1601.

dr_get_option_array()

DR_API bool dr_get_option_array	(	client_id_t	client_id,
		int *argc	DR_PARAM_OUT,
		const char ***argv	DR_PARAM_OUT
	)

Returns the client-specific option string specified at client registration, parsed into an array of argc separate option tokens stored in argv. This is the same array of arguments passed to the dr_client_main() routine.

dr_get_options()

const DR_API char* dr_get_options

(

client_id_t

client_id

)

Returns the client-specific option string specified at client registration. client_id is the client ID passed to dr_client_main().

Deprecated:

This routine is replaced by dr_client_main()'s arguments and by dr_get_option_array(). The front-end drrun and other utilities now re-quote all tokens, providing simpler option passing without escaping or extra quote layers. This routine, for compatibility, strips those quotes off and returns a flat string without any token-delimiting quotes.

dr_get_random_seed()

DR_API uint dr_get_random_seed

(

void

)

Returns the seed used for dr_get_random_value().

dr_get_random_value()

DR_API uint dr_get_random_value

(

uint

max

)

Returns a pseudo-random number in the range [0..max). The pseudo-random sequence can be repeated by passing the seed used during a run to the next run via the -prng_seed runtime option.

dr_get_stats()

DR_API bool dr_get_stats

(

dr_stats_t *

drstats

)

Retrieves various statistics exported by DR as global, process-wide values. The API is not thread-safe. The caller is expected to pass a pointer to a valid, initialized dr_stats_t value, with the size field set (see dr_stats_t). Returns false if stats are not enabled.

dr_get_stderr_file()

DR_API file_t dr_get_stderr_file

(

void

)

Returns a handle to stderr.

dr_get_stdin_file()

DR_API file_t dr_get_stdin_file

(

void

)

Returns a handle to stdin.

dr_get_stdout_file()

DR_API file_t dr_get_stdout_file

(

void

)

Returns a handle to stdout.

dr_get_string_option()

DR_API bool dr_get_string_option	(	const char *	option_name,
		char *buf	DR_PARAM_OUT,
		size_t	len
	)

Read the value of a string DynamoRIO runtime option named option_name into buf. Options are listed in DynamoRIO Runtime Options. DynamoRIO has many other undocumented options which may be queried through this API, but they are not officially supported. The option value is truncated to len bytes and null-terminated.

Returns

false if no option named option_name exists, and true otherwise.

dr_get_thread_id()

DR_API thread_id_t dr_get_thread_id

(

void *

drcontext

)

Returns the thread id of the thread with drcontext drcontext.

dr_get_time()

DR_API void dr_get_time

(

dr_time_t *

time

)

Retrieves the current time.

dr_get_tls_field()

DR_API void* dr_get_tls_field

(

void *

drcontext

)

Returns the user-controlled thread-local-storage field. To generate an instruction sequence that reads the drcontext field inline in the code cache, use dr_insert_read_tls_field().

dr_get_token()

const DR_API char* dr_get_token	(	const char *	str,
		char *	buf,
		size_t	buflen
	)

Utility function that aids in tokenizing a string, such as a client options string from dr_get_options(). The function scans str until a non-whitespace character is found. It then starts copying into buf until a whitespace character is found denoting the end of the token. If the token begins with a quote, the token continues (including across whitespace) until the matching end quote is found. Characters considered whitespace are ' ', '\t', '\r', and '\n'; characters considered quotes are '\'', '\"', and '‘’.

Parameters

[in]	str	The start of the string containing the next token.
[out]	buf	A buffer to store a null-terminated copy of the next token.
[in]	buflen	The capacity of the buffer, in characters. If the token is too large to fit, it will be truncated and null-terminated.

Returns

a pointer to the end of the token in str. Thus, to retrieve the subsequent token, call this routine again with the prior return value as the new value of str. Returns NULL when the end of str is reached.

dr_global_alloc()

DR_API void* dr_global_alloc

(

size_t

size

)

Allocates size bytes of memory from DR's global memory pool. This memory is only guaranteed to be aligned to the pointer size: 8 byte alignment for 64-bit; 4-byte alignment for 32-bit. (The wrapped malloc() guarantees the more standard double-pointer-size.)

dr_global_free()

DR_API void dr_global_free	(	void *	mem,
		size_t	size
	)

Frees memory allocated by dr_global_alloc(). size must be the same as that passed to dr_global_alloc().

dr_hashtable_add()

DR_API void dr_hashtable_add	(	void *	drcontext,
		void *	htable,
		ptr_uint_t	key,
		void *	payload
	)

Adds a new entry to the hashtable.

Parameters

[in]	drcontext	Must be the same context passed to dr_hashtable_create().
[in]	htable	A pointer to the table itself, returned by dr_hashtable_create().
[in]	key	The key to add.
[in]	payload	The payload to add.

dr_hashtable_clear()

DR_API void dr_hashtable_clear	(	void *	drcontext,
		void *	htable
	)

Removes all entries in a hashtable created by dr_hashtable_create().

Parameters

[in]	drcontext	Must be the same context passed to dr_hashtable_create().
[in]	htable	A pointer to the table itself, returned by dr_hashtable_create().

dr_hashtable_create()

DR_API void* dr_hashtable_create	(	void *	drcontext,
		uint	bits,
		uint	load_factor_percent,
		bool	synch,
		void(*)(void *, void *)	free_payload_func
	)

Allocates and initializes an open-address library-independent hashtable:

Parameters

[in]	drcontext	This context controls whether thread-private or global heap is used for the table.
[in]	bits	The base-2 log of the initial capacity of the table.
[in]	load_factor_percent	The threshold of the table's occupancy at which it will be resized (so smaller values keep the table sparser and generally more performant but at the cost of more memory). This is a percentage and so must be between 0 and 100. Values are typically in the 20-80 range and for performance critical tables would usually be below 50.
[in]	synch	Whether to use a lock around all operations.
[in]	free_payload_func	An optional function to call when removing an entry.

Returns

a pointer to the heap-allocated table.

dr_hashtable_destroy()

DR_API void dr_hashtable_destroy	(	void *	drcontext,
		void *	htable
	)

Destroys a hashtable created by dr_hashtable_create().

Parameters

[in]	drcontext	Must be the same context passed to dr_hashtable_create().
[in]	htable	A pointer to the table itself, returned by dr_hashtable_create().

dr_hashtable_lookup()

DR_API void* dr_hashtable_lookup	(	void *	drcontext,
		void *	htable,
		ptr_uint_t	key
	)

Queries whether an entry for the given key exists.

Parameters

[in]	drcontext	Must be the same context passed to dr_hashtable_create().
[in]	htable	A pointer to the table itself, returned by dr_hashtable_create().
[in]	key	The key to query.

Returns

the payload value for the key that was passed to dr_hashtable_add(), or NULL if no such key is found.

dr_hashtable_remove()

DR_API bool dr_hashtable_remove	(	void *	drcontext,
		void *	htable,
		ptr_uint_t	key
	)

Removes an entry for the given key.

Parameters

[in]	drcontext	Must be the same context passed to dr_hashtable_create().
[in]	htable	A pointer to the table itself, returned by dr_hashtable_create().
[in]	key	The key to remove.

Returns

whether the key was found.

dr_insert_read_raw_tls()

DR_API void dr_insert_read_raw_tls	(	void *	drcontext,
		instrlist_t *	ilist,
		instr_t *	where,
		reg_id_t	tls_register,
		uint	tls_offs,
		reg_id_t	reg
	)

Inserts into ilist prior to "where" instruction(s) to read into the general-purpose full-size register reg from the raw TLS slot with offset tls_offs from the TLS base tls_register.

dr_insert_write_raw_tls()

DR_API void dr_insert_write_raw_tls	(	void *	drcontext,
		instrlist_t *	ilist,
		instr_t *	where,
		reg_id_t	tls_register,
		uint	tls_offs,
		reg_id_t	reg
	)

Inserts into ilist prior to "where" instruction(s) to store the value in the general-purpose full-size register reg into the raw TLS slot with offset tls_offs from the TLS base tls_register.

dr_is_notify_on()

DR_API bool dr_is_notify_on

(

void

)

Returns true iff the -stderr_mask runtime option is non-zero, indicating that the user wants notification messages printed to stderr.

dr_is_thread_native()

DR_API bool dr_is_thread_native

(

void *

drcontext

)

Returns whether the thread represented by drcontext is currently executing natively (typically due to an earlier DR_EMIT_GO_NATIVE return value).

dr_is_tracking_where_am_i()

DR_API bool dr_is_tracking_where_am_i

(

void

)

Returns whether DR is using accurate tracking of the dr_where_am_i value. Typically this is enabled by calling dr_track_where_am_i().

dr_log()

DR_API void dr_log	(	void *	drcontext,
		uint	mask,
		uint	level,
		const char *	fmt,
			...
	)

Writes to DR's log file for the thread with drcontext drcontext if the current loglevel is >= level and the current logmask & mask != 0. The mask constants are the DR_LOG_* defines below. Logging is disabled for the release build. If drcontext is NULL, writes to the main log file.

dr_map_executable_file()

DR_API byte* dr_map_executable_file	(	const char *	filename,
		dr_map_executable_flags_t	flags,
		size_t *size	DR_PARAM_OUT
	)

Loads filename as an executable file for examination, rather than for execution. No entry point, initialization, or constructor code is executed, nor is any thread-local storage or other resources set up. Returns the size (which may include unmappped gaps) in size. The return value of the function is the base address at which the file is mapped.

Note

Not currently supported on Mac OSX.

dr_map_file()

DR_API void* dr_map_file	(	file_t	f,
		DR_PARAM_INOUT size_t *	size,
		uint64	offs,
		app_pc	addr,
		uint	prot,
		uint	flags
	)

Memory-maps size bytes starting at offset offs from the file f at address addr with privileges prot.

Parameters

[in]	f	The file to map.
[in,out]	size	The requested size to map. Upon successful return, contains the actual mapped size.
[in]	offs	The offset within the file at which to start the map.
[in]	addr	The requested start address of the map. Unless fixed is true, this is just a hint and may not be honored.
[in]	prot	The access privileges of the mapping, composed of the DR_MEMPROT_READ, DR_MEMPROT_WRITE, and DR_MEMPROT_EXEC bits.
[in]	flags	Optional DR_MAP_* flags.

Note

Mapping image files for execution is not supported.

Returns

the start address of the mapping, or NULL if unsuccessful.

dr_mark_safe_to_suspend()

DR_API bool dr_mark_safe_to_suspend	(	void *	drcontext,
		bool	enter
	)

Use this function to mark a region of code as safe for DR to suspend the client while inside the region. DR will not relocate the client from the region and will resume it at precisely the suspend point.

This function must be used in client code that acquires application locks. Use this feature with care! Do not mark code as safe to suspend that has a code cache return point. I.e., do not call this routine from a clean call. For acquiring application locks from a clean call, see dr_app_recurlock_lock().

No DR locks can be held while in a safe region. Consequently, do not call this routine from any DR event callback. It may only be used from natively executing code.

Always invoke this routine in pairs, with the first passing true for enter and the second passing false, thus delimiting the region.

dr_mark_trace_head()

DR_API bool dr_mark_trace_head	(	void *	drcontext,
		void *	tag
	)

Marks the fragment associated with tag tag as a trace head. The fragment need not exist yet – once it is created it will be marked as a trace head.

DR associates a counter with a trace head and once it passes the -hot_threshold parameter, DR begins building a trace. Before each fragment is added to the trace, DR calls the client's end_trace callback to determine whether to end the trace. (The callback will be called both for standard DR traces and for client-defined traces.)

Note

Some fragments are unsuitable for trace heads. DR will ignore attempts to mark such fragments as trace heads and will return false. If the client marks a fragment that doesn't exist yet as a trace head and DR later determines that the fragment is unsuitable for a trace head it will unmark the fragment as a trace head without notifying the client.

Some fragments' notion of trace heads is dependent on which previous block targets them. For these fragments, calling this routine will only mark as a trace head for targets from the same memory region.

Returns true if the target fragment is marked as a trace head.

dr_messagebox()

DR_API void dr_messagebox	(	const char *	fmt,
			...
	)

Displays a message in a pop-up window.

Note

Windows only.

On Windows Vista most Windows services are unable to display message boxes.

dr_mutex_create()

DR_API void* dr_mutex_create

(

void

)

Initializes a mutex.

Warning: there are restrictions on when DR-provided mutexes, and locks in general, can be held by a client: no lock should be held while application code is executing in the code cache. Locks can be used while inside client code reached from clean calls out of the code cache, but they must be released before returning to the cache. A lock must also be released by the same thread that acquired it. Failing to follow these restrictions can lead to deadlocks.

dr_mutex_destroy()

DR_API void dr_mutex_destroy

(

void *

mutex

)

Deletes mutex.

dr_mutex_lock()

DR_API void dr_mutex_lock

(

void *

mutex

)

Locks mutex. Waits until the mutex is successfully held.

dr_mutex_mark_as_app()

DR_API bool dr_mutex_mark_as_app

(

void *

mutex

)

Instructs DR to treat this lock as an application lock. Primarily this avoids debug-build checks that no DR locks are held in situations where locks are disallowed.

Warning

Any one lock should either be a DR lock or an application lock. Use this routine with caution and do not call it on a DR lock that is used in DR contexts, as it disables debug checks.

This routine is not sufficient on its own to prevent deadlocks during scenarios where DR wants to suspend all threads such as detach or relocation. See dr_app_recurlock_lock() and dr_mark_safe_to_suspend().

Returns

whether successful.

dr_mutex_self_owns()

DR_API bool dr_mutex_self_owns

(

void *

mutex

)

Returns true iff mutex is owned by the calling thread. This routine is only available in debug builds. In release builds it always returns true.

dr_mutex_trylock()

DR_API bool dr_mutex_trylock

(

void *

mutex

)

Tries once to lock mutex and returns whether or not successful.

dr_mutex_unlock()

DR_API void dr_mutex_unlock

(

void *

mutex

)

Unlocks mutex. Asserts that mutex is currently locked by the current thread.

dr_nonheap_alloc()

DR_API void* dr_nonheap_alloc	(	size_t	size,
		uint	prot
	)

Allocates size bytes of memory as a separate allocation from DR's heap, allowing for separate protection. The prot protection should use the DR_MEMPROT_READ, DR_MEMPROT_WRITE, and DR_MEMPROT_EXEC bits. When creating a region to hold dynamically generated code, use this routine in order to create executable memory.

dr_nonheap_free()

DR_API void dr_nonheap_free	(	void *	mem,
		size_t	size
	)

Frees memory allocated by dr_nonheap_alloc(). size must be the same as that passed to dr_nonheap_alloc().

dr_open_file()

DR_API file_t dr_open_file	(	const char *	fname,
		uint	mode_flags
	)

Opens the file fname. If no such file exists then one is created. The file access mode is set by the mode_flags argument which is drawn from the DR_FILE_* defines ORed together. Returns INVALID_FILE if unsuccessful.

On Windows, fname is safest as an absolute path (when using Windows system calls directly there is no such thing as a relative path). A relative path passed to this routine will be converted to absolute on a best-effort basis using the current directory that was set at process initialization time. (The most recently set current directory can be retrieved (albeit with no safety guarantees) with dr_get_current_directory().) Drive-implied-absolute paths ("\foo.txt") and other-drive-relative paths ("c:foo.txt") are not supported.

On Linux, the file descriptor will be marked as close-on-exec. The DR_FILE_CLOSE_ON_FORK flag can be used to automatically close a file on a fork.

Note

No more then one write mode flag can be specified.

On Linux, DR hides files opened by clients from the application by using file descriptors that are separate from the application's and preventing the application from closing client-opened files.

dr_prepopulate_cache()

DR_API bool dr_prepopulate_cache	(	app_pc *	tags,
		size_t	tags_count
	)

Intended to be called between dr_app_setup() and dr_app_start() to pre-create code cache fragments for each basic block address in the tags array. This speeds up the subsequent attach when dr_app_start() is called. If any code in the passed-in tags array is not readable, it is up to the caller to handle any fault, as DR's own signal handlers are not enabled at this point. Returns whether successful.

dr_prepopulate_indirect_targets()

DR_API bool dr_prepopulate_indirect_targets	(	dr_indirect_branch_type_t	branch_type,
		app_pc *	tags,
		size_t	tags_count
	)

Intended to augment dr_prepopulate_cache() by populating DR's indirect branch tables, avoiding trips back to the dispatcher during initial execution. This is only effective when one of the the runtime options -shared_trace_ibt_tables and -shared_bb_ibt_tables (depending on whether traces are enabled) is turned on, as this routine does not try to populate tables belonging to threads other than the calling thread.

This is meant to be called between dr_app_setup() and dr_app_start(), immediately after calling dr_prepopulate_cache(). It adds entries for each target address in the tags array to the indirect branch table for the branch type branch_type.

Returns whether successful.

dr_print_instr()

DR_API void dr_print_instr	(	void *	drcontext,
		file_t	f,
		instr_t *	instr,
		const char *	msg
	)

Prints msg followed by the instruction instr to file f.

dr_print_opnd()

DR_API void dr_print_opnd	(	void *	drcontext,
		file_t	f,
		opnd_t	opnd,
		const char *	msg
	)

Prints msg followed by the operand opnd to file f.

dr_printf()

DR_API void dr_printf	(	const char *	fmt,
			...
	)

Stdout printing that won't interfere with the application's own printing. It is not buffered, which means that it should not be used for very frequent, small print amounts: for that the client should either do its own buffering or it should use printf from the C library via DR's private loader.

Note

On Windows 7 and earlier, this routine is not able to print to the cmd window unless dr_enable_console_printing() is called ahead of time, and even then there are limitations: see dr_enable_console_printing().

This routine supports printing wide characters via the ls or S format specifiers. On Windows, they are assumed to be UTF-16, and are converted to UTF-8. On Linux, they are converted by simply dropping the high-order bytes.

If the data to be printed is large it will be truncated to an internal buffer size. Use dr_snprintf() and dr_write_file() for large output.

When printing floating-point values on x86, the caller's code should use proc_save_fpstate() or be inside a clean call that has requested to preserve the floating-point state, unless it can prove that its compiler will not use x87 operations.

dr_raw_brk()

DR_API void* dr_raw_brk

(

void *

new_address

)

Sets the program break to the specified value. Invokes the SYS_brk system call and returns the result. This is the application's program break, so use this system call only when deliberately changing the application's behavior.

Note

Linux-only.

dr_raw_mem_alloc()

DR_API void* dr_raw_mem_alloc	(	size_t	size,
		uint	prot,
		void *	addr
	)

Warning

This raw memory allocation interface is in flux and is subject to change in the next release. Consider it experimental in this release.

Allocates size bytes (page size aligned) of memory as a separate allocation at preferred base addr that must be page size aligned, allowing for separate protection. If addr is NULL, an arbitrary address is picked.

The prot protection should use the DR_MEMPROT_READ, DR_MEMPROT_WRITE, and DR_MEMPROT_EXEC bits. The allocated memory is not considered to be DynamoRIO or tool memory and thus is not kept separate from the application. Use of this memory is at the client's own risk.

The resulting memory is guaranteed to be initialized to all zeroes.

Returns the actual address allocated or NULL if memory allocation at preferred base fails.

dr_raw_mem_free()

DR_API bool dr_raw_mem_free	(	void *	addr,
		size_t	size
	)

Frees memory allocated by dr_raw_mem_alloc(). addr and size must be the same as that passed to dr_raw_mem_alloc() on Windows.

dr_raw_mremap()

DR_API void* dr_raw_mremap	(	void *	old_address,
		size_t	old_size,
		size_t	new_size,
		int	flags,
		void *	new_address
	)

Calls mremap with the specified parameters and returns the result. The old memory must be non-DR memory, and the new memory is also considered to be non-DR memory (see DR_ALLOC_NON_DR).

Note

Linux-only.

dr_raw_tls_calloc()

DR_API bool dr_raw_tls_calloc	(	DR_PARAM_OUT reg_id_t *	tls_register,
		DR_PARAM_OUT uint *	offset,
		DR_PARAM_IN uint	num_slots,
		DR_PARAM_IN uint	alignment
	)

Allocates num_slots contiguous thread-local storage (TLS) slots that can be directly accessed via an offset from tls_register. If alignment is non-zero, the slots will be aligned to alignment. These slots will be initialized to 0 for each new thread. The slot offsets are [offset .. offset + (num_slots - 1)]. These slots are disjoint from the dr_spill_slot_t register spill slots and the client tls field (dr_get_tls_field()). Returns whether or not the slots were successfully obtained. The linear address of the TLS base pointed at by tls_register can be obtained using dr_get_dr_segment_base. Raw TLs slots can be read directly using dr_insert_read_raw_tls() and written using dr_insert_write_raw_tls().

Supports passing 0 for num_slots, in which case tls_register will be written but no other action taken.

Note

These slots are useful for thread-shared code caches. With thread-private caches, DR's memory pools are guaranteed to be reachable via absolute or rip-relative accesses from the code cache and client libraries.

These slots are a limited resource. On Windows the slots are shared with the application and reserving even one slot can result in failure to initialize for certain applications. On Linux they are more plentiful and transparent but currently DR limits clients to no more than 64 slots.

On Mac OS, TLS slots may not be initialized to zero.

dr_raw_tls_cfree()

DR_API bool dr_raw_tls_cfree	(	uint	offset,
		uint	num_slots
	)

Frees num_slots raw thread-local storage slots starting at offset offset that were allocated with dr_raw_tls_calloc(). Returns whether or not the slots were successfully freed.

dr_raw_tls_opnd()

DR_API opnd_t dr_raw_tls_opnd	(	void *	drcontext,
		reg_id_t	tls_register,
		uint	tls_offs
	)

Returns an operand that refers to the raw TLS slot with offset tls_offs from the TLS base tls_register.

dr_read_file()

DR_API ssize_t dr_read_file	(	file_t	f,
		void *	buf,
		size_t	count
	)

Reads up to count bytes from file f into buf. Returns the actual number read.

dr_recurlock_create()

DR_API void* dr_recurlock_create

(

void

)

Creates and initializes a recursive lock. A recursive lock allows the same thread to acquire it multiple times. The lock restrictions for mutexes apply (see dr_mutex_create()).

dr_recurlock_destroy()

DR_API void dr_recurlock_destroy

(

void *

reclock

)

Deletes reclock.

dr_recurlock_lock()

DR_API void dr_recurlock_lock

(

void *

reclock

)

Acquires reclock, or increments the ownership count if already owned.

dr_recurlock_mark_as_app()

DR_API bool dr_recurlock_mark_as_app

(

void *

reclock

)

Instructs DR to treat this lock as an application lock. Primarily this avoids debug-build checks that no DR locks are held in situations where locks are disallowed.

Warning

Any one lock should either be a DR lock or an application lock. Use this routine with caution and do not call it on a DR lock that is used in DR contexts, as it disables debug checks.

Returns

whether successful.

dr_recurlock_self_owns()

DR_API bool dr_recurlock_self_owns

(

void *

reclock

)

Returns whether the calling thread owns reclock.

dr_recurlock_trylock()

DR_API bool dr_recurlock_trylock

(

void *

reclock

)

Tries once to acquire reclock and returns whether successful.

dr_recurlock_unlock()

DR_API void dr_recurlock_unlock

(

void *

reclock

)

Decrements the ownership count of reclock and releases if zero.

dr_rename_file()

DR_API bool dr_rename_file	(	const char *	src,
		const char *	dst,
		bool	replace
	)

Renames the file src to dst, replacing an existing file named dst if replace is true. Atomic if src and dst are on the same filesystem. Returns true if successful.

dr_replace_fragment()

DR_API bool dr_replace_fragment	(	void *	drcontext,
		void *	tag,
		instrlist_t *	ilist
	)

Replaces the fragment with tag tag with the instructions in ilist. This routine is only valid with the -thread_private option; it replaces the fragment for the current thread only. After replacement, the existing fragment is allowed to complete if currently executing. For example, a clean call replacing the currently executing fragment will safely return to the existing code. Subsequent executions will use the new instructions.

Note

The routine takes control of ilist and all responsibility for deleting it. The client should not keep, use, or reference, the instrlist or any of the instrs it contains after passing.

This routine supports replacement for the current thread only. drcontext must be from the current thread and must be the drcontext used to create the instruction list. This routine may not be called from the thread exit event.

Returns

false if the fragment does not exist and true otherwise.

dr_request_synchronized_exit()

DR_API void dr_request_synchronized_exit

(

void

)

Deprecated:

Replaced by dr_set_process_exit_behavior()

dr_resume_all_other_threads()

DR_API bool dr_resume_all_other_threads	(	DR_PARAM_IN void **	drcontexts,
		DR_PARAM_IN uint	num_suspended
	)

May only be used after invoking dr_suspend_all_other_threads(). This routine resumes the threads that were suspended by dr_suspend_all_other_threads() and must be passed the same array and count of suspended threads that were returned by dr_suspend_all_other_threads(). It also frees the drcontexts array and releases the locks acquired by dr_suspend_all_other_threads(). The return value indicates whether all resumption attempts were successful.

dr_retakeover_suspended_native_thread()

DR_API bool dr_retakeover_suspended_native_thread

(

void *

drcontext

)

Causes the thread owning drcontext to begin executing in the code cache again once it is resumed. The thread must currently be suspended (typically by dr_suspend_all_other_threads_ex() with DR_SUSPEND_NATIVE) and must be currently native (typically from DR_EMIT_GO_NATIVE).

Returns

whether successful.

dr_running_under_dynamorio()

DR_API bool dr_running_under_dynamorio

(

void

)

Returns false if DynamoRIO is being used as a "regular" standalone library (see dr_standalone_init() and Disassembly Library). Returns true if DynamoRIO is controlling the application by running its code through a software code cache.

dr_rwlock_create()

DR_API void* dr_rwlock_create

(

void

)

Creates and initializes a read-write lock. A read-write lock allows multiple readers or alternatively a single writer. The lock restrictions for mutexes apply (see dr_mutex_create()).

dr_rwlock_destroy()

DR_API void dr_rwlock_destroy

(

void *

rwlock

)

Deletes rwlock.

dr_rwlock_mark_as_app()

DR_API bool dr_rwlock_mark_as_app

(

void *

rwlock

)

Instructs DR to treat this lock as an application lock. Primarily this avoids debug-build checks that no DR locks are held in situations where locks are disallowed.

Warning

Any one lock should either be a DR lock or an application lock. Use this routine with caution and do not call it on a DR lock that is used in DR contexts, as it disables debug checks.

Returns

whether successful.

dr_rwlock_read_lock()

DR_API void dr_rwlock_read_lock

(

void *

rwlock

)

Acquires a read lock on rwlock.

dr_rwlock_read_unlock()

DR_API void dr_rwlock_read_unlock

(

void *

rwlock

)

Releases a read lock on rwlock.

dr_rwlock_self_owns_write_lock()

DR_API bool dr_rwlock_self_owns_write_lock

(

void *

rwlock

)

Returns whether the calling thread owns the write lock on rwlock.

dr_rwlock_write_lock()

DR_API void dr_rwlock_write_lock

(

void *

rwlock

)

Acquires a write lock on rwlock.

dr_rwlock_write_trylock()

DR_API bool dr_rwlock_write_trylock

(

void *

rwlock

)

Tries once to acquire a write lock on rwlock and returns whether successful.

dr_rwlock_write_unlock()

DR_API void dr_rwlock_write_unlock

(

void *

rwlock

)

Releases a write lock on rwlock.

dr_set_client_name()

DR_API bool dr_set_client_name	(	const char *	name,
		const char *	report_URL
	)

Sets information presented to users in diagnostic messages. Only one name is supported, regardless of how many clients are in use. If this routine is called a second time, the new values supersede the original. The report_URL is meant to be a bug tracker location where users should go to report errors in the client end-user tool.

dr_set_client_version_string()

DR_API bool dr_set_client_version_string

(

const char *

version

)

Sets the version string presented to users in diagnostic messages. This has a maximum length of 96 characters; anything beyond that is silently truncated.

dr_set_itimer()

DR_API bool dr_set_itimer	(	int	which,
		uint	millisec,
		void(*)(void *drcontext, dr_mcontext_t *mcontext)	func
	)

Installs an interval timer in the itimer sharing group that contains the calling thread.

Parameters

[in]	which	Must be one of ITIMER_REAL, ITIMER_VIRTUAL, or ITIMER_PROF
[in]	millisec	The frequency of the timer, in milliseconds. Passing 0 disables the timer.
[in]	func	The function that will be called each time the timer fires. It will be passed the context of the thread that received the itimer signal and its machine context, which has not been translated and so may contain raw code cache values. The function will be called from a signal handler that may have interrupted a lock holder or other critical code, so it must be careful in its operations: keep it as simple as possible, and avoid any non-reentrant actions such as lock usage. If a general timer that does not interrupt client code is required, the client should create a separate thread via dr_create_client_thread() (which is guaranteed to have a private itimer) and set the itimer there, where the callback function can perform more operations safely if that new thread never acquires locks in its normal operation.

Itimer sharing varies by kernel. Prior to 2.6.12 itimers were thread-private; after 2.6.12 they are shared across a thread group, though there could be multiple thread groups in one address space. The dr_get_itimer() function can be used to see whether a thread already has an itimer in its group to avoid re-setting an itimer set by an earlier thread. A client thread created by dr_create_client_thread() is guaranteed to not share its itimers with application threads.

The itimer will operate successfully in the presence of an application itimer of the same type.

Additional itimer signals are blocked while in our signal handler.

The return value indicates whether the timer was successfully installed (or uninstalled if 0 was passed for millisec).

Note

Linux-only.

dr_set_random_seed()

DR_API void dr_set_random_seed

(

uint

seed

)

Sets the seed used for dr_get_random_value(). Generally this would only be called during client initialization.

dr_set_tls_field()

DR_API void dr_set_tls_field	(	void *	drcontext,
		void *	value
	)

Sets the user-controlled thread-local-storage field. To generate an instruction sequence that reads the drcontext field inline in the code cache, use dr_insert_write_tls_field().

dr_sleep()

DR_API void dr_sleep

(

int

time_ms

)

Current thread sleeps for time_ms milliseconds.

dr_snprintf()

DR_API int dr_snprintf	(	char *	buf,
		size_t	max,
		const char *	fmt,
			...
	)

Utility routine to print a formatted message to a string. Will not print more than max characters. If successful, returns the number of characters printed, not including the terminating null character. If the number of characters to write equals max, then the caller is responsible for supplying a terminating null character. If the number of characters to write exceeds max, then max characters are written and -1 is returned. If an error occurs, a negative value is returned.

Note

This routine supports printing wide characters via the ls or S format specifiers. On Windows, they are assumed to be UTF-16, and are converted to UTF-8. On Linux, they are converted by simply dropping the high-order bytes.

When printing floating-point values, the caller's code should use proc_save_fpstate() or be inside a clean call that has requested to preserve the floating-point state, unless it can prove that its compiler will not use x87 operations..

dr_snwprintf()

DR_API int dr_snwprintf	(	wchar_t *	buf,
		size_t	max,
		const wchar_t *	fmt,
			...
	)

Wide character version of dr_snprintf(). All of the comments for dr_snprintf() apply, except for the hs or S format specifiers. On Windows, these will assume that the input is UTF-8, and will convert to UTF-16. On Linux, they will widen a single-byte character string into a wchar_t character string with zero as the high-order bytes.

dr_sscanf()

DR_API int dr_sscanf	(	const char *	str,
		const char *	fmt,
			...
	)

Utility routine to parse strings that match a pre-defined format string, similar to the sscanf() C routine.

Parameters

[in]	str	String to parse.
[in]	fmt	Format string controlling parsing.
[out]	...	All remaining parameters interpreted as output parameter pointers. The type of each parameter must match the type implied by the corresponding format specifier in fmt.

Returns

The number of specifiers matched.

The benefit of using dr_sscanf() over native sscanf() is that DR's implementation is standalone, signal-safe, and cross-platform. On Linux, sscanf() has been observed to call malloc(). On Windows, sscanf() will call strlen(), which can break when using mapped files.

The behavior of dr_sscanf() is mostly identical to that of the sscanf() C routine.

Supported format specifiers:

• %s: Matches a sequence of non-whitespace characters. The string is copied into the provided output buffer. To avoid buffer overflow, the caller should use a width specifier.
• %c: Matches any single character.
• %d: Matches a signed decimal integer.
• %u: Matches an unsigned decimal integer.
• %x: Matches an unsigned hexadecimal integer, with or without a leading 0x.
• %p: Matches a pointer-sized hexadecimal integer as x does.
• %%: Matches a literal % character. Does not store output.

Supported format modifiers:

• *: The * modifier causes the scan to match the specifier, but not store any output. No output parameter is consumed for this specifier, and one should not be passed.
• 0-9: A decimal integer preceding the specifier gives the width to match. For strings, this indicates the maximum number of characters to copy. For integers, this indicates the maximum number of digits to parse.
• h: Marks an integer specifier as short.
• l: Marks an integer specifier as long.
• ll: Marks an integer specifier as long long. Use this for 64-bit integers.

Warning

dr_sscanf() does not support parsing floating point numbers yet.

dr_standalone_exit()

DR_API void dr_standalone_exit

(

void

)

Restores application state modified by dr_standalone_init(), which can include some signal handlers.

dr_standalone_init()

DR_API void* dr_standalone_init

(

void

)

Creates a DR context that can be used in a standalone program.

Warning

This context cannot be used as the drcontext for a thread running under DR control! It is only for standalone programs that wish to use DR as a library of disassembly, etc. routines.

This context is not fully thread-safe as it stores some state (such as dr_isa_mode_t and other fields related to AArch32 encoding and decoding) that is global and may be prone to data races. For example, having different threads use dr_set_isa_mode() to set different ISA modes at the same time can result in a data race. Furthermore, encoding and decoding of AArch32 instructions in parallel may also result in a data race. Code that uses a standalone DR context across multiple threads should implement its own lock/unlock mechanism to avoid such data races when using dr_set_isa_mode() or encoding/decoding AArch32 instructions.

Returns

NULL on failure, such as running on an unsupported operating system version.

dr_suspend_all_other_threads()

DR_API bool dr_suspend_all_other_threads	(	DR_PARAM_OUT void ***	drcontexts,
		DR_PARAM_OUT uint *	num_suspended,
		DR_PARAM_OUT uint *	num_unsuspended
	)

Identical to dr_suspend_all_other_threads_ex() with flags set to 0.

dr_suspend_all_other_threads_ex()

DR_API bool dr_suspend_all_other_threads_ex	(	DR_PARAM_OUT void ***	drcontexts,
		DR_PARAM_OUT uint *	num_suspended,
		DR_PARAM_OUT uint *	num_unsuspended,
		dr_suspend_flags_t	flags
	)

Suspends all other threads in the process and returns an array of contexts in drcontexts with one context per successfully suspended thread. The contexts can be passed to routines like dr_get_thread_id() or dr_get_mcontext(). However, the contexts may not be modified: dr_set_mcontext() is not supported. dr_get_mcontext() can be called on the caller of this routine, unless in a Windows nudge callback.

The flags argument controls which threads are suspended and may add further options in the future.

The number of successfully suspended threads, which is also the length of the drcontexts array, is returned in num_suspended, which is a required parameter. The number of un-successfully suspended threads, if any, is returned in the optional parameter num_unsuspended. The calling thread is not considered in either count. DR can fail to suspend a thread for privilege reasons (e.g., on Windows in a low-privilege process where another process injected a thread). This function returns true iff all threads were suspended, in which case num_unsuspended will be 0.

The caller must invoke dr_resume_all_other_threads() in order to resume the suspended threads, free the drcontexts array, and release coarse-grain locks that prevent new threads from being created.

This routine may not be called from any registered event callback other than the nudge event or the pre- or post-system call event. It may be called from clean calls out of the cache. This routine may not be called while any locks are held that could block a thread processing a registered event callback or cache callout.

Note

A client wishing to invoke this routine from an event callback can queue up a nudge via dr_nudge_client() and invoke this routine from the nudge callback.

dr_syscall_get_param()

DR_API reg_t dr_syscall_get_param	(	void *	drcontext,
		int	param_num
	)

Usable only from a pre-syscall (dr_register_pre_syscall_event()) event. Returns the value of system call parameter number param_num.

It is up to the caller to ensure that reading this parameter is safe: this routine does not know the number of parameters for each system call, nor does it check whether this might read off the base of the stack.

Note

On some platforms, notably MacOS, a 32-bit application's system call can still take a 64-bit parameter (typically on the stack). In that situation, this routine will consider the 64-bit parameter to be split into high and low parts, each with its own parameter number.

dr_syscall_get_result()

DR_API reg_t dr_syscall_get_result

(

void *

drcontext

)

Usable only from a post-syscall (dr_register_post_syscall_event()) event. Returns the return value of the system call that will be presented to the application.

Note

On some platforms (such as MacOS), a 32-bit application's system call can return a 64-bit value. Use dr_syscall_get_result_ex() to obtain the upper bits in that case.

On some platforms (such as MacOS), whether a system call succeeded or failed cannot be determined from the main result value. Use dr_syscall_get_result_ex() to obtain the success result in such cases.

dr_syscall_get_result_ex()

DR_API bool dr_syscall_get_result_ex	(	void *	drcontext,
		dr_syscall_result_info_t *info	DR_PARAM_OUT
	)

Usable only from a post-syscall (dr_register_post_syscall_event()) event. Returns whether it successfully retrieved the results of the system call into info.

The caller should set the size, use_high, and use_errno fields of info prior to calling this routine. See the fields of dr_syscall_result_info_t for details.

dr_syscall_intercept_natively()

DR_API bool dr_syscall_intercept_natively	(	const char *	name,
		int	sysnum,
		int	num_args,
		int	wow64_index
	)

Must be invoked from dr_client_main(). Requests that the named ntoskrnl system call be intercepted even when threads are native (e.g., due to DR_EMIT_GO_NATIVE). Only a limited number of system calls being intercepted while native are supported. This routine will fail once that limit is reached.

Parameters

[in]	name	The system call name. The name must match an exported system call wrapper in ntdll.dll.
[in]	sysnum	The system call number (the value placed in the eax register).
[in]	num_args	The number of arguments to the system call.
[in]	wow64_index	The value placed in the ecx register when this system call is executed in a WOW64 process. This value should be obtainable by examining the system call wrapper.

Note

Windows only.

dr_syscall_invoke_another()

DR_API void dr_syscall_invoke_another

(

void *

drcontext

)

Usable only from a post-syscall (dr_register_post_syscall_event()) event. An additional system call will be invoked immediately, using the current values of the parameters, which can be set with dr_syscall_set_param(). The system call to be invoked should be specified with dr_syscall_set_sysnum().

Use this routine with caution. Especially on Windows, care must be taken if the application is expected to continue afterward. When system call parameters are stored on the stack, modifying them can result in incorrect application behavior, particularly when setting more parameters than were present in the original system call, which will result in corruption of the application stack.

On Windows, when the first system call is interruptible (alertable), the additional system call may be delayed.

DR will set key registers such as r10 for 64-bit or xdx for sysenter or WOW64 system calls. However, DR will not set ecx for WOW64; that is up to the client.

dr_syscall_set_param()

DR_API void dr_syscall_set_param	(	void *	drcontext,
		int	param_num,
		reg_t	new_value
	)

Usable only from a pre-syscall (dr_register_pre_syscall_event()) event, or from a post-syscall (dr_register_post_syscall_event()) event when also using dr_syscall_invoke_another(). Sets the value of system call parameter number param_num to new_value.

It is up to the caller to ensure that writing this parameter is safe: this routine does not know the number of parameters for each system call, nor does it check whether this might write beyond the base of the stack.

Note

On some platforms, notably MacOS, a 32-bit application's system call can still take a 64-bit parameter (typically on the stack). In that situation, this routine will consider the 64-bit parameter to be split into high and low parts, each with its own parameter number.

dr_syscall_set_result()

DR_API void dr_syscall_set_result	(	void *	drcontext,
		reg_t	value
	)

Usable only from a pre-syscall (dr_register_pre_syscall_event()) or post-syscall (dr_register_post_syscall_event()) event. For pre-syscall, should only be used when skipping the system call. This sets the return value of the system call that the application sees to value.

Note

On MacOS, do not use this function as it fails to set the carry flag and thus fails to properly indicate whether the system call succeeded or failed: use dr_syscall_set_result_ex() instead.

dr_syscall_set_result_ex()

DR_API bool dr_syscall_set_result_ex	(	void *	drcontext,
		dr_syscall_result_info_t *	info
	)

Usable only from a pre-syscall (dr_register_pre_syscall_event()) or post-syscall (dr_register_post_syscall_event()) event. For pre-syscall, should only be used when skipping the system call.

This sets the returned results of the system call as specified in info. Returns whether it successfully did so. See the fields of dr_syscall_result_info_t for details.

dr_syscall_set_sysnum()

DR_API void dr_syscall_set_sysnum	(	void *	drcontext,
		int	new_num
	)

Usable only from a pre-syscall (dr_register_pre_syscall_event()) event, or from a post-syscall (dr_register_post_syscall_event()) event when also using dr_syscall_invoke_another(). Sets the system call number of the system call about to be invoked to new_num.

dr_thread_alloc()

DR_API void* dr_thread_alloc	(	void *	drcontext,
		size_t	size
	)

Allocates size bytes of memory from DR's memory pool specific to the thread associated with drcontext. This memory is only guaranteed to be aligned to the pointer size: 8 byte alignment for 64-bit; 4-byte alignment for 32-bit. (The wrapped malloc() guarantees the more standard double-pointer-size.)

dr_thread_free()

DR_API void dr_thread_free	(	void *	drcontext,
		void *	mem,
		size_t	size
	)

Frees thread-specific memory allocated by dr_thread_alloc(). size must be the same as that passed to dr_thread_alloc().

dr_thread_yield()

DR_API void dr_thread_yield

(

void

)

Current thread gives up its time quantum.

dr_trace_exists_at()

DR_API bool dr_trace_exists_at	(	void *	drcontext,
		void *	tag
	)

Checks to see that if there is a trace in the code cache at tag tag.

dr_trace_head_at()

DR_API bool dr_trace_head_at	(	void *	drcontext,
		void *	tag
	)

Checks to see if the fragment (or future fragment) with tag tag is marked as a trace head.

dr_track_where_am_i()

DR_API void dr_track_where_am_i

(

void

)

Should be called during process initialization. Requests more accurate tracking of the dr_where_am_i_t value for use with dr_where_am_i(). By default, if this routine is not called, DR avoids some updates to the value that incur extra overhead, such as identifying clean callees.

dr_unlink_flush_region()

DR_API bool dr_unlink_flush_region	(	app_pc	start,
		size_t	size
	)

Flush all fragments containing any code from the region [start, start + size). Control will not enter a fragment containing code from the region after this returns, but a thread already in such a fragment will finish out the fragment. This includes the current thread if this is called from a clean call that returns to the cache. This routine may only be called during a clean call from the cache, from a nudge event handler, or from a pre- or post-system call event handler. It may not be called from any other event callback. No locks can be held when calling this routine. Returns true if successful.

Note

This routine may not be called from any registered event callback other than the nudge event, the pre- or post-system call events, the exception event, or the signal event; clean calls out of the cache may call this routine.

This routine may not be called while any locks are held that could block a thread processing a registered event callback or cache callout.

dr_delay_flush_region() has fewer restrictions on use, but is less synchronous.

Use size == 1 to flush fragments containing the instruction at address start. A flush of size == 0 is not allowed.

This routine is only available with either the -thread_private or -enable_full_api options. It is not available when -opt_memory is specified.

dr_unmap_executable_file()

DR_API bool dr_unmap_executable_file	(	byte *	base,
		size_t	size
	)

Unmaps a file loaded by dr_map_executable_file().

dr_unmap_file()

DR_API bool dr_unmap_file	(	void *	map,
		size_t	size
	)

Unmaps a portion of a file mapping previously created by dr_map_file().

Returns

whether successful.

Parameters

[in]	map	The base address to be unmapped. Must be page size aligned.
[in]	size	The size to be unmapped. All pages overlapping with the range are unmapped.

Note

On Windows, the whole file will be unmapped instead.

dr_using_all_private_caches()

DR_API bool dr_using_all_private_caches

(

void

)

Returns true if all DynamoRIO caches are thread private.

dr_using_console()

DR_API bool dr_using_console

(

void

)

Returns true if the current standard error handle belongs to a legacy console window (viz., cmd on Windows 7 or earlier). DR's dr_printf() and dr_fprintf() do not work with such console windows unless dr_enable_console_printing() is called ahead of time, and even then there are limitations detailed in dr_enable_console_printing(). This routine may result in loading a private copy of kernel32.dll.

Note

Windows only.

dr_vfprintf()

DR_API ssize_t dr_vfprintf	(	file_t	f,
		const char *	fmt,
		va_list	ap
	)

Identical to dr_fprintf() but exposes va_list.

dr_vsnprintf()

DR_API int dr_vsnprintf	(	char *	buf,
		size_t	max,
		const char *	fmt,
		va_list	ap
	)

Identical to dr_snprintf() but exposes va_list.

dr_vsnwprintf()

DR_API int dr_vsnwprintf	(	wchar_t *	buf,
		size_t	max,
		const wchar_t *	fmt,
		va_list	ap
	)

Identical to dr_snwprintf() but exposes va_list.

dr_where_am_i()

DR_API dr_where_am_i_t dr_where_am_i	(	void *	drcontext,
		app_pc	pc,
		DR_PARAM_OUT void **	tag
	)

Returns the dr_where_am_i_t value indicating in which area of code pc resides. This is meant for use with dr_set_itimer() for PC sampling for profiling purposes. If the optional tag is non-NULL and pc is inside a fragment in the code cache, the fragment's tag is returned in tag. It is recommended that the user of this routine also call dr_track_where_am_i() during process initialization for more accurate results.

dr_write_file()

DR_API ssize_t dr_write_file	(	file_t	f,
		const void *	buf,
		size_t	count
	)

Writes count bytes from buf to file f. Returns the actual number written.