NAME¶

r_search — radare2 search library

SYNOPSIS¶

#include <r_search.h>

DESCRIPTION¶

The r_search library provides comprehensive search capabilities for radare2, supporting various search modes including keyword search, regular expressions, cryptographic patterns, strings, and more. It allows for efficient searching through binary data with customizable callbacks and hit management.

The core structure is RSearch, which manages search keywords, modes, callbacks, and search results.

INITIALIZATION¶

Initialization covers creating and freeing a search context. Use these routines to allocate a fresh RSearch object configured for a search mode before adding keywords or running updates; free it when you no longer need the search context to avoid memory leaks.

RSearch * r_search_new(int mode)

Allocates and returns a new search context initialized for the given `mode` (for example `R_SEARCH_KEYWORD` or `R_SEARCH_STRING`). The returned object owns internal lists and state used by subsequent API calls.

void r_search_free(RSearch *s)

Releases all resources held by the search context, including keyword and hit lists. Do not call any other `r_search_*` functions with `s` after freeing it.

KEYWORD MANAGEMENT¶

Keywords describe the byte sequences, strings or patterns you want to find. Create keywords with the `r_search_keyword_new*` helpers and add them to the `RSearch` context. In practice keywords are used to implement literal byte searches (hex or binary), case-sensitive or -insensitive string searches, and regular expression matching. For example, `r_anal_preludes` uses `r_search_keyword_new_hexstr` to build prelude patterns for function detection.

RSearchKeyword * r_search_keyword_new(const ut8 *kw, int kwlen, const ut8 *bm, int bmlen, const char *data)

Creates a binary keyword with optional binary mask. `kw`/`kwlen` specify the pattern bytes; `bm` is an optional mask applied per-byte.

RSearchKeyword * r_search_keyword_new_str(const char *kw, const char *bm, const char *data, bool icase)

Creates a keyword from a C string; `icase` controls case sensitivity. Use this for human-readable searches (e.g. symbol names embedded in the binary).

RSearchKeyword * r_search_keyword_new_hexstr(const char *xs, const char *data)

Parses a hex string (like "9090cc") to create a binary keyword. Useful when the search pattern is expressed as hexpairs (the core search command constructs keywords this way).

RSearchKeyword * r_search_keyword_new_regexp(const char *str, const char *data)

Compiles a regular expression into a keyword for `R_SEARCH_REGEXP` mode.

bool r_search_kw_add(RSearch *s, RSearchKeyword *kw)

Appends the keyword `kw` to the search context `s`. The search context keeps ownership of added keywords and will free them when `r_search_free` or `r_search_kw_reset` is called.

SEARCHING¶

Searching covers feeding data to the search engine and retrieving hits. You can push raw buffers directly with `r_search_update`, read ranges from an `RIO` implementation using `r_search_update_read`, or search a complete buffer and obtain a ready-made list of hits using `r_search_find`. For large inputs distributed across mapped regions use `r_search_maps` to iterate over the IO maps and call `r_search_update_read` for each map — the core `search` command does this to scan an entire binary efficiently.

int r_search_update(RSearch *s, ut64 from, const ut8 *buf, long len)

Process `len` bytes from `buf` starting at virtual address `from`. The active `s->update` handler is invoked depending on the search mode set by `r_search_set_mode`.

int r_search_update_read(RSearch *s, ut64 from, ut64 to)

Read data from the configured I/O callbacks (or `s->consb`) in the address range [`from`, `to`) and run the search over that data. This is convenient to scan memory or file-backed regions without allocating a single large buffer.

RList * r_search_find(RSearch *s, ut64 addr, const ut8 *buf, int len)

Convenience wrapper that sets an internal callback which collects hits into a `RList` and calls `r_search_update`. Use it when you already have the buffer to search and need a quick list of hits.

SEARCH MODES¶

Different search engines are implemented behind `RSearch` (keyword, regexp, strings, crypto heuristics). Choose the right mode with `r_search_set_mode` before adding keywords or invoking updates; some modes (like `R_SEARCH_RABIN_KARP`) expect a different workflow and do not use `r_search_update` directly.

int r_search_set_mode(RSearch *s, int mode)

Selects the active search algorithm for the context `s` (for example `R_SEARCH_KEYWORD`, `R_SEARCH_REGEXP`, `R_SEARCH_STRING`, `R_SEARCH_AES`, etc.). The function sets internal handlers used by `r_search_update`.

STRINGS¶

String search mode detects sequences of printable characters (C-strings, UTF-16 wide strings, etc.). Use `r_search_strings` to run the string extraction and `r_search_set_string_limits` to tune what counts as a string (minimum and maximum length). This is helpful for harvesting embedded identifiers, paths or textual data from a binary before running more targeted keyword searches.

