DynamoRIO API
Symbol Access Library

Data Structures

struct  _drsym_info_t
 
struct  _drsym_type_t
 
struct  _drsym_func_type_t
 
struct  _drsym_compound_type_t
 
struct  _drsym_int_type_t
 
struct  _drsym_ptr_type_t
 
struct  _drsym_line_info_t
 

Typedefs

typedef struct _drsym_info_t drsym_info_t
 
typedef struct _drsym_type_t drsym_type_t
 
typedef struct _drsym_func_type_t drsym_func_type_t
 
typedef struct _drsym_compound_type_t drsym_compound_type_t
 
typedef struct _drsym_int_type_t drsym_int_type_t
 
typedef struct _drsym_ptr_type_t drsym_ptr_type_t
 
typedef bool(* drsym_enumerate_cb) (const char *name, size_t modoffs, void *data)
 
typedef bool(* drsym_enumerate_ex_cb) (drsym_info_t *info, drsym_error_t status, void *data)
 
typedef struct _drsym_line_info_t drsym_line_info_t
 
typedef bool(* drsym_enumerate_lines_cb) (drsym_line_info_t *info, void *data)
 

Enumerations

enum  drsym_error_t {
  DRSYM_SUCCESS,
  DRSYM_ERROR,
  DRSYM_ERROR_INVALID_PARAMETER,
  DRSYM_ERROR_INVALID_SIZE,
  DRSYM_ERROR_LOAD_FAILED,
  DRSYM_ERROR_SYMBOL_NOT_FOUND,
  DRSYM_ERROR_LINE_NOT_AVAILABLE,
  DRSYM_ERROR_NOT_IMPLEMENTED,
  DRSYM_ERROR_FEATURE_NOT_AVAILABLE,
  DRSYM_ERROR_NOMEM,
  DRSYM_ERROR_RECURSIVE
}
 
enum  drsym_flags_t {
  DRSYM_LEAVE_MANGLED = 0x00,
  DRSYM_DEMANGLE = 0x01,
  DRSYM_DEMANGLE_FULL = 0x02,
  DRSYM_DEMANGLE_PDB_TEMPLATES = 0x04,
  DRSYM_FULL_SEARCH = 0x08,
  DRSYM_DEFAULT_FLAGS = DRSYM_DEMANGLE
}
 
enum  drsym_debug_kind_t {
  DRSYM_SYMBOLS = (1 << 0),
  DRSYM_LINE_NUMS = (1 << 1),
  DRSYM_ELF_SYMTAB = (1 << 8),
  DRSYM_DWARF_LINE = (1 << 9),
  DRSYM_PDB = (1 << 10),
  DRSYM_PECOFF_SYMTAB = (1 << 11),
  DRSYM_MACHO_SYMTAB = (1 << 12)
}
 
enum  {
  DRSYM_TYPE_OTHER,
  DRSYM_TYPE_INT,
  DRSYM_TYPE_PTR,
  DRSYM_TYPE_FUNC,
  DRSYM_TYPE_VOID,
  DRSYM_TYPE_COMPOUND
}
 

Functions

DR_EXPORT drsym_error_t drsym_init (IF_WINDOWS_ELSE(const wchar_t *, int) shmid)
 
DR_EXPORT drsym_error_t drsym_exit (void)
 
DR_EXPORT drsym_error_t drsym_lookup_address (const char *modpath, size_t modoffs, drsym_info_t *info, uint flags)
 
DR_EXPORT drsym_error_t drsym_get_type (const char *modpath, size_t modoffs, uint levels_to_expand, char *buf, size_t buf_sz, drsym_type_t **type)
 
DR_EXPORT drsym_error_t drsym_get_type_by_name (const char *modpath, const char *type_name, char *buf, size_t buf_sz, drsym_type_t **type)
 
DR_EXPORT drsym_error_t drsym_get_func_type (const char *modpath, size_t modoffs, char *buf, size_t buf_sz, drsym_func_type_t **func_type)
 
DR_EXPORT drsym_error_t drsym_expand_type (const char *modpath, uint type_id, uint levels_to_expand, char *buf, size_t buf_sz, drsym_type_t **expanded_type)
 
DR_EXPORT drsym_error_t drsym_lookup_symbol (const char *modpath, const char *symbol, size_t *modoffs, uint flags)
 
