NAME¶

r_bin — Radare2 Binary Analysis Library API

SYNOPSIS¶

#include <r_bin.h>

DESCRIPTION¶

High-level helpers for opening, inspecting and manipulating executable files are exposed through the r_bin API. It hides loader and format differences behind a uniform set of objects (for example RBin , RBinFile and RBinObject ) and lets callers enumerate symbols, sections, imports, relocations and other useful metadata. The implementation relies on format plugins so callers can work with ELF, PE, Mach-O, DEX and other formats using the same API.

Main responsibilities: probing and opening files, returning parsed metadata, offering demanglers and helpers to read section bytes or line/debug info. The library does not perform control‑flow analysis — use r_anal(3) and r_core(3) for higher level analysis.

INITIALIZATION¶

Allocate an RBin context with r_bin_new () and tear it down with r_bin_free ()

To parse a file, initialise an RBinFileOptions with r_bin_file_options_init () and call r_bin_open (). Keep a reference to the previously selected file if you will open extra files (see examples below); the API provides helpers to switch the "current" file and to delete opened binfiles.

RBin * r_bin_new(void)

Create a new binary analysis context. void r_bin_free(RBin *bin)

Free a binary analysis context. bool r_bin_open(RBin *bin, const char *file, RBinFileOptions *opt)

Open a binary file for analysis with given options.

BINARY INFORMATION¶

After opening a file the API exposes a compact RBinInfo structure that summarises detected architecture, bits, endianness and a few security-related features (NX, canary, etc.). Use r_bin_get_info () to obtain it.

Symbol, section and import accessors return either RList or vector types such as RVecRBinSymbol libr/core

RBinInfo * r_bin_get_info(RBin *bin)

Retrieve general information about the binary (architecture, OS, etc.). RList * r_bin_get_sections(RBin *bin)

Get a list of sections in the binary. RList * r_bin_get_symbols(RBin *bin)

Get a list of symbols in the binary. RVecRBinSymbol * r_bin_get_symbols_vec(RBin *bin)

Get a vector of symbols for efficient iteration. RList * r_bin_get_imports(RBin *bin)

Get a list of imported symbols. RList * r_bin_get_entries(RBin *bin)

Get a list of entry points. RList * r_bin_get_strings(RBin *bin)

Get a list of strings in the binary. RRBTree * r_bin_get_relocs(RBin *bin)

Get relocation information. RList * r_bin_get_classes(RBin *bin)

Get a list of classes (for object-oriented binaries).

PLUGIN MANAGEMENT¶

Format support is implemented as plugins; the bin API exposes helpers to register or list plugins. Normal callers do not need to manipulate plugin objects directly — opening a file triggers plugin discovery automatically based on the file header and configured extract/load plugins.

bool r_bin_plugin_add(RBin *bin, RBinPlugin *plugin)

Add a binary format plugin to the registry. void r_bin_list(RBin *bin, PJ *pj, int format)

List available plugins or loaded binaries (format controls output style).

DEMANGLING¶

Radare2 exposes several demanglers. Call r_bin_demangle () to attempt demangling with an explicit language name or use language-specific helpers like r_bin_demangle_cxx (), r_bin_demangle_rust () or r_bin_demangle_java (). Pass the current RBinFile when the demangler needs context (for example some Rust and C++ demanglers consult binary metadata or symbol addresses).

Note: these functions return heap-allocated strings that must be freed by the caller.

char * r_bin_demangle(RBinFile *binfile, const char *lang, const char *str, ut64 vaddr, bool libs)

Attempt to demangle a string using the specified language and optional vaddr. char * r_bin_demangle_java(const char *str)

Demangle a Java symbol. char * r_bin_demangle_cxx(RBinFile *binfile, const char *str, ut64 vaddr)

Demangle a C++ symbol using optional binary context.

FILE OPERATIONS¶

r_bin keeps a notion of a "current" opened RBinFile that many callers use as implicit context (for example demanglers and format-specific helpers). Obtain it with r_bin_cur ().

