Zydis  v2.0.0-alpha2
Formatter.h File Reference

Functions for formatting human-readable instructions. More...

#include <Zydis/DecoderTypes.h>
#include <Zydis/Defines.h>
#include <Zydis/Status.h>
Include dependency graph for Formatter.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ZydisFormatter_
 Defines the ZydisFormatter struct. More...
 

Macros

#define ZYDIS_FMTFLAG_UPPERCASE   0x00000001
 Formats the instruction in uppercase instead of lowercase.
 
#define ZYDIS_FMTFLAG_FORCE_SEGMENTS   0x00000002
 Forces the formatter to always print the segment register of memory-operands, instead of ommiting implicit DS/SS segments.
 
#define ZYDIS_FMTFLAG_FORCE_OPERANDSIZE   0x00000004
 Forces the formatter to always print the size of memory-operands.
 

Typedefs

typedef uint8_t ZydisFormatterStyle
 Defines the ZydisFormatterStyle datatype.
 
typedef uint32_t ZydisFormatterFlags
 Defines the ZydisFormatFlags datatype.
 
typedef uint8_t ZydisFormatterAddressFormat
 Defines the ZydisFormatterAddressFormat datatype.
 
typedef uint8_t ZydisFormatterDisplacementFormat
 Defines the ZydisFormatterDisplacementFormat datatype.
 
typedef uint8_t ZydisFormatterImmediateFormat
 Defines the ZydisFormatterImmediateFormat datatype.
 
typedef uint8_t ZydisFormatterHookType
 Defines the ZydisFormatterHookType datatype.
 
typedef uint8_t ZydisDecoratorType
 Defines the ZydisDecoratorType datatype.
 
typedef struct ZydisFormatter_ ZydisFormatter
 
typedef ZydisStatus(* ZydisFormatterNotifyFunc) (const ZydisFormatter *formatter, const ZydisDecodedInstruction *instruction, void *userData)
 Defines the ZydisFormatterNotifyFunc function pointer. More...
 
typedef ZydisStatus(* ZydisFormatterFormatFunc) (const ZydisFormatter *formatter, char **buffer, size_t bufferLen, const ZydisDecodedInstruction *instruction, void *userData)
 Defines the ZydisFormatterFormatFunc function pointer. More...
 
typedef ZydisStatus(* ZydisFormatterFormatOperandFunc) (const ZydisFormatter *formatter, char **buffer, size_t bufferLen, const ZydisDecodedInstruction *instruction, const ZydisDecodedOperand *operand, void *userData)
 Defines the ZydisFormatterFormatOperandFunc function pointer. More...
 
typedef ZydisStatus(* ZydisFormatterFormatAddressFunc) (const ZydisFormatter *formatter, char **buffer, size_t bufferLen, const ZydisDecodedInstruction *instruction, const ZydisDecodedOperand *operand, uint64_t address, void *userData)
 Defines the ZydisFormatterFormatAddressFunc function pointer. More...
 
typedef ZydisStatus(* ZydisFormatterFormatDecoratorFunc) (const ZydisFormatter *formatter, char **buffer, size_t bufferLen, const ZydisDecodedInstruction *instruction, const ZydisDecodedOperand *operand, ZydisDecoratorType type, void *userData)
 Defines the ZydisFormatterFormatDecoratorFunc function pointer. More...
 

Enumerations

enum  ZydisFormatterStyles { ZYDIS_FORMATTER_STYLE_INTEL , ZYDIS_FORMATTER_STYLE_MAX_VALUE = ZYDIS_FORMATTER_STYLE_INTEL }
 Values that represent formatter-styles. More...
 
enum  ZydisFormatterAddressFormats {
  ZYDIS_FORMATTER_ADDR_DEFAULT , ZYDIS_FORMATTER_ADDR_ABSOLUTE , ZYDIS_FORMATTER_ADDR_RELATIVE_SIGNED , ZYDIS_FORMATTER_ADDR_RELATIVE_UNSIGNED ,
  ZYDIS_FORMATTER_ADDR_MAX_VALUE = ZYDIS_FORMATTER_ADDR_RELATIVE_UNSIGNED
}
 Values that represent address-formats. More...
 
