Memory Debugger for Windows, Linux, and Mac
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_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 (DR_PARAM_OUT bool *initialized)
 
DR_EXPORT drmf_status_t drsymcache_module_is_cached (const module_data_t *mod, DR_PARAM_OUT bool *cached)
 
DR_EXPORT drmf_status_t drsymcache_module_has_debug_info (const module_data_t *mod, DR_PARAM_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, DR_PARAM_OUT size_t **offs_array, DR_PARAM_OUT uint *num_entries, DR_PARAM_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_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 ( DR_PARAM_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,
DR_PARAM_OUT size_t **  offs_array,
DR_PARAM_OUT uint *  num_entries,
DR_PARAM_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,
DR_PARAM_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,
DR_PARAM_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.