Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
R_REG(3)		     Library Functions Manual			R_REG(3)

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 val-
     ues.  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 com-
     monly used to serialize register state or when emitting  a  register  snap-
     shot.  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  agnos-
     tic.   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 peek-
     ing  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 eval-
		       uation (ESIL or analysis) and pop the  arena  to  restore
		       the  original  state.  Files that follow this pattern in-
		       clude	`libr/core/canal.c`    and    `libr/core/cmd_de-
		       bug.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`  in-
		       stead of hard-coded register names.

EXAMPLES
     This example shows a common pattern used across radare2: read  PC/SP,  tem-
     porarily modify registers to simulate an instruction and restore the previ-
     ous 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)

FreeBSD ports 15.quarterly     September 20, 2025			R_REG(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=r_reg&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help