The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

RtlVirtualUnwind function

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

C++


PEXCEPTION_ROUTINE WINAPI RtlVirtualUnwind(
  _In_         HandlerType,
  _In_         ImageBase,
  _In_         ControlPC,
  _In_         FunctionEntry,
  _Inout_      ContextRecord,
  _Out_        InFunction,
  _Out_        EstablisherFrame,
  _Inout_opt_  ContextPointers
);

Parameters

HandlerType [in]

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.

ImageBase [in]

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

ControlPC [in]

The virtual address where control left the specified function.

FunctionEntry [in]

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

ContextRecord [in, out]

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

InFunction [out]

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.

EstablisherFrame [out]

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.

ContextPointers [in, out, optional]

An optional pointer to a context pointers structure.

Return value

This function returns a pointer to an EXCEPTION_ROUTINE callback function.

General Definitions

The PEXCEPTION_ROUTINE callback function is defined as follows:

C++


typedef EXCEPTION_DISPOSITION (*PEXCEPTION_ROUTINE) (
    __in struct _EXCEPTION_RECORD *ExceptionRecord,
    __in PVOID EstablisherFrame,
    __inout struct _CONTEXT *ContextRecord,
    __inout PVOID DispatcherContext
    );

x64 Definitions

This function is defined as follows:

C++


PEXCEPTION_ROUTINE WINAPI RtlVirtualUnwind (
    __in DWORD HandlerType,
    __in DWORD64 ImageBase,
    __in DWORD64 ControlPc,
    __in PRUNTIME_FUNCTION FunctionEntry,
    __inout PCONTEXT ContextRecord,
    __out PVOID *HandlerData,
    __out PDWORD64 EstablisherFrame,
    __inout_opt PKNONVOLATILE_CONTEXT_POINTERS ContextPointers OPTIONAL
    );

The KNONVOLATILE_CONTEXT_POINTERS structure is defined as follows:

C++



typedef struct DECLSPEC_ALIGN(16) _M128A {
    ULONGLONG Low;
    LONGLONG High;
} M128A, *PM128A;

typedef struct _KNONVOLATILE_CONTEXT_POINTERS {
    union {
        PM128A FloatingContext[16];
        struct {
            PM128A Xmm0;
            PM128A Xmm1;
            PM128A Xmm2;
            PM128A Xmm3;
            PM128A Xmm4;
            PM128A Xmm5;
            PM128A Xmm6;
            PM128A Xmm7;
            PM128A Xmm8;
            PM128A Xmm9;
            PM128A Xmm10;
            PM128A Xmm11;
            PM128A Xmm12;
            PM128A Xmm13;
            PM128A Xmm14;
            PM128A Xmm15;
        };
    };

    union {
        PULONG64 IntegerContext[16];
        struct {
            PULONG64 Rax;
            PULONG64 Rcx;
            PULONG64 Rdx;
            PULONG64 Rbx;
            PULONG64 Rsp;
            PULONG64 Rbp;
            PULONG64 Rsi;
            PULONG64 Rdi;
            PULONG64 R8;
            PULONG64 R9;
            PULONG64 R10;
            PULONG64 R11;
            PULONG64 R12;
            PULONG64 R13;
            PULONG64 R14;
            PULONG64 R15;
        };
    };
} KNONVOLATILE_CONTEXT_POINTERS, *PKNONVOLATILE_CONTEXT_POINTERS;

ARM Definitions

This function is defined as follows:

C++


PEXCEPTION_ROUTINE WINAPI RtlVirtualUnwind (
    __in DWORD HandlerType,
    __in DWORD ImageBase,
    __in DWORD ControlPc,
    __in PRUNTIME_FUNCTION FunctionEntry,
    __inout PCONTEXT ContextRecord,
    __out PVOID *HandlerData,
    __out PDWORD EstablisherFrame,
    __inout_opt PKNONVOLATILE_CONTEXT_POINTERS ContextPointers OPTIONAL
    );

The KNONVOLATILE_CONTEXT_POINTERS structure is defined as follows:

C++


typedef struct _KNONVOLATILE_CONTEXT_POINTERS {
    PDWORD R4;
    PDWORD R5;
    PDWORD R6;
    PDWORD R7;
    PDWORD R8;
    PDWORD R9;
    PDWORD R10;
    PDWORD R11;

    PULONGLONG D8;
    PULONGLONG D9;
    PULONGLONG D10;
    PULONGLONG D11;
    PULONGLONG D12;
    PULONGLONG D13;
    PULONGLONG D14;
    PULONGLONG D15;
    PULONGLONG D16;
    PULONGLONG D17;
    PULONGLONG D18;
    PULONGLONG D19;
    PULONGLONG D20;
    PULONGLONG D21;
    PULONGLONG D22;
    PULONGLONG D23;
    PULONGLONG D24;
    PULONGLONG D25;
    PULONGLONG D26;
    PULONGLONG D27;
    PULONGLONG D28;
    PULONGLONG D29;
    PULONGLONG D30;
    PULONGLONG D31;
} KNONVOLATILE_CONTEXT_POINTERS, *PKNONVOLATILE_CONTEXT_POINTERS;

X86 Definitions

This function is not implemented on X86

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

Product	Windows XP Professional x64 Edition or 64-bit editions of Windows Server 2003
Header	WinNT.h (include Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll

Deutsch	English	Español	Français
Italiano	日本語	한국어	Português
Pусский	简体中文	繁體中文