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] | mod | The module whose symcache should be updated.
  [in] | symbol | The name of the symbol being added.
  [in] | offs | The 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_id | The id of the client using drsymcache, as passed to dr_init().
  [in] | drsymcache_dir | The 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_threshold | The 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] | initialized | Whether 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] | mod | The module being queried.
  [in] | symbol | The name of the symbol being queried.
  [out] | offs_array | Returns 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_single | Since 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_entries | The 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] | mod | The module being queried.
  [out] | has_debug | Whether 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] | mod | The module being queried.
  [out] | cached | Whether 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] | mod | The module to save.

Returns
  success code.