Caminhos de símbolo

  • Artigo

A biblioteca DbgHelp usa o caminho de pesquisa de símbolos para localizar símbolos de depuração (arquivos .pdb e .dbg). O caminho de pesquisa pode ser composto por um ou mais elementos de caminho separados por ponto-e-vírgula.

Especificando caminhos de pesquisa

Para especificar onde o manipulador de símbolos pesquisará arquivos de símbolo em diretórios de disco, chame a função SymSetSearchPath. Como alternativa, você pode especificar um caminho de pesquisa de símbolo no parâmetro UserSearchPath da função SymInitialize .

O parâmetro UserSearchPath em SymInitialize e o parâmetro SearchPath em SymSetSearchPath levam um ponteiro para uma cadeia de caracteres terminada em nulo que especifica um caminho ou uma série de caminhos separados por ponto-e-vírgula. O manipulador de símbolos usa esses caminhos para procurar arquivos de símbolos. Se esse parâmetro for NULL, o manipulador de símbolos pesquisará o diretório que contém o módulo para o qual os símbolos estão sendo pesquisados. Caso contrário, se esse parâmetro for especificado como um valor não-NULL, o manipulador de símbolos primeiro pesquisará os caminhos definidos pelo aplicativo antes de pesquisar o diretório do módulo. Se você definir a variável de ambiente _NT_SYMBOL_PATH ou _NT_ALT_SYMBOL_PATH, o manipulador de símbolos procurará arquivos de símbolo na seguinte ordem:

  1. A variável de ambiente _NT_SYMBOL_PATH.
  2. A variável de ambiente _NT_ALT_SYMBOL_PATH.
  3. O diretório que contém o módulo correspondente.

Para recuperar os caminhos de pesquisa, chame a função SymGetSearchPath.

O caminho de pesquisa para arquivos de banco de dados de programa (.pdb) é diferente do caminho para arquivos de depuração (.dbg). O algoritmo é determinado pela funcionalidade da biblioteca de símbolos. Por padrão, o Microsoft Visual C/C++ cria símbolos de formato da Microsoft, os retira da imagem e os coloca em um arquivo .pdb separado. Normalmente, o arquivo .pdb estará localizado no diretório que contém a imagem executável. Visual C/C++ incorpora o caminho absoluto para o arquivo .pdb na imagem executável. Se o manipulador de símbolos não conseguir localizar o arquivo .pdb nesse local ou se o arquivo .pdb tiver sido movido para outro diretório, o manipulador de símbolos localizará o arquivo .pdb usando o caminho de pesquisa descrito para arquivos .dbg.

Tipos de elemento de caminho

Existem três tipos de elementos de caminho.

Elemento de caminho padrão

Um elemento de caminho padrão é pesquisado procurando na raiz do diretório especificado pelo elemento path. O manipulador de símbolos também procura em um subdiretório de "símbolos" que corresponde à extensão de arquivo do módulo que os símbolos estão sendo procurados. Isso normalmente é "dll", "exe" ou "sys". Por fim, ele procura em um subdiretório chamado "símbolos" com um diretório de mesmo nome que a extensão. Por exemplo, se o elemento de caminho do símbolo for "c:\mySymbols" e o arquivo que os símbolos estão sendo pesquisados for "boo.dll", os diretórios a seguir serão pesquisados.

  • c:\meuSímbolos
  • c:\meuSímbolos\dll
  • c:\mySymbols\símbolos\dll

O manipulador de símbolos usa essa lógica para pesquisar qualquer elemento de caminho que não atenda aos critérios para ser um servidor de símbolos ou cache (descrito abaixo).

Elemento de caminho do servidor de símbolos

Um elemento de caminho do servidor de símbolos usa tecnologia especial que pode localizar um símbolo que é uma correspondência exata para o módulo em questão. Consulte Usando o SymSrv para obter mais detalhes.

O manipulador de símbolos trata um elemento de caminho como um servidor de símbolos se ele começar com o texto, "srv*".

Observação

Se o texto "srv*" não for especificado, mas o elemento de caminho real for um armazenamento de servidor de símbolos, o manipulador de símbolos agirá como se "srv*" fosse especificado. O manipulador de símbolos faz essa determinação pesquisando a existência de um arquivo chamado "pingme.txt" no diretório raiz do caminho especificado.

 

Elemento Caminho do Cache

Um elemento de caminho de cache é uma variação em um elemento de caminho do servidor de símbolos.

Este diretório é pesquisado como qualquer outro servidor de símbolos. No entanto, se o símbolo não for encontrado aqui e for encontrado em um elemento de caminho mais abaixo na cadeia do caminho do símbolo, o símbolo será copiado e armazenado no servidor de símbolos especificado neste elemento.

O manipulador de símbolos trata um elemento path como um elemento de cache se ele começar com o texto, "cache*". Para especificar um cache em "c:\myCache", use um elemento de caminho de símbolo de "cache*c:\myCache".

Exemplo de caminho de pesquisa

Para ver como isso funciona, defina este caminho de pesquisa.

cache*c:\myCache;srv*\\symbols\symbols

A seguir está uma listagem da saída detalhada do manipulador de símbolos ao procurar ntdll.pdb, usando o caminho de pesquisa listado acima.

DBGHELP: .\ntdll.pdb - file not found
DBGHELP: .\dll\ntdll.pdb - file not found
DBGHELP: .\symbols\dll\ntdll.pdb - file not found
SYMSRV: c:\myCache\ntdll.pdb\0F7FCF88442F4B0E9FB51DC4A754D9DE2\ntdll.pdb not found
SYMSRV: ntdll.pdb from \\symbols\symbols: 10497024 bytes - copied
DBGHELP: c:\myCache\ntdll.pdb\0F7FCF88442F4B0E9FB51DC4A754D9DE2\ntdll.pdb already cached
DBGHELP: ntdll - private symbols & lines
c:\myCache\ntdll.pdb\0F7FCF88442F4B0E9FB51DC4A754D9DE2\ntdll.pdb

As três primeiras linhas de saída mostram o manipulador de símbolos processando o primeiro elemento de caminho do .. Este é um elemento de caminho padrão.

A quarta linha mostra o manipulador de símbolos usando o servidor de símbolos para procurar o arquivo no segundo elemento de caminho do qual é um elemento de caminho de cache*c:\myCache cache.

A quinta linha mostra que o arquivo é encontrado no terceiro elemento path do , que é um elemento de caminho do servidor de srv*\\symbols\symbolssímbolos.

A sexta linha mostra que o arquivo é copiado para o cache.

As duas últimas linhas em que o arquivo é aberto a partir do cache.