enum  ZydisFormatterDisplacementFormats { ZYDIS_FORMATTER_DISP_DEFAULT , ZYDIS_FORMATTER_DISP_HEX_SIGNED , ZYDIS_FORMATTER_DISP_HEX_UNSIGNED , ZYDIS_FORMATTER_DISP_MAX_VALUE = ZYDIS_FORMATTER_DISP_HEX_UNSIGNED }
 Values that represent displacement-formats. More...
 
enum  ZydisFormatterImmediateFormats {
  ZYDIS_FORMATTER_IMM_DEFAULT , ZYDIS_FORMATTER_IMM_HEX_AUTO , ZYDIS_FORMATTER_IMM_HEX_SIGNED , ZYDIS_FORMATTER_IMM_HEX_UNSIGNED ,
  ZYDIS_FORMATTER_IMM_MAX_VALUE = ZYDIS_FORMATTER_IMM_HEX_UNSIGNED
}
 Values that represent formatter immediate-formats. More...
 
enum  ZydisFormatterHookTypes {
  ZYDIS_FORMATTER_HOOK_PRE , ZYDIS_FORMATTER_HOOK_POST , ZYDIS_FORMATTER_HOOK_FORMAT_INSTRUCTION , ZYDIS_FORMATTER_HOOK_PRINT_PREFIXES ,
  ZYDIS_FORMATTER_HOOK_PRINT_MNEMONIC , ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_REG , ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_MEM , ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_PTR ,
  ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_IMM , ZYDIS_FORMATTER_HOOK_PRINT_OPERANDSIZE , ZYDIS_FORMATTER_HOOK_PRINT_SEGMENT , ZYDIS_FORMATTER_HOOK_PRINT_DECORATOR ,
  ZYDIS_FORMATTER_HOOK_PRINT_ADDRESS , ZYDIS_FORMATTER_HOOK_PRINT_DISPLACEMENT , ZYDIS_FORMATTER_HOOK_PRINT_IMMEDIATE , ZYDIS_FORMATTER_HOOK_MAX_VALUE = ZYDIS_FORMATTER_HOOK_PRINT_IMMEDIATE
}
 Values that represent formatter hook-types. More...
 
enum  ZydisDecoratorTypes {
  ZYDIS_DECORATOR_TYPE_INVALID , ZYDIS_DECORATOR_TYPE_MASK , ZYDIS_DECORATOR_TYPE_BROADCAST , ZYDIS_DECORATOR_TYPE_ROUNDING_CONTROL ,
  ZYDIS_DECORATOR_TYPE_SAE , ZYDIS_DECORATOR_TYPE_SWIZZLE , ZYDIS_DECORATOR_TYPE_CONVERSION , ZYDIS_DECORATOR_TYPE_EVICTION_HINT ,
  ZYDIS_DECORATOR_TYPE_MAX_VALUE = ZYDIS_DECORATOR_TYPE_EVICTION_HINT
}
 Values that represent decorator-types. More...
 

Functions

ZYDIS_EXPORT ZydisStatus ZydisFormatterInit (ZydisFormatter *formatter, ZydisFormatterStyle style)
 Initializes the given ZydisFormatter instance. More...
 
ZYDIS_EXPORT ZydisStatus ZydisFormatterInitEx (ZydisFormatter *formatter, ZydisFormatterStyle style, ZydisFormatterFlags flags, ZydisFormatterAddressFormat addressFormat, ZydisFormatterDisplacementFormat displacementFormat, ZydisFormatterImmediateFormat immmediateFormat)
 Initializes the given ZydisFormatter instance. More...
 
