symbol-parser.cpp File Reference

symbol parser More...

#include "pch.h"
#include "header/pdb-identity.h"

Functions
void	SymSetTextMessageCallback (PVOID Handler)
	Set the function callback that will be called if any message needs to be shown.
VOID	ShowMessages (const char *Fmt,...)
	Show messages.
PSYMBOL_LOADED_MODULE_DETAILS	SymGetModuleBaseFromSearchMask (const char *SearchMask, BOOLEAN SetModuleNameGlobally)
	Interpret and find module base, based on module name.
BOOLEAN	SymGetFieldOffsetFromModule (UINT64 Base, WCHAR *TypeName, WCHAR *FieldName, UINT32 *FieldOffset)
	Get the offset of a field from the top of a structure.
BOOLEAN	SymGetDataTypeSizeFromModule (UINT64 Base, WCHAR *TypeName, UINT64 *TypeSize)
	Get the size of a data type (structure).
BOOLEAN	SymInit ()
	initialize the DbgHelp symbols
BOOLEAN	SymCheckAndRemoveWow64Prefix (const char *ModuleAddress, const char *PdbFileName, std::string &CustomModuleName)
	Remove wow64 extension to the module names.
BOOLEAN	SymCheckNtoskrnlPrefix (const char *PdbFileName, std::string &CustomModuleName)
	Check for alternative name of ntoskrn;.
UINT32	SymLoadFileSymbol (UINT64 BaseAddress, const char *PdbFileName, const char *CustomModuleName)
	load symbol based on a file name and GUID
UINT32	SymUnloadModuleSymbol (char *ModuleName)
	Unload one module symbol.
UINT32	SymUnloadAllSymbols ()
	Unload all the symbols.
UINT64	SymConvertNameToAddress (const char *FunctionOrVariableName, PBOOLEAN WasFound)
	Convert function name to address.
BOOLEAN	SymGetFieldOffset (CHAR *TypeName, CHAR *FieldName, UINT32 *FieldOffset)
	Search and show symbols.
BOOLEAN	SymGetDataTypeSize (CHAR *TypeName, UINT64 *TypeSize)
	Get the size of structures from the symbols.
UINT32	SymSearchSymbolForMask (const char *SearchMask)
	Gets the offset from the symbol.
BOOLEAN	SymCreateSymbolTableForDisassembler (void *CallbackFunction)
	Create symbol table for disassembler.

Variables
std::vector< PSYMBOL_LOADED_MODULE_DETAILS >	g_LoadedModules
BOOLEAN	g_IsLoadedModulesInitialized = FALSE
BOOLEAN	g_AbortLoadingExecution = FALSE
CHAR *	g_CurrentModuleName = NULL
PVOID	g_MessageHandler = NULL
	The handler for ShowMessages function this is because the user might choose not to use printf and instead use his/her handler for showing messages.
SymbolMapCallback	g_SymbolMapForDisassembler = NULL

Detailed Description

symbol parser

Author

Alee Amini (alee@.nosp@m.hype.nosp@m.rdbg..nosp@m.org)

Sina Karvandi (sina@.nosp@m.hype.nosp@m.rdbg..nosp@m.org)

Version

0.1

Date

2021-05-29

Copyright

This project is released under the GNU Public License v3.

Function Documentation

ShowMessages()

VOID ShowMessages	(	const char *	Fmt,
			... )

Show messages.

Parameters

Fmt	format string message
Fmt	format string message
...	arguments

Returns

VOID

{
    va_list ArgList;
    va_list Args;
 
    if (g_MessageHandler == NULL)
    {
        va_start(Args, Fmt);
        vprintf(Fmt, Args);
        va_end(Args);
    }
    else
    {
        char TempMessage[COMMUNICATION_BUFFER_SIZE + TCP_END_OF_BUFFER_CHARS_COUNT] = {0};
        va_start(ArgList, Fmt);
        INT SprintfResult = vsprintf_s(TempMessage, Fmt, ArgList);
        va_end(ArgList);
 
        if (SprintfResult != -1)
        {
            //
            // There is another handler
            //
            ((SendMessageWithParamCallback)g_MessageHandler)(TempMessage);
        }
    }
}

SymCheckAndRemoveWow64Prefix()

BOOLEAN SymCheckAndRemoveWow64Prefix	(	const char *	ModuleAddress,
		const char *	PdbFileName,
		std::string &	CustomModuleName )

Remove wow64 extension to the module names.

Parameters

ModuleAddress
PdbFileName

Returns

BOOLEAN

