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

inflateBack

用途。 通过输入和输出回调解码一个完整的裸流。

完整章节与共同规则 ↗
int ZEXPORT inflateBack(z_streamp strm, in_func in, void FAR *in_desc,
                        out_func out, void FAR *out_desc);

用途。 通过输入和输出回调解码一个完整的裸流。

返回值与后续调用

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

结果覆盖一个完整的裸流的回调解码。此函数不返回 Z_OK,每次调用都会从一个新流开始。

inflateBack()
返回值 含义与出现条件 调用者接下来
Z_STREAM_END
裸流及输出已完成
完整的裸 DEFLATE 流已解码,且每个输出回调均返回零。 保留 next_in/avail_in 指示的未读后缀;可解码另一个独立流,或调用 inflateBackEnd。
Z_BUF_ERROR
输入回调没有更多数据
返回时 next_in 为 NULL;输入回调返回零,输入耗尽。 当前解码未完成;可结束,或准备完整输入后从头开始新的解码,不能当作暂停续接。
Z_BUF_ERROR
输出回调失败
返回时 next_in 非 NULL;输出回调返回非零。最终输出失败会把原 Z_STREAM_END 改为此值。 处理调用者输出故障;可结束,或从头开始独立解码,不能按普通 inflate 的方式续接。
Z_DATA_ERROR
DEFLATE 格式错误
发现畸形的裸 DEFLATE 并设置 msg;此前可能已经输出数据,最终输出失败不覆盖此错误。 可调用 inflateBackEnd;再次 inflateBack 会从新流开始,须重新准备输入。
Z_STREAM_ERROR
缺少流或状态
strm 或 state 为 NULL;不调用回调。 先用 inflateBackInit_ 建立有效回调解码器;普通 inflate 状态不可用于此接口。

判读要点。

  • 输入回调返回字节数,零表示无输入。

调用条件与效果

定义域 受限定义域:存活的回调解码器、有效且分离的切片,以及有限、会返回的 回调协议。包括任意畸形输入字节。

前置条件 初始化成功且尚未结束。保持流、状态和窗口存活。 初始化 next_in;NULL 表示立即请求回调输入,并忽略 avail_in。 否则初始化 avail_in,并在 next_in 提供相应数量的可读字节。 初始输入切片和回调提供的输入切片均不与窗口、流或私有状态重叠。 两个回调均非 NULL。每次回调都安全返回,且提供的输入总量有界。

回调只能读取收到的输入/输出字节以及自身的有效对象。 可以修改、分配或释放自身内存,但须保持流、私有状态和窗口切片不变。 输入片段在下一次输入回调或函数返回前须持续可读且不变,包括跨越输出回调时。 输出回调最多读取 len 个窗口字节。 若所用字节切片不重叠,回调存储与窗口可共用一次分配。 禁止对该流进行并发或重入访问。

内存与状态效果 重置解码以处理新流,消费输入、写窗口并调用回调。 完整窗口和最终非空的部分窗口均交给 out,包括错误路径。 因此回调可能在后续格式或输入失败之前已观察到输出。 库本身不分配或释放内存;回调分配的内存仍由调用者负责。

