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

deflateInit2_

选择封装和压缩设置,启动压缩器。

完整章节与共同规则 ↗
int ZEXPORT deflateInit2_(z_streamp strm, int level, int method, int windowBits,
                           int memLevel, int strategy, const char *version, int stream_size);

选择封装和压缩设置,启动压缩器。

这些参数分别决定不同的事情。level 在压缩速度与匹配搜索工作量之间作选择;method 选择压缩方法,本条目只接受 DEFLATE;memLevel 控制内部索引和符号缓冲的内存配置;strategy 调整采用哪种匹配或编码策略。windowBits 同时编码封装和窗口大小:去掉符号或所加的常数,得到指数 b,窗口就是 2^b 字节。所以 15、-15 和 31 都表示 32768 字节,封装分别是 zlib、裸和 gzip。

返回值与后续调用

返回值类型。 int — zlib 状态码

返回值区分压缩器已建立、兼容性拒绝、参数拒绝和分配失败。只有 Z_OK 建立需要结束的存活流。

deflateInit2_()
返回值 含义与出现条件 调用者接下来
Z_OK
压缩器已建立
兼容性和参数有效,五项分配均成功;采用所选封装和设置。 可以提供缓冲区并开始压缩;最后用 deflateEnd 释放,即使放弃任务。
Z_VERSION_ERROR
兼容性拒绝
version 为 NULL、版本首字节不匹配,或 stream_size 不等于 sizeof(z_stream)。此检查先于 strm 检查,且不改变流。 修正版本和结构大小后再初始化;此结果没有建立待释放的新状态。
Z_STREAM_ERROR
流指针为 NULL
兼容性检查通过,但 strm 为 NULL。 提供符合初始化前置条件的可写流记录后再初始化。
Z_STREAM_ERROR
参数被拒绝
method、level、windowBits、memLevel 或 strategy 不在接受范围。拒绝发生于分配前,但 msg 已清空,并可能安装默认分配器、清空 opaque。 修正参数后按初始化的前置条件再调用;没有新分配需要结束。
Z_MEM_ERROR
状态分配失败
首项状态分配失败;state 保持进入时的值,没有新分配的块存活。 处理内存不足后可按初始化的前置条件重试;无需为此次失败调用 deflateEnd。
Z_MEM_ERROR
缓冲分配失败并已清理
状态分配成功后,四项缓冲分配全部尝试;任何失败都会释放所有新块,state 变为 NULL,msg 报告内存不足。 此调用已完成清理;处理内存不足后可重新初始化。

判读要点。

  • 级别 -1 选择 6。

调用条件与效果

定义域 受限定义域。效果: 分配并初始化。

前置条件 满足 deflateInit_ 的流和版本条件。参数为:level 为 -1 或 0..9;method == Z_DEFLATED;memLevel 为 1..9;strategy 为 0..4;zlib 的 windowBits 为 8..15,裸流为 -15..-9,gzip 为 25..31。

证明目标。

  • 目标。 Goal.deflateInit2__safety(Safety/Initialisation.lean);必需。定理:ZlibF.Spec.Public.InitSafetyProof.deflateInit2__safety(public-init-safety.lean)。
  • 适用条件(InitArguments):
    1. 堆是库堆(Fresh、Uniq、LibraryGlobals);
    2. version 为 NULL,或其首字节可读(VersionValue);
    3. strm 为 NULL;或者指向一个可读的流记录,其 zalloc 和 zfree 各自为 NULL 或默认函数(DefaultOrNull)。
  • 无条件覆盖。 每一个 level、method、windowBits、memLevel 和 strategy,无论是否有效;每一个 stream_size;version 首字节的每一个取值;记录中其他字段的每一个取值,包括 state;每一种分配结果。如果记录原本是一个存活流,调用仍然返回,但旧状态仍处于已分配状态,而记录不再指向它:账本如实记下这次泄漏,并不排除它。
  • 保证(InitResultSafe)。
    • 返回。 调用返回。strm 为 NULL 时,返回值是 Z_VERSION_ERROR 或 Z_STREAM_ERROR。
    • 状态。 返回 Z_OK 时,strm 是可达流。
    • 写入。 strm 为 NULL 时不写任何内容:堆不变。否则只写流记录和调用自己分配的块。
    • 分配。 返回 Z_OK 时,调用分配的每个块都是流自己的块,且不释放任何块(LiveChange)。返回其他状态码时,已分配的块与调用前相同。
  • 不在本目标内。 zalloc 或 zfree 是自定义函数的流:在所有目标之外(见偏离记录)。各种拒绝和各种分配失败分别返回哪个状态码,以及调用之后各字段的值:功能目标 Goal.deflateInit2_(不在计划内;已有定理证明它)。确实存在返回 Z_OK 的调用:Goal.deflate_initialisation_domain(Safety/Domains.lean),必需。