DR_EXPORT drsym_error_t drsym_enumerate_symbols (const char *modpath, drsym_enumerate_cb callback, void *data, uint flags)
 
DR_EXPORT drsym_error_t drsym_enumerate_symbols_ex (const char *modpath, drsym_enumerate_ex_cb callback, size_t info_size, void *data, uint flags)
 
DR_EXPORT size_t drsym_demangle_symbol (char *dst, size_t dst_sz, const char *mangled, uint flags)
 
DR_EXPORT drsym_error_t drsym_get_module_debug_kind (const char *modpath, drsym_debug_kind_t *kind)
 
DR_EXPORT drsym_error_t drsym_module_has_symbols (const char *modpath)
 
DR_EXPORT drsym_error_t drsym_search_symbols (const char *modpath, const char *match, bool full, drsym_enumerate_cb callback, void *data)
 
DR_EXPORT drsym_error_t drsym_search_symbols_ex (const char *modpath, const char *match, uint flags, drsym_enumerate_ex_cb callback, size_t info_size, void *data)
 
DR_EXPORT drsym_error_t drsym_free_resources (const char *modpath)
 
DR_EXPORT drsym_error_t drsym_enumerate_lines (const char *modpath, drsym_enumerate_lines_cb callback, void *data)
 

Detailed Description

Typedef Documentation

Type information for a user-defined type: a struct, union, or class.

typedef bool(* drsym_enumerate_cb) (const char *name, size_t modoffs, void *data)

Type for drsym_enumerate_symbols and drsym_search_symbols callback function. Returns whether to continue the enumeration or search.

Parameters
[in]nameName of the symbol.
[in]modoffsOffset of the symbol from the module base. For Mach-O, the module base is after any __PAGEZERO segment.
[in]dataUser parameter passed to drsym_enumerate_symbols() or drsym_search_symbols().
typedef bool(* drsym_enumerate_ex_cb) (drsym_info_t *info, drsym_error_t status, void *data)

Type for drsym_enumerate_symbols_ex and drsym_search_symbols_ex callback function. Returns whether to continue the enumeration or search.

Parameters
[in]infoInformation about the symbol.
[in]statusStatus of info: either DRSYM_SUCCESS to indicate that all fields are filled in, or DRSYM_ERROR_LINE_NOT_AVAILABLE to indicate that line number information was not obtained. Line information is currently not available for any debug type when iterating. This has no bearing on whether line information is available when calling drsym_lookup_address().
[in]dataUser parameter passed to drsym_enumerate_symbols() or drsym_search_symbols().
typedef bool(* drsym_enumerate_lines_cb) (drsym_line_info_t *info, void *data)

Type for drsym_enumerate_lines callback function. Returns whether to continue the enumeration.

Parameters
[in]infoInformation about the line.
[in]dataUser parameter passed to drsym_enumerate_lines().

Type information for a function.

typedef struct _drsym_info_t drsym_info_t

Data structure that holds symbol information

Type information for an integer base type.

Line information returned by drsym_enumerate_lines(). This information should not be relied upon to be accessible beyond the return of the callback routine to which it is passed.

Note
On Windows, we have observed abnormally large values for line and line_addr (e.g., 0xfeefee or 0xe0b80000) in some symbol files. Be prepared for such values.

Type information for a pointer & array types.

typedef struct _drsym_type_t drsym_type_t

Base type information. Use the 'kind' member to downcast to a more specific type.

Enumeration Type Documentation

anonymous enum
Enumerator
DRSYM_TYPE_OTHER 

Unknown type, cannot downcast.

DRSYM_TYPE_INT 

Integer, cast to drsym_int_type_t.

DRSYM_TYPE_PTR 

Pointer, cast to drsym_ptr_type_t.

DRSYM_TYPE_FUNC 

Function, cast to drsym_func_type_t.

DRSYM_TYPE_VOID 

Void. No further information.

DRSYM_TYPE_COMPOUND 

Struct, union, or class; cast to drsym_compound_type_t.

Bitfield indicating the availability of different kinds of debugging information for a module. The first 8 bits are reserved for platform independent qualities of the debug info, while the rest indicate exactly which kind of debug information is present.

Enumerator
DRSYM_SYMBOLS 

Any symbol information beyond exports.

DRSYM_LINE_NUMS 