{
    char ModuleName[_MAX_FNAME]    = {0};
    char PdbModuleName[_MAX_FNAME] = {0};
 
    //
    // Determine the name of the file
    //
    _splitpath(ModuleAddress, NULL, NULL, ModuleName, NULL);
    _splitpath(PdbFileName, NULL, NULL, PdbModuleName, NULL);
 
    //
    // Convert ModuleName to lowercase
    //
    std::transform(ModuleName, ModuleName + strlen(ModuleName), ModuleName, [](unsigned char c) { return std::tolower(c); });
 
    //
    // Convert PdbModuleName to lowercase
    //
    std::transform(PdbModuleName, PdbModuleName + strlen(PdbModuleName), PdbModuleName, [](unsigned char c) { return std::tolower(c); });
 
    //
    // Compare the lowercase strings
    //
    if (std::strcmp(ModuleName, PdbModuleName) == 0)
    {
        return FALSE;
    }
    else
    {
        // Convert ModuleAddress to lowercase
        std::string LowerModuleAddress(ModuleAddress);
        std::transform(LowerModuleAddress.begin(), LowerModuleAddress.end(), LowerModuleAddress.begin(), [](unsigned char c) { return std::tolower(c); });
 
        if (PdbModuleName[0] == 'w' && LowerModuleAddress.find(":\\windows\\system32") != std::string::npos)
        {
            //
            // Set CustomModuleName to lowercase ModuleName
            //
            CustomModuleName = std::string(ModuleName);
 
            return TRUE;
        }
        else
        {
            return FALSE;
        }
    }
}

SymCheckNtoskrnlPrefix()

BOOLEAN SymCheckNtoskrnlPrefix	(	const char *	PdbFileName,
		std::string &	CustomModuleName )

Check for alternative name of ntoskrn;.

Parameters

PdbFileName
CustomModuleName

Returns

BOOLEAN

{
    char PdbModuleName[_MAX_FNAME] = {0};
 
    //
    // Determine the name of the file
    //
    _splitpath(PdbFileName, NULL, NULL, PdbModuleName, NULL);
 
    //
    // Convert PdbModuleName to lowercase
    //
    std::transform(PdbModuleName, PdbModuleName + strlen(PdbModuleName), PdbModuleName, [](unsigned char c) { return std::tolower(c); });
 
    //
    // Is it "nt" module or not
    //
    // Names of kernel
    //     NTOSKRNL.EXE : 1 CPU
    //     NTKRNLMP.EXE : N CPU, SMP
    //     NTKRNLPA.EXE : 1 CPU, PAE
    //     NTKRPAMP.EXE : N CPU SMP, PAE
    //
    if (strcmp(PdbModuleName, ("ntkrnlmp")) == 0 || strcmp(PdbModuleName, ("ntoskrnl")) == 0 ||
        strcmp(PdbModuleName, ("ntkrpamp")) == 0 || strcmp(PdbModuleName, ("ntkrnlpa")) == 0)
    {
        CustomModuleName = "nt";
        return TRUE;
    }
 
    //
    // Not nt module
    //
    return FALSE;
}

SymConvertNameToAddress()

UINT64 SymConvertNameToAddress	(	const char *	FunctionOrVariableName,
		PBOOLEAN	WasFound )

Convert function name to address.

Parameters

FunctionOrVariableName	the name of the function or variable to convert
WasFound

Returns

UINT64

