inflateInit2_
创建采用所选封装和窗口的解码器。
完整章节与共同规则 ↗int ZEXPORT inflateInit2_(z_streamp strm, int windowBits, const char *version, int stream_size);
创建采用所选封装和窗口的解码器。
窗口保存近期已经解出的字节,长度/距离引用从中取回旧内容。下表中的“窗口位数”是一个指数 b,表示最多 2^b 字节:15 表示 32768 字节。windowBits 还通过符号或加上的常数来选择裸流、zlib、gzip 或自动检测,所以这个参数不是字节数。请求 0、16 和 32 把大小交给头部或默认值决定,各自的含义见表。
返回值与后续调用
返回值类型。 int — zlib 状态码
结果说明是否已建立带指定格式的新解码器。仅成功初始化才需要后续结束操作。
inflateInit2_()| 返回值 | 含义与出现条件 | 调用者接下来 |
|---|---|---|
Z_OK解码器已建立 |
版本及流大小匹配,状态分配成功且 windowBits 被接受。 | 提供输入和输出范围后调用 inflate;完成或放弃时调用 inflateEnd。 |
Z_VERSION_ERROR版本或结构大小不匹配 |
version 为 NULL、首字节不匹配或 stream_size 错误;在检查 strm 前返回,内容不变。 | 修正版本和结构大小后重新初始化;本次失败无需 inflateEnd。 |
Z_STREAM_ERROR流或窗口请求被拒绝 |
版本检查通过后 strm 为 NULL;或成功分配状态后发现 windowBits 无效,释放该状态并将 state 置为 NULL。 | 提供可写的、不是存活流的流和可接受的 windowBits 后重新初始化;本次失败无需结束。 |
Z_MEM_ERROR状态分配失败 |
状态分配失败,保留旧 state 字段;msg 已清空,所需默认分配器字段可能已设置。 | 在资源可用时可重新初始化;本次失败未保留新分配,无需 inflateEnd。 |
调用条件与效果
定义域 受限定义域:新的可写流存储、默认分配器,以及 NULL 或可读版本指针;覆盖所有有符号标量参数。
内存与状态效果 分配状态。
前置条件 流不是存活流。分配器字段遵循公共约定。只要求版本首字节可读;不检查整个字符串。
证明目标。
- 目标。
Goal.inflateInit2__safety(Safety/Initialisation.lean);必需。定理:ZlibF.Spec.Public.InitSafetyProof.inflateInit2__safety(public-init-safety.lean)。 - 适用条件(
InitArguments):- 堆是库堆(
Fresh、Uniq、LibraryGlobals); version为 NULL,或其首字节可读(VersionValue);strm为 NULL;或者指向一个可读的流记录,其zalloc和zfree各自为 NULL 或默认函数(DefaultOrNull)。
- 堆是库堆(
- 无条件覆盖。 每一个
windowBits;每一个stream_size;version首字节的每一个取值;记录中其他字段的每一个取值,包括state;每一种分配结果。本目标比前置条件宽:它还覆盖strm为 NULL、版本或stream_size不对,以及state不为 NULL 的记录。如果该记录原本是一个存活流,调用仍然返回,但旧状态仍处于已分配状态,而记录不再指向它:账本如实记下这次泄漏,并不排除它。 - 保证(
InitResultSafe)。- 返回。 调用返回。
strm为 NULL 时,返回值是Z_VERSION_ERROR或Z_STREAM_ERROR。 - 状态。 返回
Z_OK时,strm是可达流。 - 写入。
strm为 NULL 时不写任何内容:堆不变。否则只写流记录和调用自己分配的块。 - 分配。 返回
Z_OK时,调用分配的每个块都是流自己的块,且不释放任何块(LiveChange)。返回其他状态码时,已分配的块与调用前相同。
- 返回。 调用返回。
- 不在本目标内。
zalloc或zfree是自定义函数的流:在所有目标之外(见偏离记录)。各种拒绝和各种分配失败分别返回哪个状态码,以及调用之后各字段的值:功能目标Goal.inflateInit2_(不在计划内;已有定理证明它)。确实存在返回Z_OK的调用:Goal.inflate_initialisation_domain(Safety/Domains.lean),必需。
完整返回条件与边界
返回与保证 返回 Z_OK 时,流是存活流,总计数为零,消息为 NULL,data_type 为零,没有窗口、历史、缓冲位或头部挂接。zlib/自动检测封装的 adler 初始为 1,仅 gzip 的为 0;裸流保持它不变。缓冲区指针和可用计数不变。
可接受的 windowBits 值为:
| 值 | 解码器请求 |
|---|---|
| -15 至 -8 | 裸 DEFLATE,窗口位数等于其绝对值 |
| 0;8 至 15 | zlib;0 由头部选择大小,否则以该值为最大值 |
| 16;24 至 31 | 仅 gzip;16 使用默认大小,否则为该值减 16 |
| 32;40 至 47 | zlib/gzip 检测;32 使用头部/默认大小,否则为该值减 32 |
错误路径 版本为 NULL/首字节错误,或 stream_size 错误时,在检查 strm 前返回 Z_VERSION_ERROR,不发生变化。否则,NULL strm 返回 Z_STREAM_ERROR。窗口参数检查前先尝试分配状态。分配失败返回 Z_MEM_ERROR,保留旧 state 字段,清空消息,并按需安装默认回调。分配成功后发现无效窗口参数,则返回 Z_STREAM_ERROR,释放该状态,将 state 置为 NULL。任何失败初始化都不保留新分配。只有成功初始化才需要后续 inflateEnd;其窗口可能由后续调用分配。
本组共同前提与范围
使用 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.inflateInit2__safety
状态:完成 · 结论的状态
/-- `int inflateInit2_(z_streamp strm, int windowBits, const char *version, int stream_size)`.
**Safety of `inflateInit2_`** (macro `inflateInit2`): for every `windowBits`, every
`stream_size` and every allocation outcome, on `InitArguments` the call is safe
(`InitResultSafe`). -/
def Goal.inflateInit2__safety : Prop :=
∀ h strm version size wb, InitArguments h strm version →
∃ rc after, C.run (Zlib.Inflate.inflateInit2_ strm wb version size) h = .ok (rc, after) ∧
InitResultSafe .inflate h after strm rc相关定义与源码 ↗功能契约(安全之外)
ZlibF.Spec.Public.Goal.inflateInit2_
状态:完成 · 结论的状态
/-- `int inflateInit2_(z_streamp strm, int windowBits, const char *version, int stream_size)`.
All signed window arguments and every allocation oracle are included, in source error order. -/
def Goal.inflateInit2_ : Prop :=
∀ wb, InflateInitContract (fun p v size => Zlib.Inflate.inflateInit2_ p wb v size) wb相关定义与源码 ↗