functions

此技能是 全面的目录，涵盖所有 idasql SQL 函数。可用它查询任意函数的签名、参数和用法。

---

反汇编

函数	描述
disasm_at(addr)	所在头部的规范列表行（适用于代码和数据）
disasm_at(addr, n)	规范列表行及其前后各 n 个相邻头部
disasm(addr)	地址处的一行反汇编
disasm(addr, n)	从地址开始的接下来 N 条指令（按数量计，不考虑边界）
disasm_range(start, end)	地址范围 [start, end) 内的所有反汇编行
disasm_func(addr)	包含该地址的函数的完整反汇编
make_code(addr)	在地址处创建指令（若已是代码或创建成功，则返回 1）
make_code_range(start, end)	在 [start, end) 内创建指令，返回创建的数量

SELECT disasm_at(0x401000);
SELECT disasm_at(0x401000, 2);
SELECT disasm_func(addr) FROM funcs WHERE name = '_main';
SELECT disasm_range(0x401000, 0x401100);
SELECT disasm(0x401000);
SELECT disasm(0x401000, 5);
SELECT make_code(0x401000);
SELECT make_code_range(0x401000, 0x401100);

函数创建由表驱动（不是 SQL 函数）：

INSERT INTO funcs (addr) VALUES (0x401000);

---

字节访问与修补

字节读取、批量读取和修补都通过 bytes 表进行。 load_file_bytes(...) 会将主机文件的字节写入 IDB 中给定的范围； 成功时返回 1，失败时返回 0。

函数	描述
load_file_bytes(path, file_offset, addr, size[, patchable])	将主机文件字节写入 IDB 内存的目标范围
blob_concat(value)	内置聚合函数——将字节值拼接为一个 BLOB

-- Read 16 bytes as uppercase hex
SELECT hex(blob_concat(value))
FROM (SELECT value FROM bytes WHERE start_addr = 0x401000 AND n = 16 ORDER BY addr);

-- Read 64 bytes as a BLOB (its byte length; bind the raw BLOB itself, or wrap in
-- hex() for a text-safe transport)
SELECT length(blob_concat(value)) AS blob_len
FROM (SELECT value FROM bytes WHERE start_addr = 0x401000 AND n = 64 ORDER BY addr);

-- Patch 1 byte and 4 LE bytes
UPDATE bytes SET value = 0x90 WHERE addr = 0x401000;
UPDATE bytes SET dword = 0x90909090 WHERE addr = 0x401000;
SELECT value AS current, original_value AS original FROM bytes WHERE addr = 0x401000;
DELETE FROM bytes WHERE addr = 0x401000;                   -- revert

若要进行可组合的行形态读取，可直接使用 bytes 表： SELECT addr, value FROM bytes WHERE addr >= :start AND addr < :end ORDER BY addr。 使用 heads 获取条目大小／类型元数据。

---

二进制搜索

对原始字节／操作码使用 byte_search 表。它采用表形态，因此结果可直接筛选、联接、分组和限制。

列	描述
addr	匹配地址
matched_hex	以十六进制文本形式呈现的匹配字节
matched_bytes	作为 BLOB 的匹配字节
size	匹配大小（字节）
pattern	隐藏的必需输入：IDA 字节模式
start_addr	隐藏的可选起始下界（含）
end_addr	隐藏的可选结束上界（不含）
max_results	隐藏的可选生成器上限

模式语法（IDA 原生）：

• "48 8B 05" - 精确字节（十六进制，以空格分隔）
• "48 ? 05" 或 "48 ?? 05" - ? = 任意字节通配符（仅限整字节）
• "(01 02 03)" - 多种选择（匹配其中任意字节）

SELECT addr, matched_hex, size
FROM byte_search
WHERE pattern = '48 8B ? 00'
LIMIT 10;

SELECT printf('0x%llX', addr) AS addr
FROM byte_search
WHERE pattern = 'CC CC CC'
ORDER BY addr
LIMIT 1;

优化模式：

-- Count unique functions containing RDTSC (opcode: 0F 31)
SELECT COUNT(DISTINCT f.addr) as count
FROM byte_search b
JOIN funcs f ON b.addr >= f.addr AND b.addr < f.end_addr
WHERE b.pattern = '0F 31';

---

名称与函数

使用表查询地址和所属函数的元数据。使用这些模式前，先将符号名称解析为整数 EA。

模式	描述
SELECT name FROM names WHERE addr = :addr LIMIT 1	地址处的名称
SELECT name FROM funcs WHERE :addr >= addr AND :addr < end_addr LIMIT 1	包含该地址的函数
SELECT addr FROM funcs WHERE :addr >= addr AND :addr < end_addr LIMIT 1	所属函数的起始地址
SELECT end_addr FROM funcs WHERE :addr >= addr AND :addr < end_addr LIMIT 1	所属函数的结束地址

函数计数和索引查询由表驱动：

SELECT COUNT(*) AS function_count FROM funcs;
SELECT addr FROM funcs WHERE rowid = 0;

---

交叉引用

交叉引用边查询由表驱动：