{
    BOOLEAN      Found   = FALSE;
    UINT64       Address = NULL;
    UINT64       Buffer[(sizeof(SYMBOL_INFO) + MAX_SYM_NAME * sizeof(CHAR) + sizeof(UINT64) - 1) / sizeof(UINT64)];
    PSYMBOL_INFO Symbol = (PSYMBOL_INFO)Buffer;
    string       FinalModuleName;
    string       TempName(FunctionOrVariableName);
    string       ExtractedModuleName;
    string       FunctionName;
 
    //
    // Not found by default
    //
    *WasFound = FALSE;
 
    //
    // Retrieve the address from name
    //
    Symbol->SizeOfStruct = sizeof(SYMBOL_INFO);
    Symbol->MaxNameLen   = MAX_SYM_NAME;
 
    //
    // *** Check if the module has an alternative name, then replace the
    // original name with alternative name ***
    //
 
    //
    // Check if '!' is present in the function or variable name
    //
    SIZE_T FoundIndex = TempName.find('!');
    if (FoundIndex != std::string::npos)
    {
        ExtractedModuleName = TempName.substr(0, FoundIndex);
        FunctionName        = TempName.substr(FoundIndex + 1);
 
        //
        // Convert module name to lower-case
        //
        std::transform(ExtractedModuleName.begin(), ExtractedModuleName.end(), ExtractedModuleName.begin(), [](unsigned char c) {
            return std::tolower(c);
        });
 
        //
        // Check if the we find it with an alternative module name or not
        //
        for (auto item : g_LoadedModules)
        {
            //
            // Check for the module name
            //
            if (strcmp((const char *)item->ModuleName, ExtractedModuleName.c_str()) == 0)
            {
                string ModuleName(item->ModuleName);
                FinalModuleName = ModuleName + "!" + FunctionName;
                break;
            }
 
            //
            // Check for the alternative module name
            //
            if (strcmp((const char *)item->ModuleAlternativeName, ExtractedModuleName.c_str()) == 0)
            {
                //
                // Replace the alternative module name with original module name
                //
                string ModuleName(item->ModuleName);
                FinalModuleName = ModuleName + "!" + FunctionName;
                break;
            }
        }
    }
    else
    {
        //
        // It doesn't contain a module name, so we'll use 'nt' by default
        //
        for (auto item : g_LoadedModules)
        {
            //
            // Check for the module name
            //
            if (strcmp((const char *)item->ModuleAlternativeName, "nt") == 0)
            {
                //
                // Replace the alternative module name with original module name
                //
                string ModuleName(item->ModuleName);
                FinalModuleName = ModuleName + "!" + TempName;
                break;
            }
        }
    }
 
    //
    // Check if the final module name is not empty
    //
    if (FinalModuleName.empty())
    {
        *WasFound = FALSE;
        return NULL;
    }
 
    if (SymFromName(GetCurrentProcess(), FinalModuleName.c_str(), Symbol))
    {
        //
        // SymFromName returned success
        //
        Found   = TRUE;
        Address = Symbol->Address;
    }
    else
    {
        //
        // SymFromName failed
        //
        Found = FALSE;
 
        //
        // ShowMessages("symbol not found (%x)\n", GetLastError());
        //
    }
 
    *WasFound = Found;
    return Address;
}

SymCreateSymbolTableForDisassembler()

BOOLEAN SymCreateSymbolTableForDisassembler

(

void *

CallbackFunction

)

Create symbol table for disassembler.

mainly used by disassembler for 'u' command

Parameters

CallbackFunction

Returns

BOOLEAN

{
    BOOL    Ret    = FALSE;
    BOOLEAN Result = TRUE;
 
    //
    // Set the callback function to deliver the name of module!ObjectName
    //
    g_SymbolMapForDisassembler = (SymbolMapCallback)CallbackFunction;
 
    //
    // Create a symbol table from all modules
    //
    for (auto item : g_LoadedModules)
    {
        //
        // Set module name
        //
        g_CurrentModuleName = (char *)item->ModuleName;
 
        //
        // Call the callback for the current module
        //
        Ret = SymEnumSymbols(
            GetCurrentProcess(),                     // Process handle of the current process
            item->BaseAddress,                       // Base address of the module
            NULL,                                    // Mask (NULL -> all symbols)
            SymDeliverDisassemblerSymbolMapCallback, // The callback function
            NULL                                     // A used-defined context can be passed here, if necessary
        );
 
        if (!Ret)
        {
            //
            // A module did not added correctly
            //
            //  ShowMessages("err, symbol enum failed (%x)\n", GetLastError());
            Result = FALSE;
        }
    }
 
    return Result;
}

SymGetDataTypeSize()

BOOLEAN SymGetDataTypeSize	(	CHAR *	TypeName,
		UINT64 *	TypeSize )

Get the size of structures from the symbols.

Parameters

TypeName	the type (structure) name to query
TypeSize	pointer to receive the size of the data type

Returns

BOOLEAN Whether the module is found successfully or not

