SymInitializeW, fonction (dbghelp.h)

Article
11/20/2024

Initialise le gestionnaire de symboles pour un processus.

Syntaxe

BOOL IMAGEAPI SymInitializeW(
  [in]           HANDLE hProcess,
  [in, optional] PCWSTR 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 ê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 lors du débogage d’un autre processus, car l’appel de fonctions comme SymLoadModuleEx peut avoir des résultats inattendus.

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 est 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 de retour

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.

Remarques

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, le lecteur entier 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 retourné à UserSearchPath.

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

Toutes les fonctions DbgHelp, comme celle-ci, sont monothread. Par conséquent, les appels de plusieurs threads à cette fonction entraîneront probablement une altération inattendue du comportement ou de la mémoire. Pour éviter cela, appelez SymInitialize uniquement lorsque votre processus démarre et SymCleanup uniquement lorsque votre processus se termine. Il n’est pas nécessaire pour chaque thread du processus d’appeler 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.

Note

L’en-tête dbghelp.h définit SymInitialize en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.