证明目标。

  • 目标。 Goal.inflateBack_safety(Safety/Back.lean);必需。定理:ZlibF.Spec.Public.BackSafetyProof.inflateBack_safety(public-back-safety.lean)。这个目标有三个子句:对 NULL 流的拒绝,对状态为 NULL 的流记录的拒绝,以及历史上的一次调用。第一个和第三个是序列目标 Goal.inflate_back_sequence_safety 的子句 1 和子句 3。
  • 适用条件。 第一个拒绝子句没有条件。第二个要求 strm 指向一个可读的流记录。历史上的调用要求:
    1. strm 有一段回调解码器历史(BackSafeReachable);前提 BackValid 给它的记录和状态命名;
    2. next_in 为 NULL,或者覆盖 avail_in 个可读字节(Bytes)且不与窗口重叠(Separate);
    3. 回调遵守一个协议(CallbackProtocol),其不变量在调用时成立:in 和 out 各自返回,只改变回调自己的块,并且保持窗口这一段的字节不变;in 交出一个可读的、不与窗口重叠的片段;out 保持当前输入片段可读(全部子句见偏离记录)。关于两个回调的子句只在这样的堆上才被要求:流是这个窗口上的一个有效回调解码器(CallbackEntry),库交给 in 和 out 的就是这样的堆。这样的协议确实存在,并且全部六条前提在一次具体的调用上同时成立:Goal.inflateBack_call_domain(Safety/Domains.lean),必需(回调);
    4. 协议的输入总量(包括第一个片段)少于 2^48 字节(inputBound);
    5. 平台大小上界在调用时成立,并且每个回调步骤都保持它(ByteObjectsFit、BackPlatform);
    6. 每个输入片段都位于堆字节块中:第一个片段(BackFirstChunk)和 in 交出的每一个片段(BackPlatform)。
  • 无条件覆盖。 每一个输入字节序列,无论是否合法,以及把它切分成片段的每一种方式;in 返回 0;out 报告失败;in_desc 和 out_desc 的每个取值;回调分配和释放自己的内存。在第二个拒绝子句中,记录其他字段的每一个取值。
  • 保证。
    • 返回。 strm 为 NULL 时,以及流记录的 state 为 NULL 时,调用返回 Z_STREAM_ERROR。在历史上,它返回 Z_STREAM_END、Z_DATA_ERROR 或 Z_BUF_ERROR。
    • 状态。 在历史上,流在同一个窗口上保持有效的回调解码器状态,窗口大小不变(BackValid),并且协议的不变量在调用后成立。于是流又有了一段历史,下一次调用的目标适用。
    • 写入。 两种拒绝都不写任何内容:堆不变。在历史上,只写流记录、状态记录、回调自己的块和窗口所在的块;如果这个块不是回调自己的块,则只写其中窗口这一段(CallbackFrame)。存放回调输入的块(包括第一个片段)属于回调自己的块,即使回调只读它们也是如此:否则协议的不变量无法成立。对这些块,保证是状态中的不变量子句,而不是这个框架:回调保持的关于其字节的事实在调用后成立。输入与窗口共用一个块时,这个块属于回调自己的块,框架就不再把对它的写入限制在窗口这一段之内;窗口段之外的字节由不变量描述。
    • 分配。 在历史上,回调自己的块之外的每个块,调用后是否已分配都与调用前相同:库不分配也不释放任何东西。
  • 不在本目标内。 非 NULL 状态不是来自 inflateBackInit_ 的流记录,例如来自 inflateInit_ 的状态:没有目标覆盖它。什么数据到达 out,三个返回值中返回哪一个,以及调用后的 next_in 和 avail_in:功能目标 Goal.inflateBack(不在计划内;未完成)。条件 4 到 6、窗口必须在堆字节块中以及对调用者编辑的规定都比 zlib.h 窄:见偏离记录中的行。
完整返回条件与边界

返回与保证 Z_STREAM_END 表示完整的裸流已解码,且每次输出调用都成功。 拼接各片段得到其未压缩字节,不使用预置字典。 next_in/avail_in 指出初始输入片段或最后一个回调片段的未读后缀。 输入耗尽后两者为 NULL/零;否则指针按已消费字节数前移。 累计计数、adler 和 data_type 不变;next_out/avail_out 不用于输出接口。 流保留状态和窗口,可供下次独立解码或结束操作使用。

错误路径 Z_BUF_ERROR 表示输入耗尽或输出结果非零;本函数从不返回 Z_OK。 对 Z_BUF_ERROR,NULL next_in 表示输入耗尽,非 NULL 表示输出失败。 Z_DATA_ERROR 表示畸形 DEFLATE,并设置 msg。 最终输出失败会将 Z_STREAM_END 改为 Z_BUF_ERROR,但不替换此前已选定的其他错误。 NULL strm 或 NULL 状态返回 Z_STREAM_ERROR,不调用回调。 其他无效状态不在本定义域内:普通 inflateInit_ 产生的状态不是回调解码器。 解码错误后,结束操作仍释放状态;再次调用则从一个新流开始。

本组共同前提与范围

回调接口允许调用者提供输入片段,并直接从窗口接收解码输出。 先用 inflateBackInit_ 初始化,再用 inflateBack 解码, 最后用 inflateBackEnd 释放状态。窗口始终由调用者拥有。

这些聚焦契约对应固定版本的 infback.c 和 zlib.h,针对默认 LP64 Linux 构建。 定义域和效果标签见契约约定。

