inflate
消费压缩字节,写入解码字节,跨调用保留状态。
完整章节与共同规则 ↗int ZEXPORT inflate(z_streamp strm, int flush);
消费压缩字节,写入解码字节,跨调用保留状态。
一次调用只使用交给它的输入和输出空间。返回时先看它推进了多少,再看返回码,以决定是继续、提供字典、停止还是处理错误。flush 请求的是停止点或完成方式,不是压缩级别。输出缓冲区写满不表示流已经解完,输入用完也不表示数据已损坏。
返回值与后续调用
返回值类型。 int — zlib 状态码
结果区分本次推进、一个流的完成、字典请求和错误;推进不代表解码结束。
inflate()| 返回值 | 含义与出现条件 | 调用者接下来 |
|---|---|---|
Z_OK已推进,尚未完成 |
已消费输入或产生输出,但尚未完成一个流;也可能因指定的块/头部边界而停下。 | 按需提供更多输入或输出空间后继续 inflate。 |
Z_STREAM_END一个流或成员已完成 |
已完成一个所选格式的流,包括启用的尾部校验;已完成流的重复调用也返回此值。 | 保留未读尾部输入;调用 inflateEnd,或在处理下一个 gzip 成员前重置。 |
Z_NEED_DICT需要 zlib 字典 |
zlib 头部要求预置字典;strm->adler 给出所需字典的标识。 | 用 inflateSetDictionary 提供正确字典,成功后继续;放弃则调用 inflateEnd。 |
Z_BUF_ERROR无法取得所需的推进或完成 |
本次没有输入/输出推进,或 Z_FINISH 请求无法完成;Z_FINISH 将本来为 Z_OK 的结果改为此值。 | 按需提供输入或输出空间后继续;不能仅凭此值判定数据损坏。 |
Z_DATA_ERROR检测到数据错误 |
检测到格式错误或启用的校验和/长度错误;可能已经产生输出。数据错误状态会保持。 | 使用 inflateReset 放弃当前流,或用 inflateSync 尝试恢复,或调用 inflateEnd。 |
Z_MEM_ERROR历史窗口分配失败 |
窗口分配失败;可能已经消费输入或写出数据,且错误状态会保持。 | 读取已更新的指针及可用计数;重置后再开始,或调用 inflateEnd。 |
Z_STREAM_ERROR流或缓冲条件不满足 |
流/缓冲检查失败,或 inflateSync 恢复搜索尚未完成。 | 流有效时修正缓冲区参数;恢复搜索未完成时继续 inflateSync;其他情况先建立有效流。 |
调用条件与效果
定义域 受限定义域:满足公共缓冲区/头部生命周期条件的存活流;覆盖任意压缩字节、任意输入/输出切分方式和任意有符号 flush 值。
内存与状态效果 修改流、输出和已挂接的头部存储;可能分配历史窗口。
前置条件 next_in 描述 avail_in 个可读字节,仅在计数为零时可为 NULL。即使 avail_out 为零,next_out 也非 NULL,并描述该数量的可写字节。已挂接的头部及其缓冲区保持可写。调用可以提供更多输入/空间继续,可以提供请求的字典,也可以在成功重置/恢复之后继续。终止/错误状态下重复调用的行为见下文。
计数记账 正常返回,包括数据错误和缓冲区错误,按已消费/已产生字节数更新总计数,并更新已启用的输出校验和。Z_NEED_DICT 把已消费的头部字节计入总计数,并让 adler 保持为字典标识。迟发的窗口分配失败可能发生在消费输入和写入输出之后:指针/计数已经反映这些操作,但正常的最终总计数/校验和/data_type 记账被跳过。一次调用已消费的输入不必全部属于某个有效的流:后一次调用可以拒绝该流而不再消费输入。
所有权 新窗口存储归流所有,仍可用于重置/结束,包括错误之后。一次调用的 Z_FINISH 完成可能无需窗口。拼接 gzip 成员要求成员之间重置。错误消息是借用的静态字符串。缓冲区和流检查的拒绝不改变任何内容。
证明目标。
- 目标。
Goal.inflate_safety(Safety/Streams.lean);必需。定理:ZlibF.Spec.Public.StreamCallSafetyProof.inflate_safety(public-stream-call-safety.lean)。这个目标有两个子句:对被拒绝的流的拒绝;对可达流的一次调用。Goal.inflate_refusal(Safety/Refusals.lean)也是必需目标,它陈述同一个拒绝。 - 适用条件。 拒绝子句要求
strm是被拒绝的流(RefusedInflate),并要求模型的内存在下一个未用块号及其之后没有已分配的块(Fresh,这是对模型的条件,不是对调用者的要求)。对可达流的调用要求(StreamCallDomain):strm是可达流(StreamReachable);- 平台大小上界成立(
ByteObjectsFit); next_in为 NULL,或指向avail_in个可读字节;next_out为 NULL,或指向avail_out个可写字节;两个范围都不在流自己的块内,且互不重叠(StreamBuffers);- 如果挂接了头部记录(已交给
inflateGetHeader,此后没有被重置解除):该记录存活,且不是流自己的块;它的extra、name、comment指针各自为 NULL,或分别指向extra_max、name_max、comm_max个可写字节,且这些字节在流自己的块之外(HeaderMemory)。本目标在每次调用时都要求这一点,头部读完之后也是如此; - 在把 gzip 头读入该记录期间:
extra缓冲区与尚未读取的输入不重叠;在读取 extra 字段期间,记录的extra_len不小于尚待读取的长度(InflateHeaderProgress)。这是调用时对记录的条件,不论这个字段是谁写的:inflate会写流所挂接记录中的extra_len,所以挂接在同一个记录上的两个流(例如inflateCopy之后)在目标之外。条件 4 和 5 合起来就是ActiveHeader。
- 无条件覆盖。 每一个
flush值;每一种输入字节序列,无论格式是否正确;每一种分配结果。本目标比前置条件宽:next_out可以为 NULL,next_in也可以在avail_in非零时为 NULL。C 对这两种情况都返回Z_STREAM_ERROR拒绝。拒绝子句中:每一个被拒绝的流,以及其他参数的每个取值。 - 保证(对可达流的调用是
StreamCallSafe)。- 返回。 对被拒绝的流,调用返回
Z_STREAM_ERROR。对可达流调用时,调用返回。 - 状态。 对可达流调用时,流保持其不变量(
StreamInvariant)。 - 写入。 对被拒绝的流,不写调用前已分配的任何块(
Frame);这个子句没有写成“堆不变”,因为翻译会创建并释放一个四字节的局部数组。对可达流调用时,只写流记录、流自己的块、已挂接的头部记录、next_out处的avail_out个字节,以及头部的extra、name、comment缓冲区(分别为extra_max、name_max、comm_max个字节)。 - 分配。 对被拒绝的流,已分配的块与调用前相同(
LiveChange)。对可达流调用时,精确的分配账本(LiveChange)。
- 返回。 对被拒绝的流,调用返回
- 不在本目标内。
zalloc和zfree已设置、而state是垃圾指针、指向已释放的状态或指向 deflate 状态的流记录:没有目标覆盖对这种记录的这个调用(见偏离记录)。返回哪个状态码、写出哪些字节:功能目标Goal.inflate(不在计划内;已有定理证明它)。
完整返回条件与边界
返回与保证 在所述范围内读写。按已消费/已产生字节数推进指针并减少可用计数。从初始化/重置开始的普通运行中,如果所选格式有效且字典正确,累计输出是解码数据的前缀,在 Z_STREAM_END 时等于完整数据。畸形字节也在定义域内:检测到格式错误,或启用的校验和/长度检查失败时,返回 Z_DATA_ERROR,此前可能已有输出。仅有输入不完整时需要更多输入;不必把它报告为数据错误。
各返回码的含义和下一步操作,见返回值与后续调用下的表。
边界情况 允许输入或输出空间为零。Z_BLOCK 在头部或块边界停止;Z_TREES 还在块描述之后停止。Z_FINISH 将本来为 Z_OK 的结果改为 Z_BUF_ERROR。其他有符号刷新值被接受,行为与 Z_NO_FLUSH 相同。正常返回时,data_type 记录未用位数;最终块再加 64,头部/块边界再加 128,块头之后再加 256。数据和内存错误会保持;完成的流重复返回 Z_STREAM_END。
本组共同前提与范围
使用 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.inflate_safety
状态:完成 · 结论的状态
/-- `int inflate(z_streamp strm, int flush)`.
**Safety of `inflate`**: a `NULL` or inconsistent stream (`RefusedInflate`) is refused with
`Z_STREAM_ERROR`; on a `Fresh` heap it writes no block that was live and leaves the live blocks as
they were (the local array it makes is freed); and on every reachable inflate stream, with the
caller's arguments as `zlib.h` asks, the call is safe (`StreamCallSafe`). -/
def Goal.inflate_safety : Prop :=
(∀ h p flush, Fresh h → RefusedInflate h p →
∃ after, C.run (Zlib.Inflate.inflate p flush) h = .ok (Z_STREAM_ERROR, after) ∧
Frame h after (fun _ => False) ∧ LiveChange h after (fun _ => False) (fun _ => False)) ∧
(∀ h r flush,
StreamCallDomain .inflate h r (.inflate (some r) flush) →
StreamCallSafe .inflate h r (.inflate (some r) flush))相关定义与源码 ↗功能契约(安全之外)
ZlibF.Spec.Public.Goal.inflate
状态:完成 · 结论的状态
/-- `int inflate(z_streamp strm, int flush)`.
The domain is actual init/call history, not an arbitrary hand-built decoder state.
The selected LP64 platform scope explicitly requires every live represented
byte object to have at most PTRDIFF_MAX bytes (size < 2^63), including caller
storage from non-malloc origins. See docs/en/deviations.md.
Includes all signed flush arguments, progress, terminal/error modes, output bounds,
counter timing on late memory failure, caller frame and ownership of a new window.
`Z_STREAM_ERROR` is characterized exactly: a NULL output pointer, NULL input with
pending input, or a decoder left in `SYNC` by a failed `inflateSync`; such a call changes
neither the stream nor the decoder state. `Z_BUF_ERROR` means no progress, or an
unfinished `Z_FINISH` call. With input and output space available, and a flush other than
`Z_BLOCK`/`Z_TREES` (which may stop at a block boundary using only held bits), a call that
does not end, request a dictionary or fail makes progress.
The sequence target states format correctness across all input/output splits. -/
def Goal.inflate : Prop :=
∀ h r i z s flush,
StreamReachable .inflate h r → Zlib.Inflate.Spec.Good h r i z s →
ZlibF.PlatformMemory.ByteObjectsFit h →
Zlib.Inflate.Spec.DefAlloc z → StreamBuffers h r → ActiveHeader h r →
∃ rc after z' s' used out,
C.run (Zlib.Inflate.inflate (some r) flush) h = .ok (rc, after) ∧
Zlib.Inflate.Spec.Good after r i z' s' ∧ StreamAccounting z z' used out.length ∧
Bytes after z.next_out out.length out ∧
(rc = Z_OK ∨ rc = Z_STREAM_END ∨ rc = Z_NEED_DICT ∨ rc = Z_STREAM_ERROR ∨
rc = Z_DATA_ERROR ∨ rc = Z_MEM_ERROR ∨ rc = Z_BUF_ERROR) ∧
(rc = Z_OK → (used ≠ 0 ∨ out ≠ []) ∧ flush ≠ Z_FINISH) ∧
(rc = Z_STREAM_ERROR ↔
z.next_out = .null ∨ (z.next_in = .null ∧ z.avail_in ≠ 0) ∨ s.mode = SYNC) ∧
(rc = Z_STREAM_ERROR → z' = z ∧ s' = s ∧ used = 0 ∧ out = []) ∧
(rc = Z_BUF_ERROR → (used = 0 ∧ out = []) ∨ flush = Z_FINISH) ∧
(z.avail_in ≠ 0 → z.avail_out ≠ 0 → flush ≠ Z_BLOCK → flush ≠ Z_TREES →
rc = Z_BUF_ERROR → used ≠ 0 ∨ out ≠ []) ∧
(rc = Z_STREAM_END → s'.mode = DONE) ∧
(rc = Z_NEED_DICT → s'.mode = DICT) ∧
(rc = Z_DATA_ERROR → s'.mode = BAD) ∧
(rc = Z_MEM_ERROR → s'.mode = MEM ∧ z'.total_in = z.total_in ∧ z'.total_out = z.total_out) ∧
(rc = Z_OK ∨ rc = Z_STREAM_END ∨ rc = Z_DATA_ERROR ∨ rc = Z_BUF_ERROR →
z'.total_in = z.total_in + UInt64.ofNat used ∧
z'.total_out = z.total_out + UInt64.ofNat out.length) ∧
BufferFrame h after
(fun b => StreamRoot r b ∨ InflateOwned i s b ∨ s.head = some (.tab b))
(⟨z.next_out, out.length⟩ :: HeaderRegions h s.head) ∧
LiveChange h after (fun b => InflateOwned i s' b ∧ ¬ h.live b) (fun _ => False)相关定义与源码 ↗