{
    BOOL                          Ret        = FALSE;
    UINT32                        Index      = 0;
    PSYMBOL_LOADED_MODULE_DETAILS SymbolInfo = NULL;
    BOOLEAN                       Result     = FALSE;
 
    //
    // Find module info
    //
    SymbolInfo = SymGetModuleBaseFromSearchMask(TypeName, TRUE);
 
    //
    // Check if module is found
    //
    if (SymbolInfo == NULL)
    {
        //
        // Module not found or there was an error
        //
        return FALSE;
    }
 
    //
    // Remove the *!Name from TypeName as it not supports module name
    // at the beginning of a type name
    //
    while (TypeName[Index] != '\0')
    {
        if (TypeName[Index] == '!')
        {
            TypeName = (CHAR *)(TypeName + Index + 1);
            break;
        }
 
        Index++;
    }
 
    //
    // Convert FieldName to wide-char, it's because SymGetTypeInfo supports
    // wide-char
    //
    const SIZE_T TypeNameSize = strlen(TypeName) + 1;
    WCHAR *      TypeNameW    = (WCHAR *)malloc(sizeof(wchar_t) * TypeNameSize);
 
    if (TypeNameW == NULL)
    {
        printf("err, could not allocate buffer");
        return FALSE;
    }
 
    RtlZeroMemory(TypeNameW, sizeof(wchar_t) * TypeNameSize);
    mbstowcs(TypeNameW, TypeName, TypeNameSize);
 
    Result = SymGetDataTypeSizeFromModule(SymbolInfo->ModuleBase, TypeNameW, TypeSize);
 
    free(TypeNameW);
 
    return Result;
}

SymGetDataTypeSizeFromModule()

BOOLEAN SymGetDataTypeSizeFromModule	(	UINT64	Base,
		WCHAR *	TypeName,
		UINT64 *	TypeSize )

Get the size of a data type (structure).

Parameters

Base
TypeName
TypeSize

Returns

BOOLEAN Whether the module is found successfully or not

{
    //
    // Allocate a buffer to back the SYMBOL_INFO structure
    //
    const DWORD SizeOfStruct =
        sizeof(SYMBOL_INFOW) + ((MAX_SYM_NAME - 1) * sizeof(wchar_t));
    UINT8 SymbolInfoBuffer[SizeOfStruct];
    auto  SymbolInfo = PSYMBOL_INFOW(SymbolInfoBuffer);
 
    //
    // Initialize the fields that need initialization
    //
    SymbolInfo->SizeOfStruct = sizeof(SYMBOL_INFOW);
    SymbolInfo->MaxNameLen   = MAX_SYM_NAME;
 
    //
    // Retrieve a type index for the type we're after
    //
    if (!SymGetTypeFromNameW(GetCurrentProcess(), Base, TypeName, SymbolInfo))
    {
        // ShowMessages("err, SymGetTypeFromName failed (%x)\n",
        //              GetLastError());
        return FALSE;
    }
 
    if (!SymGetTypeInfo(GetCurrentProcess(), Base, SymbolInfo->TypeIndex, TI_GET_LENGTH, TypeSize))
    {
        // ShowMessages("err, SymGetTypeInfo failed (%x)\n",
        //              GetLastError());
        return FALSE;
    }
 
    // ShowMessages("type size : %llx\n", TypeSize);
 
    return TRUE;
}

SymGetFieldOffset()

BOOLEAN SymGetFieldOffset	(	CHAR *	TypeName,
		CHAR *	FieldName,
		UINT32 *	FieldOffset )

Search and show symbols.

mainly used by the 'x' command

Parameters

TypeName
FieldName
FieldOffset

Returns

BOOLEAN Whether the module is found successfully or not

{
    BOOL                          Ret        = FALSE;
    UINT32                        Index      = 0;
    PSYMBOL_LOADED_MODULE_DETAILS SymbolInfo = NULL;
    BOOLEAN                       Result     = FALSE;
 
    //
    // Find module info
    //
    SymbolInfo = SymGetModuleBaseFromSearchMask(TypeName, TRUE);
 
    //
    // Check if module is found
    //
    if (SymbolInfo == NULL)
    {
        //
        // Module not found or there was an error
        //
        return FALSE;
    }
 
    //
    // Remove the *!Name from TypeName as it not supports module name
    // at the beginning of a type name
    //
    while (TypeName[Index] != '\0')
    {
        if (TypeName[Index] == '!')
        {
            TypeName = (CHAR *)(TypeName + Index + 1);
            break;
        }
 
        Index++;
    }
 
    //
    // Convert TypeName to wide-char, it's because SymGetTypeInfo supports
    // wide-char
    //
    const SIZE_T TypeNameSize = strlen(TypeName) + 1;
    WCHAR *      TypeNameW    = (WCHAR *)malloc(sizeof(wchar_t) * TypeNameSize);
 
    if (TypeNameW == NULL)
    {
        printf("err, could not allocate buffer");
        return FALSE;
    }
 
    RtlZeroMemory(TypeNameW, sizeof(wchar_t) * TypeNameSize);
    mbstowcs(TypeNameW, TypeName, TypeNameSize);
 
    //
    // Convert FieldName to wide-char, it's because SymGetTypeInfo supports
    // wide-char
    //
    const SIZE_T FieldNameSize = strlen(FieldName) + 1;
    WCHAR *      FieldNameW    = (WCHAR *)malloc(sizeof(wchar_t) * FieldNameSize);
 
    if (FieldNameW == NULL)
    {
        printf("err, could not allocate buffer");
        free(TypeNameW);
        return FALSE;
    }
 
    RtlZeroMemory(FieldNameW, sizeof(wchar_t) * FieldNameSize);
    mbstowcs(FieldNameW, FieldName, FieldNameSize);
 
    Result = SymGetFieldOffsetFromModule(SymbolInfo->ModuleBase, TypeNameW, FieldNameW, FieldOffset);
 
    free(TypeNameW);
    free(FieldNameW);
 
    return Result;
}