SELECT from_addr, to_addr, type, is_code, from_func
FROM xrefs
WHERE to_addr = 0x401000;

SELECT from_addr, to_addr, type, is_code, from_func
FROM xrefs
WHERE from_addr = 0x401000;

SELECT from_addr, to_addr, type, is_code, from_func
FROM xrefs
WHERE from_func = 0x401000;

---

导航

使用 heads 的排序进行已定义条目导航，并使用 SQLite 格式化函数生成显示字符串。地址相等／范围筛选已优化；ORDER BY addr 或 ORDER BY addr DESC 会用于下一项／上一项查询。

SELECT addr
FROM heads
WHERE addr > 0x401000
ORDER BY addr
LIMIT 1;

SELECT addr
FROM heads
WHERE addr < 0x401000
ORDER BY addr DESC
LIMIT 1;

SELECT printf('0x%llx', addr) AS address_hex
FROM heads
LIMIT 10;

段查询由表驱动：

SELECT name
FROM segments
WHERE 0x401000 >= start_addr
  AND 0x401000 < end_addr
LIMIT 1;

---

注释

通过 comments 表读取注释：

SELECT COALESCE(NULLIF(comment, ''), NULLIF(rpt_comment, '')) AS comment
FROM comments
WHERE addr = 0x401000
LIMIT 1;

通过该表写入注释：

INSERT INTO comments(addr, comment) VALUES (0x401000, 'regular comment');
INSERT INTO comments(addr, rpt_comment) VALUES (0x401000, 'repeatable comment');
-- Replace an existing comment in place
UPDATE comments SET comment = 'revised comment' WHERE addr = 0x401000;
-- Remove a comment
DELETE FROM comments WHERE addr = 0x401000;

注意：在已有注释的地址执行 INSERT 会替换该注释（每个 EA 的每个槽位仅有一条注释）。UPDATE 的效果相同。

---

修改

界面	说明
applied_types(addr, decl, ordinal, type_name)	在地址处读取／应用／替换／清除 C 声明
parse_decls(text)	将 C 声明（struct／union／enum／typedef）导入本地类型

函数元数据首选 SQL 写入方式：

• UPDATE funcs SET name = '...', prototype = '...', folder_path = 'idasql/review/annotated' WHERE addr = ...
• INSERT INTO names(addr, name) VALUES (..., '...') 或 UPDATE names SET name = '...' WHERE addr = ...
• prototype 对应 applied_types 的行为，并使反编译器缓存失效。
• folder_path 会在 IDA 的 Function 窗口树中移动函数；可通过 dirtree_folders 创建／重命名／删除空文件夹。
• 对于每次调用的间接调用类型，请更新 disasm_calls.callee_type。

---

Python 执行

函数	说明
idapython_snippet(code[, sandbox])	执行 Python 代码片段并返回捕获的输出文本
idapython_file(path[, sandbox])	执行 Python 文件并返回捕获的输出文本

运行时保护：

PRAGMA idasql.enable_idapython = 1;

SELECT idapython_snippet('print("hello from idapython")');
SELECT idapython_file('C:/temp/script.py');
SELECT idapython_snippet('counter = globals().get("counter", 0) + 1; print(counter)', 'alpha');

---

上下文感知（插件 UI）

函数	说明
get_ui_context_json()	返回当前 UI／窗口小部件／上下文的 JSON，供上下文感知提示词使用（在各处均已注册；GUI 插件中提供实时 UI，在 idalib／CLI 下提供 source:"cli" 存根）

SELECT get_ui_context_json();

---

项目分析

使用 heads 获取项目分类、大小和原始标志：

SELECT addr, size, type, flags, disasm
FROM heads
WHERE addr = 0x401000;

---

指令详情

使用 instructions 和 instruction_operands 获取已解码的指令信息。instruction_operands 每个非 void 操作数对应一行。

SELECT addr, itype, mnemonic
FROM instructions
WHERE func_addr = 0x401000
LIMIT 10;

SELECT opnum, text, type_code, type_name, value
FROM instruction_operands
WHERE addr = 0x401000
ORDER BY opnum;

SELECT i.addr, i.itype, i.mnemonic, i.size, o.opnum, o.text, o.type_name, o.value
FROM instructions i
LEFT JOIN instruction_operands o
  ON o.addr = i.addr AND o.addr = 0x401000
WHERE i.addr = 0x401000
ORDER BY o.opnum;

---

反编译

需要 Hex-Rays。 本节中的所有函数（decompile、call_arg_addrs、 set_union_selection* / get_union_selection* 系列、call_arg_item、 ctree_item_at 和 set_numform* / get_numform* 系列）仅在 Hex-Rays 反编译器可用时才会注册。在不含 Hex-Rays 的构建版本或运行时环境中，这些函数不存在，调用时会返回 no such function。请先通过 SELECT decompile(<addr>) 探测，再依赖这些函数。