Any line number info.

DRSYM_ELF_SYMTAB 

ELF .symtab symbol names.

DRSYM_DWARF_LINE 

DWARF line info.

DRSYM_PDB 

Windows PDB files.

DRSYM_PECOFF_SYMTAB 

PE COFF (Cygwin or MinGW) symbol table names.

DRSYM_MACHO_SYMTAB 

Mach-O symbol table names.

Success code for each DRSyms operation

Enumerator
DRSYM_SUCCESS 

Operation succeeded.

DRSYM_ERROR 

Operation failed.

DRSYM_ERROR_INVALID_PARAMETER 

Operation failed: invalid parameter

DRSYM_ERROR_INVALID_SIZE 

Operation failed: invalid size

DRSYM_ERROR_LOAD_FAILED 

Operation failed: unable to load symbols

DRSYM_ERROR_SYMBOL_NOT_FOUND 

Operation failed: symbol not found

DRSYM_ERROR_LINE_NOT_AVAILABLE 

Operation failed: line info not available

DRSYM_ERROR_NOT_IMPLEMENTED 

Operation failed: not yet implemented

DRSYM_ERROR_FEATURE_NOT_AVAILABLE 

Operation failed: not available

DRSYM_ERROR_NOMEM 

Operation failed: not enough memory

DRSYM_ERROR_RECURSIVE 

Operation failed: unavailable when recursive

Bitfield of options to each DRSyms operation.

Enumerator
DRSYM_LEAVE_MANGLED 

Do not demangle C++ symbols. This option is not available for Windows PDB symbols.

DRSYM_DEMANGLE 

Demangle C++ symbols, omitting templates and parameter types. For all symbol types, templates are collapsed to <> while function parameters are omitted entirely (without any parentheses).

DRSYM_DEMANGLE_FULL 

Demangle template arguments and parameter types. This option is not available for Windows PDB symbols (except in drsym_demangle_symbol()).

DRSYM_DEMANGLE_PDB_TEMPLATES 

For Windows PDB, do not collapse templates to <>.

DRSYM_FULL_SEARCH 

Windows-only, for drsym_search_symbols_ex(). Requests a full search for all symbols and not just functions. This adds overhead: see drsym_search_symbols_ex() for details.

DRSYM_DEFAULT_FLAGS 

Default flags.

Function Documentation

DR_EXPORT size_t drsym_demangle_symbol ( char *  dst,
size_t  dst_sz,
const char *  mangled,
uint  flags 
)

Given a mangled or decorated C++ symbol, outputs the source name into dst. If the unmangled name requires more than dst_sz bytes, it is truncated and null-terminated to fit into dst. If the unmangling fails, symbol is copied as-is into dst, and truncated and null-terminated to fit. Returns zero if the name could not be unmangled; else returns the number of characters in the unmangled name, including the terminating null.

If the unmangling is successful but dst is too small to hold it, returns the number of characters required to store the name, including the terminating null, just as in a successful case. On Linux or for Windows PDB, symbol is copied as-is into dst just like for unmangling failure; for Windows PECOFF, the unmangled name is copied, truncated to fit, and null-terminated.

If there was overflow, the return value may be an estimate of the required size, so a second attempt with the return value is not guaranteed to be successful. If the caller needs the full name, they may need to make multiple attempts with a larger buffer.

Note
If the passed-in mangled symbol is truncated already, there is no guarantee that the demangling will even partically succeed.
Parameters
[out]dstOutput buffer for demangled name.
[in]dst_szSize of the output buffer in bytes.
[in]mangledMangled C++ symbol to demangle.
[in]flagsOptions for the operation as a combination of drsym_flags_t values. DRSYM_DEMANGLE is implied.
DR_EXPORT drsym_error_t drsym_enumerate_lines ( const char *  modpath,
drsym_enumerate_lines_cb  callback,
void *  data 
)

Enumerates all source lines for a given module. Calls the given callback function for each line. If the callback returns false, the enumeration will end.

If an individual compilation unit is missing line number information, the callback will still be called once for that unit, with the fields other than cu_name set to NULL or 0.

Parameters
[in]modpathThe full path to the module to be queried.
[in]callbackFunction to call for each line.
[in]dataUser parameter passed to callback.
DR_EXPORT drsym_error_t drsym_enumerate_symbols ( const char *  modpath,
drsym_enumerate_cb  callback,
void *  data,
uint  flags 
)

