find_references
Find all references to a C/C++ symbol: calls, reads, member accesses, function-pointer registrations, and macro usages. libclang-powered detection catches indirect references that text search cannot see.
Instructions
Find ALL references to a C/C++ symbol — calls, reads, member accesses, function pointer registrations, template references, and macro usages. libclang-powered: detects function-pointer registrations (interrupt vector table writes, callback attachments, ISR handler assignments) 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: Build variant (multi-build project). Omit to use default_variant. One query answers for ONE build. image: Sysbuild image within the variant. Required when the variant holds several: each image is a separate program.
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), "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 the methods that override the same base method.
Those rows reach a PEER and not the symbol you named, and the page
notice counts them, thus a ``warning`` dict always leads such an
answer and says so. Read it 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 | Sysbuild image within the variant. Required when the variant holds several: each image is a separate program. | |
| limit | No | Maximum results of one page. | |
| 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 | Build variant (multi-build project). Omit to use default_variant. 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 |