完整返回条件与边界

返回与保证 Z_OK 建立存活流,拥有五项分配和所选设置。zlib 窗口请求 8 变为 9。总计数为零,msg 为 NULL,data_type 为 Z_UNKNOWN,裸流/zlib 的 adler 为 1,gzip 的为 0。输入/输出指针和可用计数不变;不消费或输出字节。调用者用 deflateEnd 释放状态。

Z_MEM_ERROR 不留下任何新分配的存活块。如果状态分配失败,state 保持进入时的值。如果后续分配失败,state 变为 NULL,msg 报告内存不足。状态分配成功后,全部四项缓冲区分配都会被尝试,然后才进行失败清理。

聚焦范围之外: 版本指针为 NULL、首字节不匹配,或结构大小错误时,返回 Z_VERSION_ERROR,不改变流。版本兼容且 strm 为 NULL 时,返回 Z_STREAM_ERROR。其他超出可接受范围的标量参数在分配前返回 Z_STREAM_ERROR,此前会清空 msg,并按需安装默认分配器字段。安装默认分配器会清空 opaque。安全目标覆盖这些调用:每一个都返回,并且已分配的块保持原样。它们各自返回哪个状态码,由初始化的功能目标陈述。

本组共同前提与范围

输入分批到达、输出空间有限,或需要选择封装、字典、刷新边界时,使用 z_stream 压缩器。封装是在 DEFLATE 压缩数据之外增加的头部、尾部和完整性信息;裸 DEFLATE 则不带这些封装。初始化一次,使用连续的缓冲区调用 deflate,即使放弃压缩也要结束流。单个缓冲区的操作见 compress 和 compress2。

任务 条目
开始或复用 初始化、配置初始化、重置、保留历史的重置
提供元数据或历史 字典、读取历史、gzip 头
压缩与输出大小 压缩、上界、待输出数据、最近刷新位数
调整或分支 参数、调优、位预置、复制
释放存储 结束

这些契约遵循固定版本的 zlib 在应用各补丁之后的 zlib.h 和 deflate.c,采用默认 LP64 Linux 构建。七个补丁中只有补丁 0006 和 0007 改动 deflate.c。两者都修改 deflateBound_z,deflateBound 调用 deflateBound_z,其结果也随之改变:0006 修改一个条件,0007 修改封装大小中 gzip extra 字段的长度。两处改动见条目 deflateBound_z。这些补丁不改动其他函数。这些是聚焦契约:前置条件描述通常的正确用法,有意比函数实际接受的范围窄。前置条件之外、C 仍会处理的情况,写在“错误”或聚焦范围之外下。超出前置条件的调用并不因此就是未定义行为,也不一定返回错误码。定义域和效果标签的含义见契约约定。

已证明的内容。 只证明安全性:每次调用都返回,没有未定义行为和内存错误,只写其目标指明的内容,并且不泄漏(见安全性)。各条目在“证明目标”下给出自己的目标,所用的五项和固定用语由阅读证明目标段落定义:目标及其定理;目标适用的条件,按 Lean 命题中的顺序列出;对每一个取值都覆盖的内容;保证的内容(返回、状态、写入、分配);以及留给其他目标的内容。证明所假设的是那里列出的条件,而不是文档中的前置条件。后置条件、返回值表和各项说明描述的是功能行为:它们读自 C 源码,凡是没有定理陈述的,都尚未由证明确认;安全结论不需要它们。哪些目标已完成,见进度。

共享约定

在每条所述前置条件下,文档描述的行为是:调用终止且不产生运行时故障,并且后置条件成立。调用之后流仍然存活时,它的表示不变量保持成立。其中已被证明的部分,就是该条目的安全目标。

