Chemins d'accès aux symboles

La bibliothèque DbgHelp utilise le chemin de recherche de symboles pour localiser les symboles de débogage (fichiers .pdb et .dbg). Le chemin de recherche peut être constitué d’un ou plusieurs éléments de chemin séparés par des points-virgules.

Spécification des chemins de recherche

Pour spécifier l’emplacement où le gestionnaire de symboles recherche les fichiers de symboles dans les répertoires de disque, appelez la fonction SymSetSearchPath . Vous pouvez également spécifier un chemin de recherche de symbole dans le paramètre UserSearchPath de la fonction SymInitialize .

Le paramètre UserSearchPath dans SymInitialize et le paramètre SearchPath dans SymSetSearchPath prennent un pointeur vers une chaîne terminée par un caractère Null qui spécifie un chemin d’accès ou une série de chemins séparés par un point-virgule. Le gestionnaire de symboles utilise ces chemins d’accès pour rechercher des fichiers de symboles. Si ce paramètre a la valeur NULL, le gestionnaire de symboles recherche le répertoire qui contient le module pour lequel les symboles font l’objet d’une recherche. Sinon, si ce paramètre est spécifié en tant que valeur non NULL , le gestionnaire de symboles recherche d’abord les chemins définis par l’application avant de rechercher le répertoire du module. Si vous définissez la variable d’environnement _NT_SYMBOL_PATH ou _NT_ALT_SYMBOL_PATH, le gestionnaire de symboles recherche les fichiers de symboles dans l’ordre suivant :

1. Variable d’environnement _NT_SYMBOL_PATH.
2. Variable d’environnement _NT_ALT_SYMBOL_PATH.
3. Répertoire qui contient le module correspondant.

Pour récupérer les chemins de recherche, appelez la fonction SymGetSearchPath .

Le chemin de recherche des fichiers de base de données de programme (.pdb) est différent du chemin d’accès pour les fichiers de débogage (.dbg). L’algorithme est déterminé par les fonctionnalités de la bibliothèque de symboles. Par défaut, Microsoft Visual C/C++ crée des symboles de format Microsoft, les supprime de l’image et les place dans un fichier .pdb distinct. En règle générale, le fichier .pdb se trouve dans le répertoire qui contient l’image exécutable. Visual C/C++ incorpore le chemin absolu du fichier .pdb dans l’image exécutable. Si le gestionnaire de symboles ne trouve pas le fichier .pdb à cet emplacement ou si le fichier .pdb a été déplacé vers un autre répertoire, le gestionnaire de symboles localise le fichier .pdb à l’aide du chemin de recherche décrit pour les fichiers .dbg.

Types d’éléments Path

Il existe trois types d’éléments de chemin d’accès.

Standard Path, élément

Un élément de chemin d’accès standard fait l’objet d’une recherche à la racine du répertoire spécifié par l’élément path. Le gestionnaire de symboles recherche également dans un sous-répertoire de « symboles » qui correspond à l’extension de fichier du module que les symboles sont recherchés. Il s’agit généralement de « dll », « exe » ou « sys ». Enfin, il se trouve dans un sous-répertoire appelé « symbols » avec un répertoire du même nom que l’extension. Par exemple, si l’élément de chemin de symbole est « c:\mySymbols » et que le fichier dans lequel les symboles sont recherchés est « boo.dll », les répertoires suivants font l’objet d’une recherche.

• c:\mySymbols
• c:\mySymbols\dll
• c:\mySymbols\symbols\dll

Le gestionnaire de symboles utilise cette logique pour rechercher un élément de chemin qui ne répond pas aux critères d’un serveur de symboles ou d’un cache (décrits ci-dessous).

Symbol Server Path, élément

Un élément de chemin du serveur de symboles utilise une technologie spéciale qui peut localiser un symbole qui correspond exactement au module en question. Pour plus d’informations, consultez Utilisation de SymSrv .

Le gestionnaire de symboles traite un élément path comme un serveur de symboles s’il commence par le texte, « srv* ».

Notes

Si le texte « srv* » n’est pas spécifié, mais que l’élément path réel est un magasin de serveurs de symboles, le gestionnaire de symboles agit comme si « srv* » était spécifié. Le gestionnaire de symboles effectue cette détermination en recherchant l’existence d’un fichier appelé « pingme.txt » dans le répertoire racine du chemin spécifié.

 

Cache Path, élément

Un élément de chemin d’accès au cache est une variante d’un élément de chemin de serveur de symboles.

Ce répertoire fait l’objet d’une recherche comme n’importe quel autre serveur de symboles. Toutefois, si le symbole est introuvable ici et qu’il se trouve dans un élément path plus loin dans la chaîne du chemin d’accès du symbole, le symbole est copié et stocké dans le serveur de symboles spécifié dans cet élément.

Le gestionnaire de symboles traite un élément path comme un élément de cache s’il commence par le texte, « cache* ». Pour spécifier un cache dans « c:\myCache », utilisez un élément de chemin de symbole de « cache*c:\myCache ».

Exemple de chemin de recherche

Pour voir comment cela fonctionne, définissez ce chemin de recherche.

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

Voici une liste de la sortie détaillée du gestionnaire de symboles lors de la recherche de ntdll.pdb, à l’aide du chemin de recherche répertorié ci-dessus.

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

Les trois premières lignes de sortie montrent le gestionnaire de symboles qui traite le premier élément path de .. Il s’agit d’un élément path standard.

La quatrième ligne montre le gestionnaire de symboles à l’aide du serveur de symboles pour rechercher le fichier dans le deuxième élément path dont est un élément de chemin d’accès au cache*c:\myCache cache.

La cinquième ligne montre que le fichier se trouve dans le troisième élément path de srv*\\symbols\symbols, qui est un élément de chemin de serveur de symboles.

La sixième ligne indique que le fichier est copié dans le cache.

Les deux dernières lignes que le fichier est ouvert à partir du cache.