StackWalk2 函数（dbghelp.h）

2025-02-05

获取堆栈跟踪。

语法

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，并且未初始化在 StackFrame 参数中传递的 STACKFRAME64 结构 成员，则对此函数的第一次调用将失败。

所有 DbgHelp 函数（如此函数）都是单线程的。因此，从多个线程调用此函数可能会导致意外行为或内存损坏。若要避免这种情况，必须将来自多个线程的所有并发调用同步到此函数。