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

uncompress

不报告已消费输入计数的 uLong 解码条目。

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

不报告已消费输入计数的 uLong 解码条目。

返回值与后续调用

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

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

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

调用条件与效果

定义域 受限定义域。

前置条件 uncompress2 的受限缓冲区定义域,且 destLen 非 NULL。

内存与状态效果 有状态;输出长度的写入、部分输出的保留和完整清理均与 uncompress2 相同。

证明目标。

  • 目标。 Goal.uncompress_safe(Safety/Utilities.lean;其命题是 Common/Utilities.lean 中的 UncompressSingleSafe);必需。定理:ZlibF.Spec.Public.Proofs.Uncompress.uncompress_safe(public-uncompress-safe.lean)。
  • 适用条件(UncompressSingleSafe):
    1. 堆是库堆(Fresh、Uniq、LibraryGlobals);
    2. 平台大小上界成立(ByteObjectsFit);
    3. 非 NULL 的 destLen 指向一个可读可写的 8 字节单元(LengthCell);
    4. destLen 不为 NULL;
    5. 非 NULL 的 source 指向 sourceLen 个可读字节;
    6. 非 NULL 的 dest 指向 *destLen 个可写字节;
    7. dest 范围、source 范围和长度单元两两不重叠(Separate)。
  • 无条件覆盖。 源字节的每一种内容:有效的 zlib 流、被截断或畸形的流、裸流或 gzip 数据;每一种分配结果。内存条件与前置条件相同。
  • 保证。
    • 返回。 调用返回。如果 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 个;以及 *destLen,写入已写出的字节数。返回 Z_MEM_ERROR 时,也可能一个字节都没写,该单元保持进入时的值。其他对象都不变(Store、SameObjectsUpToTableShape)。
    • 分配。 调用分配的每个块都在返回之前释放,每条路径都是如此:已分配的块与调用前相同。
  • 不在本目标内。 长度单元与缓冲区重叠,以及 source 与 dest 重叠:在所有目标之外(见偏离记录中“计数解压”一行)。哪种输入返回哪个状态码,以及写出的字节:功能目标 Goal.uncompress(不在计划内;未完成)。
完整返回条件与边界

返回与保证 输出和返回码与 uncompress2 相同;忽略尾随输入。

本组共同前提与范围

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

状态:完成 · 结论的状态

/-- Safety of `int uncompress(Bytef *dest, uLongf *destLen, const Bytef *source, uLong sourceLen)`. -/
def Goal.uncompress_safe : Prop := UncompressSingleSafe Zlib.Uncompr.uncompress false
相关定义与源码 ↗

功能契约(安全之外)

ZlibF.Spec.Public.Goal.uncompress

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

/-- `int uncompress(Bytef *dest, uLongf *destLen, const Bytef *source, uLong sourceLen)`.
The output-length cell must be readable before the wrapper calls `_z`. -/
def Goal.uncompress : Prop := UncompressSingle Zlib.Uncompr.uncompress false
相关定义与源码 ↗
ZLIB × LEAN

目录

正在阅读uncompress