inflateGetHeader
挂接调用者存储,用于下一个 gzip 头。
完整章节与共同规则 ↗int ZEXPORT inflateGetHeader(z_streamp strm, gz_headerp head);
挂接调用者存储,用于下一个 gzip 头。
gzip 头可以带有 extra 字节、文件名和注释。调用者分别提供这三类结果的目的地址与容量:extra/extra_max、name/name_max、comment/comm_max,容量均以字节计。挂接只保存这些地址;真正解析头部并填充结果的是后续 inflate 调用。
返回值与后续调用
返回值类型。 int — zlib 状态码
返回值只说明头部目的存储是否已挂接;解析进度稍后由 head->done 表示。
inflateGetHeader()| 返回值 | 含义与出现条件 | 调用者接下来 |
|---|---|---|
Z_OK头部目的存储已挂接 |
有效流支持 gzip,挂接 head 并将 head->done 置为 0;尚未解析头部。 | 保持所有已挂接的存储有效并调用 inflate;通过 done 查看后续结果。 |
Z_STREAM_ERROR挂接被拒绝 |
流检查失败或请求未启用 gzip 支持;内容不变。 | 先建立支持 gzip 的有效流,再在解码前挂接存储。 |
调用条件与效果
定义域 受限定义域:初始化/重置后、解码前,支持 gzip 的存活流。
内存与状态效果 挂接借用存储,写入 head->done。
前置条件 head 非 NULL 且可写。其 extra、name、comment 指针为 NULL,或分别具有可写容量 extra_max、name_max、comm_max。所有已挂接的存储保持有效,直到头部解析结束或请求被清空。头部记录及其目的缓冲区彼此分离,并与流、流拥有的存储,以及使用它们的调用的输入/输出范围分离。
证明目标。
- 目标。
Goal.inflateGetHeader_safety(Safety/Streams.lean);必需。定理:ZlibF.Spec.Public.StreamCallSafetyProof.inflateGetHeader_safety(public-stream-call-safety.lean)。这个目标有两个子句:对被拒绝的流的拒绝;对可达流的一次调用。 - 适用条件。 拒绝子句要求
strm是被拒绝的流(RefusedInflate)。对可达流的调用要求(StreamCallDomain):strm是可达流(StreamReachable);- 平台大小上界成立(
ByteObjectsFit); head不为 NULL,指向一个存活的头部记录,且该记录不是流自己的块;它的extra、name、comment指针各自为 NULL,或分别指向extra_max、name_max、comm_max个可写字节,且这些字节在流自己的块之外(HeaderMemory;head不为 NULL 这一条由StreamArguments另加)。
- 无条件覆盖。 每一个可达流,无论处于哪种模式:解码之前、块的中途、流结束处,以及数据错误或内存错误之后。本目标比前置条件宽:流不必支持 gzip。拒绝子句中:每一个被拒绝的流,以及其他参数的每个取值。
- 保证(对可达流的调用是
StreamCallSafe)。- 返回。 对被拒绝的流,调用返回
Z_STREAM_ERROR。对可达流调用时,调用返回。 - 状态。 对可达流调用时,流保持其不变量(
StreamInvariant)。 - 写入。 对被拒绝的流不写任何内容:堆不变。对可达流调用时,只写流记录、流自己的块和头部记录
head。 - 分配。 对可达流调用时,精确的分配账本(
LiveChange)。
- 返回。 对被拒绝的流,调用返回
- 不在本目标内。 对可达流调用而
head为 NULL:在所有安全目标之外(见偏离记录中“头部参数”一行)。流不支持 gzip 时,C 在用到head之前就返回Z_STREAM_ERROR;功能目标Goal.inflateGetHeader陈述了这个返回值。zalloc和zfree已设置、而state是垃圾指针、指向已释放的状态或指向 deflate 状态的流记录:没有目标覆盖对这种记录的这个调用(见偏离记录)。返回值,以及后续inflate调用在记录中存入的内容:功能目标Goal.inflateGetHeader(不在计划内;已有定理证明它)。
完整返回条件与边界
返回与保证 返回 Z_OK,保留指针,将 done 置为 0。后续 inflate 调用填充标量字段和可用缓冲区前缀。存在 extra 字段时,extra_len 为实际长度;不存在时,extra 变为 NULL,extra_len 不变。只有终止符能放下时,名称/注释才以零终止。缺失的可选字段使对应指针变为 NULL。完成时将 done 置为 1;自动检测到 zlib 时置为 -1。
边界情况 不分配,也不转移所有权。重置清空挂接。流检查失败或请求不支持 gzip 时,返回 Z_STREAM_ERROR,不发生变化。对已接受的请求传入 NULL head 不在本契约范围内:C 会解引用它。
本组共同前提与范围
使用 inflate 流分批解码输入,同时控制输出空间。初始化时选择 zlib、gzip 或裸 DEFLATE,随后提供更多输入或空间继续,直到完成、请求字典或发生错误。无论出现哪种结果,inflateEnd 都可释放解码器。整块缓冲区的 zlib 解码见 uncompress。
| 任务 | 条目 |
|---|---|
| 开始或复用 | 初始化、配置初始化、重置、新配置、保留历史 |
| 解码或提供元数据 | 解压、设置字典、读取历史、gzip 头 |
| 恢复或检查 | 同步搜索、同步点、位置标记、表使用量 |
| 调整或分支 | 预置位、校验、距离选项、复制 |
| 释放存储 | 结束 |
这些契约遵循打上补丁 0001 之后的固定版本 inflate.c 以及 zlib.h,采用默认 LP64 Linux 构建,启用 gzip,不启用可选的无效距离或严格距离模式。补丁 0001 只改动 inflateCopy(见补丁说明)。这些是聚焦契约:前置条件描述通常的正确用法,有意比函数实际接受的范围窄。前置条件之外、C 仍会处理的情况,写在“错误”或“边界情况”下。超出前置条件的调用并不因此就是未定义行为,也不一定返回错误码。各标签的含义见契约约定。
已证明的内容。 只证明安全性:每次调用都返回,没有未定义行为和内存错误,只写其目标指明的内容,并且不泄漏(见安全性)。各条目在“证明目标”下给出自己的目标,所用的五项和固定用语由阅读证明目标段落定义:目标及其定理;目标适用的条件,按 Lean 命题中的顺序列出;对每一个取值都覆盖的内容;保证的内容(返回、状态、写入、分配);以及留给其他目标的内容。证明所假设的是那里列出的条件,而不是文档中的前置条件。后置条件、返回值表和各项说明描述的是功能行为:它们读自 C 源码,凡是没有定理陈述的,都尚未由证明确认;安全结论不需要它们。哪些目标已完成,见进度。
公共条件
调用者与解码器各自保留不同的内容。调用者提供每次调用的输入和输出缓冲区;解码器保留当前解析阶段、尚未用完的位,以及后续复制可能需要的历史。给它换一个输出数组,并不会开始一个新的解码任务。
next_in 是未读输入的起点,avail_in 是可读字节数;next_out 是下一个输出位置,avail_out 是从这里开始的剩余可写字节数。例如,一个 5 字节的输出数组在返回时还剩 2 字节空间,就说明它已收到 3 字节。先取走这些字节,再把指针和计数设置为下一块可写区域。
下列所有契约都有受限定义域。仅凭 C 指针类型,不能提供这里要求的存储、生命周期或调用历史。
- 存活流已成功初始化或复制,尚未结束,保留库拥有的状态,且不发生并发调用。使用默认分配器和释放函数。初始化调用接收可写的、不是存活流的流对象,分配器字段为 NULL 或默认函数。
- 可读或可写范围在整个调用期间都具有所述容量。调用者范围与流及流拥有的存储分离。输入与输出范围不重叠。字典目的缓冲区、已挂接的头部记录及其目的缓冲区彼此分离,也与流分离。使用已挂接的头部存储的调用还要求它与输入/输出范围分离。这些限制属于前置条件;各条目的“证明目标”说明其目标假设了其中哪些。
- 调用者拥有流对象及缓冲区。库拥有状态和可选窗口。调用只改变自己的流、流拥有的存储、所述输出范围和任何已挂接的头部目的存储。它绝不释放调用者缓冲区。
- 流检查拒绝时返回
Z_STREAM_ERROR,不发生变化,除非查询或复制契约另有说明。这覆盖 NULL 和可安全读取但未通过检查的记录,不覆盖悬空或任意指针。检查要求有分配器、状态、状态的回指指针和有效的模式。 - 计数器使用 C 无符号位宽并回绕。没有契约假设分配成功。解码、字典或分配错误之后,仍可调用
inflateEnd。 - 证明目标里说的是可达流,契约里说的是存活流(见契约约定)。目标所覆盖的调用会延长流的历史:调用返回后,无论返回哪个状态码,流仍然是可达流,下一次调用的目标随之适用。
inflateEnd结束这段历史。 - 结果单元作为值。
inflateGetDictionary通过uInt *dictLength报告长度。翻译没有把这个单元建模为内存:函数接收该单元的旧值(或者指针为 NULL 这一事实),并返回新值。因此目标不涉及这个单元的地址,也无法表达它与其他对象重叠的情况。
flowchart LR
I["初始化"] --> F["inflate"]
F -->|"Z_NEED_DICT"| D["设置字典"] --> F
F -->|"更多空间或输入"| F
F -->|"结束或放弃"| E["结束"]
F -->|"数据错误"| R["重置或同步搜索"] --> F
安全目标
ZlibF.Spec.Public.Goal.inflateGetHeader_safety
状态:完成 · 结论的状态
/-- `int inflateGetHeader(z_streamp strm, gz_headerp head)`.
**Safety of `inflateGetHeader`**: a `NULL` or inconsistent stream (`RefusedInflate`) is refused with
`Z_STREAM_ERROR` and nothing changed; and on every reachable inflate stream, with the caller's
arguments as `zlib.h` asks, the call is safe (`StreamCallSafe`). -/
def Goal.inflateGetHeader_safety : Prop :=
(∀ h p head, RefusedInflate h p →
C.run (Zlib.Inflate.inflateGetHeader p head) h = .ok (Z_STREAM_ERROR, h)) ∧
(∀ h r head,
StreamCallDomain .inflate h r (.inflateGetHeader (some r) head) →
StreamCallSafe .inflate h r (.inflateGetHeader (some r) head))相关定义与源码 ↗功能契约(安全之外)
ZlibF.Spec.Public.Goal.inflateGetHeader
状态:完成 · 结论的状态
/-- `int inflateGetHeader(z_streamp strm, gz_headerp head)`.
Only gzip-capable wrappers accept the header. Set `done` to zero and retain all other fields. -/
def Goal.inflateGetHeader : Prop :=
∀ h r i z s head, InflateView h r i z s →
((s.wrap &&& 2) ≠ 0 → ∃ g gh, head = some (.tab g) ∧ h.gzheaders g = some gh) →
∃ rc after, C.run (Zlib.Inflate.inflateGetHeader (some r) head) h = .ok (rc, after) ∧
(if (s.wrap &&& 2) = 0 then rc = Z_STREAM_ERROR ∧ after = h
else ∃ g gh, head = some (.tab g) ∧ h.gzheaders g = some gh ∧ rc = Z_OK ∧
after = { putInflate h i { s with head := head } with
gzheaders := upd h.gzheaders g (some { gh with done := 0 }) })相关定义与源码 ↗