函数	描述
decompile(addr)	首选 — 带行前缀的完整伪代码
decompile(addr, 1)	强制重新反编译（写入或重命名后使用）
call_arg_addrs(call_addr)	持久化参数加载指令 EA 的 JSON 数组
set_union_selection(func_addr, addr, path)	在 EA 处设置／清除联合体选择路径
set_union_selection_item(func_addr, item_id, path)	按 ctree.item_id 设置／清除联合体选择路径
set_union_selection_addr_arg(func_addr, addr, arg_idx, path[, callee])	首选调用参数定位辅助函数
call_arg_item(func_addr, addr, arg_idx[, callee])	将调用参数坐标解析为显式的 arg_item_id
ctree_item_at(func_addr, addr[, op_name[, nth]])	将通用表达式坐标解析为 ctree.item_id
set_union_selection_addr_expr(func_addr, addr, path[, op_name[, nth]])	通过表达式坐标设置／清除联合体选择
get_union_selection(func_addr, addr)	读取 EA 处联合体选择路径的 JSON
get_union_selection_item(func_addr, item_id)	按 ctree.item_id 读取联合体选择路径的 JSON
get_union_selection_addr_arg(func_addr, addr, arg_idx[, callee])	通过调用参数坐标读取联合体选择 JSON
get_union_selection_addr_expr(func_addr, addr[, op_name[, nth]])	通过表达式坐标读取联合体选择 JSON
set_numform(func_addr, addr, opnum, spec)	按 EA 和操作数索引设置／清除数字格式
get_numform(func_addr, addr, opnum)	按 EA 和操作数索引读取数字格式 JSON
set_numform_item(func_addr, item_id, opnum, spec)	按 ctree 项目 ID 设置／清除数字格式
get_numform_item(func_addr, item_id, opnum)	按 ctree 项目 ID 读取数字格式 JSON
set_numform_addr_arg(func_addr, addr, arg_idx, opnum, spec[, callee])	通过调用参数坐标设置／清除数字格式
get_numform_addr_arg(func_addr, addr, arg_idx, opnum[, callee])	通过调用参数坐标读取数字格式 JSON
set_numform_addr_expr(func_addr, addr, opnum, spec[, op_name[, nth]])	通过表达式坐标设置／清除数字格式
get_numform_addr_expr(func_addr, addr, opnum[, op_name[, nth]])	通过表达式坐标读取数字格式 JSON

反编译器局部变量和标签的修改由表驱动：

• 使用 SELECT idx, name, type, comment, size, is_arg, is_result, stkoff, mreg FROM ctree_lvars WHERE func_addr = ... ORDER BY idx 列出局部变量。
• 使用 func_addr 和选定的 idx，通过 UPDATE ctree_lvars SET name = ... 或 comment = ... 重命名局部变量或添加注释。
• 使用 UPDATE ctree_labels SET name = ... WHERE func_addr = ... AND label_num = ... 重命名标签。

---

文件生成

函数	描述
gen_listing(path)	生成完整数据库的列表文件（LST）

SELECT gen_listing('C:/tmp/full.lst');

---

图生成

函数	描述
gen_cfg_dot(addr)	将 CFG 生成为 DOT 图字符串
gen_cfg_dot_file(addr, path)	将 CFG DOT 写入文件
gen_schema_dot()	将数据库架构生成为 DOT

SELECT gen_cfg_dot(0x401000);
SELECT gen_schema_dot();

---

数据库持久化

函数	描述
save_database()	持久化当前 IDA 数据库文件；成功时返回 1，失败时返回 0

-- Save once after a batch of SQL edits
SELECT save_database();

在需要持久化写入的长时间运行 HTTP/MCP/插件会话中使用此函数。 优先使用 save_database()，而不是 IDAPython 保存代码片段；它会调用 idasql 自身的持久化接口。对于大型数据库，save_database() 可能耗时较长，因此请批量执行编辑，并在适当的节点保存。

---

实体搜索（grep）

规范工作流指南位于 ../grep/SKILL.md。

接口	描述
grep 表	可组合 SQL 搜索的结构化行

SELECT name, kind, addr FROM grep WHERE pattern = 'sub%' LIMIT 10;
SELECT name, kind, addr FROM grep WHERE pattern = 'init' LIMIT 50 OFFSET 0;

---

字符串列表函数

函数	描述
rebuild_strings()	使用 ASCII + UTF-16 重建，最小长度为 5（默认值）
rebuild_strings(minlen)	使用自定义最小长度重建
rebuild_strings(minlen, types)	使用自定义长度和类型掩码重建

类型掩码：1=ASCII，2=UTF-16，4=UTF-32，3=ASCII+UTF-16（默认值），7=全部。 使用 COUNT(*) FROM strings，即可在不实例化字符串行的情况下获取当前字符串列表数量。

SELECT COUNT(*) AS strings FROM strings;
SELECT rebuild_strings();
SELECT rebuild_strings(4);
SELECT rebuild_strings(5, 7);

---

另请参阅

• connect — 前端目录和路由矩阵；选择技能时使用，而非选择函数时使用。
• 与函数相关的主题技能（data 用于字节/字符串，decompiler 用于 decompile()，disassembly 用于 disasm_*，types 用于 parse_decls，debugger 用于修补辅助函数）。