ZYDIS_EXPORT ZydisStatus ZydisFormatterSetHook (ZydisFormatter *formatter, ZydisFormatterHookType hook, const void **callback)
 Replaces a formatter function with a custom callback and/or retrieves the currently used function. More...
 
ZYDIS_EXPORT ZydisStatus ZydisFormatterFormatInstruction (const ZydisFormatter *formatter, ZydisDecodedInstruction *instruction, char *buffer, size_t bufferLen)
 Formats the given instruction and writes it into the output buffer. More...
 
ZYDIS_EXPORT ZydisStatus ZydisFormatterFormatInstructionEx (const ZydisFormatter *formatter, ZydisDecodedInstruction *instruction, char *buffer, size_t bufferLen, void *userData)
 Formats the given instruction and writes it into the output buffer. More...
 

Detailed Description

Functions for formatting human-readable instructions.

Typedef Documentation

◆ ZydisFormatterFormatAddressFunc

typedef ZydisStatus(* ZydisFormatterFormatAddressFunc) (const ZydisFormatter *formatter, char **buffer, size_t bufferLen, const ZydisDecodedInstruction *instruction, const ZydisDecodedOperand *operand, uint64_t address, void *userData)

Defines the ZydisFormatterFormatAddressFunc function pointer.

Parameters
formatterA pointer to the ZydisFormatter instance.
bufferA pointer to the string-buffer.
bufferLenThe length of the string-buffer.
instructionA pointer to the ZydisDecodedInstruction struct.
operandA pointer to the ZydisDecodedOperand struct.
userDataA pointer to user-defined data.
Returns
Returning a status code other than ZYDIS_STATUS_SUCCESS will immediately cause the formatting process to fail.

After appending text to the buffer you MUST increase the buffer-pointer by the size of the number of chars written. Not increasing the buffer-pointer will cause unexpected behavior.

This function type is used for the ZYDIS_FORMATTER_HOOK_PRINT_ADDRESS hook-type.

◆ ZydisFormatterFormatDecoratorFunc

typedef ZydisStatus(* ZydisFormatterFormatDecoratorFunc) (const ZydisFormatter *formatter, char **buffer, size_t bufferLen, const ZydisDecodedInstruction *instruction, const ZydisDecodedOperand *operand, ZydisDecoratorType type, void *userData)

Defines the ZydisFormatterFormatDecoratorFunc function pointer.

Parameters
formatterA pointer to the ZydisFormatter instance.
bufferA pointer to the string-buffer.
bufferLenThe length of the string-buffer.
instructionA pointer to the ZydisDecodedInstruction struct.
operandA pointer to the ZydisDecodedOperand struct.
typeThe decorator type.
userDataA pointer to user-defined data.
Returns
Returning a status code other than ZYDIS_STATUS_SUCCESS will immediately cause the formatting process to fail.

After appending text to the buffer you MUST increase the buffer-pointer by the size of the number of chars written.

Returning ZYDIS_STATUS_SUCCESS without increasing the buffer-pointer is valid and will cause the formatter to omit the current decorator.

This function type is used for the ZYDIS_FORMATTER_HOOK_PRINT_DECORATOR hook-type.

◆ ZydisFormatterFormatFunc

typedef ZydisStatus(* ZydisFormatterFormatFunc) (const ZydisFormatter *formatter, char **buffer, size_t bufferLen, const ZydisDecodedInstruction *instruction, void *userData)

Defines the ZydisFormatterFormatFunc function pointer.

Parameters
formatterA pointer to the ZydisFormatter instance.
bufferA pointer to the string-buffer.
bufferLenThe length of the string-buffer.
instructionA pointer to the ZydisDecodedInstruction struct.
userDataA pointer to user-defined data.
Returns
Returning a status code other than ZYDIS_STATUS_SUCCESS will immediately cause the formatting process to fail.

After appending text to the buffer you MUST increase the buffer-pointer by the size of the number of chars written. Not increasing the buffer-pointer will cause unexpected behavior.

