Format:PE (Portable Executable)/Exception directory
Data directory 3 of a 64-bit PE (.pdata): a sorted array of 12-byte RUNTIME_FUNCTION entries, one per non-leaf function, pointing to UNWIND_INFO records that describe the prologue, the frame, and an optional language-specific exception handler.
Scope
On x64 (and IA-64, in another form) every function that allocates stack, saves non-volatile registers or can raise an exception has an entry in the exception directory (index 3, section .pdata). 32-bit x86 has none: its SEH is stack based (the FS:[0] chain, SafeSEH tables in Format:PE (Portable Executable)/Load config directory). ARM, ARM64 use other .pdata layouts (packed unwind data) that this page does not cover.
RUNTIME_FUNCTION (x64, 12 bytes)
u32 BeginAddress (RVA of the function), u32 EndAddress (RVA one past its last byte), u32 UnwindData (RVA of an UNWIND_INFO). The array is sorted by BeginAddress, so the loader and the unwinder binary search it (RtlLookupFunctionEntry); the count is Size / 12. If bit 0 of UnwindData is set, pefile's authors treat the remaining bits as the RVA of a chained RUNTIME_FUNCTION instead of an UNWIND_INFO (Unverified in this wiki: not tested on a binary). Several functions may share one UNWIND_INFO (identical prologue).
Functions without an entry are leaf functions: they call nothing, change no non-volatile register and allocate no stack, and are unwound by popping the return address.
UNWIND_INFO
- byte 0:
Version(3 bits; 1, or 2 when UWOP_EPILOG codes are used) andFlags(5 bits): 0x01UNW_FLAG_EHANDLER(an exception handler for__try/exceptor C++), 0x02UNW_FLAG_UHANDLER(termination/unwind handler), 0x04UNW_FLAG_CHAININFO(the record continues another function's). - byte 1:
SizeOfPrologin bytes; byte 2:CountOfCodes(number of 2-byte slots, not of operations); byte 3:FrameRegister(low 4 bits, 0 = none, else the register number such as 5 = rbp) andFrameOffset(high 4 bits, scaled by 16). - then
CountOfCodesUNWIND_CODE slots, the array padded to an even number of slots, in reverse prologue order (last instruction first); - if Flags has EHANDLER or UHANDLER:
u32RVA of the handler (for example__C_specific_handler,__GSHandlerCheck,__CxxFrameHandler3/4) followed by handler-specific data, which for__C_specific_handleris aSCOPE_TABLE(au32 Countfollowed by records of RVAs: begin, end, handler or filter, jump target; Unverified here, from the documented layout). With CHAININFO the tail is instead a RUNTIME_FUNCTION.
UNWIND_CODE slot: u8 CodeOffset (offset in the prologue after the instruction), UnwindOp (low 4 bits of byte 1), OpInfo (high 4 bits). Operations and their sizes in slots (pefile.py lines 394-404 and 2005-2200):
| Op | Name | Slots | Meaning |
|---|---|---|---|
| 0 | UWOP_PUSH_NONVOL | 1 | push of register OpInfo (0 RAX ... 15 R15) |
| 1 | UWOP_ALLOC_LARGE | 2 or 3 | OpInfo 0: next slot x 8 bytes; OpInfo 1: next two slots as a 32-bit byte count |
| 2 | UWOP_ALLOC_SMALL | 1 | stack allocation of OpInfo * 8 + 8 bytes (8 to 128) |
| 3 | UWOP_SET_FPREG | 1 | frame register = rsp + FrameOffset * 16 |
| 4 | UWOP_SAVE_NONVOL | 2 | register OpInfo saved at [rsp + next slot * 8] |
| 5 | UWOP_SAVE_NONVOL_FAR | 3 | same with a 32-bit byte offset |
| 6 | UWOP_EPILOG | 1-2 | version 2 only: epilogue size/offset marker |
| 8 | UWOP_SAVE_XMM128 | 2 | XMM register OpInfo saved at [rsp + next slot * 16] |
| 9 | UWOP_SAVE_XMM128_FAR | 3 | same with a 32-bit offset |
| 10 | UWOP_PUSH_MACHFRAME | 1 | hardware interrupt frame; OpInfo 1 means an error code is pushed first |
Op 7 is not defined in pefile's table and should not occur.
For reversers
.pdatais the most reliable list of function boundaries in a stripped x64 PE: every BeginAddress is a function (or funclet) start and EndAddress its end. Seed the disassembler with it; IDA, Ghidra and radare2 do.- The unwind codes tell the frame size and saved registers before reading the prologue: add up ALLOC ops and pushes for the stack depth at any point.
- Funclets (catch/finally handlers and
__trybodies) have their own RUNTIME_FUNCTION, usually chained to the parent's UNWIND_INFO with the handler data, so a small function with CHAININFO or a second entry inside a larger function is a funclet, not a separate function. - The handler RVA identifies the compiler runtime:
__C_specific_handler(SEH, C),__GSHandlerCheck(/GS),__CxxFrameHandler3(older C++),__CxxFrameHandler4(compressed FuncInfo4, see Platform:Microsoft Visual C++ ABI). - Windows:
RtlLookupFunctionEntry,RtlVirtualUnwindimplement it; the format is the x64 ABI described by Microsoft as "x64 exception handling".
Code & repositories
- pefile
parse_directory_exceptions/UnwindInfoclasses (pefile.py lines 1802-2200, 2888-2891, 3796-3880): a complete decoder written from the ABI, with the registers (lines 373-392). - LIEF
RuntimeFunctionX64andUnwindCodeX64(include/LIEF/PE/exceptions_info/).
Evidence & references
- Microsoft, "x64 exception handling" and "PE Format", section ".pdata"; pefile author's write-up linked in the source (auscitte.github.io/posts/Exception-Directory-pefile).