Símbolos públicos, globais e locais

Os recursos de manipulação de símbolos da API DbgHelp evoluíram ao longo dos anos. Para garantir que seu código funcione em uma variedade de cenários e forneça detalhes completos sobre os símbolos, use as funções mais recentes sempre que possível. Por exemplo, SymEnumSymbols substitui SymEnumerateSymbols64, SymFromName substitui SymGetSymFromName64 e SymFromAddr substitui SymGetSymFromAddr64.

Símbolos Públicos

As versões iniciais do DbgHelp.dll suportavam o exame apenas de símbolos públicos. Esses símbolos são gerados para qualquer item no código que deve ser exposto entre diferentes arquivos de origem. Eles também incluem todos os itens que são exportados para fora do módulo.

Os símbolos são incorporados na imagem ou armazenados separadamente em um arquivo .dbg ou .pdb. A única informação armazenada é o nome e endereço do símbolo. Os nomes estão disponíveis como nomes decorados. Para exibir nomes não decorados, chame a função SymSetOptions com SYMOPT_UNDNAME ou use a função UnDecorateSymbolName.

Observe que a API DbgHelp não foi inicialmente projetada para oferecer suporte a várias instâncias do mesmo símbolo em um módulo. Isso ocorre porque os símbolos públicos são restritos a nomes exclusivos dentro de um módulo. Portanto, SymGetSymFromName64 retorna apenas o primeiro símbolo que corresponde. Para recuperar todos os símbolos que correspondem, chame SymEnumSymbols.

Símbolos Globais e Locais

As versões mais recentes do DbgHelp.dll oferecem suporte a símbolos globais e locais ao usar arquivos .pdb. Essas novas versões incluem funções estáticas, funções com escopo em um arquivo de origem, parâmetros de função e variáveis locais. Quando o DbgHelp procura um símbolo, ele verifica as tabelas de símbolos globais e locais antes de verificar a tabela de símbolos públicos. Isso ocorre porque há mais informações disponíveis para esses tipos de símbolos do que disponíveis para símbolos públicos.

Símbolos globais e locais são armazenados com nomes não decorados. Portanto, a bandeira SYMOPT_UNDNAME não tem efeito. Para obter nomes de símbolos decorados, você deve usar a bandeira SYMOPT_PUBLICS_ONLY. Isso faz com que o DbgHelp pesquise apenas os símbolos públicos.

Para exibir símbolos locais ou parâmetros de função, chame a função SymSetContext com o membro InstructionOffset da estrutura IMAGEHLP_STACK_FRAME definida como o endereço de qualquer símbolo de função. Chamadas subsequentes para SymFromName e SymEnumSymbols podem operar dentro do contexto deste endereço. Para fazer isso, defina o parâmetro BaseOfDll como NULL e omita o especificador de módulo do parâmetro Name ou Mask. Isso força o DbgHelp a procurar símbolos correspondentes dentro do escopo indicado por SymSetContext.

Para determinar se um símbolo é um parâmetro, verifique o membro Flags da estrutura SYMBOL_INFO. Se o símbolo for um parâmetro, o membro conterá SYMFLAG_PARAMETER. Se for um símbolo local, o membro conterá SYMFLAG_LOCAL.