Find where a C/C++ symbol (function, struct, macro, typedef, enum) is defined.

Use this INSTEAD of grep whenever you need a symbol's definition: an indexed lookup that returns only the definition site(s). Multiply-defined symbols (#ifdef alternates) carry each definition's guard stack. Macro-generated symbols resolve too: "sys_read", "trace_sched_switch", or a DEFINE_SPINLOCK/module_param name returns the generator invocation site (SYSCALL_DEFINE3(read, ...)), flagged resolved_via — no build needed. Definitions the index parser missed are recovered from their EXPORT_SYMBOL* site via ctags, flagged resolved_via "ctags:...". On a miss the envelope carries "suggestions": defined symbols starting with the queried name.

JSON records: {symbol, path, line, col, kind, typeref, scope, signature, guard, snippet} — kind/typeref/scope/signature are ctags metadata when available; guard is the enclosing #if/#ifdef stack, outermost first, [] = unconditional.

Args: symbol: Exact symbol name, e.g. "tcp_v4_rcv". case_insensitive: Match ignoring case. active_config: Kernel .config path or macro list like "CONFIG_SMP,BITS_PER_LONG=64,!CONFIG_DEBUG"; drops definitions whose guard stack is definitely false under it (count reported as config_filtered). Unknown macros never drop anything.

Find all call/usage sites of a C/C++ symbol.

Use this INSTEAD of grep for "who calls/uses this?": only real reference sites from the index, each with its #if/#ifdef guard stack. Symbols with no in-tree definition (libc calls, some variables) work too — the query falls back to symbol-usage records, flagged "fallback": "symbol_usages".

Args: symbol: Exact symbol name. case_insensitive: Match ignoring case. active_config: Kernel .config path or macro list; drops references whose guard stack is definitely false under it (config_filtered).

Return the full source of a symbol's definition — just the body.

Use this INSTEAD of reading a whole file to see how a function, struct, or macro is implemented: it extracts only the definition's lines, so a one-screen function never costs a 5000-line file read. Macro-generated and parser-missed (EXPORT_SYMBOL-recovered) definitions resolve too, flagged resolved_via. JSON results: {path, line, body} items.

Args: symbol: Exact symbol name. max_definitions: Return at most this many bodies when the symbol is multiply defined (default 3).

Find the FUNCTIONS that call a symbol, deduplicated, with call counts.

Use this INSTEAD of find_references when you want the call graph rather than raw match lines: each reference is mapped to its enclosing function. The highest signal-to-noise "who uses this?" view; iterate it to walk the caller graph upward. JSON results: {caller, path, sites} items.

Args: symbol: Exact symbol name whose callers you want.

Per-file reference counts for a symbol — the cheapest wide view.

Use this FIRST for very widely used symbols (thousands of references): one line per file, sorted by count, shows where usage concentrates; then drill in with find_references or find_callers. JSON results: {path, count} items plus total_references.

Args: symbol: Exact symbol name.

What functions does this function CALL? (the outgoing call graph)

Use this to see a function's dependencies without reading any file: call sites are detected in its body and verified against the index. Macro-generated and parser-missed (EXPORT_SYMBOL-recovered) definitions resolve too, flagged resolved_via. JSON results: {in_tree: [{symbol, path, line}], external: [names]}.

Args: symbol: Exact name of the function to analyze.

Does FROM transitively call TO — and through which call chain?

Use this instead of chaining find_callers rounds when the question is "can this function end up in that one?". BFS over the caller graph returns the SHORTEST chain, each hop with the call site's file:line. JSON results: {path_found, hops, depth, nodes_explored}; hops run from from_symbol to to_symbol. Static analysis cannot follow function pointers (ops structs, callbacks).

Args: from_symbol: The caller end ("can this reach ..."). to_symbol: The callee end ("... this function?"). max_depth: Longest chain to consider, in calls (1-12, default 8).

Which functions are impacted by a change? (refactoring blast radius)

Use this after editing or before merging: maps every line of git diff <git_ref> to its enclosing function via the index, then walks the caller graph outward. Ranked by distance — changed functions first, direct callers next. JSON results: {symbol, path, line, distance, via, call_sites} records.

Args: git_ref: Diff base for git diff (default HEAD = uncommitted changes; "HEAD~1" for the last commit, "main..." for a branch). depth: Caller levels to expand beyond the changed functions (0-3, default 1; 0 = just list the changed functions).

One-shot overview card for a symbol — the best FIRST query.

One call returns where a symbol is defined, WHAT it is (kind, signature, scope), under WHICH #ifdef guards each definition lives (guard_variants

1 means the flat list is really a config choice), how widely it's used and where, plus the tool to use next. Macro-generated symbols resolve (resolved_via); definitions the index parser missed are recovered from their EXPORT_SYMBOL* site via ctags; kernel symbols report their EXPORT_SYMBOL* variant in "exported". JSON results: {definitions, definition_count, guard_variants, resolved_via, exported, reference_count, file_count, top_files}.

Args: symbol: Exact symbol name. active_config: Kernel .config path or macro list; definitions whose guard stack is definitely false under it are dropped (config_filtered).

List every symbol defined in one source file.

Use this INSTEAD of reading a file when you only need its API surface — the functions, structs, and macros it defines — as a compact list with ctags metadata and #ifdef guard stacks when available.

Args: file_path: Source file, relative to the project root or absolute.

Synchronously refresh the index — the guaranteed-freshness barrier.

Query tools refresh the index automatically in the background, so results can lag very recent edits by a few seconds. Call this right after editing files when the very next query must see the changes.

Args: full: Rebuild the index from scratch instead of refreshing it incrementally (rarely needed — large branch switch, suspected corruption).