c-systems

C 系统与原生代码

涵盖用于库、系统代码和原生扩展的 C11 及更高版本。有关 C++（RAII、模板、移动语义），请参阅 ia-cpp-systems 技能。

工作规则

• 保留仓库认可的惯用写法和 ABI；不要把范围明确的修复变成全面改写风格。
• 明确所有权，检查可能失败的调用，验证公共边界，并断言内部不变量。
• 保留优化器假设之外的恢复路径。 断言一旦变成假设，可能会移除处理断言为假时情况的分支。将可恢复的检查保留为运行时分支，并在调试预处理器保护下添加仅用于诊断的断言。在优化版 release 构建中测试回退路径。
• 防止分阶段初始化遭到重入。 在每个构造函数或工厂路径中、执行任何可能触发回调的工作之前，设置进行中标记。只有在完全释放并重置部分状态后，才允许失败后重试。测试递归进入和初始化失败后的重试。
• 限制对外部输入的遍历，并在分配或缩窄类型之前检查大小。
• 只有在辅助函数能够命名一个概念、拥有一个错误或隔离副作用时，才选择使用它。
• 验证实际重新构建的产物；使用插桩测试检查安全性，并使用有代表性的 release 构建评估性能。

仓库约定优先于本技能

开始编写前，阅读仓库的 AGENTS.md/CLAUDE.md、公共头文件，以及相邻的两个 .c 文件。若它们与以下规则冲突，以仓库约定为准，且 diff 中不必对此作说明。

不得跳过此步骤。成熟的 C 代码库认可的惯用写法可能会被以下规则误判：

本地惯用写法	适用场景
Tab 缩进	php-src 及其扩展、Linux 内核
goto cleanup / goto err	Kernel、OpenSSL、curl、php-src：主流的多资源释放惯用写法
包含 return 的宏	PHP 扩展中的 RETURN_*/RETVAL_*、CPython 中的 Py_RETURN_*
项目状态类型	zend_result、CURLcode、int 加 errno：不要在已有类型旁另造一套枚举

不要仅仅因为相邻且未修改的 C 代码早于此处规则，就把范围明确的任务扩大成全仓库风格重写。

若目标是 PHP 扩展（php_*.h、PHP_FUNCTION、zend_、config.m4），在应用以下任何规则前，先加载 php-extension-c.md。布局、宏、错误模型、内存和断言均有扩展专属的覆盖规则，其中内存规则尤其会颠倒基础指南：扩展使用请求作用域分配器，而非 malloc/free。

验证

• 在仓库的警告配置下构建成功，且没有新增警告（新建项目：完整使用 -Wall -Wextra -Werror -Wconversion -Wshadow 组合，零警告）
• 在 -fsanitize=address,undefined 下通过测试套件，且无任何报告
• 若测试套件可在其下链接，则 valgrind --leak-check=full --error-exitcode=1 检查通过
• 每个新增的可失败调用点都经过检查；每个新增错误值都能追溯到一个产生它的位置
• 每个新增的状态变更叶函数都带有断言
• 不得新增仓库认可形式之外的 goto，单次向前跳转的清理语句除外；不得递归处理外部输入；遍历外部输入的循环必须有明确命名的上限

特定任务参考

实现或审查相应行为前，请阅读相关参考资料：

• 模块布局、命名、分解、控制流、错误、类型或宏：请参阅 implementation-structure.md。
• 内存、外部输入、断言、ABI 更改或共享辅助函数契约：请参阅 runtime-safety.md。
• 编译器设置、测试、构建来源、打包或性能声明：请参阅 build-and-measurement.md。

适用时，请参阅现有的专项参考资料：

• php-extension-c.md。
• memory-safety.md。
• correctness-traps.md。
• legibility-standard.md。