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
为其生成堆栈跟踪的计算机的体系结构类型。 此参数的取值可为下列值之一:
值 | 含义 |
---|---|
|
Intel x86 |
|
Intel Itanium |
|
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
要求
要求 | 值 |
---|---|
目标平台 | Windows |
标头 | dbghelp.h |
Library | DbgHelp.lib |
DLL | DbgHelp.dll |
可再发行组件 | DbgHelp.dll 5.1 或更高版本 |