Enumerates all symbol information for a given module, including exports. Calls the given callback function for each symbol. If the callback returns false, the enumeration will end.

Parameters
[in]modpathThe full path to the module to be queried.
[in]callbackFunction to call for each symbol found.
[in]dataUser parameter passed to callback.
[in]flagsOptions for the operation as a combination of drsym_flags_t values. Ignored for Windows PDB (DRSYM_PDB) except for DRSYM_DEMANGLE_PDB_TEMPLATES.
DR_EXPORT drsym_error_t drsym_enumerate_symbols_ex ( const char *  modpath,
drsym_enumerate_ex_cb  callback,
size_t  info_size,
void *  data,
uint  flags 
)

Enumerates all symbol information for a given module, including exports. Calls the given callback function for each symbol, passing full information about the symbol (as opposed to selected information returned by drsym_enumerate_symbols()). If the callback returns false, the enumeration will end.

Parameters
[in]modpathThe full path to the module to be queried.
[in]callbackFunction to call for each symbol found.
[in]info_sizeThe size of the drsym_info_t struct to pass to callback. Enough space for each name will be allocated automatically.
[in]dataUser parameter passed to callback.
[in]flagsOptions for the operation as a combination of drsym_flags_t values. Ignored for Windows PDB (DRSYM_PDB) except for DRSYM_DEMANGLE_PDB_TEMPLATES.
DR_EXPORT drsym_error_t drsym_exit ( void  )

Clean up and shut down the symbol access library.

DR_EXPORT drsym_error_t drsym_expand_type ( const char *  modpath,
uint  type_id,
uint  levels_to_expand,
char *  buf,
size_t  buf_sz,
drsym_type_t **  expanded_type 
)

Retrieves symbol type information for all sub-types of the type referenced by type_id. After a successful execution, *expanded_type points to the expanded type. All memory used to represent the types comes from buf, so the caller only needs to dispose buf to free them. Returns DRSYM_ERROR_NOMEM if the buffer is not big enough.

The initial type index to pass as type_id can be retrieved by calling drsym_get_type() or drsym_get_func_type().

The resulting expanded type tree may be recursive, so the caller should take care when traversing it. Any already-referenced type is guaranteed to have a smaller pointer value than its parent. This allows safe traversing without recording the already-seen types.

Note
This function is currently implemented only for Windows PDB symbols (DRSYM_PDB).
The public Windows symbol files typically do not contain type information for function parameters.
Parameters
[in]modpathThe full path to the module to be queried.
[in]type_idThe type index, acquired from a prior call to drsym_get_type() or drsym_get_func_type().
[in]levels_to_expandThe maximum levels of sub-types to expand. Set to UINT_MAX for unlimited expansion.
[out]bufMemory used for the types.
[in]buf_szNumber of bytes in buf.
[out]expanded_typePointer to the expanded type tree for the symbol.
DR_EXPORT drsym_error_t drsym_free_resources ( const char *  modpath)

Indicates that no further symbol queries will be performed and that this module's debug information can be de-allocated. A later query will result in a new load. The typical usage is to call this after a series of queries at module load. For large applications with many libraries, calling this can save hundreds of MB of memory.

Parameters
[in]modpathThe full path to the module to be unloaded.
Note
When called from within a callback for drsym_enumerate_symbols() or drsym_search_symbols(), will fail with DRSYM_ERROR_RECURSIVE as it is not safe to free resources while iterating.
DR_EXPORT drsym_error_t drsym_get_func_type ( const char *  modpath,
size_t  modoffs,
char *  buf,
size_t  buf_sz,
drsym_func_type_t **  func_type 
)

Retrieves function type information for a given module offset. After a successful execution, *func_type points to the function type. All memory used to represent the types comes from buf, so the caller only needs to dispose buf to free them. Returns DRSYM_ERROR_NOMEM if the buffer is not big enough.

This routine does not expand arguments of function or compound types into their child types.

