R_FLAG(3)

💖 R_FLAG(3) — the Radare2 Flag Management Library API 💖

okay so this is R_FLAG(3) from the Library Functions Manual, and bestie, it's the whole named-address management situation for radare2. buckle up 🎀

---

✨ NAME ✨

r_flag — the Radare2 Flag Management Library API. it names your addresses. that's the whole vibe. 💅

---

🌸 SYNOPSIS 🌸

#include <r_flag.h>

---

🦋 DESCRIPTION 🦋

so r_flag is the library that implements radare2's named-address management, aka "flags". a flag is a lightweight little label you stick onto an address (or an address range) and it can carry optional metadata like a comment, an alias, a color and a type. flags are everywhere in radare2 — they're how functions, variables, user labels and literally any other addressable symbol get named during analysis and debugging. iconic behavior honestly. 👑

the terminology, because i love a glossary

• a Flag (represented by the C structure RFlagItem) is a named address descriptor. it's got a name, a target addr, a size (length in bytes — 0 means no size, not a vibe), an internal numeric id, an optional realname (that's the original/demangled name) and a space pointer referencing the namespace it belongs to. flags can also have metadata entries — comment, alias expression, color, type — and those get stored separately, keyed by id. very organized of them. ✨
• a Flag Space (type RSpace) is a namespace for flags. spaces let you keep multiple independent sets of flag names alive at once (think functions, locals, vars). the library supports a current space and a stack of spaces so callers can push/pop contexts. and when multiple flags sit at the same address? spaces are how you prioritize which flag gets considered first. main character energy. 💜
• Zones (managed as RFlagZoneItem) are named address ranges (from..to) meant to group related regions of the binary — like a section, a module, or just some logical region. zones are fully independent from flag spaces and they get used a lot for UI/visualization (bar lists, context lookups). 🎀
• Tags are simple keyword lists attached to a flag name and stored in a key-value database (sdb). they let you group and search flags by words, fast. internally they're stored as tag.<flagname> = "word1 word2 ..." and matched with glob-like patterns. slay. 🌈
• and flags get indexed both ways: by name (a hash table) and by address using a skiplist (RFlagsAtOffset) that holds a list of flags for each normalized address. the RFlag context may use an address mask to normalize addresses (think page-level grouping). 🧚

---

🌟 INITIALIZATION 🌟

flag management starts with making a new context to hold all your flags. these functions allocate the structures you need at the start of a session and clean them up at the end, so resource management stays cute and correct in radare2. 🫶

• RFlag * r_flag_new(void) — creates a new flag context.
• void r_flag_free(RFlag *f) — frees a flag context and all associated flags.

---

💖 FLAG MANAGEMENT 💖

these are the core operations: creating, retrieving and removing flags. this is the foundation of all flag manipulation in radare2's analysis and debugging workflows. no cap.

• RFlagItem * r_flag_set(RFlag *f, const char *name, ut64 addr, ut32 size) — sets a flag with the given name at the specified address and size.
• RFlagItem * r_flag_get(RFlag *f, const char *name) — retrieves a flag by name.
• RFlagItem * r_flag_get_at(RFlag *f, ut64 addr, bool closest) — gets the flag at the specified address, or the closest one if closest is true.
• bool r_flag_unset(RFlag *f, RFlagItem *item) — removes the specified flag item.
• bool r_flag_unset_name(RFlag *f, const char *name) — removes the flag with the given name.
• bool r_flag_unset_addr(RFlag *f, ut64 addr) — removes all flags at the specified address.
• void r_flag_unset_all(RFlag *f) — removes all flags. all of them. everything. 💀

---

🎀 FLAG SPACES 🎀

flag spaces give you isolated namespaces for flags. use them to separate different kinds of symbols (for example functions, locals, vars) or to keep per-analysis labeling without collisions. here's the important behavior, as implemented in the code:

• getting/creating a space: r_flag_space_get returns the RSpace for a given name (it creates it when requested by other helpers).
• the current space: r_flag_space_cur returns the active space — the one used by operations that don't explicitly specify one.
• switching context: r_flag_space_set sets the current space; r_flag_space_push pushes the current space onto an internal stack and activates another; r_flag_space_pop restores the previous space.
• priority and lookup: when multiple flags exist at the same address, functions like r_flag_get_by_spaces accept an ordered list of space names to resolve which flag should be chosen first. there's also support for a "no space" priority so flags without a space can be preferred. 👑

---

🌈 METADATA 🌈

flag metadata is stored separately from the RFlagItem structure and keyed by the flag's numeric id. this lets you attach optional properties to flags without touching the main item structure. the typical fields and behavior:

