zError
返回 zlib 结果码对应的文本。
完整章节与共同规则 ↗const char * ZEXPORT zError(int err);
返回 zlib 结果码对应的文本。
返回值与后续调用
返回值类型。 const char * — 借用的不可变错误文本指针
把传入的结果码映射为文本。函数本身总是返回非 NULL 字符串指针。
zError()| 返回值 | 含义与出现条件 | 调用者接下来 |
|---|---|---|
"need dictionary"需要字典文本 |
err == 2。 | 读取借用的静态文本;不得写入或释放。 |
"stream end"流结束文本 |
err == 1。 | 读取借用的静态文本;不得写入或释放。 |
"file error"文件错误文本 |
err == -1。 | 读取借用的静态文本;不得写入或释放。 |
"stream error"流错误文本 |
err == -2。 | 读取借用的静态文本;不得写入或释放。 |
"data error"数据错误文本 |
err == -3。 | 读取借用的静态文本;不得写入或释放。 |
"insufficient memory"内存不足文本 |
err == -4。 | 读取借用的静态文本;不得写入或释放。 |
"buffer error"缓冲区错误文本 |
err == -5。 | 读取借用的静态文本;不得写入或释放。 |
"incompatible version"版本不兼容文本 |
err == -6。 | 读取借用的静态文本;不得写入或释放。 |
""空文本 |
err == 0,或 err 不在 -6–2 范围内,包括 int 的最小值和最大值。 | 按需读取空字符串;这既不是 NULL 指针,也不是另一个错误码。 |
调用条件与效果
定义域 完整类型定义域。
前置条件 完整类型定义域:每个 int,包括最小和最大值。
内存与状态效果 只读。结果是借用的不可变静态存储;不得写入或释放。 没有分配、堆变化或错误返回。索引计算前会检查 -6–2 范围外的值, 因此两个标量极值均安全返回空文本。
证明目标。 没有必需目标:zlib.h 把这个函数声明在“undocumented functions (not part of the zlib API)”(未文档化的函数,不属于 zlib API)之下。为它陈述了一个目标:功能目标 Goal.zError(不在计划内;已有定理证明它),在 Functional/Queries.lean 中,定理为 ZlibF.Spec.Public.Proofs.zError(public-zerror.lean)。称它为功能目标,是因为它确定了返回的文本;它同时也陈述了安全方面的事实。对每一个堆和每一个 err,这个目标陈述:调用返回,调用之后的堆就是调用之前的堆(没有写入、分配或释放),结果指向只读的静态存储,其中存放的是后置条件所述的文本。
完整返回条件与边界
返回与保证 返回非 NULL 指针,指向下列以 NUL 结尾的文本。
err |
文本 |
|---|---|
| 2 | need dictionary |
| 1 | stream end |
| -1 | file error |
| -2 | stream error |
| -3 | data error |
| -4 | insufficient memory |
| -5 | buffer error |
| -6 | incompatible version |
| 0 或任意其他值 | 空字符串 |
本组共同前提与范围
调用时若已知完整的输入和输出容量,可使用缓冲区工具。它们在内部管理临时流。 需要增量 I/O、其他封装、字典或显式刷新边界时,应使用流式接口页面。
| 任务 | 条目 |
|---|---|
| 压缩缓冲区 | 选择级别、默认级别、确定目的缓冲区容量 |
| 解压缓冲区 | 报告已消费输入、仅报告输出 |
| 查询库信息 | 版本、编译标志、错误文本 |
这些契约遵循固定版本的 compress.c、uncompr.c、zutil.c 和 zlib.h,采用默认 LP64 Linux 构建。
没有补丁改动这三个 C 文件(见补丁说明)。
_z 形式使用 z_size_t;普通形式使用 uLong。这里两者均为 64 位。
定义域和效果标签见契约约定。
这些是聚焦契约:前置条件描述通常的正确用法,有意比函数实际接受的范围窄。
超出前置条件的调用并不因此就是未定义行为,也不一定返回错误码。
已证明的内容。 只证明安全性:每次调用都返回,没有未定义行为和内存错误,只写其目标指明的内容,并且不泄漏(见安全性)。各条目在“证明目标”下给出自己的目标,所用的五项和固定用语由阅读证明目标段落定义:目标及其定理;目标适用的条件,按 Lean 命题中的顺序列出;对每一个取值都覆盖的内容;保证的内容(返回、状态、写入、分配);以及留给其他目标的内容。证明所假设的是那里列出的条件,而不是文档中的前置条件。后置条件、返回值表和各项说明描述的是功能行为:它们读自 C 源码,凡是没有定理陈述的,都尚未由证明确认;安全结论不需要它们。哪些目标已完成,见进度。
缓冲区工具的安全目标实例化三个命题
(Common/Utilities.lean):四个压缩函数用
CompressorSafety,uncompress2 和 uncompress2_z 用 UncompressCountedSafe,
uncompress 和 uncompress_z 用 UncompressSingleSafe。
缓冲区工具使用 zlib 封装和默认设置,创建并释放一个局部流。流记录是自动变量,不是堆块,所以它不占用任何一次分配尝试。一次调用的分配尝试都来自编解码器。compress* 调用至多尝试五次分配,全部在 deflateInit 中:状态、窗口、prev、head 和待输出缓冲区;当它拒绝参数或级别时,一次也不尝试。uncompress* 调用在 inflateInit 中尝试分配解码器状态,并在解码需要时于 inflate 内尝试分配窗口。
先说明长度的约定:sourceLen 指定可读输入的字节数;*destLen 在调用前是目的数组的可写容量,调用后改为实际写入量。例如目的缓冲区有 1000 字节容量、最终写入 120 字节,调用前应设置 *destLen = 1000,成功返回后读取到 120。这个长度单元自身也是需要保持存活、可读写的调用者存储。uncompress2_z 的 *sourceLen 同样在调用前给出可用的输入字节数,返回后报告已消费的字节数。
上界函数只计算一个数,并不分配目的数组。
flowchart LR
B["compressBound"] --> C["compress / compress2"]
C --> Z["zlib 流"] --> U["uncompress / uncompress2"]
U --> D["解码字节"]
通用约定
缓冲区调用的定义域限于有效内存:非 NULL 源覆盖指定的可读输入; 非 NULL 目的缓冲区覆盖指定的可写容量。非 NULL 长度指针指向可读写的标量单元。 输入、输出和长度单元互相分离,包括同时出现的两个长度单元。 调用期间,调用者保持这些对象存活且不修改它们。 各条目分别说明允许的 NULL 情形。其他无效指针不在此范围内。 处理解压错误不要求压缩数据有效。
通用效果。 范围内的每次调用都终止,且不产生故障。 缓冲区调用保持输入以及输出、长度单元以外的内存不变,写入不超过原始容量。 返回前释放所有内部分配,包括分配失败路径;调用不给调用者留下局部流,也不留下它自己做的分配。 返回指针的查询,返回的是借用的不可变存储。 “证明目标”下列出的安全目标陈述了这些效果,借用存储那一条除外;输出的内容属于功能行为。
模型中的长度单元。 对 compress、compress2 及它们的 _z 形式,翻译把 *destLen 作为值传递:函数接收容量(或者 destLen 为 NULL 这一事实),并返回要存入的长度。这个单元在模型中不是内存,所以这四个函数的安全目标无法谈论与源或目的缓冲区重叠的长度单元(见偏离记录中“整缓冲区压缩”一行)。对 uncompress 系列,长度单元是内存,每个为 8 个可读可写的字节,它们与缓冲区的分离是目标中写明的条件。
功能契约(安全之外)
ZlibF.Spec.Public.Goal.zError
状态:完成 · 结论的状态
/-- `const char *zError(int err)`.
Every signed argument returns the public error text as static read-only storage.
Every heap is unchanged; no allocation, leak or runtime fault is permitted. -/
def Goal.zError : Prop :=
∀ (h : Heap) (err : Int32), ∃ p,
C.run (Zlib.Zutil.zError err) h = .ok (p, h) ∧ StaticString h p (errorText err.toInt)相关定义与源码 ↗