Note
This function is currently implemented only for Windows PDB symbols (DRSYM_PDB).
The public Windows symbol files typically do not contain type information for function parameters.
Despite the name, this routine will retrieve type information for non-functions as well.
Parameters
[in]modpathThe full path to the module to be queried.
[in]modoffsThe offset from the base of the module specifying the start address of the function. For Mach-O, the module base is after any __PAGEZERO segment.
[out]bufMemory used for the types.
[in]buf_szNumber of bytes in buf.
[out]func_typePointer to the type of the function.
DR_EXPORT drsym_error_t drsym_get_module_debug_kind ( const char *  modpath,
drsym_debug_kind_t kind 
)

Outputs the kind of debug information available for the module modpath in *kind if the operation succeeds.

Parameters
[in]modpathThe full path to the module to be queried.
[out]kindThe kind of debug information available.
DR_EXPORT drsym_error_t drsym_get_type ( const char *  modpath,
size_t  modoffs,
uint  levels_to_expand,
char *  buf,
size_t  buf_sz,
drsym_type_t **  type 
)

Retrieves symbol type information for a given module offset. After a successful execution, *type points to the function type. All memory used to represent the types comes from buf, so the caller only needs to dispose buf to free them. Returns DRSYM_ERROR_NOMEM if the buffer is not big enough.

This routine expands arguments of function or fields compound types into their child types as far as levels_to_expand levels deep. The resulting expanded type tree may be recursive, so the caller should take care when traversing it. Any already-referenced type is guaranteed to have a smaller pointer value than its parent. This allows safe traversing without recording the already-seen types.

When querying type information for a symbol that has already been located via drsym_lookup_address() or via enumeration or searching, it is better to invoke drsym_expand_type() using the type_id parameter of drsym_info_t to properly handle cases where multiple symbols map to the same module offset.

Note
This function is currently implemented only for Windows PDB symbols (DRSYM_PDB).
Parameters
[in]modpathThe full path to the module to be queried.
[in]modoffsThe offset from the base of the module specifying the start address of the function. For Mach-O, the module base is after any __PAGEZERO segment.
[in]levels_to_expandThe maximum levels of sub-types to expand. Set to UINT_MAX for unlimited expansion. Further expansion can be performed by calling drsym_expand_type().
[out]bufMemory used for the types.
[in]buf_szNumber of bytes in buf.
[out]typePointer to the type of the function.
DR_EXPORT drsym_error_t drsym_get_type_by_name ( const char *  modpath,
const char *  type_name,
char *  buf,
size_t  buf_sz,
drsym_type_t **  type 
)

Retrieves symbol type information for a given type_name. After a successful execution, *type points to the type of the symbol. All memory used to represent the type comes from buf, so the caller only needs to dispose buf to free everything. Returns DRSYM_ERROR_NOMEM if the buffer is not big enough.

Note
This function is currently implemented only for Windows PDB symbols (DRSYM_PDB).
Parameters
[in]modpathThe full path to the module to be queried.
[in]type_nameThe string name of the base type.
[out]bufMemory used for the type.
[in]buf_szNumber of bytes in buf.
[out]typePointer to the type for the symbol.
DR_EXPORT drsym_error_t drsym_init ( IF_WINDOWS_ELSE(const wchar_t *, int)  shmid)

Initialize the symbol access library. Can be called multiple times (by separate components, normally) but each call must be paired with a corresponding call to drsym_exit(), and only the symbol server parameter of the first call will be honored.

Parameters
[in]shmidIdentifies the symbol server for sideline operation.
Note
Sideline operation is not yet implemented.
DR_EXPORT drsym_error_t drsym_lookup_address ( const char *  modpath,
size_t  modoffs,
drsym_info_t info,
uint  flags 
)

Retrieves symbol information for a given module offset. When returning DRSYM_ERROR_LINE_NOT_AVAILABLE, the symbol information start_offs, end_offs, and name will still be valid.

Parameters
[in]modpathThe full path to the module to be queried.
[in]modoffsThe offset from the base of the module specifying the address to be queried. For Mach-O executables, the module base is after any __PAGEZERO segment.
[in,out]infoInformation about the symbol at the queried address.
[in]flagsOptions for the operation as a combination of drsym_flags_t values. Ignored for Windows PDB (DRSYM_PDB) except for DRSYM_DEMANGLE_PDB_TEMPLATES.
DR_EXPORT drsym_error_t drsym_lookup_symbol ( const char *  modpath,
const char *  symbol,
size_t *  modoffs,
uint  flags 
)

Retrieves the address for a given symbol name.

