StackWalk 函式 (dbghelp.h)

發行項
03/05/2024

取得堆疊追蹤。

語法

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

參數

[in] MachineType

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

值	意義
IMAGE_FILE_MACHINE_I386 0x014c	Intel x86
IMAGE_FILE_MACHINE_IA64 0x0200	Intel Itanium
IMAGE_FILE_MACHINE_AMD64 0x8664	x64 (AMD64 或 EM64T)

[in] hProcess

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

[in] hThread

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

[in, out] StackFrame

STACKFRAME64 結構的指標。如果函數調用成功，這個結構就會接收下一個框架的資訊。

[in, out] ContextRecord

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

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

[in, optional] ReadMemoryRoutine

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

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

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

[in, optional] FunctionTableAccessRoutine

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

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

[in, optional] GetModuleBaseRoutine

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

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

[in, optional] TranslateAddress

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

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

傳回值

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

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

備註

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

如果未初始化在 StackFrame 參數中傳遞之STACKFRAME64結構的 AddrPC、AddrFrame 和 AddrStack 成員，則第一次呼叫此函式將會失敗。

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

此函式會取代 StackWalk 函式。如需詳細資訊，請參閱更新的平台支援。 StackWalk 的定義如下：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