--- title: "drsymcache.h File Reference" layout: default permalink: /drsymcache_8h.html ---
Dr. Memory
Macros | Enumerations | Functions
drsymcache.h File Reference

Header for Dr. SymCache: Symbol Lookup Cache Extension. More...

#include "drmemory_framework.h"
#include "drmgr.h"

Macros

#define DRMGR_PRIORITY_NAME_DRSYMCACHE   "drsymcache"
 
#define DRMGR_PRIORITY_NAME_DRSYMCACHE_SAVE   "drsymcache_save"
 

Enumerations

enum  {
  DRMGR_PRIORITY_PRESYS_DRSYS = -100,
  DRMGR_PRIORITY_POSTSYS_DRSYS = -100,
  DRMGR_PRIORITY_POSTSYS_DRSYS_LAST = 10000,
  DRMGR_PRIORITY_MODLOAD_DRSYS = -100,
  DRMGR_PRIORITY_EXCPT_UMBRA = -100,
  DRMGR_PRIORITY_MODLOAD_DRSYMCACHE_READ = -150,
  DRMGR_PRIORITY_MODLOAD_DRSYMCACHE_SAVE = 150,
  DRMGR_PRIORITY_MODUNLOAD_DRSYMCACHE = -150
}
 

Functions

DR_EXPORT drmf_status_t drsymcache_init (client_id_t client_id, const char *drsymcache_dir, size_t modsize_cache_threshold)
 
DR_EXPORT drmf_status_t drsymcache_exit (void)
 
DR_EXPORT drmf_status_t drsymcache_is_initialized (OUT bool *initialized)
 
DR_EXPORT drmf_status_t drsymcache_module_is_cached (const module_data_t *mod, OUT bool *cached)
 
DR_EXPORT drmf_status_t drsymcache_module_has_debug_info (const module_data_t *mod, OUT bool *has_debug)
 
DR_EXPORT drmf_status_t drsymcache_module_save_symcache (const module_data_t *mod)
 
DR_EXPORT drmf_status_t drsymcache_add (const module_data_t *mod, const char *symbol, size_t offs)
 
DR_EXPORT drmf_status_t drsymcache_lookup (const module_data_t *mod, const char *symbol, OUT size_t **offs_array, OUT uint *num_entries, OUT size_t *offs_single)
 
DR_EXPORT drmf_status_t drsymcache_free_lookup (size_t *offs, uint num)
 

Detailed Description

Header for Dr. SymCache: Symbol Lookup Cache Extension.

Macro Definition Documentation

◆ DRMGR_PRIORITY_NAME_DRSYMCACHE

#define DRMGR_PRIORITY_NAME_DRSYMCACHE   "drsymcache"

Name of drsymcache events DRMGR_PRIORITY_MODLOAD_DRSYMCACHE_READ and DRMGR_PRIORITY_MODUNLOAD_DRSYMCACHE.

◆ DRMGR_PRIORITY_NAME_DRSYMCACHE_SAVE

#define DRMGR_PRIORITY_NAME_DRSYMCACHE_SAVE   "drsymcache_save"

Name of drsymcache events DRMGR_PRIORITY_MODLOAD_DRSYMCACHE_SAVE.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Priority of drsymcache events.

Enumerator
DRMGR_PRIORITY_PRESYS_DRSYS 

Priority of the drsyscall pre-syscall and post-syscall events that are meant to take place before the corresponding events of a regular user of drsyscall. Dynamic iteration is not allowed until these events have taken place. Users of drsyscall should arrange their pre-syscall and post-syscall event callbacks to be called after the drsyscall event, unless they want to modify the pre-syscall arguments before they're stored or they want to modify the application's context, in which case their event should go beforehand.

DRMGR_PRIORITY_POSTSYS_DRSYS 

See the comment for DRMGR_PRIORITY_PRESYS_DRSYS.

DRMGR_PRIORITY_POSTSYS_DRSYS_LAST 

Priority of the drsyscall last-chance post-syscall event. This event must take place after any dynamic iteration of system call arguments, which means it must be after the post-syscall event in all users of drsyscall.

DRMGR_PRIORITY_MODLOAD_DRSYS 

Priority of the drsyscall module load event. This event must take place before any user of drsyscall in order to populate the tables used by drsys_name_to_syscall().

DRMGR_PRIORITY_EXCPT_UMBRA 

Priority of the Umbra signal/exception handling event. This event must take place before any user of drsyscall in order to allocate shadow memory if necessary.

DRMGR_PRIORITY_MODLOAD_DRSYMCACHE_READ 

Priority of the drsymcache module load event action that checks for a symbol cache file and reads it in. This event must occur before any drsymcache API usage in module load events of users of drsymcache.

DRMGR_PRIORITY_MODLOAD_DRSYMCACHE_SAVE 

Priority of the drsymcache module load event action that saves the current symbol cache from memory to disk.

DRMGR_PRIORITY_MODUNLOAD_DRSYMCACHE 

