参考文档 / ZLIB × LEAN

inflateGetHeader

登记调用者存储，用于下一个 gzip 头。

此页源文件快照 · ecafc184cdf44b7f · 对应提交的原文 ↗

先看本函数的前置条件和返回结果；可展开下方共同规则，查看整组接口的缓冲区与所有权要求。

int ZEXPORT inflateGetHeader(z_streamp strm, gz_headerp head);

登记调用者存储，用于下一个 gzip 头。

头部可能含有扩展字节、文件名和注释。调用者分别提供这三类结果的目标地址与容量：extra／extra_max、name／name_max、comment／comm_max，容量均以字节计。登记只保存这些地址；真正解析头部并填充结果的是后续 inflate 调用。

定义域 受限定义域：初始化/重置后、解码前，支持 gzip 的有效流。

内存与状态效果 登记借用存储，写入 head->done。

前置条件 head 非 NULL 且可写。其 extra、name、comment 指针为 NULL，或分别具有可写容量 extra_max、name_max、comm_max。所有已登记存储保持有效，直到头部解析结束或请求被清空。头部记录及其目标缓冲区彼此分离，并与流、流拥有的存储，以及使用它们的调用的输入/输出范围分离。

返回与保证 返回 Z_OK，保留指针，将 done 置为 0。后续 inflate 调用填充标量字段和可用缓冲区前缀。存在扩展字段 extra 时，extra_len 为实际长度；不存在时，extra 变为 NULL，extra_len 不变。只有终止符能放下时，名称/注释才以零终止。缺失的可选字段使对应指针变为 NULL。完成时将 done 置为 1；自动检测到 zlib 时置为 -1。

边界情况 不分配，也不转移所有权。重置清空登记。流检查失败或请求不支持 gzip 时，返回 Z_STREAM_ERROR，不发生变化。对已接受的请求传入 NULL head 不在本契约范围内，C 会解引用它；这不是可干净返回错误的情况。

本组共同前提与范围

API 手册 · 共享流规则 · 流式压缩

使用 inflate 流分批解码输入，同时控制输出空间。初始化时选择 zlib、gzip 或不带封装的 raw DEFLATE，随后提供更多输入或空间继续，直到完成、请求字典或发生错误。无论出现哪种结果，inflateEnd 都可释放解码器。整块缓冲区的 zlib 解码见 uncompress。

任务	条目
开始或复用	初始化、配置初始化、重置、新配置、保留历史
解码或提供元数据	解压、设置字典、读取历史、gzip 头
恢复或检查	同步搜索、同步点、位置标记、表使用量
调整或分支	预置位、校验、距离选项、复制
释放存储	结束

聚焦契约遵循固定版本的 inflate.c 和 zlib.h，采用默认 LP64 Linux 构建，启用 gzip，不启用可选的无效距离或严格距离模式。范围更广的已登记公开目标保持各自定义域。术语见契约约定，证明状态和剩余工作见进度。

公共条件

调用者与解码器各自保留不同的内容。调用者提供本轮输入和输出缓冲区；解码器保留当前解析阶段、尚未用完的位，以及可能供后续复制使用的历史。更换调用者的输出数组，并不会开始一个新解码任务。

next_in 是本轮未读输入的起点，avail_in 是可读字节数；next_out 是下一个输出位置，avail_out 是从这里开始的剩余可写字节数。例如一块 5 字节输出数组返回时剩余 2 字节空间，就说明本轮写入了 3 字节。先接走这些结果，再把指针和容量设置为下一块可写区域。

下列所有契约都有受限定义域。仅凭 C 指针类型，不能提供这里要求的存储、生命周期或调用历史。

有效流已成功初始化或复制，尚未结束，保留库拥有的状态，且不发生并发调用。使用默认分配器和释放函数。初始化调用接收可写、尚未有效初始化为流的对象，分配器字段为 NULL 或默认函数。
可读或可写范围在整个调用期间都具有所述容量。调用者范围与流及流拥有的存储分离。输入与输出范围不重叠。字典目标、已登记头部记录及其目标缓冲区彼此分离，也与流分离。使用已登记头部存储的调用还要求它与输入/输出范围分离。这些是聚焦定义域的显式限制。
调用者拥有流对象及缓冲区。库拥有状态和可选窗口。调用只改变自己的流、拥有的存储、所述输出范围和任何已登记头部目标。它绝不释放调用者缓冲区。
流检查拒绝时返回 Z_STREAM_ERROR，不发生变化，除非查询或复制契约另有说明。这覆盖 NULL 和可安全读取但未通过检查的记录，不覆盖悬空或任意指针。检查要求分配器、状态、状态的回指针和有效模式满足条件。
计数器使用 C 无符号位宽并回绕。没有契约假设分配成功。解码、字典或分配错误之后，仍可调用 inflateEnd。

flowchart LR
    I["初始化"] --> F["inflate"]
    F -->|"Z_NEED_DICT"| D["设置字典"] --> F
    F -->|"更多空间或输入"| F
    F -->|"结束或放弃"| E["结束"]
    F -->|"数据错误"| R["重置或同步搜索"] --> F

形式化约定

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 }) })