• set or get a human readable comment with r_flag_item_set_comment. an empty string removes the comment. comments get used when exporting flags or printing in the UI, and heads up — some output formats encode comments as Base64 to preserve arbitrary bytes. 📝
• an alias is an expression (e.g. arithmetic or symbol expression) associated with a flag using r_flag_item_set_alias. when present, the library will evaluate the alias using the numeric evaluator (RNum) and present the computed address as the flag's address in some queries. alias values live in metadata and do not replace the flag's canonical addr unless explicitly applied in code. important distinction bestie, don't skip it. ✨
• set with r_flag_item_set_color, colors are stored in metadata to help UI rendering and export. you can remove the color by passing an empty string. 🎨
• set with r_flag_item_set_type, which stores a textual type classification for the flag.

internally, metadata is held in a hash table (ht_up) indexed by the numeric id and it's freed when flags are removed. 🧹

also, just floating here at the end of this section in the source, unattached to anything: Iterates over flags with the given prefix. we're keeping it because it's part of the page, even if it's just... vibing there. 😭

---

💜 ZONES 💜

zones are named ranges that give you a coarse grouping of addresses. every zone has a name, a from and a to bound. typical uses: section-like grouping, bar-list visualizations, and handing contextual names to UI elements.

API behavior as implemented in the source:

• r_flag_zone_add extends an existing zone or creates a new one. adding addresses expands the zone bounds to cover the new address.
• r_flag_zone_del removes a zone by name; r_flag_zone_reset clears all zones.
• r_flag_zone_around returns the nearest zone names located before and after a given address — super useful for contextual lookups.
• r_flag_zone_list and r_flag_zone_barlist help produce textual or bar-list representations of zones for display. 🌸

---

🍓 TAGS 🍓

tags are simple word lists attached to a flag name and stored in an sdb key-value database. they let callers assign keywords to flags and later pull up every flag that matches one or more words. implementation notes:

• r_flag_tags_set(f, name, words) stores the space-separated words under the key tag.<name>.
• r_flag_tags_get(f, name) returns a list of flags that match the words associated to name. the implementation splits the stored words and performs glob-like matching against existing flag names.
• r_flag_tags_list lists all tags present, and r_flag_tags_reset clears tags for a name or for all flags. 🧚

---

⭐ UTILITIES ⭐

these utility functions handle the everyday maintenance and interaction tasks — listing flags, counting matches, renaming — which keeps user workflows and automation flowing. 💅

• char * r_flag_list(RFlag *f, int rad, const char *pfx) — lists flags in radare2 format with optional prefix.
• int r_flag_count(RFlag *f, const char *glob) — counts flags matching the glob pattern.
• int r_flag_rename(RFlag *f, RFlagItem *item, const char *name) — renames a flag item.
• void r_flag_foreach(RFlag *f, RFlagItemCb cb, void *user) — iterates over all flags, calling the callback for each.
• void r_flag_foreach_prefix(RFlag *f, const char *pfx, int pfx_len, RFlagItemCb cb, void *user) — iterates over flags with the given prefix. (ngl the one-liners in this section are a little scrambled in the source page — "Renames a flag item." is dangling off the end — but we're keeping everything exactly where it landed. 🙈)

---

🔥 EXAMPLES 🔥

here are some practical code examples showing off the r_flag API in typical radare2 workflows — flag creation, space management and iteration. 🫶

creating and managing flags:

RFlag *f = r_flag_new();
RFlagItem *item = r_flag_set(f, "main", 0x1000, 4);
if (item) {
    r_flag_item_set_comment(f, item, "Entry point");
}
RFlagItem *got = r_flag_get(f, "main");
if (got) {
    printf("Address: 0x%"PFMT64x"\n", got->addr);
}
r_flag_free(f);

using flag spaces:

RFlag *f = r_flag_new();
r_flag_space_push(f, "functions");
r_flag_set(f, "func1", 0x2000, 0);
r_flag_space_push(f, "variables");
r_flag_set(f, "var1", 0x3000, 4);
r_flag_space_pop(f); // back to functions
r_flag_set(f, "func2", 0x2100, 0);
r_flag_free(f);

iterating over flags:

void print_flag(RFlagItem *fi, void *user) {
    printf("%s @ 0x%"PFMT64x"\n", fi->name, fi->addr);
}
RFlag *f = r_flag_new();
// ... set some flags ...
r_flag_foreach(f, print_flag, NULL);
r_flag_free(f);

---

👑 SEE ALSO 👑

r_core(3), r_anal(3), r_bin(3) — go read those next, bestie, they're the whole friend group. 🌸

---

💜 AUTHORS 💜

The radare2 project team. legends, honestly.

---

okay that's the whole page!! and for the cute sign-off: this one's the Debian build, dated September 20, 2025, and it lives at R_FLAG(3). mwah. 💅✨💖