跳到正文
参考文档 / ZLIB × LEAN

uncompress2_z

解码第一个 zlib 流,并报告输出大小和输入消费量。

完整章节与共同规则 ↗
int ZEXPORT uncompress2_z(Bytef *dest, z_size_t *destLen, const Bytef *source, z_size_t *sourceLen);

解码第一个 zlib 流,并报告输出大小和输入消费量。

返回值与后续调用

返回值类型。 int — zlib 状态码;计数由长度参数报告

状态码说明第一个 zlib 流是否完整解码。长度值报告输出及输入消费量。

uncompress2_z()
返回值 含义与出现条件 调用者接下来
Z_OK
完整解码完成
第一个 zlib 流已完整解码且校验通过;*destLen 报告已写字节数,*sourceLen 报告已消费字节数。尾随输入未使用。 使用恰好 *destLen 字节的输出。可根据 *sourceLen 定位未使用的输入。
Z_BUF_ERROR
输出已满且仍有输入
输出填满容量且仍有输入;*destLen 报告已写字节数,*sourceLen 报告已消费字节数。已写输出保持可用。 若从原始输入完整重试,先把 *destLen 重新设为目的缓冲区容量,并把 *sourceLen 重新设为原始输入的完整长度。若需完整结果,扩大目的缓冲区容量并从原始输入重新调用;该工具不返回可续用的流。
Z_DATA_ERROR
数据、输入完整性或字典错误
输入畸形或不完整,或需要预置字典;裸流、gzip 输入也在错误范围内。成功初始化后的空输入亦为数据错误。解码器在无剩余输入时返回的 Z_BUF_ERROR 也映射为此码。 不要把部分输出视为已校验的完整结果;检查格式、输入完整性及字典需求,改用合适的调用。
Z_MEM_ERROR
初始化分配失败
初始化失败;现有长度值均不变,未写入输出。 若从原始输入完整重试,先把 *destLen 重新设为目的缓冲区容量,并把 *sourceLen 重新设为原始输入的完整长度。资源允许时可从原输入重新发起完整调用,并重新提供容量。
Z_MEM_ERROR
解码期间分配失败
成功初始化后分配失败,可能已有部分输出;*destLen 报告已写字节数,*sourceLen 报告已消费字节数。 若从原始输入完整重试,先把 *destLen 重新设为目的缓冲区容量,并把 *sourceLen 重新设为原始输入的完整长度。保留需要的已写字节;它们不是已完整校验的结果。新调用须从原输入开始并重新设置容量。
Z_STREAM_ERROR
初始化前参数拒绝
非空输入的 NULL source,或正容量的 NULL dest,或 NULL destLen 或 NULL sourceLen,会在初始化前被拒绝;现有长度值均不变。 修正已拒绝的参数,再重新调用。

调用条件与效果

定义域 受限定义域。

前置条件 上述受限缓冲区定义域。*sourceLen 是可用输入量,*destLen 是输出容量。 任一长度指针都可在经检查的拒绝情形中为 NULL。 数据指针仅可在对应长度为零,或经检查的拒绝情形中为 NULL。 畸形、截断、裸流、gzip 和依赖字典的输入也在定义域内,属于错误情形。

内存与状态效果 有状态;适用通用效果。参数检查先于初始化:NULL sourceLen、 非空输入的 NULL 源、NULL destLen,或正容量的 NULL 目的缓冲区,返回 Z_STREAM_ERROR, 并保持两个已有长度单元不变。初始化失败也保持两个长度不变,且不写输出。 初始化后,每次返回都会在 *sourceLen 存储已消费字节数,在 *destLen 存储已产生 字节数,包括后续内存失败。此前写入的输出仍可用。

