Provided by: radare2_6.0.7+ds-1_amd64 
NAME
r_flag — Radare2 Flag Management Library API
SYNOPSIS
#include <r_flag.h>
DESCRIPTION
r_flag is the library that implements radare2's named-address management ("flags"). A flag is a
lightweight label attached to an address (or an address range) and carries optional metadata such as
comment, alias, color and type. Flags are used throughout radare2 to name functions, variables, user
labels and any other addressable symbol used during analysis and debugging.
Terminology and core concepts:
• A Flag (represented by the C structure `RFlagItem`) is a named address descriptor: it has a `name`, a
target `addr`, a `size` (length in bytes, 0 for no size), an internal numeric `id`, an optional
`realname` (original/demangled name) and a `space` pointer referencing the namespace it belongs to.
Flags can also have metadata entries (comment, alias expression, color, type) stored separately by
id.
• A Flag Space (type `RSpace`) is a namespace for flags. Spaces let you maintain multiple independent
sets of flag names (for example `functions`, `locals`, `vars`). The library supports a current space
and a stack of spaces so callers can push/pop contexts. When multiple flags exist at the same
address, spaces can be used to prioritize which flag is considered first.
• Zones (managed as `RFlagZoneItem`) are named address ranges (`from`..`to`) intended to group related
regions of the binary (for example a section, module, or logical region). Zones are independent from
flag spaces and are frequently used for UI/visualization (bar lists, context lookups).
• Tags are simple keyword lists associated to a flag name and stored in a key-value database (`sdb`).
Tags allow fast grouping and searching of flags by words; internally tags are stored as
`tag.<flagname> = "word1 word2 ..."` and matched with glob-like patterns.
• Flags are indexed both by name (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 (e.g. page-level grouping).
INITIALIZATION
Flag management starts with creating a new context to hold all flags. These functions allocate the
necessary structures at the beginning of a session and clean them up at the end, ensuring proper resource
management 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 functions provide core operations for creating, retrieving, and removing flags, forming the
foundation of flag manipulation in radare2's analysis and debugging workflows.
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 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.
FLAG SPACES
Flag spaces provide isolated namespaces for flags. Use them to separate different kinds of symbols (for
example `functions`, `locals`, `vars`) or to maintain per-analysis labeling without collisions. Important
behaviors implemented in the code:
• Getting/creating a space: `r_flag_space_get` returns the `RSpace` for a given name (creates it when
requested by other helpers).
• The current space: `r_flag_space_cur` returns the active space used by operations that do not
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 is 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 numeric id.
Metadata allows attaching optional properties to flags without changing the main item structure. Typical
metadata fields and behavior:
• Set or get a human readable comment with `r_flag_item_set_comment`. Empty string removes the comment.
Comments are used when exporting flags or printing in the UI; 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 are
stored in metadata and do not replace the flag's canonical `addr` unless explicitly applied in code.
• Set with `r_flag_item_set_color`, colors are stored in metadata to aid UI rendering and export.
Removing the color is supported by passing an empty string.
• Set with `r_flag_item_set_type`, stores a textual type classification for the flag.
Internally metadata is held in a hash table (`ht_up`) indexed by the numeric id and freed when flags are
removed.
Iterates over flags with the given prefix.
ZONES
Zones are named ranges intended to provide a coarse grouping of addresses. Each zone has a `name`, `from`
and `to` bounds. Typical uses include section-like grouping, bar-list visualizations, and providing
contextual names for UI elements.
API behavior implemented in the source:
• `r_flag_zone_add` extends an existing zone or creates a new one. Adding addresses expands 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, 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 retrieve all flags that match 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 support common maintenance and interaction tasks, such as listing flags, counting
matches, and renaming, aiding in user workflows and automation.
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)
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) Renames a
flag item.
EXAMPLES
Here there are some practical code examples demonstrating the usage of the r_flag API functions in
typical radare2 workflows, including 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)
AUTHORS
The radare2 project team.
Debian September 20, 2025 R_FLAG(3)