StackWalkEx-Funktion (dbghelp.h)

Artikel
02/29/2024

Ruft eine Stapelablaufverfolgung ab.

Syntax

BOOL IMAGEAPI StackWalkEx(
  [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]           DWORD                            Flags
);

Parameter

[in] MachineType

Der Architekturtyp des Computers, für den die Stapelablaufverfolgung 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 Stapelablaufverfolgung 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 StackWalkEx-Funktion eindeutig und konsistent gleich ist. Wenn der Symbolhandler mit StackWalkEx verwendet wird, verwenden Sie die gleichen Prozesshandles für die Aufrufe jeder Funktion.

[in] hThread

Ein Handle für den Thread, für den die Stapelablaufverfolgung 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 StackWalkEx-Funktion eindeutig und konsistent gleich ist.

[in, out] StackFrame

Ein Zeiger auf eine STACKFRAME_EX-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 StackWalkEx eine größere Vielfalt von Situationen bewältigen.

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

[in, optional] ReadMemoryRoutine

Eine Rückrufroutine, die Speicherlesedienste bereitstellt. Wenn die StackWalkEx-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 für Symbolhandler 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 StackWalkEx-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 bestimmte 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 Adressübersetzung für 16-Bit-Adressen bereitstellt. Weitere Informationen finden Sie unter TranslateAddressProc64.

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

[in] Flags

Eine Kombination aus null oder mehr Flags.

SYM_STKWALK_DEFAULT (0)

SYM_STKWALK_FORCE_FRAMEPTR (1)

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 StackWalkEx in der Regel nicht den letzten Fehlercode festgelegt.

Hinweise

Die StackWalkEx-Funktion stellt eine portable Methode zum Abrufen einer Stapelablaufverfolgung bereit. Die Verwendung der StackWalkEx-Funktion wird aufgrund aller Komplexitäten, die mit dem Stapelgehen 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 unterschiedlich angezeigt wird, je nachdem, wie das Modul kompiliert wird. Wenn Sie diese Funktion verwenden, verfügt Ihre Anwendung über eine portable Stapelablaufverfolgung, die weiterhin funktioniert, wenn sich der Compiler und das Betriebssystem ändern.

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

Alle DbgHelp-Funktionen, z. B. diese, sind single threaded. 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.