SymGetFieldOffsetFromModule()

BOOLEAN SymGetFieldOffsetFromModule	(	UINT64	Base,
		WCHAR *	TypeName,
		WCHAR *	FieldName,
		UINT32 *	FieldOffset )

Get the offset of a field from the top of a structure.

Parameters

Base
TypeName
FieldName
FieldOffset

This function is derived from: https://github.com/0vercl0k/sic/blob/master/src/sic/sym.cc

Returns

BOOLEAN Whether the module is found successfully or not

{
    BOOLEAN Found = FALSE;
 
    //
    // Allocate a buffer to back the SYMBOL_INFO structure
    //
    const DWORD SizeOfStruct =
        sizeof(SYMBOL_INFOW) + ((MAX_SYM_NAME - 1) * sizeof(wchar_t));
    UINT8 SymbolInfoBuffer[SizeOfStruct];
    auto  SymbolInfo = PSYMBOL_INFOW(SymbolInfoBuffer);
 
    //
    // Initialize the fields that need initialization
    //
    SymbolInfo->SizeOfStruct = sizeof(SYMBOL_INFOW);
    SymbolInfo->MaxNameLen   = MAX_SYM_NAME;
 
    //
    // Retrieve a type index for the type we're after
    //
    if (!SymGetTypeFromNameW(GetCurrentProcess(), Base, TypeName, SymbolInfo))
    {
        // ShowMessages("err, SymGetTypeFromName failed (%x)\n",
        //              GetLastError());
        return FALSE;
    }
 
    //
    // Now that we have a type, we need to enumerate its children to find the
    // field we're after. First step is to get the number of children
    //
    const ULONG TypeIndex     = SymbolInfo->TypeIndex;
    DWORD       ChildrenCount = 0;
    if (!SymGetTypeInfo(GetCurrentProcess(), Base, TypeIndex, TI_GET_CHILDRENCOUNT, &ChildrenCount))
    {
        // ShowMessages("err, SymGetTypeInfo failed (%x)\n",
        //              GetLastError());
        return FALSE;
    }
 
    //
    // Allocate enough memory to receive the children ids
    //
    auto FindChildrenParamsBacking = std::make_unique<UINT8[]>(
        sizeof(_TI_FINDCHILDREN_PARAMS) + ((ChildrenCount - 1) * sizeof(ULONG)));
    auto FindChildrenParams =
        (_TI_FINDCHILDREN_PARAMS *)FindChildrenParamsBacking.get();
 
    //
    // Initialize the structure with the children count
    //
    FindChildrenParams->Count = ChildrenCount;
 
    //
    // Get all the children ids
    //
    if (!SymGetTypeInfo(GetCurrentProcess(), Base, TypeIndex, TI_FINDCHILDREN, FindChildrenParams))
    {
        // ShowMessages("err, SymGetTypeInfo failed (%x)\n",
        //             GetLastError());
        return FALSE;
    }
 
    //
    // Now that we have all the ids, we can walk them and find the one that
    // matches the field we're looking for
    //
 
    for (DWORD ChildIdx = 0; ChildIdx < ChildrenCount; ChildIdx++)
    {
        //
        // Grab the child name
        //
        const ULONG ChildId   = FindChildrenParams->ChildId[ChildIdx];
        WCHAR *     ChildName = nullptr;
        SymGetTypeInfo(GetCurrentProcess(), Base, ChildId, TI_GET_SYMNAME, &ChildName);
 
        //
        // Grab the child size - this is useful to know if a field is a bit or a
        // normal field
        //
        UINT64 ChildSize = 0;
        SymGetTypeInfo(GetCurrentProcess(), Base, ChildId, TI_GET_LENGTH, &ChildSize);
 
        //
        // Does this child's name match the field we're looking for?
        //
        Found = FALSE;
        if (wcscmp(ChildName, FieldName) == 0)
        {
            //
            // If we have found the field, now we need to find its offset if
            // it's a normal field, or its bit position if it is a bit
            //
            const IMAGEHLP_SYMBOL_TYPE_INFO Info =
                (ChildSize == 1) ? TI_GET_BITPOSITION : TI_GET_OFFSET;
            SymGetTypeInfo(GetCurrentProcess(), Base, ChildId, Info, FieldOffset);
 
            Found = TRUE;
        }
 
        //
        // Even if we have found a match, we need to clean up the memory
        //
        LocalFree(ChildName);
        ChildName = nullptr;
 
        //
        // We can now break out of the loop if we have what we came looking for
        //
        if (Found)
        {
            break;
        }
    }
 
    return Found;
}