已证明的内容。 每个函数的必需目标是它的安全目标:没有未定义行为、没有内存错误、没有泄漏,并且终止(见安全性)。各条目在“证明目标”下写出这个目标及其前提。证明所假设的是这些前提,而不是文档中的前置条件;两者不同时,以 Lean 陈述为准。这里描述的返回值、输出字节和状态变化属于功能行为:它们读自 C 源码,凡是没有定理陈述的,都尚未由证明确认。它们不是安全结论所必需的。哪些目标已完成,见进度。

每个函数都有自己的必需安全目标:Goal.inflateBackInit__safety、Goal.inflateBack_safety 和 Goal.inflateBackEnd_safety(Safety/Back.lean)。 序列目标 Goal.inflate_back_sequence_safety(Safety/Sequences.lean) 同样是必需的。它多说一点:每段历史之后,解码器状态都是有效的;它的调用子句和结束子句,就是 inflateBack 和 inflateBackEnd 的目标所重复的子句。功能目标 Goal.inflateBackInit_、Goal.inflateBack 和 Goal.inflateBackEnd(Functional/Back.lean)不在计划内; 每个条目都说明它的功能目标有没有定理证明。

inflateBack 和 inflateBackEnd 的目标所覆盖的,是回调解码器历史(BackSafeReachable)。 历史从一次返回 Z_OK 的 inflateBackInit_ 调用开始:

  • 堆是库堆(Fresh、Uniq、LibraryGlobals),stream_size 为 112,version 的首字节是 '1'; 大小或版本字节不同的调用不会返回 Z_OK;
  • 流记录可读,其 zalloc 和 zfree 各自为 NULL 或默认函数,其他字段(包括 state)取任意值(BackInitArguments);
  • windowBits 为 8 到 15,窗口非 NULL,有 2^windowBits 个可写字节,并且是某个堆字节块的一段。

此后可以接任意多步,每步是下面两种之一。一种是一次 inflateBack 调用,它满足其目标的条件 2、3、5 和 6,并且已经返回。另一种是调用者编辑:只改 next_in、avail_in、next_out、avail_out 以及流不拥有的内存,并且保持窗口这一段的字节不变。编辑还保持每个仍然存活的块的只读标志不变,而 C 代码本来就无法改变这个标志。 比 zlib.h 窄的前提,都是偏离记录中的行。

inflateBack 解码裸 DEFLATE。任何 zlib/gzip 头部、尾部和校验和都由调用者处理。 调用者拥有一个至少 2^windowBits 字节的可写窗口,它同时也是输出缓冲区。 windowBits 是窗口字节数的二进制指数:15 表示 2^15 = 32768 字节。对一般流使用这个配置;更小窗口可能拒绝有效的长距离引用。

flowchart LR
    I["inflateBackInit_: 分配状态"] --> B["inflateBack: 解码一个流"]
    B -->|另一个流| B
    B -->|成功或解码错误| E["inflateBackEnd: 释放状态"]
    I -->|无需解码| E

回调让库在需要数据时主动调用应用代码。输入回调的参数 in_desc 是应用自己的上下文;buf 接收下一个输入片段的起始指针,返回值给出这个片段的字节数。输出回调的 out_desc 也是应用上下文;buf 和 len 给出本次可以读取的输出范围,len 以字节计。库把指针和长度交给回调,不转移窗口的所有权。

回调类型如下:

typedef unsigned (*in_func)(void FAR *, z_const unsigned char FAR * FAR *);
typedef int (*out_func)(void FAR *, unsigned char FAR *, unsigned);

in(in_desc, &buf) 返回字节数并设置 buf;零表示没有输入,此时忽略 buf。 out(out_desc, buf, len) 接收至多一个窗口的字节;零表示成功。 若回调支持 NULL,描述参数可以为 NULL。

安全目标

ZlibF.Spec.Public.Goal.inflateBack_safety

状态:完成 · 结论的状态

