netrc

解析、修改和保存 UTF-8 netrc 凭据文件，支持 machine、default 和 macdef。

版本 1.0.0 · C / xlang · 无扩展库依赖

快速开始

import netrc

netrc.Netrc config = netrc.parse("machine api.example login alice password sample\n")
var auth = config.authenticators("api.example")
println(auth["login"])

C/XLang 对照范例还展示具名主机、default 回退与 macdef 宏，用 hostNames/macroNames 检查条目，并以 stringify/parse 验证内存往返。固定的未闭合引号示例演示错误码、行列、字节偏移及成功调用后清除诊断。可显式传入目标路径，通过 save/load 保存并读回凭据和宏；密码只参与核对，不写入输出。实际凭据不应写入日志，也不要把 stringify() 的结果直接打印到控制台。

接口

入口	用途
`parse / load`	解析文本或从 UTF-8 路径读取。
`netrc.Netrc`	导出的文档类型，可用于变量和参数声明；直接构造要求 `hosts`、`macros` 字典。
`Netrc.authenticators(host)`	优先查找指定主机，缺失时返回 `default`。
`Netrc.hosts / macros`	访问与修改凭据和宏字典。
`Netrc.hostNames / macroNames`	枚举主机与宏名称。
`Netrc.stringify / save`	生成文本或以同目录临时文件替换目标。
`errorCode / errorLine / errorColumn / errorOffset`	读取最近一次原生操作的错误位置；非法 UTF-8 指向首个错误字节，偏移从去掉可选 BOM 后的文本起算；token 间已接受的单独 CR 计作新行，CRLF 只计一行。

C 端包含 extlibs/netrc/include/xrt_netrc.h；文档由调用方用 xrtValueRelease 释放。拥有型 Reader/Writer 在退出时关闭；正文成功但关闭失败时，内存不足报告 MEMORY，其他关闭失败报告 IO；正文已有错误不被关闭故障覆盖。借用型流仍由调用方关闭。Reader 输入限额按当前游标之后的字节计算；无法同时查询总大小和当前位置时由实际限额读取裁决。传入选项结构时须先调用 xrtNetrcOptionsInit；结构或内嵌资源限额的版本、长度无效会报 ARGUMENT，不会回退到默认限额。netrc 不使用深度、压缩比或资源标志；这些字段及保留字段必须保持初始化值，否则报 ARGUMENT。传入 NULL 才使用默认选项。解析结果只存储在当前对象中，本库不会自动读取用户主目录的凭据，也不会自行向网络请求附加认证信息。

文档顶层只接受 hosts 和 macros；主机条目只接受 login、account、password。未知字段或空主机名、空宏名会使 stringify/save 报错，不会写出无法读回的凭据。写出时具名 machine 总在 default 前面，与外部 netrc 读取器的匹配顺序一致。保存失败时原文件保持不变。

单独 CR 与 CRLF 均可结束注释行，不会吞掉后一行的凭据声明；宏正文支持 CRLF 行尾，但行内独立 CR 会报语法错误。解析成功的宏能够写出并再次读回。

验证与边界

资源预算在解析和写出两侧生效：主机、宏定义、非 null 凭据字段与宏行分别计节点；条目只计主机、宏定义和宏行。单项按 UTF-8 字节计，宏行超限报告 LIMIT，非法 UTF-8 报告 UTF8，不会误报内存不足或字段类型错误。关闭、删除的后续错误不会覆盖正文首因。新增 C285 项资源边界、126 项复合 I/O 故障，以及语言限额用例；这些定向检查不替代完整包验收。

examples/bounded_credentials.xl 与 bounded_credentials_c.c 使用同一组有限预算，展示主机/default 选择、宏与凭据往返、超限恢复，输出与共同黄金文件一致；不打印密码、不读取真实凭据。门禁要求 GCC、Python 3 和对应平台发布物，记录输入指纹与完整输出，失败现场保留。

powershell -NoProfile -ExecutionPolicy Bypass -File release/extlibs/netrc/test/check.ps1
bash release/extlibs/netrc/test/check.sh

Windows C/XLang 边界与双语同输出、Linux C ASan/UBSan 和原生文件系统 0600 权限用例通过；原生入口的 64 位无符号参数与 XRT 的 uint64 ABI 一致。parse(string) 直接传入 UTF-8 数据及字节长度；原生层检查输入限额并拒绝内嵌 NUL。流式写入或刷新发生内存错误时报告 MEMORY，普通 I/O 错误报告 IO；保存阶段分配失败保持旧文件。POSIX 保存采用同目录私有临时文件并替换；Windows 仍依赖目标目录 ACL。当前 Windows/Linux 发布物的最小用例均在语言字典直接构造 Netrc 时失败，属于共享 var 字典投影阻断；Windows 默认门禁此前的 C、UTF-8 文件与 Python 互通通过，但后续分配/AOT 未执行。完整状态和复现见包内 README。