For Windows PDB symbols (DRSYM_PDB), we don't support the DRSYM_DEMANGLE_FULL flag. Also for Windows PDB, if DRSYM_DEMANGLE is set, symbol must include the template arguments. Consider using drsym_search_symbols_ex() instead with "<*>" for each template instantation in order to locate all symbols regardless of template arguments.

Parameters
[in]modpathThe full path to the module to be queried.
[in]symbolThe name of the symbol being queried. To specify a target module, pass "modulename!symbolname" as the symbol string to look up.
[out]modoffsThe offset from the base of the module specifying the address of the specified symbol. For Mach-O, the module base is after any __PAGEZERO segment.
[in]flagsOptions for the operation as a combination of drsym_flags_t values. Ignored for Windows PDB (DRSYM_PDB).
DR_EXPORT drsym_error_t drsym_module_has_symbols ( const char *  modpath)

Returns whether debug information is available for the module modpath. This can be faster than calling drsym_get_module_debug_kind(), but it should be equivalent to calling drsym_get_module_debug_kind() and looking for DRSYM_SYMBOLS in the output.

Parameters
[in]modpathThe full path to the module to be queried.
DR_EXPORT drsym_error_t drsym_search_symbols ( const char *  modpath,
const char *  match,
bool  full,
drsym_enumerate_cb  callback,
void *  data 
)

Enumerates all symbol information (including exports) matching a pattern for a given module. Calls the given callback function for each matching symbol. If the callback returns false, the enumeration will end.

This routine is only supported for PDB symbols (DRSYM_PDB).

Modifying the demangling is currently not supported: DRSYM_DEFAULT_FLAGS is used.

Due to dbghelp leaving template parameters in place (they are removed for DRSYM_DEMANGLE in the drsyms library itself), searching may find symbols that do not appear to match due to drsyms having removed that part of the symbol name.

Note
drsym_search_symbols() with full=false is significantly faster and uses less memory than drsym_enumerate_symbols(), and is faster than drsym_lookup_symbol(), but requires dbghelp.dll version 6.3 or higher. If an earlier version is used, this function will use a slower mechanism to perform the search.
Parameters
[in]modpathThe full path to the module to be queried.
[in]matchRegular expression describing the names of the symbols to be enumerated. To specify a target module, use the "module_pattern!symbol_pattern" format.
[in]fullWhether to search all symbols or (the default) just functions. A full search takes significantly more time and memory and eliminates the performance advantage over other lookup methods. A full search requires dbghelp.dll version 6.6 or higher.
[in]callbackFunction to call for each matching symbol found.
[in]dataUser parameter passed to callback.
DR_EXPORT drsym_error_t drsym_search_symbols_ex ( const char *  modpath,
const char *  match,
uint  flags,
drsym_enumerate_ex_cb  callback,
size_t  info_size,
void *  data 
)

Enumerates all symbol information (including exports) matching a pattern for a given module. Calls the given callback function for each symbol, passing full information about the symbol (as opposed to selected information returned by drsym_search_symbols()). If the callback returns false, the enumeration will end.

This routine is only supported for PDB symbols (DRSYM_PDB).

Modifying the demangling is currently not supported: DRSYM_DEFAULT_FLAGS is used.

Due to dbghelp leaving template parameters in place (they are removed for DRSYM_DEMANGLE in the drsyms library itself), searching may find symbols that do not appear to match due to drsyms having removed that part of the symbol name.

Note
The performance note for drsym_search_symbols() applies here as well.
Parameters
[in]modpathThe full path to the module to be queried.
[in]matchRegular expression describing the names of the symbols to be enumerated. To specify a target module, use the "module_pattern!symbol_pattern" format.
[in]flagsOptions for the operation as a combination of drsym_flags_t values. DRSYM_LEAVE_MANGLED and DRSYM_DEMANGLE_FULL are ignored. DRSYM_FULL_SEARCH, if set, requests to search all symbols as opposed to the default of just functions. A full search takes significantly more time and memory and eliminates the performance advantage over other lookup methods. A full search requires dbghelp.dll version 6.6 or higher.
[in]callbackFunction to call for each matching symbol found.
[in]info_sizeThe size of the drsym_info_t struct to pass to callback. Enough space for each name will be allocated automatically.
[in]dataUser parameter passed to callback.