NAME¶

r_reg — radare2 register management library

SYNOPSIS¶

#include <r_reg.h>

DESCRIPTION¶

The r_reg API implements a portable register model used across analysis, emulation and debugging subsystems in radare2. It exposes typed register items, aliases (roles like PC/SP), an arena to push/pop register snapshots and helpers to read/write register values in different representations.

INITIALIZATION¶

A register context must be created before use; the context owns profiles, the arena and the register list. Typical callers are the analysis engine and the debugger which keep separate register contexts. RReg * r_reg_new(void)

Creates a new register context.

void r_reg_free(RReg *reg)

Frees all resources associated with the register context.

PROFILES¶

Profiles describe which registers exist, their sizes and roles. Profiles are loaded from strings or files and are used by analysis and ESIL to map register names and roles. bool r_reg_set_profile(RReg *reg, const char *profile)

Loads a profile from a file path.

bool r_reg_set_profile_string(RReg *reg, const char *profile)

Loads a profile directly from a string buffer.

char * r_reg_profile_to_cc(RReg *reg)

Dumps the profile as C-compatible declarations (used by tools).

REGISTER ACCESS¶

Register names and roles are the primary API for callers that only need scalar accesses. Use the typed APIs when you need float/double/packed values. RRegItem * r_reg_get(RReg *reg, const char *name, int type)

Retrieve a register item by name; pass type as -1 to ignore type.

ut64 r_reg_getv(RReg *reg, const char *name)

Get a 64-bit value for register `name`. This is the most common convenience function used throughout the codebase (analysis, esil, debug).

bool r_reg_setv(RReg *reg, const char *name, ut64 val)

Set a 64-bit value for register `name`. ESIL and many subsystems call this to perform register writes.

ut64 r_reg_get_value_by_role(RReg *reg, RRegAlias alias)

Get the value of a register given its alias role (for example `R_REG_ALIAS_PC`). Useful when code works with roles instead of concrete names.

REGISTER VALUES¶

When working with non-integer registers (floating point, long double) or when manipulating sub-parts of registers, use the typed getters/setters. ut64 r_reg_get_value(RReg *reg, RRegItem *item)

Return the integer value of a register item.

bool r_reg_set_value(RReg *reg, RRegItem *item, ut64 value)

Set the integer value for a register item.

float r_reg_get_float(RReg *reg, RRegItem *item)

Get a `float` value from the register item when applicable.

double r_reg_get_double(RReg *reg, RRegItem *item)

Get a `double` value from the register item when applicable.

long double r_reg_get_longdouble(RReg *reg, RRegItem *item)

Get a long double value (useful for extended FP registers).

bool r_reg_set_longdouble(RReg *reg, RRegItem *item, long double value)

Set a long double value in the register item.

REGISTER LISTS¶

You can iterate registers by type (GPR, FPU, vector, flags). This is commonly used to serialize register state or when emitting a register snapshot. RList * r_reg_get_list(RReg *reg, int type)

Return a list of `RRegItem` for the requested type.

RRegItem * r_reg_index_get(RReg *reg, int idx)

Get a register item by absolute index.

ALIASES¶

Aliases map roles to concrete register names for each profile (for example `PC` -> `rip` on x86_64). Use them when code should be architecture agnostic. bool r_reg_alias_setname(RReg *reg, RRegAlias alias, const char *name)

Assign a name to an alias role.

const char * r_reg_alias_getname(RReg *reg, RRegAlias alias)

Return the concrete register name for the alias.

const char * r_reg_alias_tostring(RRegAlias alias)

Return a textual representation of the alias role.

ARENA MANAGEMENT¶

The arena allows temporarily changing registers and restoring them later. This is heavily used by analysis passes and by debugger backends when peeking or modifying registers without permanently changing the user-visible state. int r_reg_arena_push(RReg *reg)

Push the current register snapshot to the arena stack and return the new stack depth.

void r_reg_arena_pop(RReg *reg)

Pop the last snapshot and restore register values to that state.

ut8 * r_reg_get_bytes(RReg *reg, int type, int *size)

Get a packed byte representation of registers of `type` (useful to copy to a target or to compute diffs).

bool r_reg_set_bytes(RReg *reg, int type, const ut8 *buf, const int len)

Set the bytes for registers of `type` from a buffer.

CONDITIONS¶

Helpers convert CPU flags into boolean conditions (equal, greater etc.) and back. These are used by ESIL and analysis to evaluate branching conditions. bool r_reg_cond(RReg *r, int type)

Evaluate a condition represented by `type` using the current register flags. For example `R_REG_COND_EQ` checks the zero flag.

RRegFlags * r_reg_cond_retrieve(RReg *r, RRegFlags *f)

Fill the `RRegFlags` structure from the current register flags (fields like zero, carry, sign) so callers can inspect or modify them.

void r_reg_cond_apply(RReg *r, RRegFlags *f)

Apply a `RRegFlags` structure back into the register context.

USAGE NOTES¶

The typical usage patterns found in the codebase are:

When analyzing or emulating instructions, push the arena, modify registers (for example set `PC` to the next address), run the evaluation (ESIL or analysis) and pop the arena to restore the original state. Files that follow this pattern include `libr/core/canal.c` and `libr/core/cmd_debug.inc.c`.

Use `r_reg_getv`/`r_reg_setv` for most reads/writes because they are simple and fast wrappers over the typed APIs. ESIL registers also call `r_reg_setv` through `.reg_write` hooks.

When code needs to be architecture-agnostic prefer `r_reg_get_value_by_role` or `r_reg_alias_getname` instead of hard-coded register names.

EXAMPLES¶

This example shows a common pattern used across radare2: read PC/SP, temporarily modify registers to simulate an instruction and restore the previous state.

// obtain the register context from core
RReg *reg = core->anal->reg;
// read program counter and stack pointer
ut64 pc = r_reg_getv (reg, "PC");
ut64 sp = r_reg_getv (reg, "SP");
// create a temporary snapshot
r_reg_arena_push (reg);
// modify registers for analysis/emulation
r_reg_setv (reg, "PC", pc + insn_size);
// run evaluation or analysis using modified registers...
// restore previous register state
r_reg_arena_pop (reg);

Another practical example: retrieving an alias value (role based)

// get program counter regardless of arch-specific name
ut64 pc = r_reg_get_value_by_role (reg, R_REG_ALIAS_PC);

ESIL integration note:

// ESIL uses r_reg_setv as the register write callback:
// in libr/esil/esil.c: .reg_write = (REsilRegWrite)r_reg_setv
// so using r_reg_setv keeps behavior consistent with ESIL expectations.

SEE ALSO¶

r_anal(3), r_esil(3)