Fonction StackWalk64 (dbghelp.h)
Obtient une trace de pile.
Syntaxe
BOOL IMAGEAPI StackWalk64(
[in] DWORD MachineType,
[in] HANDLE hProcess,
[in] HANDLE hThread,
[in, out] LPSTACKFRAME64 StackFrame,
[in, out] PVOID ContextRecord,
[in, optional] PREAD_PROCESS_MEMORY_ROUTINE64 ReadMemoryRoutine,
[in, optional] PFUNCTION_TABLE_ACCESS_ROUTINE64 FunctionTableAccessRoutine,
[in, optional] PGET_MODULE_BASE_ROUTINE64 GetModuleBaseRoutine,
[in, optional] PTRANSLATE_ADDRESS_ROUTINE64 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 n’a pas besoin d’être un handle de processus valide. Il peut s’agir d’un jeton unique et toujours le même 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 du 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 toujours le même 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 n’est requis que 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 étant susceptible d’être modifié, 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’a pas la valeur NULL, l’application doit implémenter et inscrire une fonction de rappel du 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 des 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 passer la valeur NULL en toute sécurité 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.
Notes
La fonction StackWalk64 fournit une méthode portable pour obtenir une trace de pile. Il est recommandé d’utiliser la fonction StackWalk64 plutôt que d’écrire votre propre fonction en raison de toutes les complexités associées à la marche à pied de la pile sur les plateformes. En outre, il existe des options de compilateur qui entraînent l’affichage de la pile différemment, en fonction de 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és 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
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 |