StackWalk

The StackWalk function provides a portable method for obtaining a stack trace.

This function is implemented as a wrapper that calls StackWalk64. For more information, see New 64-bit Functions.

BOOL StackWalk(
  DWORD MachineType, 
  HANDLE hProcess, 
  HANDLE hThread, 
  LPSTACKFRAME StackFrame, 
  PVOID ContextRecord, 
  PREAD_PROCESS_MEMORY_ROUTINE ReadMemoryRoutine,  
  PFUNCTION_TABLE_ACCESS_ROUTINE FunctionTableAccessRoutine,
  PGET_MODULE_BASE_ROUTINE GetModuleBaseRoutine, 
  PTRANSLATE_ADDRESS_ROUTINE TranslateAddress 
);

For StackWalk64, the parameter list is as follows.

BOOL StackWalk64(
  DWORD MachineType, 
  HANDLE hProcess, 
  HANDLE hThread, 
  LPSTACKFRAME64 StackFrame, 
  PVOID ContextRecord, 
  PREAD_PROCESS_MEMORY_ROUTINE64 ReadMemoryRoutine,  
  PFUNCTION_TABLE_ACCESS_ROUTINE64 FunctionTableAccessRoutine,
  PGET_MODULE_BASE_ROUTINE64 GetModuleBaseRoutine, 
  PTRANSLATE_ADDRESS_ROUTINE64 TranslateAddress 
);

Parameters

MachineType

[in] Specifies the architecture type of the computer for which the stack trace is generated. This parameter can be one of the following values.

Value	Meaning
IMAGE_FILE_MACHINE_I386	Intel
IMAGE_FILE_MACHINE_ALPHA	DEC Alpha
IMAGE_FILE_MACHINE_IA64	Intel (64-bit)
IMAGE_FILE_MACHINE_AXP64	DEC Alpha (64-bit)

hProcess

[in] Handle to the process for which the stack trace is generated. If the caller supplies a valid callback pointer for the ReadMemoryRoutine parameter, then this value does not have to be a valid process handle. It can be a token that is unique and consistently the same for all calls to the StackWalk function. If the symbol handler is used with StackWalk, use the same process handles for the calls to each function.

hThread

[in] Handle to the thread for which the stack trace is generated. If the caller supplies a valid callback pointer for the ReadMemoryRoutine parameter, then this value does not have to be a valid thread handle. It can be a token that is unique and consistently the same for all calls to the StackWalk function.

StackFrame

[out] Pointer to a STACKFRAME structure. This structure receives information for the next frame, if the function call succeeds.

ContextRecord

[in] Pointer to a CONTEXT structure. This parameter is required only when the MachineType parameter is not IMAGE_FILE_MACHINE_I386.

ReadMemoryRoutine

[in] Pointer to a callback routine that provides memory read services. When the StackWalk function needs to read memory from the process's address space, the ReadProcessMemoryProc callback is used. If NULL is passed, then the ReadProcessMemory function is used. In this case, the hProcess parameter must be a valid process handle.

FunctionTableAccessRoutine

[in] Pointer to a callback routine that provides access to the run-time function table for the process. For RISC computers, this function accesses the pdata table, while on X86 computers this function accesses the fpo table. This parameter is required because the StackWalk function does not have access to the process's run-time function table. For more information, see FunctionTableAccessProc.

The symbol handler provides functions that load and access the run-time table. If these functions are used, then SymFunctionTableAccess can be passed as a valid parameter.

GetModuleBaseRoutine

[in] Pointer to a callback routine that provides a module base for any given virtual address. This parameter is required. For more information, see GetModuleBaseProc.

The symbol handler provides functions that load and maintain module information. If these functions are used, then SymGetModuleBase can be passed as a valid parameter.

TranslateAddress

[in] Pointer to a callback routine that provides address translation for 16-bit addresses. For more information, see TranslateAddressProc.

Most callers of StackWalk can safely pass NULL for this parameter.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The StackWalk function provides a portable method for obtaining a stack trace. Using the StackWalk function is recommended over writing your own function because of all the complexities associated with stack walking on platforms. In addition, there are compiler options that cause the stack to appear differently, depending on how the module is compiled. By using this function, your application has a portable stack trace that continues to work as the compiler and operating system change.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 or later.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in Dbghelp.h.
  Library: Use Dbghelp.lib.

See Also

Debug Help Library Overview, DbgHelp Functions, CONTEXT, FunctionTableAccessProc, GetModuleBaseProc, ReadProcessMemoryProc, STACKFRAME, TranslateAddressProc