扩展库 / tar
tar
内存与文件 TAR 归档读写。
当前 Windows 发布版的 C/TCC 归档主路径及双语入门范例通过；完整门禁在 extractSelected 的语言名称数组投影处失败，后续 AOT 未签收。覆盖提取另有独立的旧文件失败非原子性风险。
提供条目元数据、追加、选择性提取与显式资源限额。硬链接仅能指向本次提取写出的文件，不借用目标目录原有文件。XLang tar.open(Buffer) 持有输入副本，支持内联临时 Buffer；XRT 原始 C 内存 Reader 仍借用输入。C Reader 的输入限额从当前读取位置起算，进度总量不包含归档前缀；无法取得当前位置时由流式读取执行限额，并将进度总量标为未知。Linux 联合门禁曾通过 C sanitizer、LP64 桥接、XLang 边界与双语范例逐字对照；不能替代当前 Windows 发布物的完整验收。
主要接口
C 选项的顶层和嵌套资源限额保留字段必须为零；无效配置在读写器创建时拒绝。TAR 不使用深度、压缩倍率或资源标志：OptionsInit 将前两项清零，显式设置 iMaxDepth、iMaxCompressionRatio 或 iFlags 会报参数错误。
TarInfo.uid/gid、其构造参数和文本/Buffer 两个 writer.add 重载的同名参数均为 uint64，默认值为0；负数实参在类型检查时拒绝。PAX 可保留完整64位无符号 ID，未提供有符号兼容重载。mtime 为 int64 整秒；读取时超范围时间戳与超宽 mode/设备号明确报格式错误，不截断。mode/设备号按无符号32位读取，再安全拓宽到 XLang int；这不代表操作系统允许恢复任意元数据。
| 接口 | 用途 |
|---|---|
tar.create()、writer.add()、writer.finish() | 在内存中创建归档并取得 Buffer |
tar.open(buffer/path)、reader.next() | 顺序读取归档条目 |
tar.create(path)、tar.openForAppend(path) | 创建文件归档，关闭后再追加条目 |
reader.info()、reader.read() | 读取条目元数据与原始内容；元数据类型可写为 tar.TarInfo |
reader.extractAll()、extractSelected() | 提取到指定目录；目标根路径允许调用方选用符号链接，归档条目不得经目录内链接逃逸；选择白名单按完整名称匹配，含 NUL 的名称在提取前拒绝。覆盖提取尚无单文件失败原子性，失败时可能改写旧文件，不宜直接覆盖需保留的生产数据 |
xlang
import tar
auto writer = tar.create()
writer.add("hello.txt", "hello")
Buffer packed = writer.finish()
auto reader = tar.open(packed)
assert reader.next()
tar.TarInfo entry = reader.info()
println(entry.name, reader.readText())C
包含 include/xrt_tar.h；用 xrtTarWriterDestroy、xrtTarReaderDestroy 和 xrtBufferDestroy 释放对应对象。xrtTarWriterAdd 仅允许普通文件携带正文；非文件条目的传入长度与声明长度都必须为零，否则在写入归档字节前报参数错误。包内 examples/basic_c.c 与 XLang 范例同输出；examples/append_c.c 和 examples/append.xl 成对演示创建、追加与读回，使用独占临时目录，不覆盖已有文件。从发布目录直接运行 ./xl run extlibs/tar/examples/append_c.c 即可。单文件 C 范例只包含所需读写实现单元，正式包仍按清单分别编译。
验证范围
2026-10-29 Writer：构造、流式添加/复制、来源文件、事务创建/追加/提交的内存故障保留 MemoryError；开放事务先用 XRT 原生句柄删除再关闭，避免异常展开时再次分配路径。十组 C 分配矩阵、活动快照、大正文/PAX、原文件保留、零分配析构及八类语言 JIT/AOT、临时文件检查在 Windows/Linux 通过，Linux 另有 ASan/UBSan；这不是持续 OOM 或所有 OS 故障的完整证明。test/check_writer.ps1 / test/check_writer.sh 还强制运行已关闭事务回滚探针：Windows 在提交改名失败后、Destroy 路径删除再遇 OOM 时遗留临时文件，原目标不变，门禁保持红色；Linux 同探针通过。该风险需要 XRT 层预备提交/回滚能力，不在包内复制系统实现。名称数组投影、覆盖提取失败原子性与整包签收仍未关闭。
2026-10-29：Reader 路径/元数据分配失败不再被误报为格式/参数错误或返回成功；便利构造器中间层失败会释放内部输入并保留首因。PAX local/global、GNU L/K 扩展头之后只有实际文件条目才能使 next 返回 true，EOF/截断不会生成虚假条目。无前缀名称直接移交给条目，少一次分配和复制。test/check_reader.ps1 / test/check_reader.sh 在 Windows/Linux 通过 C 逐分配点故障、活动分配快照、格式/旧 OOM 隔离、正文分配失败重读及 XLang JIT/AOT 的构造/next/readText/info 低内存矩阵；Linux 另有 ASan/UBSan。原 C/TAR 套件与数值专题再次通过。低层 Create 返回 NULL 时不接管调用方输入，Open* 自行清理内部输入；原始 C 内存 Reader 仍借用数据。整包仍有名称数组投影和覆盖失败原子性阻断，不据专题通过签收提取与完整回调。
2026-10-28：修复 GNU 二进制负时间戳下溢、mode 截断及桥接有符号窄化，完整 uint64 ID 的双语往返通过。Windows/Linux 数值专题门禁检查 C18组边界、Python 独立生成的40组归档在 C/JIT/AOT 间逐行一致、负 ID 编译拒绝与同输出范例；Linux C 使用 ASan/UBSan。可直接运行 examples/metadata.xl 与 examples/metadata_c.c，两端均输出 mtime=-1;uid=18446744073709551615;gid=9223372036854775808。专题门禁为 test/check_numeric.ps1 / test/check_numeric.sh，需要 Python 3。原有 C/TAR 套件亦通过，但两平台整包门禁仍在名称数组投影处失败；根内原子提交、完整回调与整包发布签收未完成，不以数值专题的 AOT 通过替代。
2026-10-15：C/XLang 最小归档范例均输出 hello；验证 UTF-8 正文、内联 Buffer 生命周期、限额、含 NUL 的路径/条目名，以及 mode/uid/gid 范围拒绝。选择提取的原生 ABI 已与生成的 xvalue* 原型一致；有效名称实际提取成功，含 NUL 名称不再误匹配前缀。中央 XLang 和 C 选择提取范例均使用独占系统临时目录并清理，避免固定目录误删及并发冲突；Windows/Linux 包门禁均运行并固定输出。writer.save(path, "xz") 写出标准 XZ 流，要求文件名以 .xz 结尾，tar.open(path) 可重开；Python 的 lzma.FORMAT_XZ 与 tarfile 已双向互通。不提供旧 .lzma 路径。压缩归档和原生文件读取桥的 maxInput=0 均使用 XRT 默认上限，不会回退为无上限读取；256 MiB + 1 字节稀疏文件在 Windows/Linux 桥接测试中被拒绝。Linux 桥接的 64 位参数与生成 C 原型一致。无效格式/扩展名不会提前关闭 writer。Windows 不支持还原 POSIX mode 时会在创建目标前拒绝。extractWhere / extractWithProgress 的 XLang 回调及完整 AOT 仍被主线问题阻断，不能将普通归档读写的通过结果外推到该路径。
PAX 记录按声明长度拒绝内嵌 NUL，包括数字、路径和未知扩展键；size/uid/gid/mtime 数字使用严格解析，也不接受无符号字段的正号。mtime 允许有数字的小数部分，但当前整数元数据只保存向零截取的整秒。读写器现在拒绝内嵌资源限制的未知版本或截断结构，返回参数错误。Linux 权限恢复以最后一个同名条目为准，dir 与 dir/ 等价；旧文件改为链接后不会把旧 mode 施加到链接目标。Windows 可用 test/check.ps1 -SkipAot 单独复验包内 C/XLang 路径，Linux 可用 test/check.sh 运行 ASan/UBSan 与双语对照；当前 Windows 默认门禁先在语言数组投影处停止，完整 AOT 未执行。
2026-10-21：包内综合回调测试已去掉固定 build/tmp/tar_xlang_test 的递归删除，改用独占临时目录和 finally 清理；但仍在执行前受函数值入 var 的主线语义错误阻断。Windows/Linux 聚焦门禁通过不能代替该综合测试，路径改动与回调路径均待主线修复后验收。
自定义 C Reader/Writer 的回调故障区分内存故障与普通 I/O；归档正文真正提前结束仍报格式错误。文件提取的 Writer 阶段已有写入、刷新、关闭与复合失败的 C 注入矩阵，后续关闭故障不覆盖首次失败。Windows 聚焦门禁与 Linux C ASan/UBSan、XLang、XZ 互通曾通过。Windows 默认门禁还须构建、运行公开 XLang 范例并与 C 同输出，不能只凭无输出核心 AOT 签收。当前首先失败的是语言数组进入选择性提取的投影；真实文件句柄的操作系统刷新/关闭失败尚未注入，完整回调测试和 AOT 仍未签收。