stackWalk 函数 (dbghelp.h)

项目
02/28/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