StackWalk2, fonction (dbghelp.h)

Obtient une trace de pile.

Syntaxe

BOOL IMAGEAPI StackWalk2(
  [in]           DWORD                            MachineType,
  [in]           HANDLE                           hProcess,
  [in]           HANDLE                           hThread,
  [in, out]      LPSTACKFRAME_EX                  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,
  [in, optional] PGET_TARGET_ATTRIBUTE_VALUE64    GetTargetAttributeValue,
  [in]           DWORD                            Flags
);

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 être l’une des valeurs suivantes.

[in] hProcess

Handle vers le 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 cohérent pour tous les appels à la fonction StackWalk2. Si le gestionnaire de symboles est utilisé avec StackWalk2, utilisez les mêmes handles de processus pour les appels à chaque fonction.

[in] hThread

Handle vers 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 StackWalk2.

[in, out] StackFrame

Pointeur vers une structure STACKFRAME_EX. Cette structure reçoit des informations pour l’image suivante, si l’appel de fonction réussit.

[in, out] ContextRecord

Pointeur vers une structure ARM64_NT_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 StackWalk2 de gérer une plus grande variété de situations.

Ce contexte peut être modifié. Ne passez donc 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 StackWalk2 doit lire la mémoire à partir de l’espace d’adressage du processus, la fonction de rappel ReadProcessMemoryProc64 est utilisée.

Si ce paramètre est 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 requis, car la fonction StackWalk2 n’a pas accès à la table de fonctions d’exécution du processus. Pour plus d’informations, consultez fonction de rappel FunctionTableAccessProc64.

Le gestionnaire de symboles fournit des fonctions qui chargent et accèdent à la table d’exécution. Si ces fonctions sont utilisées, la fonction SymFunctionTableAccess64 peut être passée 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 requis. Pour plus d’informations, consultez PGET_MODULE_BASE_ROUTINE64 fonction de rappel.

Le gestionnaire de symboles fournit des fonctions qui chargent et gèrent les informations du module. Si ces fonctions sont utilisées, la fonction SymGetModuleBase64 peut être passée 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 PTRANSLATE_ADDRESS_ROUTINE64 fonction de rappel.

La plupart des appelants de StackWalk2 peuvent passer en toute sécurité NULL pour ce paramètre.

[in, optional] GetTargetAttributeValue

Routine de rappel qui fournit les valeurs des attributs cibles requis pour parcourir la pile. Pour plus d’informations, consultez PGET_TARGET_ATTRIBUTE_VALUE64 fonction de rappel.

De nombreux appelants de StackWalk2 peuvent passer en toute sécurité NULL pour ce paramètre. Les appelants sur les plateformes ARM64 qui peuvent utiliser l’authentification de pointeur doivent fournir un rappel.

[in] Flags

Combinaison de zéro ou plus d’indicateurs.

SYM_STKWALK_DEFAULT (0)

SYM_STKWALK_FORCE_FRAMEPTR (1)

Valeur de retour

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

Si la fonction échoue, la valeur de retour est FALSE. Notez que StackWalk2 ne définit généralement pas le dernier code d’erreur.

Remarques

La fonction StackWalk2 fournit une méthode portable pour obtenir une trace de pile. L’utilisation de la fonction StackWalk2 est recommandée pour écrire votre propre fonction en raison de toutes les complexités associées à la marche 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é. À l’aide de cette fonction, votre application dispose d’une trace de pile portable qui continue de fonctionner en tant que compilateur et modification du système d’exploitation.

Le premier appel à cette fonction échoue si le AddrPC, AddrFrameet les membres AddrStack de la structure STACKFRAME64 passées dans le paramètre StackFrame ne sont pas initialisés.

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, vous devez synchroniser tous les appels simultanés de plusieurs threads vers cette fonction.

Exigences

Voir aussi

ARM64_NT_CONTEXT structure

fonctions DbgHelp

fonction de rappel FunctionTableAccessProc64

fonction de rappel ReadProcessMemoryProc64

STACKFRAME_EX structure

fonction SymFunctionTableAccess64

fonction SymGetModuleBase64

PTRANSLATE_ADDRESS_ROUTINE64 fonction de rappel

PGET_TARGET_ATTRIBUTE_VALUE64 fonction de rappel