amos 8b7616bfd8 Batch 22 (20261027-C-hwe-hard-22): add 63 calibrated HWE hard-design tasks
From the 101 lk/man/pth code-gen sources: 63 tasks (C11 36, C++17 27,
11 canonical families), 38 skipped for scope or duplication. Each task
has at least one independent contract-edge defect, boundary types
rotate, and public docs state trap clauses as plain contract prose.
Claude reviewed 63/63 USABLE against current digests. Difficulty is
unmeasured.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 16:14:57 +08:00

9.1 KiB
Raw Permalink Blame History

文件流工作台合同

使用与数据范围

  1. 本工程运行在普通 Linux 进程中,使用 C11、POSIX 文件接口;不依赖板卡、网络、特权操作或真实时间。公开声明位于 descriptor.h,链接库由 fd_ops.c、bank.c、stream.c、wire.c 组成,console.c 提供控制台入口。所有下列非 void 函数失败返回 -1,并设置 errno;成功时 errno 的值不作约定。函数不终止进程,不写标准输出。
  2. DR_SLOTS 为 8,槽号范围为 0..7;DR_LIMIT 为 4096,限制种子长度、单次读写长度、文件长度和可设置的位置;DR_NAME 为 32。槽名为 1..31 个 ASCII 字母、数字、下划线或短横线。任意字节(包括零)均可作为流内容。位置与长度均以字节为单位。
  3. 调用者提供有效、足够长的存储区。bank 必须经 dr_init 初始化;不直接修改其内部字段,也不关闭它持有的文件描述符。调用串行发生,不含信号中断、并发修改、进程间传递或外部 I/O 故障。实现可改变内部结构;对外观察由 dr_view 和接口给出。
  4. 所有接受 bank 的非 void 函数对 NULL bank 或范围外槽号返回 EINVAL。dr_seek 先校验 position;dr_take/dr_emit 先校验数据跨度;dr_bind 先校验两个槽号,再检查源是否打开;dr_flags 先校验 bank/槽号,再校验 enabled,再检查是否打开。多个错误组合时按这个次序选择 errno。没有声明顺序的参数错误均为 EINVAL。

槽和生命周期

  1. void dr_init(dr_bank *bank) 初始化一个尚未使用的 bank,全部槽为空;NULL 为无操作。不要用它重新初始化持有资源的 bank。int dr_reset(dr_bank *bank) 关闭全部槽并清空元数据,返回 0;已为空的 bank 仍成功,可连续调用并再次 seed。只释放本 bank 拥有的描述符。
  2. int dr_seed(dr_bank *bank, int slot, const void *bytes, size_t length, const char *name) 创建独立、可读写、可定位的匿名文件,复制 length 个字节,装入 slot,返回 0。length 为 0 时 bytes 可为 NULL,name 始终必须有效。成功替换该槽原来持有的描述符,其他槽仍保留原来的流。新流位置为 0、close-on-exec 为 0、读写计数为 0,名称取 name。名称非法、length 大于 DR_LIMIT 或非零 length 对应 NULL bytes 均为 EINVAL,原槽保持原状。
  3. int dr_bind(dr_bank *bank, int source, int target) 使 target 接入 source 的流,返回 0。source 为空返回 EBADF,target 保持原状;target 可为空或已有流。source 与 target 相同时保留描述符、close-on-exec、位置、内容、名称和计数。其余成功调用关闭 target 原有描述符,接入后两个槽共享同一个 open file description 的位置和内容,target 的 close-on-exec 为 0,名称复制 source,target 的两个计数清零。source 的描述符、标志和计数不变。
  4. int dr_drop(dr_bank *bank, int slot) 关闭并清空一个已打开的槽,返回 0;空槽返回 EBADF。其他接入同一流的槽继续有效。以后可在这个槽 seed 或 bind。
  5. int dr_flags(dr_bank *bank, int slot, int enabled) 设置该槽描述符的 close-on-exec 标志,enabled 只能为 0 或 1,其他值为 EINVAL;空槽返回 EBADF。成功返回 0。该标志属于单个描述符,不改变接入同一流的其他槽、位置、内容或计数。

数据与观察

  1. ssize_t dr_take(dr_bank *bank, int slot, void *bytes, size_t length) 从流的当前位置读取最多 length 个字节,返回实际读取数量。到达文件末尾返回 0,不越过末尾推进位置。读取成功把共享位置增加实际数量,仅为当前槽累计 read_bytes;不改变内容、名称、标志或 written_bytes。length 可为 0,此时 bytes 可为 NULL,仍检查槽是否打开,成功不移动位置也不改变计数。length 大于 DR_LIMIT 或非零 length 对应 NULL bytes 为 EINVAL;空槽为 EBADF。
  2. ssize_t dr_emit(dr_bank *bank, int slot, const void *bytes, size_t length) 从共享当前位置覆盖写入 length 个字节并返回 length,推进共享位置,仅为当前槽累计 written_bytes。写入不截断已有尾部;从末尾以外写入时空隙补零。length 可为 0,此时 bytes 可为 NULL,不延长文件也不移动位置。跨度校验同 dr_take;空槽为 EBADF;位置加 length 大于 DR_LIMIT 返回 EFBIG,位置和内容保持原状。写入不改变名称、标志或 read_bytes。
  3. off_t dr_seek(dr_bank *bank, int slot, off_t position) 把共享位置设置为 position 并返回该位置,不改变文件长度、内容或两个计数。position 可为 0..DR_LIMIT,包括末尾以外;超出为 EINVAL,空槽为 EBADF。
  4. int dr_inspect(const dr_bank *bank, int slot, dr_view *view) 对打开的槽返回 0,填入 cursor(共享位置)、size(文件长度)、cloexec(0 或 1)、read_bytes、written_bytes(该槽累计成功读/写字节数)、name(以零结尾的槽名)。不改变任何状态;NULL view 为 EINVAL,空槽为 EBADF。view 仅在成功时有定义。各流的长度和位置通过实际文件描述符取得,不依赖控制台是否访问过该槽。