先看一次调用的数据交接。next_in 指向尚未读取的输入的起点,avail_in 是从这里开始可读的字节数;next_out 指向下一个可写位置,avail_out 是剩余输出容量,也以字节计。一次调用可以只消耗部分输入、只交付部分输出。调用者应读取更新后的指针和计数,接走已交付字节,再为同一个流补充输入或输出空间。

  • 存活流: 可写的 z_stream,其压缩器状态由成功初始化或复制建立,经过合法调用保持,且尚未结束。调用者不改变其内部状态或分配器字段。同一个流的调用按顺序执行。
  • 缓冲区: 输入覆盖 avail_in 个可读字节;输出覆盖 avail_out 个可写字节。它们彼此不重叠,也不与流或流拥有的状态重叠。非 NULL 标量结果指向可写单元,与其他结果及流内存分离。这些分离条件是契约的假设。安全目标也假设其中某一条时,该条目的“证明目标”会写明,偏离记录中也有对应的一行。
  • 分配器: 使用默认分配/释放函数对,或在初始化前将两个字段都置为 NULL。任意一次分配尝试都可能失败。自定义分配器回调不在本页范围内。
  • 帧性质与所有权: 调用只改变自己的流、其拥有的状态和所述输出区域。调用者输入只读。调用者缓冲区和头部记录仍归调用者所有。只有初始化和复制会分配;只有它们失败时的清理与 deflateEnd 会释放内存。其他调用保持流的分配集合。
  • 头部生命周期: 保留的 gzip 头及其可选字段在使用期间保持可读且不变。非 NULL 的 name 和 comment 以零终止;extra 覆盖所述长度。本页的契约取 extra_len <= 65535。
  • 检查后的拒绝: 除初始化和上界查询外,流检查失败会在正常操作之前返回 Z_STREAM_ERROR,不发生写入。deflateCopy 还会清空非 NULL 目的流的状态。这种拒绝不修改查询输出单元。
  • 受限定义域指这些显式内存、生命周期和调用顺序条件,加上条目自身的前置条件。它不意味着接受每个可表示的指针或整数。错误概述覆盖各项检查读得到的流记录和状态,不覆盖任意无效地址。
  • 可达流: 证明目标里说的是可达流,契约里说的是存活流(见契约约定)。目标所覆盖的调用会延长流的历史:调用返回后,无论返回哪个状态码,流仍然是可达流,下一次调用的目标随之适用。deflateEnd 结束这段历史。
  • 结果单元作为值: deflateGetDictionary、deflatePending 和 deflateUsed 通过指针报告结果(uInt *dictLength、unsigned *pending、int *bits)。翻译没有把这些单元建模为内存:各函数只接收“指针是否为 NULL”这一事实,并把结果作为值返回。因此目标不涉及结果单元的地址,也无法表达结果单元与其他对象重叠的情况。

安全目标

ZlibF.Spec.Public.Goal.deflateInit2__safety

状态:完成 · 结论的状态

/-- `int deflateInit2_(z_streamp strm, int level, int method, int windowBits, int memLevel,
int strategy, const char *version, int stream_size)`.
**Safety of `deflateInit2_`** (macro `deflateInit2`): for every level, method, window, memory
level and strategy, every `stream_size` and every allocation outcome, on `InitArguments` the
call is safe (`InitResultSafe`). -/
def Goal.deflateInit2__safety : Prop :=
  ∀ h strm version size level method wb mem strategy, InitArguments h strm version →
    ∃ rc after, C.run (Zlib.Deflate.deflateInit2_ strm level method wb mem strategy version size) h =
      .ok (rc, after) ∧ InitResultSafe .deflate h after strm rc
相关定义与源码 ↗

功能契约(安全之外)

ZlibF.Spec.Public.Goal.deflateInit2_

状态:完成 · 结论的状态

/-- `int deflateInit2_(z_streamp strm, int level, int method, int windowBits, int memLevel,
int strategy, const char *version, int stream_size)`.
Every signed argument, source-ordered refusal, five allocations, failure cleanup and success invariant. -/
def Goal.deflateInit2_ : Prop :=
  ∀ level method wb mem strategy,
    DeflateInitContract (fun p v size => Zlib.Deflate.deflateInit2_ p level method wb mem strategy v size)
      level method wb mem strategy
相关定义与源码 ↗
ZLIB × LEAN

目录

正在阅读deflateInit2_