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.