Edit

Share via

RtlVirtualUnwind function (winnt.h)

  • Article

Retrieves the invocation context of the function that precedes the specified function context.

Note

 This function is not implemented on all processor platforms and the implementation is different on each platform that supports it. The following prototype lists all the potential parameters and their application. Read further for processor-specific function prototypes.

Syntax

NTSYSAPI PEXCEPTION_ROUTINE RtlVirtualUnwind(
  [in]                DWORD                          HandlerType,
  [in]                DWORD64                        ImageBase,
  [in]                DWORD64                        ControlPc,
  [in]                PRUNTIME_FUNCTION              FunctionEntry,
  [in, out]           PCONTEXT                       ContextRecord,
  [out]               PVOID                          *HandlerData,
  [out]               PDWORD64                       EstablisherFrame,
  [in, out, optional] PKNONVOLATILE_CONTEXT_POINTERS ContextPointers
);

Parameters

[in] HandlerType

The handler type. This parameter can be one of the following values.

This parameter is only present on x64.

Value Meaning
UNW_FLAG_NHANDLER
0x0
 The function has no handler.
UNW_FLAG_EHANDLER
0x1
 The function has an exception handler that should be called.
UNW_FLAG_UHANDLER
0x2
 The function has a termination handler that should be called when unwinding an exception.
UNW_FLAG_CHAININFO
0x4
 The FunctionEntry member is the contents of a previous function table entry.

[in] ImageBase

The base address of the module to which the function belongs.

[in] ControlPc

The virtual address where control left the specified function.

[in] FunctionEntry

The address of the function table entry for the specified function. To obtain the function table entry, call the RtlLookupFunctionEntry function.

[in, out] ContextRecord

A pointer to a CONTEXT structure that represents the context of the previous frame.

[out] HandlerData

The location of the PC. If this parameter is 0, the PC is in the prologue, epilogue, or a null frame region of the function. If this parameter is 1, the PC is in the body of the function.

This parameter is not present on x64.

[out] EstablisherFrame

A pointer to a FRAME_POINTERS structure that receives the establisher frame pointer value. The real frame pointer is defined only if InFunction is 1.

This parameter is of type PULONG64 on x64.

[in, out, optional] ContextPointers

An optional pointer to a context pointers structure.

Return value

This function returns a pointer to an EXCEPTION_ROUTINE callback function.

Remarks

The complete list of epilogue markers for x64 is as follows:

  • ret
  • ret n
  • rep ret
  • jmp imm8 | imm32 where the target is outside the function being unwound
  • jmp qword ptr imm32
  • rex.w jmp reg

Requirements

Requirement Value
Target Platform Windows
Header winnt.h (include Windows.h)
Library Kernel32.lib
DLL Kernel32.dll

See also

CONTEXT

EXCEPTION_RECORD

RtlLookupFunctionEntry

Vertdll APIs available in VBS enclaves