SymGetModuleBaseFromSearchMask()

PSYMBOL_LOADED_MODULE_DETAILS SymGetModuleBaseFromSearchMask	(	const char *	SearchMask,
		BOOLEAN	SetModuleNameGlobally )

Interpret and find module base, based on module name.

Parameters

SearchMask	the search mask to find module
SetModuleNameGlobally	whether to set module name globally

Returns

PSYMBOL_LOADED_MODULE_DETAILS NULL means error or not found, otherwise it returns the instance of loaded module based on search mask

{
    string Token;
    char   ModuleName[_MAX_FNAME] = {0};
    int    Index                  = 0;
    char   Ch                     = '\0';
 
    if (!g_IsLoadedModulesInitialized || SearchMask == NULL)
    {
        //
        // no module is loaded or search mask is invalid
        //
        return NULL;
    }
 
    //
    // Convert search mask to string
    //
    string SearchMaskString(SearchMask);
 
    //
    // Check if the string contains '!'
    //
    char Delimiter = '!';
    if (SearchMaskString.find(Delimiter) != std::string::npos)
    {
        //
        // Found
        //
        Token = SearchMaskString.substr(0, SearchMaskString.find(Delimiter));
 
        strcpy(ModuleName, Token.c_str());
 
        if (ModuleName[0] == '\0')
        {
            //
            // Invalid name
            //
            return NULL;
        }
 
        //
        // Convert module name to lowercase
        //
        while (ModuleName[Index])
        {
            Ch = ModuleName[Index];
 
            //
            // convert ch to lowercase using toLower()
            //
            ModuleName[Index] = tolower(Ch);
 
            Index++;
        }
    }
    else
    {
        //
        // There is no '!' in the middle of the search mask so,
        // we assume that the module is nt
        //
        RtlZeroMemory(ModuleName, _MAX_FNAME);
 
        ModuleName[0] = 'n';
        ModuleName[1] = 't';
    }
 
    //
    // ************* Interpret based on remarks type name *************
    //
    for (auto item : g_LoadedModules)
    {
        //
        // Check for the module name
        //
        if (strcmp((const char *)item->ModuleName, ModuleName) == 0)
        {
            if (SetModuleNameGlobally)
            {
                g_CurrentModuleName = (char *)item->ModuleName;
            }
 
            return item;
        }
 
        //
        // Check for alternative module name
        //
        if (strcmp((const char *)item->ModuleAlternativeName, ModuleName) == 0)
        {
            if (SetModuleNameGlobally)
            {
                g_CurrentModuleName = (char *)item->ModuleAlternativeName;
            }
 
            return item;
        }
    }
 
    //
    // If the function continues until here then it means
    // that the module not found
    //
    return NULL;
}

SymInit()

BOOLEAN SymInit

(

)

initialize the DbgHelp symbols

Returns

BOOLEAN

{
    BOOL  Ret     = FALSE;
    DWORD Options = 0;
 
    //
    // Get options
    //
    Options = SymGetOptions();
 
    //
    // SYMOPT_DEBUG option asks DbgHelp to print additional troubleshooting
    // messages to debug output - use the debugger's Debug Output window
    // to view the messages
    //
    Options |= SYMOPT_DEBUG;
    Options |= SYMOPT_CASE_INSENSITIVE;
    SymSetOptions(Options);
 
    //
    // Initialize DbgHelp and load symbols for all modules of the current process
    //
    Ret = SymInitialize(
        GetCurrentProcess(), // Process handle of the current process
        NULL,                // No user-defined search path -> use default
        FALSE                // Do not load symbols for modules in the current process
    );
 
    if (!Ret)
    {
        ShowMessages("err, symbol init failed (%x)\n",
                     GetLastError());
        return FALSE;
    }
 
    //
    // Indicate that at least one module is loaded
    //
    g_IsLoadedModulesInitialized = TRUE;
 
    return TRUE;
}

