Caminhos de símbolos

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 procurará arquivos de símbolo nos diretórios de disco, chame a funçãoSymSetSearchPath. Como alternativa, você pode especificar um caminho de pesquisa de símbolo no parâmetro UserSearchPath da funçãoSymInitialize.

O parâmetro UserSearchPath em SymInitialize e o parâmetro SearchPath em SymSetSearchPath levar um ponteiro para uma cadeia de caracteres terminada em nulo que especifica um caminho ou uma série de caminhos separados por um ponto-e-vírgula. O manipulador de símbolos usa esses caminhos para procurar arquivos de símbolo. 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 deNULL não, 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 o SymGetSearchPath função.

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 remove 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 encontrar 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 elementos 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. Isto é normalmente "dll", "exe" ou "sys". Por fim, ele aparece em um subdiretório chamado "símbolos" com um diretório com o mesmo nome da 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 seguintes diretórios serão pesquisados.

• c:\meuSímbolos
• c:\mySymbols\dll
• c:\mySymbols\symbols\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 Caminho do Servidor de Símbolos

Um servidor de símbolos elemento de caminho 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*".

Elemento de caminho de 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 nesse 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 lista 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 de .. 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 de cache*c:\myCache que é um elemento de caminho de cache.

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

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

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