This function type is used for the ZYDIS_FORMATTER_HOOK_FORMAT_INSTRUCTION, ZYDIS_FORMATTER_HOOK_PRINT_PREFIXES and ZYDIS_FORMATTER_HOOK_PRINT_MNEMONIC hook-types.

◆ ZydisFormatterFormatOperandFunc

typedef ZydisStatus(* ZydisFormatterFormatOperandFunc) (const ZydisFormatter *formatter, char **buffer, size_t bufferLen, const ZydisDecodedInstruction *instruction, const ZydisDecodedOperand *operand, void *userData)

Defines the ZydisFormatterFormatOperandFunc function pointer.

Parameters
formatterA pointer to the ZydisFormatter instance.
bufferA pointer to the string-buffer.
bufferLenThe length of the string-buffer.
instructionA pointer to the ZydisDecodedInstruction struct.
operandA pointer to the ZydisDecodedOperand struct.
userDataA pointer to user-defined data.
Returns
Returning a status code other than ZYDIS_STATUS_SUCCESS will immediately cause the formatting process to fail.

After appending text to the buffer you MUST increase the buffer-pointer by the size of the number of chars written.

Returning ZYDIS_STATUS_SUCCESS in one of the ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_X hooks without increasing the buffer-pointer is valid and will cause the formatter to omit the current operand.

Returning ZYDIS_STATUS_SUCCESS in ZYDIS_FORMATTER_HOOK_PRINT_OPERANDSIZE, ZYDIS_FORMATTER_HOOK_PRINT_SEGMENT or ZYDIS_FORMATTER_HOOK_PRINT_DECORATOR without increasing the buffer-pointer is valid and signals that the corresponding element should not be printed for the current operand.

Not increasing the buffer-pointer for any other hook-type will cause unexpected behavior.

This function type is used for the ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_REG, ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_MEM, ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_PTR, ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_IMM, ZYDIS_FORMATTER_HOOK_PRINT_OPERANDSIZE, ZYDIS_FORMATTER_HOOK_PRINT_SEGMENT, ZYDIS_FORMATTER_HOOK_PRINT_DECORATOR, ZYDIS_FORMATTER_HOOK_PRINT_DISPLACEMENT and ZYDIS_FORMATTER_HOOK_PRINT_IMMEDIATE hook-types.

◆ ZydisFormatterNotifyFunc

typedef ZydisStatus(* ZydisFormatterNotifyFunc) (const ZydisFormatter *formatter, const ZydisDecodedInstruction *instruction, void *userData)

Defines the ZydisFormatterNotifyFunc function pointer.

Parameters
formatterA pointer to the ZydisFormatter instance.
instructionA pointer to the ZydisDecodedInstruction struct.
userDataA pointer to user-defined data.
Returns
Returning a status code other than ZYDIS_STATUS_SUCCESS will immediately cause the formatting process to fail.

This function type is used for the ZYDIS_FORMATTER_HOOK_PRE and ZYDIS_FORMATTER_HOOK_POST hook-types.

Enumeration Type Documentation

◆ ZydisDecoratorTypes

Values that represent decorator-types.

Enumerator
ZYDIS_DECORATOR_TYPE_MAX_VALUE 

Maximum value of this enum.

◆ ZydisFormatterAddressFormats

Values that represent address-formats.

Enumerator
ZYDIS_FORMATTER_ADDR_DEFAULT 

Currently defaults to ZYDIS_FORMATTER_ADDR_ABSOLUTE.

ZYDIS_FORMATTER_ADDR_ABSOLUTE 

Displays absolute addresses instead of relative ones.

ZYDIS_FORMATTER_ADDR_RELATIVE_SIGNED 

Uses signed hexadecimal values to display relative addresses.

Examples: "JMP 0x20" "JMP -0x20"

ZYDIS_FORMATTER_ADDR_RELATIVE_UNSIGNED 

Uses unsigned hexadecimal values to display relative addresses.