SymLoadFileSymbol()

UINT32 SymLoadFileSymbol	(	UINT64	BaseAddress,
		const char *	PdbFileName,
		const char *	CustomModuleName )

load symbol based on a file name and GUID

Parameters

BaseAddress
PdbFileName
CustomModuleName

Returns

UINT32

{
    DWORD                         FileSize                        = 0;
    int                           Index                           = 0;
    char                          Ch                              = '\0';
    char                          ModuleName[_MAX_FNAME]          = {0};
    char                          AlternateModuleName[_MAX_FNAME] = {0};
    PSYMBOL_LOADED_MODULE_DETAILS ModuleDetails                   = NULL;
 
    //
    // Check if the loaded modules are initialized or not
    //
    if (!g_IsLoadedModulesInitialized)
    {
        //
        // Initialize the symbol table
        //
        SymInit();
    }
 
    //
    // Determine the base address and the file size
    //
    if (!SymGetFileParams(PdbFileName, FileSize))
    {
        ShowMessages("err, cannot obtain file parameters (internal error)\n");
        return -1;
    }
 
    //
    // Determine the name of the file
    //
    _splitpath(PdbFileName, NULL, NULL, ModuleName, NULL);
 
    //
    // Move to alternate list
    //
    strcpy(AlternateModuleName, ModuleName);
 
    //
    // Convert module name to lowercase
    //
    while (ModuleName[Index])
    {
        Ch = ModuleName[Index];
 
        //
        // convert ch to lowercase using toLower()
        //
        ModuleName[Index] = tolower(Ch);
 
        Index++;
    }
 
    //
    // Allocate buffer to store the details
    //
    ModuleDetails = (SYMBOL_LOADED_MODULE_DETAILS *)malloc(sizeof(SYMBOL_LOADED_MODULE_DETAILS));
 
    if (ModuleDetails == NULL)
    {
        ShowMessages("err, allocating buffer for storing symbol details (%x)\n",
                     GetLastError());
        return -1;
    }
 
    RtlZeroMemory(ModuleDetails, sizeof(SYMBOL_LOADED_MODULE_DETAILS));
 
    ModuleDetails->ModuleBase = SymLoadModule64(
        GetCurrentProcess(), // Process handle of the current process
        NULL,                // Handle to the module's image file (not needed)
        PdbFileName,         // Path/name of the file
        NULL,                // User-defined short name of the module (it can be NULL)
        BaseAddress,         // Base address of the module (cannot be NULL if .PDB file is
                             // used, otherwise it can be NULL)
        FileSize             // Size of the file (cannot be NULL if .PDB file is used,
                             // otherwise it can be NULL)
    );
 
    if (ModuleDetails->ModuleBase == NULL)
    {
        ShowMessages("err, loading symbols failed (%x)\n",
                     GetLastError());
 
        free(ModuleDetails);
        return -1;
    }
 
#ifndef DoNotShowDetailedResult
 
    //
    // Load symbols for the module
    //
    ShowMessages("loading symbols for: %s\n", PdbFilePath);
 
    ShowMessages("load address: %I64x\n", ModuleDetails.ModuleBase);
 
    //
    // Obtain and display information about loaded symbols
    //
    SymShowSymbolInfo(ModuleDetails.ModuleBase);
 
#endif // !DoNotShowDetailedResult
 
    //
    // Make the details (to save)
    //
    ModuleDetails->BaseAddress = BaseAddress;
    strcpy((char *)ModuleDetails->ModuleName, ModuleName);
    strcpy((char *)ModuleDetails->PdbFilePath, PdbFileName);
 
    //
    // Save the custom module name (if any)
    //
    if (CustomModuleName != NULL)
    {
        strcpy((char *)ModuleDetails->ModuleAlternativeName, CustomModuleName);
    }
 
    //
    // Save it
    //
    g_LoadedModules.push_back(ModuleDetails);
 
    return 0;
}

SymSearchSymbolForMask()

UINT32 SymSearchSymbolForMask

(

const char *

SearchMask

)

Gets the offset from the symbol.

Parameters

SearchMask

Returns

UINT32