To switch between multiple opened files use r_bin_file_set_cur_binfile () and use r_bin_file_delete () to close and remove opened binfiles when no longer required. When opening secondary files from a running program (for example to look up a symbol in libc) save the previous current file, open the new one and restore the old one when finished — see examples below.

RBinFile * r_bin_cur(RBin *bin)

Get the current binary file. bool r_bin_select(RBin *bin, const char *arch, int bits, const char *name)

Select a binary object by architecture and name. bool r_bin_file_close(RBin *bin, int bd)

Close a binary file descriptor (helper for raw fd-based operations).

ADDRESS LINE INFORMATION¶

If the binary contains debug information the bin API can return address → source mappings through r_bin_addrline_at ().

Address line data is stored per RBinFile and callers can reset or iterate the internal storage with r_bin_addrline_reset () and associated helpers. These facilities are commonly used by frontends to show filename/line information for a given instruction address.

RBinAddrline * r_bin_addrline_at(RBin *bin, ut64 addr)

Get debug line information for an address. void r_bin_addrline_reset(RBin *bin)

Reset stored address line information for the current file.

BINARY WRITING¶

Lightweight helpers to patch metadata are provided, such as adding a dependency or changing the entry point. These are convenience wrappers and do not replace a full binary rewriter; use them for small modifications exposed in the CLI and plugins.

bool r_bin_wr_addlib(RBin *bin, const char *lib)

Add a library dependency to the binary. bool r_bin_wr_entry(RBin *bin, ut64 addr)

Set the entry point address for the current binary.

FILTERING¶

Symbol and string filters let callers reduce the amount of reported data (for example hiding platform runtime symbols). Use r_bin_load_filter () to set filtering rules and r_bin_string_filter () to test strings against the active filter.

void r_bin_load_filter(RBin *bin, ut64 rules)

Load symbol filtering rules into the current context. bool r_bin_string_filter(RBin *bin, const char *str, ut64 addr)

Test whether a given string matches the active string filter.

EXAMPLES¶

The examples below show common patterns found in libr/core —opening a secondary file (for example libc), iterating symbols with the vector API and restoring the previous current file; and using the demanglers.

/* Open a file and inspect basic info */
RBin *bin = r_bin_new ();
RBinFileOptions opt;
/* helper that fills sensible defaults */
r_bin_file_options_init (&opt, -1, 0, 0, false);
if (!r_bin_open (bin, "/usr/lib/libc.so.6", &opt)) {
    fprintf (stderr, "failed to open file0);
    r_bin_free (bin);
    return;
}

/* RBinInfo summarises arch/bits and security features */
RBinInfo *info = r_bin_get_info (bin);
if (info) {
    printf ("file=%s arch=%s bits=%d nx=%d canary=%d0,
        info->file, info->arch, info->bits, info->has_nx, info->has_canary);
}

/* Iterate symbols efficiently using the vector API (used in core code) */
RVecRBinSymbol *syms = r_bin_get_symbols_vec (bin);
RBinSymbol *s;
R_VEC_FOREACH (syms, s) {
    const char *name = r_bin_name_tostring (s->name);
    printf ("%s @ 0x%"PFMT64x"0, name, s->vaddr);
}

/* When opening helper libraries from a running process, remember to close them */
/* Example pattern (used in dmh_glibc.inc.c):
 *  RBinFile *prev = r_bin_cur (core->bin);
 *  r_bin_open (core->bin, path, &opt);
 *  // use core->bin (current) for lookups
 *  r_bin_file_delete (core->bin, r_bin_cur (core->bin)->id);
 *  r_bin_file_set_cur_binfile (core->bin, prev);
 */
r_bin_free (bin);

/* Demangle an identifier using the current file context */
RBin *bin = r_bin_new ();
/* open file earlier and make it the current file */
RBinFile *cur = r_bin_cur (bin);
char *dem = r_bin_demangle_cxx (cur, "_ZN4Test4funcEi", 0);
if (dem) {
    puts (dem);
    free (dem);
}
r_bin_free (bin);

SEE ALSO¶

r_core(3), r_anal(3), r_flag(3)

AUTHORS¶

The radare2 project team.