Fonction StackWalk (dbghelp.h)
Obtient une trace de pile.
Syntaxe
BOOL IMAGEAPI StackWalk(
[in] DWORD MachineType,
[in] HANDLE hProcess,
[in] HANDLE hThread,
[in, out] LPSTACKFRAME StackFrame,
[in, out] PVOID ContextRecord,
[in, optional] PREAD_PROCESS_MEMORY_ROUTINE ReadMemoryRoutine,
[in, optional] PFUNCTION_TABLE_ACCESS_ROUTINE FunctionTableAccessRoutine,
[in, optional] PGET_MODULE_BASE_ROUTINE GetModuleBaseRoutine,
[in, optional] PTRANSLATE_ADDRESS_ROUTINE TranslateAddress
);
Paramètres
[in] MachineType
Type d’architecture de l’ordinateur pour lequel la trace de pile est générée. Ce paramètre peut prendre les valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Intel x86 |
|
Intel Itanium |
|
x64 (AMD64 ou EM64T) |
[in] hProcess
Handle du processus pour lequel la trace de pile est générée. Si l’appelant fournit un pointeur de rappel valide pour le paramètre ReadMemoryRoutine , cette valeur ne doit pas être un handle de processus valide. Il peut s’agir d’un jeton unique et cohérent pour tous les appels à la fonction StackWalk64 . Si le gestionnaire de symboles est utilisé avec StackWalk64, utilisez les mêmes handles de processus pour les appels à chaque fonction.
[in] hThread
Handle pour le thread pour lequel la trace de pile est générée. Si l’appelant fournit un pointeur de rappel valide pour le paramètre ReadMemoryRoutine , cette valeur n’a pas besoin d’être un handle de thread valide. Il peut s’agir d’un jeton unique et cohérent pour tous les appels à la fonction StackWalk64 .
[in, out] StackFrame
Pointeur vers une structure STACKFRAME64 . Cette structure reçoit des informations pour l’image suivante, si l’appel de fonction réussit.
[in, out] ContextRecord
Pointeur vers une structure CONTEXT . Ce paramètre est requis uniquement lorsque le paramètre MachineType n’est pas IMAGE_FILE_MACHINE_I386. Toutefois, il est recommandé que ce paramètre contienne un enregistrement de contexte valide. Cela permet à StackWalk64 de gérer une plus grande variété de situations.
Ce contexte peut être modifié. Par conséquent, ne passez pas d’enregistrement de contexte qui ne doit pas être modifié.
[in, optional] ReadMemoryRoutine
Routine de rappel qui fournit des services de lecture de mémoire. Lorsque la fonction StackWalk64 doit lire la mémoire à partir de l’espace d’adressage du processus, le rappel ReadProcessMemoryProc64 est utilisé.
Si ce paramètre a la valeur NULL, la fonction utilise une routine par défaut. Dans ce cas, le paramètre hProcess doit être un handle de processus valide.
Si ce paramètre n’est pas NULL, l’application doit implémenter et inscrire une fonction de rappel de gestionnaire de symboles qui gère CBA_READ_MEMORY.
[in, optional] FunctionTableAccessRoutine
Routine de rappel qui fournit l’accès à la table de fonctions d’exécution pour le processus. Ce paramètre est obligatoire, car la fonction StackWalk64 n’a pas accès à la table de fonctions d’exécution du processus. Pour plus d’informations, consultez FunctionTableAccessProc64.
Le gestionnaire de symboles fournit des fonctions qui chargent et accèdent à la table d’exécution. Si ces fonctions sont utilisées, SymFunctionTableAccess64 peut être passé en tant que paramètre valide.
[in, optional] GetModuleBaseRoutine
Routine de rappel qui fournit une base de module pour une adresse virtuelle donnée. Ce paramètre est obligatoire. Pour plus d’informations, consultez GetModuleBaseProc64.
Le gestionnaire de symboles fournit des fonctions qui chargent et gèrent les informations de module. Si ces fonctions sont utilisées, SymGetModuleBase64 peut être passé en tant que paramètre valide.
[in, optional] TranslateAddress
Routine de rappel qui fournit la traduction d’adresses pour les adresses 16 bits. Pour plus d’informations, consultez TranslateAddressProc64.
La plupart des appelants de StackWalk64 peuvent transmettre en toute sécurité la valeur NULL pour ce paramètre.
Valeur retournée
Si la fonction réussit, la valeur de retour est TRUE.
Si la fonction échoue, la valeur de retour est FALSE. Notez que StackWalk64 ne définit généralement pas le dernier code d’erreur.
Remarques
La fonction StackWalk64 fournit une méthode portable pour obtenir une trace de pile. L’utilisation de la fonction StackWalk64 est recommandée plutôt que l’écriture de votre propre fonction en raison de toutes les complexités associées à la marche de pile sur les plateformes. En outre, il existe des options de compilateur qui entraînent l’affichage de la pile différemment, selon la façon dont le module est compilé. En utilisant cette fonction, votre application dispose d’une trace de pile portable qui continue de fonctionner en tant que modification du compilateur et du système d’exploitation.
Le premier appel à cette fonction échoue si les membres AddrPC, AddrFrame et AddrStack de la structure STACKFRAME64 passées dans le paramètre StackFrame ne sont pas initialisés.
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, vous devez synchroniser tous les appels simultanés de plusieurs threads vers cette fonction.
Cette fonction remplace la fonction StackWalk . Pour plus d’informations, consultez Mise à jour de la prise en charge de la plateforme. StackWalk est défini comme suit dans DbgHelp.h.
#if !defined(_IMAGEHLP_SOURCE_) && defined(_IMAGEHLP64)
#define StackWalk StackWalk64
#else
BOOL
IMAGEAPI
StackWalk(
DWORD MachineType,
__in HANDLE hProcess,
__in HANDLE hThread,
__inout LPSTACKFRAME StackFrame,
__inout PVOID ContextRecord,
__in_opt PREAD_PROCESS_MEMORY_ROUTINE ReadMemoryRoutine,
__in_opt PFUNCTION_TABLE_ACCESS_ROUTINE FunctionTableAccessRoutine,
__in_opt PGET_MODULE_BASE_ROUTINE GetModuleBaseRoutine,
__in_opt PTRANSLATE_ADDRESS_ROUTINE TranslateAddress
);
#endif
Configuration requise
| Condition requise | Valeur |
|---|---|
| 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 |
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour