RtlCaptureStackBackTrace function (ntifs.h)

The RtlCaptureStackBackTrace routine captures a stack trace by walking the stack and recording the information for each frame.

Syntax

NTSYSAPI USHORT RtlCaptureStackBackTrace(
  ULONG  FramesToSkip,
  ULONG  FramesToCapture,
  PVOID  *BackTrace,
  PULONG BackTraceHash
);

Parameters

FramesToSkip

[in] Number of frames to skip from the start (current call point) of the back trace.

FramesToCapture

[in] Number of frames to be captured.

BackTrace

[out] Caller-allocated array in which pointers to the return addresses captured from the current stack trace are returned.

BackTraceHash

[out, optional] Optional value that can be used to organize hash tables. If this parameter is NULL, RtlCaptureStackBackTrace does not compute and return a hash value.

This hash value is calculated based on the values of the pointers returned in the BackTrace array. Two identical stack traces will generate identical hash values.

Return value

The number of captured frames.

Remarks

RtlCaptureStackBackTrace captures a stack trace for the caller by walking the stack (walking back in call time), and recording information for each frame. Specifically, RtlCaptureStackBackTrace returns pointers to the return addresses of each call on the stack, where the first pointer in the BackTrace array points to the return address of the most recent call, and so on.

Back trace hash values can be used to quickly determine whether two stack traces are identical or different. You can use the hash returned in BackTraceHash to compare stack traces. If you don't want to use hashes, or want to compute your own hash values, set BackTraceHash to NULL.

Requirements

   
Minimum supported client Available in starting with Windows XP.
Target Platform Universal
Header ntifs.h (include Ntifs.h, FltKernel.h)
Library NtosKrnl.lib; OneCoreUAP.lib on Windows 10
DLL NtDll.dll (user mode); NtosKrnl.exe (kernel mode)
IRQL <= DISPATCH_LEVEL