/-- `int inflateBack(z_streamp strm, in_func in, void FAR *in_desc, out_func out, void FAR *out_desc)`.
**Safety of `inflateBack`**: a `NULL` stream, and a stream record whose state is `NULL`, are refused
with `Z_STREAM_ERROR` and nothing changed; one more call on a history of `BackSafeReachable` returns
without a fault, keeps the state valid over the same window, and changes only its frame (clauses 1
and 3 of `Goal.inflate_back_sequence_safety`). -/
def Goal.inflateBack_safety : Prop :=
  (∀ h input inDesc output outDesc,
    C.run (Zlib.Infback.inflateBack none input inDesc output outDesc) h = .ok (Z_STREAM_ERROR, h)) ∧
  (∀ h r z input inDesc output outDesc, r.get h = some z → z.state = none →
    C.run (Zlib.Infback.inflateBack (some r) input inDesc output outDesc) h = .ok (Z_STREAM_ERROR, h)) ∧
  (∀ h r i window n z s input inDesc output outDesc
      (protocol : CallbackProtocol r i window n input inDesc output outDesc) first,
    BackSafeReachable h r i window n → BackValid h r i z s →
    (if z.next_in = .null then first = [] else Bytes h z.next_in z.avail_in.toNat first) →
    Separate z.next_in first.length window n →
    protocol.invariant h { supplied := first, chunks := [], active := z.next_in, held := first } →
    protocol.inputBound < 2 ^ 48 →
    ZlibF.PlatformMemory.ByteObjectsFit h → BackPlatform protocol → BackFirstChunk z first →
    ∃ rc after z' s' log,
      C.run (Zlib.Infback.inflateBack (some r) input inDesc output outDesc) h = .ok (rc, after) ∧
      BackValid after r i z' s' ∧ s'.window = window ∧ s'.wsize = s.wsize ∧
      protocol.invariant after log ∧
      (rc = Z_STREAM_END ∨ rc = Z_DATA_ERROR ∨ rc = Z_BUF_ERROR) ∧
      CallbackFrame protocol.own h after r i window n ∧
      (∀ b, ¬ protocol.own b → (after.live b ↔ h.live b)))
相关定义与源码 ↗

功能契约(安全之外)

ZlibF.Spec.Public.Goal.inflateBack

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

/-- `int inflateBack(z_streamp strm, in_func in, void *in_desc, out_func out, void *out_desc)`.
For every finite, returning caller protocol, decode raw DEFLATE and deliver the chunks through
that actual output callback. The protocol's observation relation records the bytes delivered.
No allocation or free by the library is charged to the caller's callbacks. -/
def Goal.inflateBack : Prop :=
  (∀ h input inDesc output outDesc,
    C.run (Zlib.Infback.inflateBack none input inDesc output outDesc) h = .ok (Z_STREAM_ERROR, h)) ∧
  (∀ h r i z s input inDesc output outDesc
      (protocol : CallbackProtocol r i s.window s.wsize.toNat input inDesc output outDesc) first,
    BackValid h r i z s →
    (if z.next_in = .null then first = [] else Bytes h z.next_in z.avail_in.toNat first) →
    Separate z.next_in first.length s.window s.wsize.toNat →
    protocol.invariant h { supplied := first, chunks := [], active := z.next_in, held := first } →
    ∃ rc after z' s' log unused consumed,
      C.run (Zlib.Infback.inflateBack (some r) input inDesc output outDesc) h = .ok (rc, after) ∧
      BackValid after r i z' s' ∧ s'.window = s.window ∧ s'.wsize = s.wsize ∧
      protocol.invariant after log ∧
      (rc = Z_STREAM_END ∨ rc = Z_DATA_ERROR ∨ rc = Z_BUF_ERROR) ∧
      consumed ++ unused = log.supplied ∧ unused.length = z'.avail_in.toNat ∧
      unused <:+ log.held ∧
      (log.exhausted = true → z'.next_in = .null ∧ unused = []) ∧
      (log.exhausted = false → z'.next_in = advance log.active (log.held.length - unused.length)) ∧
      (∀ chunk, chunk ∈ log.chunks → chunk ≠ [] ∧ chunk.length ≤ s.wsize.toNat) ∧
      (rc = Z_STREAM_END → Deflate.Decodes [] consumed log.chunks.flatten ∧ log.failed = false) ∧
      (rc = Z_BUF_ERROR → log.exhausted = true ∨ log.failed = true) ∧
      z'.total_in = z.total_in ∧ z'.total_out = z.total_out ∧ z'.adler = z.adler ∧
      CallbackFrame protocol.own h after r i s.window s.wsize.toNat ∧
      (∀ b, ¬ protocol.own b → (after.live b ↔ h.live b)))
相关定义与源码 ↗
ZLIB × LEAN

目录

正在阅读inflateBack