int r_search_strings(RSearch *s, ut32 min, ut32 max)

Scans for printable strings with length between `min` and `max` and records them as hits.

bool r_search_set_string_limits(RSearch *s, ut32 min, ut32 max)

Configure the minimum (`min`) and maximum (`max`) string lengths considered when scanning in string mode. The function returns `false` if `max` is non-zero and smaller than `min`.

RANGES¶

Ranges control which address intervals are scanned when the search engine reads from I/O. Adding ranges is useful when you want to restrict the search to sections, mapped regions, or other subsets of the address space and skip unmapped or irrelevant areas.

int r_search_range_add(RSearch *s, ut64 from, ut64 to)

Include the half-open interval [`from`, `to`) in the set of ranges that `r_search_update_read` may iterate over.

int r_search_range_reset(RSearch *s)

Remove all previously added ranges.

CALLBACKS¶

Callbacks let you stream matches as they are found, or customize how data is read for `r_search`. The typical pattern used in core is to set a callback that appends `RSearchHit` objects into a list or emits JSON output. Callbacks are also used to interrupt searches early (for example when a maximum number of hits was reached).

void r_search_set_callback(RSearch *s, RSearchCallback callback, void *user)

Register a hit callback. The callback receives the matching `RSearchKeyword`, the `user` pointer and the `addr` of the hit. Return values from the callback can control search continuation.

void r_search_set_read_cb(RSearch *s, RSearchRCb cb, void *user)

Provide a custom read callback used by `r_search_update_read` to access the backing I/O. Core uses the default I/O when this is not set.

HITS¶

A hit represents a successful match of a keyword at a given virtual address. Hits can be created internally by the engine or explicitly via `r_search_hit_new`. When no callback is set hits are stored in `s->hits` and can be consumed after the search finishes.

int r_search_hit_new(RSearch *s, RSearchKeyword *kw, ut64 addr)

Append a hit for `kw` found at `addr` into the internal hits list. The function enforces alignment and overlap rules configured on the search context and returns status codes used by `r_search_update`.

RESET¶

Reset routines reinitialize search state between runs and allow switching modes without leaking state. Use `r_search_begin` before starting a new search pass if you want to preserve keywords but clear per-search counters; use `r_search_kw_reset` to remove all keywords.

void r_search_reset(RSearch *s, int mode)

Reset the context and set a new `mode`. This clears hit counters and reconfigures internal handlers.

void r_search_kw_reset(RSearch *s)

Remove all keywords and clear any stored leftover buffers used by some search algorithms.

PATTERNS¶

Pattern settings control heuristics such as pattern size used for block-similarity searches and delta/differential searches. Adjust these when searching for repetitive or structured data blocks.

void r_search_pattern_size(RSearch *s, int size)

Set the pattern size used by pattern-based search algorithms.

EXAMPLES¶

The examples below illustrate realistic usage patterns found in core code: creating keywords from prelude hex strings, searching entire mapped regions and collecting hits via a callback.

1) Simple keyword search returning a list

RSearch *s = r_search_new (R_SEARCH_KEYWORD);
RSearchKeyword *kw = r_search_keyword_new_str ("password", NULL, NULL, false);
if (!r_search_kw_add (s, kw)) { /* handle error */ }
// Convenience: r_search_find collects hits into a new RList using an internal callback
RList *hits = r_search_find (s, 0x1000, buffer, 1024);
// iterate `hits` and free it when done

2) Using a callback to stream hits (pattern from core: `listcb`)

static int listcb(RSearchKeyword *k, void *user, ut64 addr) {
    RSearchHit *hit = R_NEW0 (RSearchHit);
    if (!hit) { return 0; }
    hit->kw = k; hit->addr = addr; r_list_append (user, hit);
    return 1;
}

RSearch *s = r_search_new (R_SEARCH_KEYWORD);
// add keywords...
r_search_set_callback (s, listcb, my_hits_list);
r_search_update_read (s, map_from, map_to);

3) Searching entire IO maps (as `r_search_maps` does in the interactive command)

// prepare search context and keywords
int rc = r_search_maps (s, core->io->maps);
// `r_search_maps` calls `r_search_update_read` for each mapped region

4) Building preludes from architecture session data (used by `r_anal_preludes`)

// r_anal_preludes builds a RList of RSearchKeyword* with `r_search_keyword_new_hexstr`:
RList *preludes = r_anal_preludes (anal);
// then keywords are appended to a search context to match known function entry patterns

5) String extraction and limits

r_search_set_mode (s, R_SEARCH_STRING);
r_search_set_string_limits (s, 4, 256);
r_search_update_read (s, base, base + size);

SEE ALSO¶

r_io(3), r_core(3)