Symbol Access Library

Data Structures
struct	_drsym_info_t
struct	_drsym_type_t
Typedefs
typedef struct _drsym_info_t	drsym_info_t
typedef struct _drsym_type_t	drsym_type_t
typedef bool(*	drsym_enumerate_cb )(const char *name, size_t modoffs, 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 }
enum	drsym_flags_t {   DRSYM_LEAVE_MANGLED = 0x00,   DRSYM_DEMANGLE = 0x01,   DRSYM_DEMANGLE_FULL = 0x02,   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) }
enum	{   DRSYM_TYPE_OTHER,   DRSYM_TYPE_INT,   DRSYM_TYPE_PTR,   DRSYM_TYPE_FUNC }
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_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_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 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_search_symbols (const char *modpath, const char *match, bool full, drsym_enumerate_cb callback, void *data)

---

Typedef Documentation

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]	name	Name of the symbol.
[out]	modoffs	Offset of the symbol from the module base.
[in]	data	User parameter passed to drsym_enumerate_symbols() or drsym_search_symbols().

typedef struct _drsym_info_t drsym_info_t

Data structure that holds symbol information

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.

enum drsym_debug_kind_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.

enum drsym_error_t

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

enum drsym_flags_t

Bitfield of options to each DRSyms operation.

Enumerator:

DRSYM_LEAVE_MANGLED	Do not demangle C++ symbols.
DRSYM_DEMANGLE	Demangle C++ symbols, omitting templates and parameter types. On Linux, both templates and parameters are collapsed to <> and () respectively. On Windows, templates are still expanded, and parameters are omitted without parentheses.
DRSYM_DEMANGLE_FULL	Demangle template arguments and parameter types.
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, and the number of characters required to store the name if it succeeded. 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.

Parameters:

[out]	dst	Output buffer for demangled name.
[in]	dst_sz	Size of the output buffer in bytes.
[in]	mangled	Mangled C++ symbol to demangle.
[in]	flags	Options for the operation. DRSYM_DEMANGLE is implied.

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. Calls the given callback function for each symbol. If the callback returns false, the enumeration will end.

Parameters:

[in]	modpath	The full path to the module to be queried.
[in]	callback	Function to call for each symbol found.
[in]	data	User parameter passed to callback.
[in]	flags	Options for the operation. Ignored on Windows.

DR_EXPORT drsym_error_t drsym_exit

(

void

)

Clean up and shut down the symbol access library.

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.

Parameters:

[in]	modpath	The full path to the module to be queried.
[in]	modoffs	The offset from the base of the module specifying the start address of the function.
[out]	buf	Memory used for the types.
[in]	buf_sz	Number of bytes in buf.
[out]	func_type	Pointer 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]	modpath	The full path to the module to be queried.
[out]	kind	The kind of debug information available.

DR_EXPORT drsym_error_t drsym_init

(

IF_WINDOWS_ELSE(const wchar_t *, int)

shmid

)

Initialize the symbol access library.

Parameters:

[in]

shmid

Identifies 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]	modpath	The full path to the module to be queried.
[in]	modoffs	The offset from the base of the module specifying the address to be queried.
[in,out]	info	Information about the symbol at the queried address.
[in]	flags	Options for the operation. Ignored on Windows.

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.

On Windows, we don't support the DRSYM_DEMANGLE_FULL flag. Also on Windows, if DRSYM_DEMANGLE is set, symbol must include the template arguments.

Parameters:

[in]	modpath	The full path to the module to be queried.
[in]	symbol	The name of the symbol being queried. To specify a target module, pass "modulename!symbolname" as the symbol string to look up.
[out]	modoffs	The offset from the base of the module specifying the address of the specified symbol.
[in]	flags	Options for the operation. Ignored on Windows.

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 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.

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]	modpath	The full path to the module to be queried.
[in]	match	Regular expression describing the names of the symbols to be enumerated. To specify a target module, use the "module_pattern!symbol_pattern" format.
[in]	full	Whether 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]	callback	Function to call for each matching symbol found.
[in]	data	User parameter passed to callback.