StackWalk-Funktion (dbghelp.h)

Artikel
08/23/2023

Ruft eine Stapelüberwachung ab.

Syntax

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
);

Parameter

[in] MachineType

Der Architekturtyp des Computers, für den die Stapelüberwachung generiert wird. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
IMAGE_FILE_MACHINE_I386 0x014c	Intel x86
IMAGE_FILE_MACHINE_IA64 0x0200	Intel Itanium
IMAGE_FILE_MACHINE_AMD64 0x8664	x64 (AMD64 oder EM64T)

[in] hProcess

Ein Handle für den Prozess, für den die Stapelüberwachung generiert wird. Wenn der Aufrufer einen gültigen Rückrufzeiger für den ReadMemoryRoutine-Parameter bereitstellt, muss dieser Wert kein gültiges Prozesshandle sein. Es kann ein Token sein, das für alle Aufrufe der StackWalk64-Funktion eindeutig und konsistent identisch ist. Wenn der Symbolhandler mit StackWalk64 verwendet wird, verwenden Sie die gleichen Prozesshandles für die Aufrufe der einzelnen Funktionen.

[in] hThread

Ein Handle für den Thread, für den die Stapelüberwachung generiert wird. Wenn der Aufrufer einen gültigen Rückrufzeiger für den ReadMemoryRoutine-Parameter bereitstellt, muss dieser Wert kein gültiges Threadhandle sein. Es kann ein Token sein, das für alle Aufrufe der StackWalk64-Funktion eindeutig und konsistent identisch ist.

[in, out] StackFrame

Ein Zeiger auf eine STACKFRAME64-Struktur . Diese Struktur empfängt Informationen für den nächsten Frame, wenn der Funktionsaufruf erfolgreich ist.

[in, out] ContextRecord

Ein Zeiger auf eine CONTEXT-Struktur . Dieser Parameter ist nur erforderlich, wenn der MachineType-Parameter nicht IMAGE_FILE_MACHINE_I386 ist. Es wird jedoch empfohlen, dass dieser Parameter einen gültigen Kontextdatensatz enthält. Dadurch kann StackWalk64 eine größere Vielfalt von Situationen bewältigen.

Dieser Kontext kann geändert werden. Übergeben Sie daher keinen Kontextdatensatz, der nicht geändert werden soll.

[in, optional] ReadMemoryRoutine

Eine Rückrufroutine, die Speicherlesedienste bereitstellt. Wenn die StackWalk64-Funktion Arbeitsspeicher aus dem Adressraum des Prozesses lesen muss, wird der ReadProcessMemoryProc64-Rückruf verwendet.

Wenn dieser Parameter NULL ist, verwendet die Funktion eine Standardroutine. In diesem Fall muss der hProcess-Parameter ein gültiges Prozesshandle sein.

Wenn dieser Parameter nicht NULL ist, sollte die Anwendung eine Rückruffunktion des Symbolhandlers implementieren und registrieren, die CBA_READ_MEMORY verarbeitet.

[in, optional] FunctionTableAccessRoutine

Eine Rückrufroutine, die Zugriff auf die Laufzeitfunktionstabelle für den Prozess ermöglicht. Dieser Parameter ist erforderlich, da die StackWalk64-Funktion keinen Zugriff auf die Laufzeitfunktionstabelle des Prozesses hat. Weitere Informationen finden Sie unter FunctionTableAccessProc64.

Der Symbolhandler stellt Funktionen bereit, die die Laufzeittabelle laden und darauf zugreifen. Wenn diese Funktionen verwendet werden, kann SymFunctionTableAccess64 als gültiger Parameter übergeben werden.

[in, optional] GetModuleBaseRoutine

Eine Rückrufroutine, die eine Modulbasis für jede angegebene virtuelle Adresse bereitstellt. Dieser Parameter ist erforderlich. Weitere Informationen finden Sie unter GetModuleBaseProc64.

Der Symbolhandler stellt Funktionen bereit, die Modulinformationen laden und verwalten. Wenn diese Funktionen verwendet werden, kann SymGetModuleBase64 als gültiger Parameter übergeben werden.

[in, optional] TranslateAddress

Eine Rückrufroutine, die die Adressübersetzung für 16-Bit-Adressen bereitstellt. Weitere Informationen finden Sie unter TranslateAddressProc64.

Die meisten Aufrufer von StackWalk64 können NULL für diesen Parameter sicher übergeben.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert TRUE.

Wenn die Funktion fehlschlägt, ist der Rückgabewert FALSE. Beachten Sie, dass StackWalk64 im Allgemeinen nicht den letzten Fehlercode festgelegt.

Hinweise

Die StackWalk64-Funktion stellt eine portable Methode zum Abrufen einer Stapelüberwachung bereit. Die Verwendung der StackWalk64-Funktion wird aufgrund aller Komplexitäten, die mit dem Gehen von Stapeln auf Plattformen verbunden sind, gegenüber dem Schreiben einer eigenen Funktion empfohlen. Darüber hinaus gibt es Compileroptionen, die dazu führen, dass der Stapel je nach Kompilierung des Moduls unterschiedlich angezeigt wird. Mit dieser Funktion verfügt Ihre Anwendung über eine portable Stapelüberwachung, die weiterhin funktioniert, wenn sich der Compiler und das Betriebssystem ändern.

Der erste Aufruf dieser Funktion schlägt fehl, wenn die AddrPC-, AddrFrame- und AddrStack-Member der im StackFrame-Parameter übergebenen STACKFRAME64-Struktur nicht initialisiert sind.

Alle DbgHelp-Funktionen, z. B. diese, sind singlethreaded. Daher führen an diese Funktion gerichtete Aufrufe mehrerer Threads wahrscheinlich zu unerwartetem Verhalten oder einer Beschädigung des Speichers. Um dies zu vermeiden, müssen Sie alle an diese Funktion gerichteten gleichzeitigen Aufrufe mehrerer Threads synchronisieren.

Diese Funktion ersetzt die StackWalk-Funktion . Weitere Informationen finden Sie unter Aktualisierte Plattformunterstützung. StackWalk ist in DbgHelp.h wie folgt definiert.

#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