Finding Symbols

After a symbol file has been loaded into the symbol handler, an application can use the symbol locator functions to return symbol information for a specified address. These functions can also find a source code file name and line number location for an address.

Enumerating Symbol Files

To retrieve a list of all symbol files loaded by module name, call the SymEnumerateModules function. To retrieve a list of symbols for a given module, call the SymEnumerateSymbols function.

Retrieving Symbols By Address

To retrieve symbolic information for a specific address, use the SymGetSymFromAddr function. This function retrieves information and stores it in an IMAGEHLP_SYMBOL structure. Because symbol names are variable in length, you must provide additional buffer space following the IMAGEHLP_SYMBOL structure declaration. The following is an example using SymGetSymFromAddr:

DWORD dwAddress;
DWORD dwDisplacement;
BYTE      buffer[MAX_BUFFER_LENGTH];
PIMAGEHLP_SYMBOL pSymbol = (PIMAGEHLP_SYMBOL)buffer;

pSymbol->SizeOfStruct = sizeof(IMAGEHLP_SYMBOL);
pSymbol->MaxNameLength = sizeof(buffer) - sizeof(IMAGEHLP_SYMBOL) + 1;
SymGetSymFromAddr(hProcess, dwAddress, &dwDisplacement, pSymbol)

Note that hProcess is the handle to the process originally passed to the SymInitialize function, and dwAddress contains the address for which a symbol is to be located. The address does not need to be on a symbol boundary. If the address comes after the beginning of a symbol but before the end of the symbol (the beginning of the symbol plus the symbol size), the function will locate the symbol.

Retrieving Symbols By Symbol Name

To retrieve symbolic information in an IMAGEHLP_SYMBOL structure for a specific module and symbol name, use the SymGetSymFromName function. If deferred symbol loading is set, SymGetSymFromName will attempt to load the symbol file for a module if it has not already been loaded. To specify a module name along with a symbol name, use the syntax Module!SymName. The "!" character delimits the module name from the symbol name. The following is an example using SymGetSymFromName:

BYTE szSymbolName[MAX_SYMBOLNAME_LENGTH];
BYTE buffer[MAX_BUFFER_LENGTH];
PIMAGEHLP_SYMBOL pSymbol = (PIMAGEHLP_SYMBOL)buffer;

pSymbol->SizeOfStruct = sizeof(IMAGEHLP_SYMBOL);
pSymbol->MaxNameLength = sizeof(buffer) - sizeof(IMAGEHLP_SYMBOL) + 1;
SymGetSymFromName(hProcess, szSymbolName, pSymbol)

Note that hProcess is the handle to the process originally passed to SymInitialize, and szSymbolName is a null-terminated string that specifies the symbol name for which a symbol is to be located.

Retrieving Line Numbers By Address

To retrieve the source code location for a specific address, use the SymGetLineFromAddr function. This function fills an IMAGEHLP_LINE structure that includes the source file name and line number location referred to by the specified address. The following is an example using SymGetLineFromAddr:

DWORD dwAddress;
DWORD dwDisplacement;
IMAGEHLP_LINE line;

SymSetOptions(SYMOPT_LOAD_LINES);
...
line.SizeOfStruct = sizeof(IMAGEHLP_LINE);
SymGetLineFromAddr(hProcess, dwAddress, &dwDisplacement, &line);

Note that hProcess is the handle to the process originally passed to SymInitialize, and dwAddress contains the address for which the source file name and line number should be located.

Retrieving Line Numbers By Symbol Name

To retrieve source code location for a specific symbol name, use the SymGetLineFromName function. This function is similar to SymGetSymFromName, but retrieves an IMAGEHLP_LINE structure. To use SymGetLineFromAddr or SymGetLineFromName, you must set the load lines option (SYMOPT_LOAD_LINES) using the SymSetOptions function. The following is an example using SymGetLineFromName:

BYTE      szModuleName[MAX_PATH];
BYTE      szFileName[MAX_PATH];
DWORD dwLineNumber;
LONG     lDisplacement;
IMAGEHLP_LINE line;

SymSetOptions(SYMOPT_LOAD_LINES);
...
line.SizeOfStruct = sizeof(IMAGEHLP_LINE);
SymGetLineFromName(hProcess, szModuleName, szFileName, dwLineNumber, &lDisplacement, &line);

Note that hProcess is the handle to the process originally passed to SymInitialize. Also, szModuleName contains the source module name, which can be NULL. The szFileName parameter contains the source file name, and dwLineNumber contains the line number for which the virtual address should be retrieved.