Priority of the drsymcache module unload event action that saves the current symbol cache from memory to disk and then frees the in-memory cache data structures. This event must occur after any drsymcache API usage in module unload events of users of drsymcache.

Function Documentation

◆ drsymcache_add()

DR_EXPORT drmf_status_t drsymcache_add ( const module_data_t *  mod,
const char *  symbol,
size_t  offs 
)

Adds a new entry for the symbol name symbol to the symbol cache for mod. If an entry already exists and is 0, replaces it; else adds a new value equal to offset for that symbol.

Parameters
[in]modThe module whose symcache should be updated.
[in]symbolThe name of the symbol being added.
[in]offsThe offset from the module base to add.
Returns
success code. If there is no cache for this module, returns DRMF_ERROR_NOT_FOUND.

◆ drsymcache_exit()

DR_EXPORT drmf_status_t drsymcache_exit ( void  )

Cleans up drsymcache.

Returns
success code.

◆ drsymcache_free_lookup()

DR_EXPORT drmf_status_t drsymcache_free_lookup ( size_t *  offs,
uint  num 
)

Frees the array of offsets allocated by drsymcache_lookup().

Returns
success code.

◆ drsymcache_init()

DR_EXPORT drmf_status_t drsymcache_init ( client_id_t  client_id,
const char *  drsymcache_dir,
size_t  modsize_cache_threshold 
)

Initializes drsymcache. Can be called multiple times (by separate components, normally) but each call must be paired with a corresponding call to drsymcache_exit(), and only the first call's parameters are honored: subsequent calls return DRMF_WARNING_ALREADY_INITIALIZED and ignore the parameters passed in favor of those passed to the original call. Libraries that use drsymcache should typically require that their callers initialize drsymcache, as the location of the cache files is usually a top-level tool property.

Parameters
[in]client_idThe id of the client using drsymcache, as passed to dr_init().
[in]drsymcache_dirThe directory in which to store symbol cache files. If this directory does not exist, drsymcache will attempt to create it, and return DRMF_ERROR_INVALID_PARAMETER on failure.
[in]modsize_cache_thresholdThe minimum module size for which symbols should be cached. Normally there's little downside to caching, so passing 0 here is reasonable.
Returns
success code.

◆ drsymcache_is_initialized()

DR_EXPORT drmf_status_t drsymcache_is_initialized ( OUT bool *  initialized)

Queries whether drsymcache has been initialized.

Parameters
[out]initializedWhether drsymcache is initialized.
Returns
success code.

◆ drsymcache_lookup()

DR_EXPORT drmf_status_t drsymcache_lookup ( const module_data_t *  mod,
const char *  symbol,
OUT size_t **  offs_array,
OUT uint *  num_entries,
OUT size_t *  offs_single 
)

Queries the symbol cache for mod. If symbol is not present in the cache, returns DRMF_ERROR_NOT_FOUND. If symbol is present, allocates and returns an array of all entries found. The size of the array is returned in num. The array must be freed by calling drsymcache_free_lookup().

Parameters
[in]modThe module being queried.
[in]symbolThe name of the symbol being queried.
[out]offs_arrayReturns a pointer to an array of offsets from the module base containing the locations of each instance of the symbol. If the symbol is not present in the module, there will only be one entry with offset of 0.
[out]offs_singleSince many symbols have only one entry, to avoid the overhead of allocating memory the caller must pass in a single slot that offs_array will point to if num_entries is just 1.
[out]num_entriesThe total count of instances of symbol within the module.
Returns
success code.

◆ drsymcache_module_has_debug_info()

DR_EXPORT drmf_status_t drsymcache_module_has_debug_info ( const module_data_t *  mod,
OUT bool *  has_debug 
)

Queries whether mod has debug information (any symbol information, even if there is no line number information: i.e., whether the symbol is stripped).

Parameters
[in]modThe module being queried.
[out]has_debugWhether the module has debug information.
Returns
success code.

◆ drsymcache_module_is_cached()

DR_EXPORT drmf_status_t drsymcache_module_is_cached ( const module_data_t *  mod,
OUT bool *  cached 
)

Queries whether mod has a corresponding symbol cache.

Parameters
[in]modThe module being queried.
[out]cachedWhether the module has a symbol cache.
Returns
success code.

◆ drsymcache_module_save_symcache()

DR_EXPORT drmf_status_t drsymcache_module_save_symcache ( const module_data_t *  mod)

Proactively writes the symbol cache file corresponding to mod to disk. Symbol cache files are automatically saved at three points, without the user needing to invoke this routine: after a module is loaded (with a late priority DRMGR_PRIORITY_MODLOAD_DRSYMCACHE_SAVE), when a module is unloaded (with priority DRMGR_PRIORITY_MODUNLOAD_DRSYMCACHE), and when the final drsymcache_exit() is called.

Parameters
[in]modThe module to save.
Returns
success code.