Examples: "JMP 0x20" "JMP 0xE0"

ZYDIS_FORMATTER_ADDR_MAX_VALUE 

Maximum value of this enum.

◆ ZydisFormatterDisplacementFormats

Values that represent displacement-formats.

Enumerator
ZYDIS_FORMATTER_DISP_DEFAULT 

Currently defaults to ZYDIS_FORMATTER_DISP_HEX_SIGNED.

ZYDIS_FORMATTER_DISP_HEX_SIGNED 

Formats displacements as signed hexadecimal values.

Examples: "MOV EAX, DWORD PTR SS:[ESP+0x400]" "MOV EAX, DWORD PTR SS:[ESP-0x400]"

ZYDIS_FORMATTER_DISP_HEX_UNSIGNED 

Formats displacements as unsigned hexadecimal values.

Examples: "MOV EAX, DWORD PTR SS:[ESP+0x400]" "MOV EAX, DWORD PTR SS:[ESP+0xFFFFFC00]"

ZYDIS_FORMATTER_DISP_MAX_VALUE 

Maximum value of this enum.

◆ ZydisFormatterHookTypes

Values that represent formatter hook-types.

Enumerator
ZYDIS_FORMATTER_HOOK_PRE 

This function is called before the formatter starts formatting an instruction.

ZYDIS_FORMATTER_HOOK_POST 

This function is called before the formatter finished formatting an instruction.

ZYDIS_FORMATTER_HOOK_FORMAT_INSTRUCTION 

This function refers to the main formatting function, that internally calls all
other function except the ones that are hooked by ZYDIS_FORMATTER_HOOK_PRE and ZYDIS_FORMATTER_HOOK_POST.

Replacing this function allows for complete custom formatting, but indirectly disables all other hooks except for ZYDIS_FORMATTER_HOOK_PRE and ZYDIS_FORMATTER_HOOK_POST.

ZYDIS_FORMATTER_HOOK_PRINT_PREFIXES 

This function is called to print the instruction prefixes.

ZYDIS_FORMATTER_HOOK_PRINT_MNEMONIC 

This function is called to print the instruction mnemonic.

ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_REG 

This function is called to format an register operand.

ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_MEM 

This function is called to format an memory operand.

Replacing this function might indirectly disable some specific calls to the ZYDIS_FORMATTER_PRINT_ADDRESS and ZYDIS_FORMATTER_HOOK_PRINT_DISPLACEMENT functions.

ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_PTR 

This function is called to format an pointer operand.

ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_IMM 

This function is called to format an immediate operand.

Replacing this function might indirectly disable some specific calls to the ZYDIS_FORMATTER_PRINT_ADDRESS and ZYDIS_FORMATTER_HOOK_PRINT_IMMEDIATE functions.

ZYDIS_FORMATTER_HOOK_PRINT_OPERANDSIZE 

This function is called right before formatting an memory operand to print the optional size-specifier.

ZYDIS_FORMATTER_HOOK_PRINT_SEGMENT 

This function is called right before formatting an memory operand to print the optional segment-register.

ZYDIS_FORMATTER_HOOK_PRINT_DECORATOR 

This function is called right after formatting an operand to print the optional EVEX/MVEX operand-decorator.

ZYDIS_FORMATTER_HOOK_PRINT_ADDRESS 

This function is called to print an absolute address.

ZYDIS_FORMATTER_HOOK_PRINT_DISPLACEMENT 

This function is called to print a memory displacement value.

ZYDIS_FORMATTER_HOOK_PRINT_IMMEDIATE 

This function is called to print an immediate value.

ZYDIS_FORMATTER_HOOK_MAX_VALUE 

Maximum value of this enum.

◆ ZydisFormatterImmediateFormats

Values that represent formatter immediate-formats.

Enumerator
ZYDIS_FORMATTER_IMM_DEFAULT 

Currently defaults to ZYDIS_FORMATTER_IMM_HEX_UNSIGNED.