描述符接口

  1. int dr_raw_replace(int source, int target) 为 bank 外的调用者提供 Linux dup2 行为,source 和 target 是进程文件描述符数值,成功返回 target。有效 source 替换 target 时,target 原来打开则原子关闭后接入 source 的 open file description;接入后共享位置及文件状态标志,target 的 close-on-exec 清除。有效 source 等于 target 时返回 target,保持该描述符的全部状态。source 无效或 target 为负数返回 EBADF;无效 source 不关闭或改变 target。输入包含合法同值、已打开/未打开目标和无效源组合。接口不拥有 source,也不在失败时释放调用者的有效描述符。
  2. int dr_raw_cloexec(int fd, int enabled) 修改一个描述符的 FD_CLOEXEC 位并返回 0,其他描述符标志保持;enabled 仅可为 0/1,否则返回 EINVAL,然后才检查 fd。无效 fd 返回 EBADF。该接口不改变共享位置和文件内容,也不关闭 fd。

文本 helper

  1. int dr_parse_i32(const char *text, int *value) 把零结尾的 ASCII 十进制文本解析为 -2147483648..2147483647 的数值,成功写入 value 并返回 0。语法为可选的一个 + 或 - 后接至少一个 0..9;不接受空白、其他字符或空串,前导零数量不限。NULL 参数、语法或范围错误为 EINVAL,不改变 value。
  2. int dr_hex_decode(const char *text, void *bytes, size_t capacity, size_t *length) 解析零结尾的十六进制文本;文本为偶数个 0..9/a..f/A..F,或单个 - 表示空字节串,空串非法。成功返回 0,写入解码字节并设置 length,不改动输出的其余部分。不接受空白、奇数长度或其他字符;解码后超过 capacity、非空输出对应 NULL bytes、NULL text 或 NULL length 为 EINVAL。错误时 bytes 和 length 保持原状;空输出可使用 NULL bytes。
  3. int dr_hex_encode(const void *bytes, size_t length, char *text, size_t capacity) 把 length 个字节写为十六进制文本并以零结尾,成功返回 0;字母大小写均可。输出至少需要 2*length+1 字节,包括 length 为 0 的情况。NULL text、非零 length 对应 NULL bytes、容量不足或长度计算溢出为 EINVAL,输出不变。length 为 0 可使用 NULL bytes,不限制输入内容。

控制台

  1. descriptor-console 无参数,从 stdin 读到 EOF,正常退出 0,输入流发生 I/O 故障退出 1;每次启动是一个空 bank,EOF 释放全部资源。输入为 ASCII 行,不含嵌入零字节;每行是一个操作。空行忽略。词之间可用空格、TAB、CR、LF 分隔;其他字节不视为空白。行长不限,包括数字中的任意合法前导零。
  2. 命令为 seed SLOT HEX NAME、bind SOURCE TARGET、read SLOT LENGTH、write SLOT HEX、seek SLOT POSITION、flags SLOT ENABLED、info SLOT、drop SLOT、reset。所有整数词使用 dr_parse_i32 的语法和范围;负长度为 EINVAL。HEX 使用 dr_hex_decode 的格式,解码长度最多 DR_LIMIT。命令参数数量、名称、数字或 HEX 错误输出 EINVAL,bank 保持原状,并继续处理后续行。合法命令遵守上面的库合同。
  3. 每个非空输入行产生一个 UTF-8 JSON 对象记录,占一行;允许额外字段和 JSON 空白。普通记录含数值字段 rc(接口返回值)和 err(失败时 errno,成功为 0);read 另含 data 字符串,为实际读取字节的十六进制文本(字母大小写均可),空或失败为 "";info 成功另含 cursor、size、cloexec、read_bytes、written_bytes 数值字段及 name 字符串。解析失败只需普通记录。stderr 只用于诊断,不参与行为结果比较。
  4. 只交付 README 列出的六个源码/头文件,其他文件和构建产物不参与评分。可重写内部模块,但所有库接口、helper 与控制台的公开行为均应满足上述条款。构建命令为 cc -std=c11 -D_POSIX_C_SOURCE=200809L -O2 fd_ops.c bank.c stream.c wire.c console.c -o descriptor-console,不要求无警告。