证明目标。

  • 目标。 Goal.uncompress2_z_safe(Safety/Utilities.lean;其命题是 Common/Utilities.lean 中的 UncompressCountedSafe);必需。定理:ZlibF.Spec.Public.Proofs.Uncompress.uncompress2_z_safe(public-uncompress-safe.lean)。
  • 适用条件(UncompressCountedSafe):
    1. 堆是库堆(Fresh、Uniq、LibraryGlobals);
    2. 平台大小上界成立(ByteObjectsFit);
    3. 非 NULL 的 destLen 指向一个可读可写的 8 字节单元,非 NULL 的 sourceLen 也是如此(LengthCell);
    4. 非 NULL 的 source 指向 *sourceLen 个可读字节;
    5. 非 NULL 的 dest 指向 *destLen 个可写字节;
    6. dest 范围、source 范围和两个长度单元两两不重叠(UtilitySeparation)。
  • 无条件覆盖。 destLen 或 sourceLen 为 NULL(调用会拒绝);源字节的每一种内容:有效的 zlib 流、被截断或畸形的流、裸流或 gzip 数据;每一种分配结果。内存条件与前置条件相同。
  • 保证。
    • 返回。 调用返回。如果 sourceLen 或 destLen 为 NULL、source 为 NULL 而 *sourceLen 非零,或 dest 为 NULL 而 *destLen 非零,返回值是 Z_STREAM_ERROR。否则返回值是 Z_OK、Z_BUF_ERROR、Z_DATA_ERROR 或 Z_MEM_ERROR,并且只有在某次分配确实失败之后才返回 Z_MEM_ERROR(AllocationFailed)。
    • 状态。 不保留任何状态:调用结束后,它用过的流、状态和窗口都不存在。
    • 写入。 因上述参数返回 Z_STREAM_ERROR 时,不写任何内容。其他情况下只写:dest 处的字节,至多为进入时给出的 *destLen 个;*sourceLen,写入一个不超过其进入值的计数;以及 *destLen,写入已写出的字节数。返回 Z_MEM_ERROR 时,也可能一个字节都没写,两个单元都保持进入时的值。其他对象都不变(Store、SameObjectsUpToTableShape)。
    • 分配。 调用分配的每个块都在返回之前释放,每条路径都是如此:已分配的块与调用前相同。
  • 不在本目标内。 长度单元与缓冲区或另一个长度单元重叠,以及 source 与 dest 重叠:在所有目标之外(见偏离记录中“计数解压”一行)。哪种输入返回哪个状态码,以及写出的字节:功能目标 Goal.uncompress2_z(不在计划内;未完成)。
完整返回条件与边界

返回与保证 Z_OK 表示完整且通过检查的 zlib 流被解码到输出。 尾随输入未使用。Z_BUF_ERROR 表示输出已填满容量,且仍有输入。 Z_DATA_ERROR 包括畸形或不完整输入,以及需要预置字典的情形。 Z_MEM_ERROR 表示分配失败,且可能发生在部分输出之后。

边界情况 NULL 目的缓冲区配合零容量时,使用私有输出指针,因而可以接受; 完整空流可以成功。空输入在成功初始化后是数据错误。 最终精确映射为:Z_STREAM_END 到 Z_OK,Z_NEED_DICT 到 Z_DATA_ERROR, 无剩余输入时 Z_BUF_ERROR 到 Z_DATA_ERROR。其他解码器返回码保留。

本组共同前提与范围

调用时若已知完整的输入和输出容量,可使用缓冲区工具。它们在内部管理临时流。 需要增量 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.uncompress2_z_safe

状态:完成 · 结论的状态

/-- Safety of `int uncompress2_z(Bytef *dest, z_size_t *destLen, const Bytef *source, z_size_t *sourceLen)`. -/
def Goal.uncompress2_z_safe : Prop := UncompressCountedSafe Zlib.Uncompr.uncompress2_z true
相关定义与源码 ↗

功能契约(安全之外)

ZlibF.Spec.Public.Goal.uncompress2_z

状态:未完成,不在计划内 · 结论的状态

/-- `int uncompress2_z(Bytef *dest, z_size_t *destLen, const Bytef *source, z_size_t *sourceLen)`.
Includes both nullable scalar checks, trailing input, partial output on memory failure and cleanup. -/
def Goal.uncompress2_z : Prop := UncompressCounted Zlib.Uncompr.uncompress2_z true
相关定义与源码 ↗
ZLIB × LEAN

目录

正在阅读uncompress2_z