ZYDIS_FORMATTER_IMM_HEX_AUTO 

Automatically chooses the most suitable formatting-mode based on the operands ZydisOperandInfo.imm.isSigned attribute.

ZYDIS_FORMATTER_IMM_HEX_SIGNED 

Formats immediates as signed hexadecimal values.

Examples: "MOV EAX, 0x400" "MOV EAX, -0x400"

ZYDIS_FORMATTER_IMM_HEX_UNSIGNED 

Formats immediates as unsigned hexadecimal values.

Examples: "MOV EAX, 0x400" "MOV EAX, 0xFFFFFC00"

ZYDIS_FORMATTER_IMM_MAX_VALUE 

Maximum value of this enum.

◆ ZydisFormatterStyles

Values that represent formatter-styles.

Enumerator
ZYDIS_FORMATTER_STYLE_INTEL 

Generates intel-style disassembly.

ZYDIS_FORMATTER_STYLE_MAX_VALUE 

Maximum value of this enum.

Function Documentation

◆ ZydisFormatterFormatInstruction()

ZYDIS_EXPORT ZydisStatus ZydisFormatterFormatInstruction ( const ZydisFormatter formatter,
ZydisDecodedInstruction instruction,
char *  buffer,
size_t  bufferLen 
)

Formats the given instruction and writes it into the output buffer.

Parameters
formatterA pointer to the ZydisFormatter instance.
instructionA pointer to the ZydisDecodedInstruction struct.
bufferA pointer to the output buffer.
bufferLenThe length of the output buffer.
Returns
A zydis status code.

◆ ZydisFormatterFormatInstructionEx()

ZYDIS_EXPORT ZydisStatus ZydisFormatterFormatInstructionEx ( const ZydisFormatter formatter,
ZydisDecodedInstruction instruction,
char *  buffer,
size_t  bufferLen,
void *  userData 
)

Formats the given instruction and writes it into the output buffer.

Parameters
formatterA pointer to the ZydisFormatter instance.
instructionA pointer to the ZydisDecodedInstruction struct.
bufferA pointer to the output buffer.
bufferLenThe length of the output buffer.
userDataA pointer to user-defined data which can be used in custom formatter callbacks.
Returns
A zydis status code.

◆ ZydisFormatterInit()

ZYDIS_EXPORT ZydisStatus ZydisFormatterInit ( ZydisFormatter formatter,
ZydisFormatterStyle  style 
)

Initializes the given ZydisFormatter instance.

Parameters
formatterA pointer to the ZydisFormatter instance.
styleThe formatter style.
Returns
A zydis status code.

◆ ZydisFormatterInitEx()

ZYDIS_EXPORT ZydisStatus ZydisFormatterInitEx ( ZydisFormatter formatter,
ZydisFormatterStyle  style,
ZydisFormatterFlags  flags,
ZydisFormatterAddressFormat  addressFormat,
ZydisFormatterDisplacementFormat  displacementFormat,
ZydisFormatterImmediateFormat  immmediateFormat 
)

Initializes the given ZydisFormatter instance.

Parameters
formatterA pointer to the ZydisFormatter instance.
styleThe formatter style.
addressFormatThe address format.
displacementFormatThe displacement format.
immmediateFormatThe immediate format.
Returns
A zydis status code.

◆ ZydisFormatterSetHook()

ZYDIS_EXPORT ZydisStatus ZydisFormatterSetHook ( ZydisFormatter formatter,
ZydisFormatterHookType  hook,
const void **  callback 
)

Replaces a formatter function with a custom callback and/or retrieves the currently used function.

Parameters
formatterA pointer to the ZydisFormatter instance.
hookThe formatter hook-type.
callbackA pointer to a variable that contains the pointer of the callback function and receives the pointer of the currently used function.
Returns
A zydis status code.

Call this function with callback pointing to a NULL value to retrieve the currently used function without replacing it.