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

inflateBackEnd

用途。 释放回调初始化所分配的状态。

完整章节与共同规则 ↗
int ZEXPORT inflateBackEnd(z_streamp strm);

用途。 释放回调初始化所分配的状态。

返回值与后续调用

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

结果说明内部回调状态是否已释放;调用者窗口始终由调用者管理。

inflateBackEnd()
返回值 含义与出现条件 调用者接下来
Z_OK
内部状态已释放
有效回调解码器的内部状态已释放,state 置为 NULL;窗口及其他字段不变。 现在可释放或复用调用者窗口;再次解码前重新初始化。
Z_STREAM_ERROR
未执行释放
strm、state 或 zfree 为 NULL;不释放任何内存。 确认生命周期及匹配的释放函数;不能由这些检查推断任意非 NULL 状态有效。

调用条件与效果

定义域 受限定义域:使用有效默认释放函数的存活回调解码器,另包括经检查的 NULL 流、NULL 状态和 NULL 释放函数拒绝情形。

前置条件 清理时初始化已成功、尚未结束,且没有解码或回调正在活动。 流和所关联状态仍有效;保留匹配的 zfree 和 opaque。 成功解码或任何解码错误后均允许清理。

内存与状态效果 恰好释放内部状态,并清除 state。

证明目标。

  • 目标。 Goal.inflateBackEnd_safety(Safety/Back.lean);必需。定理:ZlibF.Spec.Public.BackSafetyProof.inflateBackEnd_safety(public-back-safety.lean)。这个目标有三个子句:对 NULL 流的拒绝,对 state 或 zfree 为 NULL 的流记录的拒绝,以及历史的结束。第三个是序列目标 Goal.inflate_back_sequence_safety 的子句 4。
  • 适用条件。 第一个拒绝子句没有条件。第二个要求 strm 指向一个可读的流记录。历史的结束要求:
    1. strm 有一段回调解码器历史(BackSafeReachable)。
  • 无条件覆盖。 每一段历史:刚初始化之后,以及一次返回 Z_STREAM_END、Z_DATA_ERROR 或 Z_BUF_ERROR 的解码之后。结束子句没有平台前提。在第二个拒绝子句中,记录其他字段的每一个取值。
  • 保证。
    • 返回。 strm 为 NULL 时,以及流记录的 state 或 zfree 为 NULL 时,调用返回 Z_STREAM_ERROR。在历史上,它返回 Z_OK。
    • 状态。 在历史上,调用之后流记录的 state 字段为 NULL。历史到此结束。
    • 写入。 两种拒绝都不写任何内容:堆不变。在历史上,只写流记录和状态块(Frame)。
    • 分配。 在历史上,恰好释放状态块,并且不分配任何块(LiveChange)。
  • 不在本目标内。 非 NULL 状态不是来自 inflateBackInit_ 的流记录:没有目标覆盖它。调用之后其他字段的值:功能目标 Goal.inflateBackEnd(不在计划内;已有定理证明它)。
完整返回条件与边界

返回与保证 Z_OK 使 state 为 NULL。调用者的窗口及其他所有流字段不变。 调用者此时可释放或复用窗口;库从不释放它。

错误路径 NULL strm、NULL 状态或 NULL zfree 返回 Z_STREAM_ERROR,不释放任何内存。 这些检查不会验证任意非 NULL 状态,也不会检测所有权错误。

本组共同前提与范围

回调接口允许调用者提供输入片段,并直接从窗口接收解码输出。 先用 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.inflateBackEnd_safety

状态:完成 · 结论的状态

/-- `int inflateBackEnd(z_streamp strm)`.
**Safety of `inflateBackEnd`**: a `NULL` stream, and a stream record whose state or `zfree` is
`NULL`, are refused with `Z_STREAM_ERROR` and nothing changed (clauses 1 and 2 of
`Goal.inflateBackEnd`); on a history of `BackSafeReachable` it returns `Z_OK`, clears the state
field, and frees exactly the state block (clause 4 of `Goal.inflate_back_sequence_safety`). -/
def Goal.inflateBackEnd_safety : Prop :=
  (∀ h, C.run (Zlib.Infback.inflateBackEnd none) h = .ok (Z_STREAM_ERROR, h)) ∧
  (∀ h r z, r.get h = some z → z.state = none ∨ z.zfree = .null →
    C.run (Zlib.Infback.inflateBackEnd (some r)) h = .ok (Z_STREAM_ERROR, h)) ∧
  ∀ h r i window n, BackSafeReachable h r i window n →
    ∃ after z, C.run (Zlib.Infback.inflateBackEnd (some r)) h = .ok (Z_OK, after) ∧
      r.get after = some z ∧ z.state = none ∧
      Frame h after (fun b => StreamRoot r b ∨ b = i) ∧
      LiveChange h after (fun _ => False) (fun b => b = i)
相关定义与源码 ↗

功能契约(安全之外)

ZlibF.Spec.Public.Goal.inflateBackEnd

状态:完成 · 结论的状态

/-- `int inflateBackEnd(z_streamp strm)`.
Free only the state record. The caller's window is retained, even when it is a slice of another object. -/
def Goal.inflateBackEnd : Prop :=
  (∀ h, C.run (Zlib.Infback.inflateBackEnd none) h = .ok (Z_STREAM_ERROR, h)) ∧
  (∀ h r z, r.get h = some z → z.state = none ∨ z.zfree = .null →
    C.run (Zlib.Infback.inflateBackEnd (some r)) h = .ok (Z_STREAM_ERROR, h)) ∧
  (∀ h r i z s, BackValid h r i z s →
    ∃ after, C.run (Zlib.Infback.inflateBackEnd (some r)) h = .ok (Z_OK, after) ∧
      r.get after = some { z with state := none } ∧
      LiveChange h after (fun _ => False) (fun b => b = i) ∧
      Frame h after (fun b => StreamRoot r b ∨ b = i) ∧
      after.nalloc = h.nalloc ∧ after.nextBlk = h.nextBlk)
相关定义与源码 ↗
ZLIB × LEAN

目录

正在阅读inflateBackEnd