compress
默认级别的 uLong 压缩条目。
完整章节与共同规则 ↗int ZEXPORT compress(Bytef *dest, uLongf *destLen, const Bytef *source, uLong sourceLen);
默认级别的 uLong 压缩条目。
返回值与后续调用
返回值类型。 int — zlib 状态码;输出长度另行写回
状态码说明整个缓冲区是否已压成完整 zlib 流。字节数在 *destLen 中。
compress()| 返回值 | 含义与出现条件 | 调用者接下来 |
|---|---|---|
Z_OK完整压缩完成 |
输出是完整的 zlib 编码;*destLen 是写入字节数。 |
使用恰好 *destLen 字节作为压缩结果。 |
Z_BUF_ERROR输出容量耗尽 |
容量由编码前缀填满;非 NULL 目的缓冲区配合零容量在成功初始化后也返回此码。*destLen 报告已写字节数。 |
若从原始输入完整重试,先把 *destLen 重新设为目的缓冲区容量。提供更大的目的缓冲区,从原始输入重新调用;这个前缀不是完整的流。 |
Z_MEM_ERROR分配失败且无输出 |
通过早期参数检查后,初始化分配失败。没有写入输出;*destLen 为零。 |
若从原始输入完整重试,先把 *destLen 重新设为目的缓冲区容量。仅在资源允许时重新发起完整调用;本次没有压缩结果。 |
Z_STREAM_ERROR早期参数拒绝 |
source 为 NULL 且 sourceLen > 0,或 dest 为 NULL 且原始容量 > 0。现有长度值不变。 | 修正已拒绝的参数,再用有效缓冲区重新调用。 |
Z_STREAM_ERROR零容量 NULL 目的缓冲区 |
通过早期参数检查,dest == NULL 且容量为零,初始化成功;*destLen 为零。分配失败时则返回 Z_MEM_ERROR。 |
提供有效的目的缓冲区和足够容量,再重新调用。 |
调用条件与效果
定义域 受限定义域。
前置条件 compress2 的受限定义域;destLen 必须非 NULL。
内存与状态效果 有状态;长度写入和完整清理与 compress2 相同。
证明目标。
- 目标。
Goal.compress_safety(Safety/Utilities.lean;其命题是 Common/Utilities.lean 中的CompressorSafety);必需。定理:ZlibF.Spec.Public.Proofs.Compress.compress_safety(public-compress-safe-mid.lean)。 - 适用条件(
CompressorSafety):- 堆是库堆(
Fresh、Uniq、LibraryGlobals); - 平台大小上界成立(
ByteObjectsFit); destLen不为 NULL;- 参数或者属于调用会拒绝的情况(
source为 NULL 而sourceLen非零,或dest为 NULL 而*destLen非零;compressRejected),或者满足:source指向sourceLen个可读字节,dest指向*destLen个可写字节,且两个范围不重叠(CompressArguments)。NULL 的source或dest视为零字节的范围。
- 堆是库堆(
- 无条件覆盖。 源字节的每一种内容;每一种分配结果。在翻译中,长度单元
*destLen是一个值而不是内存(见通用约定):对于与缓冲区重叠的长度单元,本目标什么也没说,前置条件也排除了这种情况。 - 保证。
- 返回。 调用返回。参数属于被拒绝的情况时,返回值是
Z_STREAM_ERROR。只有在某次分配确实失败之后才返回Z_MEM_ERROR(AllocationFailed)。 - 状态。 不保留任何状态:调用结束后,它用过的流、状态和缓冲区都不存在。
- 写入。 只写
dest处的字节,至多为进入时给出的*destLen个;参数被拒绝时不写任何内容,长度值也不变。其他对象都不变(Store、SameObjectsUpToTableShape)。 - 分配。 调用分配的每个块都在返回之前释放,每条路径都是如此:已分配的块与调用前相同。
- 返回。 调用返回。参数属于被拒绝的情况时,返回值是
- 不在本目标内。
source与dest重叠:在所有目标之外(见偏离记录中“整缓冲区压缩”一行)。参数被接受时返回哪个状态码、写出哪些字节、存入的长度:功能目标Goal.compress(不在计划内;未完成)。
完整返回条件与边界
返回与保证 与级别 -1 的 compress2 相同。
本组共同前提与范围
调用时若已知完整的输入和输出容量,可使用缓冲区工具。它们在内部管理临时流。 需要增量 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.compress_safety
状态:完成 · 结论的状态
/-- Safety of `compress` (`CompressorSafety`). -/
def Goal.compress_safety : Prop :=
CompressorSafety (fun d c s n => do
let (rc, size) ← Zlib.Compress.compress d c s n
pure (rc, some size)) false相关定义与源码 ↗功能契约(安全之外)
ZlibF.Spec.Public.Goal.compress
状态:未完成,不在计划内 · 结论的状态
/-- `int compress(Bytef *dest, uLongf *destLen, const Bytef *source, uLong sourceLen)`.
The nonnull-length wrapper contract at the default compression level. -/
def Goal.compress : Prop :=
CompressorContract (fun d c s n => do
let (rc, size) ← Zlib.Compress.compress d c s n
pure (rc, some size)) Z_DEFAULT_COMPRESSION false相关定义与源码 ↗