Export (0) Print
Expand All

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


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.

ValueMeaning
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:


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:


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:



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:


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:


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

See also

CONTEXT
EXCEPTION_RECORD
RtlLookupFunctionEntry

 

 

Community Additions

ADD
Show:
© 2014 Microsoft