R_SEARCH(3)

R_SEARCH(3) 💅✨

okay bestie, buckle UP, because this is r_search, the radare2 search library, and it is lowkey the moment. it's a section 3 library functions manual, so it's for you, a programmer, a real one. 💖

---

🌸 NAME 🌸

r_search — radare2 search library. yes that's it. that's the whole vibe. it searches. it's a library. slay.

---

✨ SYNOPSIS ✨

#include <r_search.h>

that's the include. put it at the top of your file like a little hello. 🫶

---

👑 DESCRIPTION 👑

okay so the r_search library gives radare2 comprehensive search capabilities. it's giving "we can find anything." it supports a whole bunch of search modes, including:

• keyword search
• regular expressions
• cryptographic patterns
• strings
• and more, bestie, so much more

it lets you search through binary data efficiently, with customizable callbacks and hit management. no cap.

the core structure is RSearch, which manages search keywords, modes, callbacks, and search results. it's the main character of this whole situation. 🌈

---

🎀 INITIALIZATION 🎀

initialization = creating and freeing a search context. use these routines to allocate a fresh RSearch object, configured for a search mode, before you add keywords or run updates. and free it when you're done with it, okay?? because memory leaks are not the vibe. 😭

RSearch * r_search_new(int mode)

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. it's yours now. take care of it. 💜

void r_search_free(RSearch *s)

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. that's use-after-free territory and it will absolutely not slay. 💀

---

💖 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 case-insensitive string searches
• regular expression matching

for example, r_anal_preludes uses r_search_keyword_new_hexstr to build prelude patterns for function detection. see? iconic behavior. 🔥

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

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

creates a binary keyword with an optional binary mask. kw/kwlen specify the pattern bytes; bm is an optional mask applied per-byte. mask girlies rise. 🎀

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

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 one for human-readable searches (e.g. symbol names embedded in the binary). it's the friendly one. 🦋

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

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

parses a hex string (like "9090cc") to create a binary keyword. super useful when the search pattern is expressed as hexpairs — fun fact, the core search command constructs keywords this way. iykyk. ✨

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

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

compiles a regular expression into a keyword for R_SEARCH_REGEXP mode. regex girlies, this one's for you. 💅

bool r_search_kw_add(RSearch *s, RSearchKeyword *kw)

bool r_search_kw_add(RSearch *s, RSearchKeyword *kw)

appends the keyword kw to the search context s. heads up bestie: the search context keeps ownership of added keywords and will free them when r_search_free or r_search_kw_reset is called. so don't go freeing them yourself, that's double-free energy. 🙈

---

🔍 SEARCHING 🔍

searching covers feeding data to the search engine and retrieving hits. there's a few ways to do it:

• push raw buffers directly with r_search_update
• read ranges from an RIO implementation using r_search_update_read
• search a complete buffer and get a ready-made list of hits using r_search_find

and 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 literally does this to scan an entire binary efficiently. ate. 👑

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

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)

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

reads data from the configured I/O callbacks (or s->consb) in the address range [from, to), and runs the search over that data. this is the convenient one — you can scan memory or file-backed regions without allocating one giant buffer. your RAM says thank you. 🌸

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

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 you just need a quick list of hits. it's giving "i don't have time for setup." ⭐

---

🌈 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.

heads up: some modes (like R_SEARCH_RABIN_KARP) expect a different workflow and do not use r_search_update directly. don't assume, bestie. check the mode.

int r_search_set_mode(RSearch *s, int mode)

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.). this function sets the internal handlers used by r_search_update. mode switch = glow up. 💅

---

🦋 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. snack first, then the real meal. 🍓

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

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)

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.

note: the function returns false if max is non-zero and smaller than min. so like... don't do that. 😭

---

🧚 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 the unmapped or irrelevant areas. boundaries, bestie. we love them. ✨

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

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. half-open means to is not included, just so we're clear. 🫶

int r_search_range_reset(RSearch *s)

int r_search_range_reset(RSearch *s)

removes all previously added ranges. clean slate. 🧼

---

🎀 CALLBACKS 🎀

callbacks let you stream matches as they're 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). multitasking queen behavior. 👑

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

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. so like, you can say "enough" from inside the callback. the power. 💖

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

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. they'll wait for you. patient. 🥺

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

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 let you switch 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.

fresh start, no baggage. we love a reset arc. 🌸

void r_search_reset(RSearch *s, int mode)

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)

void r_search_kw_reset(RSearch *s)

remove all keywords and clear any stored leftover buffers used by some search algorithms. bye bestie 👋

---

⭐ PATTERNS ⭐

pattern settings control heuristics such as the pattern size used for block-similarity searches and delta/differential searches. adjust these when you're searching for repetitive or structured data blocks. structure girlies, this is your section. 🎀

void r_search_pattern_size(RSearch *s, int size)

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)

go read those too, they're part of the lore. 📚

---

and that's the whole page bestie!! 💖 this one came from the Debian build, dated September 20, 2025 — so if you're reading this, hi from that exact moment in time. now go forth and search something. slay. 👑✨🦋