IDebugControl4::GetContextStackTrace method (dbgeng.h)

The GetContextStackTrace method returns the frames at the top of the call stack, starting with an arbitrary register context and returning the reconstructed register context for each stack frame.

Syntax

HRESULT GetContextStackTrace(
  [in, optional]  PVOID              StartContext,
  [in]            ULONG              StartContextSize,
  [out, optional] PDEBUG_STACK_FRAME Frames,
  [in]            ULONG              FramesSize,
  [out, optional] PVOID              FrameContexts,
  [in]            ULONG              FrameContextsSize,
  [in]            ULONG              FrameContextsEntrySize,
  [out, optional] PULONG             FramesFilled
);

Parameters

[in, optional] StartContext

Specifies the register context for the top of the stack.

[in] StartContextSize

Specifies the size, in bytes, of the StartContext register context.

[out, optional] Frames

Receives the stack frames. The number of elements this array holds is FrameSize. If Frames is NULL, this information is not returned.

[in] FramesSize

Specifies the number of items in the array Frames.

[out, optional] FrameContexts

Receives the reconstructed register context for each frame in the stack. The entries in this array correspond to the entries in the Frames array. The type of the thread context is the CONTEXT structure for the target's effective processor. If FrameContexts is NULL, this information is not returned.

[in] FrameContextsSize

Specifies the size, in bytes, of the memory pointed to by FrameContexts. The number of stack frames returned equals the number of contexts returned, and FrameContextsSize must equal FramesSize times FrameContextsEntrySize.

[in] FrameContextsEntrySize

Specifies the size, in bytes, of each frame context in FrameContexts.

[out, optional] FramesFilled

Receives the number of frames that were placed in the array Frames and contexts in FrameContexts. If FramesFilled is NULL, this information is not returned.

Return value

This method can also return error values. For more information, see Return Values.

Remarks

The stack trace returned to Frames and FrameContexts can be printed using OutputContextStackTrace.

It is common for stack unwinds to restore only a subset of the registers. For example, stack unwinds will not always restore the volatile register state because the volatile registers are scratch registers and code does not need to preserve them. Registers that are not restored on unwind are left as the last value restored, so care should be taken when using the register state that might not be restored by an unwind.

Requirements

See also

GetStackTrace

IDebugControl4

OutputContextStackTrace

k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace)