Fonction SymInitialize (dbghelp.h)

Article
03/11/2023

Initialise le gestionnaire de symboles pour un processus.

Syntaxe

BOOL IMAGEAPI SymInitialize(
  [in]           HANDLE hProcess,
  [in, optional] PCSTR  UserSearchPath,
  [in]           BOOL   fInvadeProcess
);

Paramètres

[in] hProcess

Handle qui identifie l’appelant. Cette valeur doit être unique et différente de zéro, mais ne doit pas nécessairement être un handle de processus. Toutefois, si vous utilisez un handle de processus, veillez à utiliser le handle approprié. Si l’application est un débogueur, utilisez le handle de processus pour le processus en cours de débogage. N’utilisez pas le handle retourné par GetCurrentProcess. Le handle utilisé doit être unique pour éviter de partager une session avec un autre composant, et l’utilisation de GetCurrentProcess peut avoir des résultats inattendus lorsque plusieurs composants tentent d’utiliser dbghelp pour inspecter le processus actuel. L’utilisation de GetCurrentProcess lors du débogage d’un autre processus entraîne également des résultats inattendus pour des fonctions telles que SymLoadModuleEx .

Ce paramètre ne peut pas être NULL.

[in, optional] UserSearchPath

Chemin d’accès, ou série de chemins séparés par un point-virgule (;), utilisé pour rechercher des fichiers de symboles. Si ce paramètre a la valeur NULL, la bibliothèque tente de former un chemin de symbole à partir des sources suivantes :

Répertoire de travail actuel de l’application
Variable d’environnement _NT_SYMBOL_PATH
Variable d’environnement _NT_ALTERNATE_SYMBOL_PATH

Notez que le chemin de recherche peut également être défini à l’aide de la fonction SymSetSearchPath .

[in] fInvadeProcess

Si cette valeur est TRUE, énumère les modules chargés pour le processus et appelle efficacement la fonction SymLoadModule64 pour chaque module.

Valeur retournée

Si la fonction réussit, la valeur de retour est TRUE.

Si la fonction échoue, la valeur de retour est FALSE. Pour récupérer des informations d’erreur étendues, appelez GetLastError.

Notes

La fonction SymInitialize est utilisée pour initialiser le gestionnaire de symboles pour un processus. Dans le contexte du gestionnaire de symboles, un processus est un objet pratique à utiliser lors de la collecte d’informations sur les symboles. En règle générale, les gestionnaires de symboles sont utilisés par les débogueurs et d’autres outils qui doivent charger des symboles pour un processus en cours de débogage.

Le handle passé à SymInitialize doit être la même valeur passée à toutes les autres fonctions de gestionnaire de symboles appelées par le processus. Il s’agit du handle que les fonctions utilisent pour identifier l’appelant et localiser les informations de symbole correctes. Lorsque vous avez terminé d’utiliser les informations de symbole, appelez la fonction SymCleanup pour libérer toutes les ressources associées au processus pour lequel les symboles sont chargés.

La recherche de fichiers de symboles est effectuée de manière récursive pour tous les chemins spécifiés dans le paramètre UserSearchPath . Par conséquent, si vous spécifiez le répertoire racine dans une recherche, l’ensemble du lecteur est recherché, ce qui peut prendre beaucoup de temps. Notez que le répertoire qui contient le fichier exécutable du processus ne fait pas automatiquement partie du chemin de recherche. Pour inclure ce répertoire dans le chemin de recherche, appelez la fonction GetModuleFileNameEx , puis ajoutez le chemin d’accès retourné à UserSearchPath.

Un processus qui appelle SymInitialize ne doit pas l’appeler à nouveau, sauf s’il appelle SymCleanup en premier. Si l’appel à SymInitialize définit fInvadeProcess sur TRUE et que vous devez simplement recharger la liste des modules, utilisez la fonction SymRefreshModuleList .

Toutes les fonctions DbgHelp, telles que celle-ci, sont à thread unique. Par conséquent, les appels de plusieurs threads à cette fonction entraîneront probablement un comportement inattendu ou une altération de la mémoire. Pour éviter cela, appelez SymInitialize uniquement au démarrage de votre processus et SymCleanup uniquement à la fin de votre processus. Il n’est pas nécessaire que chaque thread du processus appelle ces fonctions.

Pour appeler la version Unicode de cette fonction, définissez DBGHELP_TRANSLATE_TCHAR.

Exemples

Pour obtenir un exemple, consultez Initialisation du gestionnaire de symboles.

Spécifications


Plateforme cible	Windows
En-tête	dbghelp.h
Bibliothèque	Dbghelp.lib
DLL	Dbghelp.dll
Composant redistribuable	DbgHelp.dll 5.1 ou version ultérieure