FreeBSD Manual Pages
R_SEARCH(3) Library Functions Manual R_SEARCH(3) 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 effi- cient searching through binary data with customizable callbacks and hit management. The core structure is RSearch, which manages search keywords, modes, call- backs, and search results. INITIALIZATION Initialization covers creating and freeing a search context. Use these rou- tines to allocate a fresh RSearch object configured for a search mode be- fore 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 bi- nary). 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 con- structs 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 iter- ate over the IO maps and call `r_search_update_read` for each map a 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 ac- tive `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_RA- BIN_KARP`) expect a different workflow and do not use `r_search_update` di- rectly. 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 ex- traction and `r_search_set_string_limits` to tune what counts as a string (minimum and maximum length). This is helpful for harvesting embedded iden- tifiers, 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 call- back 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 `RSearchKey- word`, 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 ad- dress. 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 con- text 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 recon- figures 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_pre- ludes`) // 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) FreeBSD ports 15.quarterly September 20, 2025 R_SEARCH(3)
NAME | SYNOPSIS | DESCRIPTION | INITIALIZATION | KEYWORD MANAGEMENT | SEARCHING | SEARCH MODES | STRINGS | RANGES | CALLBACKS | HITS | RESET | PATTERNS | EXAMPLES | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=r_search&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>