stackWalk 函数 (dbghelp.h)

获取堆栈跟踪。

语法

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 结构的 AddrPCAddrFrameAddrStack 成员,则对此函数的第一次调用将失败。

所有 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

要求

要求
目标平台 Windows
标头 dbghelp.h
Library DbgHelp.lib
DLL DbgHelp.dll
可再发行组件 DbgHelp.dll 5.1 或更高版本

另请参阅

CONTEXT

DbgHelp 函数

FunctionTableAccessProc64

GetModuleBaseProc64

ReadProcessMemoryProc64

STACKFRAME64

TranslateAddressProc64