find_references
Locate every C/C++ reference to a symbol—calls, reads, member accesses, function-pointer registrations, vector table slots, macro uses—including indirect references text search misses.
Instructions
Find ALL references to a C/C++ symbol — calls, reads, member accesses,
function pointer registrations, vector table slots, and macro
usages. libclang-powered: detects function-pointer registrations
(vector table entries, callback attachments, NVIC_SetVector
installs) that text-based search cannot see.
Falls back to macro lookup when the symbol is not found as a function/method: returns the macro definition (kind="macro") and files that reference it (ref_kind="macro_use").
Read-only. No side effects. Returns every reference in the indexed codebase,
including call sites, variable reads, struct member accesses, indirect
function-pointer references, and macro usages. Requires the reference
index (fw-context index — refs on by default).
For direct callers only use find_callers. For transitive callers use
find_all_callers_recursive. For call paths between two symbols use
find_call_path.
Args: name: Symbol name to find all references of. project_root: Project root directory. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. limit: Maximum results of one page (default 50, max 200). offset: Skip this many results. Reads the next page of a symbol with many references; the page notice names the offset to use. variant: Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build. One query answers for ONE build. image: Image of the build: a separate program, such as the application or the bootloader. Give it when the build has an image name.
Returns:
The page notice first — total, offset, shown, more
— then a dict per reference with: file, line, ref_kind, caller,
caller_kind.
ref_kind is one of: "call", "ref", "member",
"indirect" (function-pointer reference in arguments, assignments,
initializers, or init lists), "implicit_construct" (implicit
constructor call from global/static object or member-field
initialization), "dispatch" (synthetic edge from a dispatch
bridge such as EventQueue::call_every), "vector" (a slot of
an assembly vector table names the symbol; file and line are the
table entry), "vector_data" (a slot holds an address computed
from the symbol, such as the initial stack pointer),
"runtime_vector" (an NVIC_SetVector call installs the
symbol at run time), "alias" (.thumb_set: another assembly
name for the symbol), "macro_use" (macro usage
in file). Macro fallback puts a dict with kind="macro",
signature (NAME or NAME(a, b)), is_function_like,
value (the replacement text ALONE) and expanded_value
between the notice and the rows;
that answer pages too, and its total counts the uses in active
code only — a use inside a comment is not one.
When *name* matches more than one symbol, the answer holds the
references of all of them. A ``warning`` dict then comes first and
names the symbols, and each result carries
``target_qualified_name``. Give the full qualified name to ask
about one symbol only.
A virtual method with no reference of its own answers with the
references of its base method and of the other overrides of that
base. A ``warning`` dict leads such an answer, and each row
carries ``recorded_against`` and ``reaches_this_symbol`` (true only
for a row on the base method), as in ``find_callers``. Read both
before you report a reference count.
Never empty: one dict with ``error`` (symbol not resolved) or
``info`` (no references). Check both keys first.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Symbol name to find all references of — calls, reads, member accesses. | |
| image | No | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. | |
| limit | No | Maximum results of one page (default 50, max 200). | |
| offset | No | Skip this many results. Reads the next page of a symbol with many references. | |
| project | No | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. | |
| variant | No | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build for you. One query answers for ONE build. | |
| project_root | No | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |