NAME¶

This section provides the manual page name and a short description of the `r_bp` library so you can quickly identify the purpose of the document. r_bp — radare2 breakpoint library

SYNOPSIS¶

The synopsis shows the primary header to include when using the `r_bp` API and gives a high-level cue about how to reference the functions described in this manual.
#include <r_bp.h>

DESCRIPTION¶

This section gives an overview of the `r_bp` library and the kinds of breakpoint and watchpoint functionality it provides.

The r_bp library provides breakpoint management for radare2, supporting software breakpoints, hardware breakpoints, watchpoints, and conditional breakpoints across different architectures.

The core structure is RBreakpoint, which manages breakpoint lists, plugins, and tracing functionality.

INITIALIZATION¶

The initialization section describes how to create and destroy a breakpoint context — the starting point for using the `r_bp` API. RBreakpoint * r_bp_new(void)

Creates a new breakpoint context with built-in plugins loaded.

RBreakpoint * r_bp_free(RBreakpoint *bp)

Frees all resources associated with the breakpoint context.

BREAKPOINT MANAGEMENT¶

This section documents functions to add, remove and manage individual breakpoints and watchpoints — the core primitives for inserting and removing breakpoints. RBreakpointItem * r_bp_add_sw(RBreakpoint *bp, ut64 addr, int size, int perm)

Adds a software breakpoint at the specified address.

RBreakpointItem * r_bp_add_hw(RBreakpoint *bp, ut64 addr, int size, int perm)

Adds a hardware breakpoint at the specified address.

RBreakpointItem * r_bp_watch_add(RBreakpoint *bp, ut64 addr, int size, int hw, int rw)

Adds a watchpoint at the specified address.

bool r_bp_del(RBreakpoint *bp, ut64 addr)

Deletes the breakpoint at the specified address.

bool r_bp_del_all(RBreakpoint *bp)

Deletes all breakpoints.

BREAKPOINT CONTROL¶

Breakpoint control functions let you enable, disable or change the state of breakpoints globally or individually; this section explains those controls. RBreakpointItem * r_bp_enable(RBreakpoint *bp, ut64 addr, int set, int count)

Enables or disables the breakpoint at the specified address.

void r_bp_enable_all(RBreakpoint *bp, int set)

Enables or disables all breakpoints.

BREAKPOINT QUERY¶

Query helpers let you inspect and locate breakpoints by address or permissions; use these when you need to check whether a breakpoint is present or which breakpoint covers an address. RBreakpointItem * r_bp_get_at(RBreakpoint *bp, ut64 addr)

Gets the breakpoint at the specified address.

RBreakpointItem * r_bp_get_in(RBreakpoint *bp, ut64 addr, int perm)

Gets the breakpoint that covers the specified address with the given permissions.

int r_bp_in(RBreakpoint *bp, ut64 addr, int perm)

Checks if there's a breakpoint at the specified address with the given permissions.

BREAKPOINT LISTING¶

Listing utilities produce human-readable or machine-oriented representations of the current breakpoints and provide counts and summaries for diagnostics. char * r_bp_list(RBreakpoint *bp, int rad)

Lists all breakpoints in the specified format.

int r_bp_size(RBreakpoint *bp)

Returns the number of breakpoints.

CONDITIONAL BREAKPOINTS¶

Conditional breakpoints allow expressions or conditions to be attached to breakpoints so they only trigger when the condition holds; this section covers adding and removing those conditions. bool r_bp_add_cond(RBreakpoint *bp, const char *cond)

Adds a conditional breakpoint with the specified condition.

bool r_bp_del_cond(RBreakpoint *bp, int idx)

Deletes the conditional breakpoint at the specified index.

FAULT BREAKPOINTS¶

Fault breakpoints are used to detect memory faults or exceptional accesses; this short section explains how to register fault-related breakpoints. void r_bp_add_fault(RBreakpoint *bp, ut64 addr, int size, int perm)

Adds a fault breakpoint at the specified address.

TRACING¶

Tracing features let you record execution or breakpoint hit information; the functions here enable per-breakpoint or global tracing behavior. bool r_bp_set_trace(RBreakpoint *bp, ut64 addr, int set)

Enables or disables tracing for the breakpoint at the specified address.

void r_bp_set_trace_all(RBreakpoint *bp, int set)

Enables or disables tracing for all breakpoints.

PLUGINS¶

The plugin API lets you extend the breakpoint system with custom backends or behavior; use these functions to register and select plugins. int r_bp_plugin_add(RBreakpoint *bp, RBreakpointPlugin *plugin)

Adds a breakpoint plugin.

int r_bp_plugin_remove(RBreakpoint *bp, RBreakpointPlugin *plugin)

Removes a breakpoint plugin.

int r_bp_use(RBreakpoint *bp, const char *name, int bits)

Selects the breakpoint plugin to use.

RESTORATION¶

Restoration functions provide a way to reapply or rollback breakpoint changes, for example when resuming or detaching from a process. int r_bp_restore(RBreakpoint *bp, bool set)

Restores all breakpoints to their original state.

void r_bp_restore_one(RBreakpoint *bp, RBreakpointItem *b, bool set)

Restores a single breakpoint.

TRAPTRACE¶

Trap tracing collects ranges and events for traps and exceptions; this section shows how to enable, reset and manage those ranges. void r_bp_traptrace_enable(RBreakpoint *bp, int enable)

Enables or disables trap tracing.

void r_bp_traptrace_reset(RBreakpoint *bp, int hard)

Resets trap tracing.

int r_bp_traptrace_add(RBreakpoint *bp, ut64 from, ut64 to)

Adds a trap trace range.

BREAKPOINT TYPES¶

This section enumerates the supported breakpoint kinds and briefly explains their intended use-cases and differences. The library supports different breakpoint types:

R_BP_TYPE_SW

Software breakpoint

R_BP_TYPE_HW

Hardware breakpoint

R_BP_TYPE_COND

Conditional breakpoint

R_BP_TYPE_FAULT

Fault breakpoint

PERMISSIONS¶

Permission flags describe what kind of memory accesses the breakpoint should monitor; consult these when creating watchpoints or specifying protection semantics. Breakpoints can have different permissions:

R_BP_PROT_EXEC

Execute permission

R_BP_PROT_WRITE

Write permission

R_BP_PROT_READ

Read permission

R_BP_PROT_ACCESS

Access permission

EXAMPLES¶

The examples section provides short code snippets demonstrating common tasks like creating contexts, adding breakpoints, hardware breakpoints, watchpoints, and conditional breakpoints — use these as a quick reference for typical usage. Basic breakpoint setup:

RBreakpoint *bp = r_bp_new();
RBreakpointItem *b = r_bp_add_sw(bp, 0x400000, 1, R_BP_PROT_EXEC);

Hardware breakpoint:

RBreakpointItem *hw = r_bp_add_hw(bp, 0x400010, 4, R_BP_PROT_EXEC);

Watchpoint:

RBreakpointItem *wp = r_bp_watch_add(bp, 0x600000, 8, 1, R_BP_PROT_WRITE);

Conditional breakpoint:

r_bp_add_cond(bp, "rax == 0x1234");

SEE ALSO¶

r_debug(3), r_io(3)