{
    BOOL                          Ret        = FALSE;
    PSYMBOL_LOADED_MODULE_DETAILS SymbolInfo = NULL;
 
    //
    // Get the module info
    //
    SymbolInfo = SymGetModuleBaseFromSearchMask(SearchMask, TRUE);
 
    //
    // Check to see if module info is found
    //
    if (SymbolInfo == NULL)
    {
        //
        // Module not found or there was an error
        //
        return -1;
    }
 
    Ret = SymEnumSymbols(
        GetCurrentProcess(),           // Process handle of the current process
        SymbolInfo->ModuleBase,        // Base address of the module
        SearchMask,                    // Mask (NULL -> all symbols)
        SymDisplayMaskSymbolsCallback, // The callback function
        NULL                           // A used-defined context can be passed here, if necessary
    );
 
    if (!Ret)
    {
        ShowMessages("err, symbol enum failed (%x)\n",
                     GetLastError());
    }
 
    return 0;
}

SymSetTextMessageCallback()

void SymSetTextMessageCallback

(

PVOID

Handler

)

Set the function callback that will be called if any message needs to be shown.

Parameters

Handler

Function that handles the messages

{
    g_MessageHandler = Handler;
 
    //
    // Set the pdbex's message handler
    //
    pdbex_set_logging_method_export(Handler);
}

SymUnloadAllSymbols()

UINT32 SymUnloadAllSymbols

(

)

Unload all the symbols.

Returns

UINT32

{
    BOOL    Ret              = FALSE;
    BOOLEAN IsAnythingLoaded = FALSE;
 
    //
    // Check if it's already initialized
    //
    if (!g_IsLoadedModulesInitialized)
    {
        return 0;
    }
 
    for (auto item : g_LoadedModules)
    {
        //
        // At least one module is loaded
        //
        IsAnythingLoaded = TRUE;
 
        //
        // Unload symbols for the module
        //
        Ret = SymUnloadModule64(GetCurrentProcess(), item->ModuleBase);
 
        if (!Ret)
        {
            // ShowMessages("err, unload symbol failed (%x)\n",
            //              GetLastError());
        }
 
        free(item);
    }
 
    //
    // Check if there is at least one module is loaded
    //
    if (!IsAnythingLoaded)
    {
        //
        // Nothing is loaded yet!
        //
        return 0;
    }
 
    //
    // Clear the list
    //
    g_LoadedModules.clear();
 
    //
    // Uninitialize DbgHelp
    //
    Ret = SymCleanup(GetCurrentProcess());
 
    if (!Ret)
    {
        ShowMessages("err, symbol cleanup failed (%x)\n", GetLastError());
        return 0;
    }
 
    //
    // It's not initialized anymore
    //
    g_IsLoadedModulesInitialized = FALSE;
 
    return 0;
}

SymUnloadModuleSymbol()

UINT32 SymUnloadModuleSymbol

(

char *

ModuleName

)

Unload one module symbol.

Parameters

ModuleName

Returns

UINT32

{
    BOOLEAN OneModuleFound = FALSE;
    BOOL    Ret            = FALSE;
    UINT32  Index          = 0;
 
    for (auto item : g_LoadedModules)
    {
        Index++;
 
        if (strcmp(item->ModuleName, ModuleName) == 0 || strcmp(item->ModuleAlternativeName, ModuleName) == 0)
        {
            //
            // Unload symbol for the module
            //
            Ret = SymUnloadModule64(GetCurrentProcess(), item->ModuleBase);
 
            if (!Ret)
            {
                ShowMessages("err, unload symbol failed (%x)\n",
                             GetLastError());
                return -1;
            }
 
            OneModuleFound = TRUE;
 
            free(item);
 
            break;
        }
    }
 
    if (!OneModuleFound)
    {
        //
        // Not found
        //
        return -1;
    }
 
    //
    // Remove it from the vector
    //
    std::vector<PSYMBOL_LOADED_MODULE_DETAILS>::iterator it = g_LoadedModules.begin();
    std::advance(it, --Index);
    g_LoadedModules.erase(it);
 
    //
    // Success
    //
    return 0;
}

Variable Documentation

g_AbortLoadingExecution

BOOLEAN g_AbortLoadingExecution = FALSE

g_CurrentModuleName

CHAR* g_CurrentModuleName = NULL

g_IsLoadedModulesInitialized

BOOLEAN g_IsLoadedModulesInitialized = FALSE

g_LoadedModules

std::vector<PSYMBOL_LOADED_MODULE_DETAILS> g_LoadedModules

g_MessageHandler

PVOID g_MessageHandler = NULL

The handler for ShowMessages function this is because the user might choose not to use printf and instead use his/her handler for showing messages.

g_SymbolMapForDisassembler

SymbolMapCallback g_SymbolMapForDisassembler = NULL