StackWalk2 函式（dbghelp.h）

發行項
02/05/2025

取得堆疊追蹤。

語法

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

參數

[in] MachineType

產生堆疊追蹤之電腦的架構類型。此參數可以是下列其中一個值。

價值	意義
IMAGE_FILE_MACHINE_I386 0x014c	Intel x86
IMAGE_FILE_MACHINE_IA64 0x0200	Intel Itanium
IMAGE_FILE_MACHINE_AMD64 0x8664	x64 （AMD64 或 EM64T）
IMAGE_FILE_MACHINE_ARM64 0xaa64	ARM64

[in] hProcess

產生堆疊追蹤之進程的句柄。如果呼叫端為 ReadMemoryRoutine 參數提供有效的回呼指標，則此值不一定是有效的進程句柄。它可以是一個令牌，對於所有呼叫 StackWalk2 函式而言，都是唯一且一致的令牌。如果符號處理程式與 StackWalk2搭配使用，請針對每個函式的呼叫使用相同的進程句柄。

[in] hThread

產生堆疊追蹤之線程的句柄。如果呼叫端提供 ReadMemoryRoutine 參數的有效回呼指標，則此值不一定是有效的線程句柄。它可以是一個令牌，對於所有呼叫 StackWalk2 函式而言，都是唯一且一致的令牌。

[in, out] StackFrame

STACKFRAME_EX 結構的指標。如果函式呼叫成功，這個結構會接收下一個框架的資訊。

[in, out] ContextRecord

ARM64_NT_CONTEXT 結構的指標。只有當 MachineType 參數不是 IMAGE_FILE_MACHINE_I386時，才需要此參數。不過，建議此參數包含有效的內容記錄。這可讓 StackWalk2 處理各種不同的情況。

此內容可以修改，因此請勿傳遞不應修改的內容記錄。

[in, optional] ReadMemoryRoutine

提供記憶體讀取服務的回呼例程。當 StackWalk2 函式需要從進程的位址空間讀取記憶體時，會使用 ReadProcessMemoryProc64 回呼函式。

如果此參數 NULL，則函式會使用預設例程。在此情況下，hProcess 參數必須是有效的進程句柄。

如果此參數未 NULL，則應用程式應該實作並註冊處理 CBA_READ_MEMORY的符號處理程式回呼函式。

[in, optional] FunctionTableAccessRoutine

回呼例程，提供進程運行時間函式數據表的存取權。這是必要參數，因為 StackWalk2 函式無法存取進程的運行時間函式數據表。如需詳細資訊，請參閱 FunctionTableAccessProc64 回呼函式。

符號處理程式會提供載入及存取運行時間數據表的函式。如果使用這些函式，則 SymFunctionTableAccess64 函式可以傳遞為有效的參數。

[in, optional] GetModuleBaseRoutine

回呼例程，提供任何指定虛擬位址的模組基底。這是必要參數。如需詳細資訊，請參閱 PGET_MODULE_BASE_ROUTINE64 回呼函式。

符號處理程式會提供載入和維護模組資訊的函式。如果使用這些函式，則 SymGetModuleBase64 函式可以傳遞為有效的參數。

[in, optional] TranslateAddress

回呼例程，提供16位位址的位址轉譯。如需詳細資訊，請參閱 PTRANSLATE_ADDRESS_ROUTINE64 回呼函式。

大部分 StackWalk2 呼叫者都可以安全地傳遞此參數的 NULL 。

[in, optional] GetTargetAttributeValue

回呼例程，提供逐步執行堆疊所需的目標屬性值。如需詳細資訊，請參閱 PGET_TARGET_ATTRIBUTE_VALUE64 回呼函式。

StackWalk2 的許多呼叫端可以安全地傳遞此參數的 NULL 。 ARM64 平臺上可能利用指標驗證的呼叫端應該提供回呼。

[in] Flags

零個或多個旗標的組合。

SYM_STKWALK_DEFAULT （0）

SYM_STKWALK_FORCE_FRAMEPTR （1）

傳回值

如果函式成功，則傳回值 TRUE。

如果函式失敗，則傳回值 FALSE。請注意，StackWalk2 通常不會設定最後一個錯誤碼。

言論

StackWalk2 函式提供可攜式方法來取得堆疊追蹤。建議使用 StackWalk2 函式來撰寫自己的函式，因為平臺上與堆棧行走相關的所有複雜度。此外，還有一些編譯程式選項會導致堆疊以不同的方式顯示，視模組的編譯方式而定。藉由使用此函式，您的應用程式具有可攜式堆疊追蹤，可在編譯程式和作系統變更時繼續運作。

如果 AddrPC、AddrFrame，以及 AddrStackSTACKFRAME64 結構成員傳入 StackFrame 參數，則第一次呼叫此函式將會失敗。

所有 DbgHelp 函式，例如此函式，都是單個線程。因此，從一個以上的線程呼叫此函式可能會導致非預期的行為或記憶體損毀。若要避免這種情況，您必須將多個線程的所有並行呼叫同步至此函式。