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

deflateCopy

创建压缩进度相同、彼此独立的压缩器。

完整章节与共同规则 ↗
int ZEXPORT deflateCopy(z_streamp dest, z_streamp source);

创建压缩进度相同、彼此独立的压缩器。

返回值与后续调用

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

返回值说明目的流是否获得独立的压缩状态。失败时的清理涉及的是此次的新分配,源流保持不变。

deflateCopy()
返回值 含义与出现条件 调用者接下来
Z_OK
独立状态已复制
源存活,且目的流满足“另一个空记录”的前置条件;目的流获得五项新分配及等价进度,内部指针重定位,源不变。 两个流分别需要 deflateEnd;继续推进两个流之前,给它们各自独立的输出空间。复制的 I/O 指针起初相同,保留的头部仍是两个流共享、归调用者所有的存储。
Z_MEM_ERROR
分配失败并已清理
任意新分配失败;所有新块已释放,dest->state 清空,目的流的其他字段和源不变,没有新的存活目的流。 不要结束失败的目的流;处理内存不足后可按复制的前置条件重试,源仍可合法继续或结束。
Z_STREAM_ERROR
目的流为 NULL
dest 为 NULL,复制未开始。 提供不同于源且不拥有状态的可写目的记录,再按复制的前置条件调用。
Z_STREAM_ERROR
源检查未通过
目的流非 NULL,但源检查失败;dest->state 清空,不进行复制分配。 先建立存活的源;只对不同且不拥有状态的目的流调用,不能据此认为任意原有目的流状态已被释放。

调用条件与效果

定义域 受限定义域。效果: 分配并复制拥有的状态。

前置条件 source 存活。dest 是另一个可写 z_stream,不拥有状态,且与源的内存分离。源缓冲区和任何保留的头部满足生命周期要求。

证明目标。

  • 目标。 Goal.deflateCopy_safety(Safety/Copy.lean);必需。定理:Zlib.Deflate.Universal.deflate_copy_safety(public-deflate-copy.lean)。这个目标有四个子句:对 NULL dest 的拒绝;对 NULL source 的拒绝;从可达的源复制(主子句);对属于被拒绝的流的 source 的拒绝。Goal.deflate_refusal(Safety/Refusals.lean)也是必需目标,它同样陈述对被拒绝的源的拒绝。
  • 适用条件。 对 NULL dest 的拒绝没有条件。对 NULL source 的拒绝要求 dest 指向一个可读的流记录。对被拒绝的 source 的拒绝要求 dest 指向一个可读的流记录,并要求 source 不是 NULL 且是被拒绝的流(RefusedDeflate);它不要求 dest 与 source 不同。主子句要求:
    1. source 是可达流(StreamReachable)。命题还把它的不变量和默认分配器作为假设(DGood、DefAlloc);每个可达流都满足它们(Goal.deflate_sequence_safety 的第一个子句);
    2. dest 指向一个可读的流记录,且不是 source 记录(source ≠ dest)。不要求平台大小上界。
  • 无条件覆盖。 dest 记录的每一种内容;每一种分配结果。拒绝子句中:dest 记录的每一种内容,每一个被拒绝的 source,以及 dest 为 NULL 时的每一个 source 指针。如果 dest 原本是一个存活流,它的旧状态仍处于已分配状态,而记录不再指向它。
  • 保证。
    • 返回。 dest 为 NULL、source 为 NULL 或 source 被拒绝时,调用返回 Z_STREAM_ERROR。从可达的源复制时,调用返回,返回值为 Z_OK 或 Z_MEM_ERROR。只有在某次分配确实失败之后才返回 Z_MEM_ERROR(AllocationFailed)。
    • 状态。 从可达的源复制时:source 记录及其状态不变。返回 Z_OK 时,dest 满足流不变量(StreamInvariant),并且按 StreamReachable 的定义是可达流。返回 Z_MEM_ERROR 时,dest->state 为 NULL,dest 的其他字段不变。
    • 写入。 dest 为 NULL 时不写任何内容:堆不变。source 为 NULL 或被拒绝时,只写 dest->state,把它置为 NULL;dest 的其他字段和堆的其余部分不变。从可达的源复制时,只写 dest 记录和调用自己分配的块。
    • 分配。 三种拒绝都不分配也不释放任何块。从可达的源复制时:返回 Z_OK 时,新块恰好有五个:新的状态记录和它的四个缓冲区(window、prev、head、pending_buf)。不释放任何块。安全目标没有说 dest->state 指向这个记录;功能目标 Goal.deflateCopy 说了这一点。返回 Z_MEM_ERROR 时,已分配的块与调用前相同。
  • 不在本目标内。 zalloc 和 zfree 已设置、而 state 是垃圾指针、指向已释放的状态或指向 inflate 状态的 source 记录:没有目标覆盖从这种源的复制(见偏离记录)。source 可达而 dest == source:此时 C 的 zmemcpy(dest, source, sizeof(z_stream)) 把记录复制到它自身,这是未定义行为;没有目标覆盖这个调用(见偏离记录中“复制的目的流”一行)。副本的内容:功能目标 Goal.deflateCopy(不在计划内;已有定理证明它)。
完整返回条件与边界

返回与保证 Z_OK 使 dest 获得五项新拥有的分配,包含等价的压缩状态;源不变。复制的流字段包括总计数、分配器字段、输入/输出指针和保留的头部指针。内部拥有的指针被重定位到新分配。两个流各自需要 deflateEnd,可独立继续。复制得到的调用者输入/输出指针起初指向相同的缓冲区;继续推进两个流之前,应给它们各自独立的输出空间。头部仍是共享的调用者自有存储。

Z_MEM_ERROR 释放每项新分配、清空 dest->state,并保持目的流的其他字段和源不变。没有新的存活状态需要释放。

聚焦范围之外: NULL 目的流返回 Z_STREAM_ERROR;源检查失败还会清空非 NULL 目的流的状态。对可达的源,功能目标 Goal.deflateCopy 有同样的前提 source ≠ dest。

本组共同前提与范围

输入分批到达、输出空间有限,或需要选择封装、字典、刷新边界时,使用 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.deflateCopy_safety

状态:完成 · 结论的状态

/-- **Safety of `deflateCopy`** (the safety content of `Goal.deflateCopy`). Null arguments are
refused. From every reachable source (`StreamInvariant .deflate` is `DGood` with the default
allocator) into a distinct, readable destination record, the call returns without a fault, with
`Z_OK` or `Z_MEM_ERROR`. It leaves the source record and its state unchanged and writes only the
destination record and new blocks. On `Z_MEM_ERROR` an allocation really failed, the destination
state is cleared and the live blocks are unchanged (no leak). On `Z_OK` the destination satisfies
the stream invariant (`StreamInvariant .deflate`, written out) and the live blocks grow by exactly the five new blocks it owns. The copied
contents (`copiedDeflate` and the prefix clauses) are left to `Goal.deflateCopy`. The last clause is
zlib.h's refusal of an inconsistent source ("such as zalloc being Z_NULL"): a source the state check
refuses (`RefusedDeflate`: a null `zalloc` or `zfree`, no state, or a live state with a wrong back
pointer or status) is refused with `Z_STREAM_ERROR`, and the destination state is cleared. -/
def Goal.deflateCopy_safety : Prop :=
  (∀ h source, C.run (Zlib.Deflate.deflateCopy none source) h = .ok (Z_STREAM_ERROR, h)) ∧
  (∀ h dest z, dest.get h = some z →
    C.run (Zlib.Deflate.deflateCopy (some dest) none) h =
      .ok (Z_STREAM_ERROR, dest.put h { z with state := none })) ∧
  (∀ h source i z s dest oldDest,
    StreamReachable .deflate h source → Zlib.Deflate.Spec.DGood h source i z s →
    Zlib.Deflate.Spec.DefAlloc z → source ≠ dest → dest.get h = some oldDest →
    ∃ rc after,
      C.run (Zlib.Deflate.deflateCopy (some dest) (some source)) h = .ok (rc, after) ∧
      source.get after = some z ∧ after.dstates i = some s ∧ Frame h after (StreamRoot dest) ∧
      ((rc = Z_MEM_ERROR ∧ AllocationFailed h after ∧
        dest.get after = some { oldDest with state := none } ∧
        LiveChange h after (fun _ => False) (fun _ => False)) ∨
       (rc = Z_OK ∧ (∃ i' z' s', Zlib.Deflate.Spec.DGood after dest i' z' s' ∧ Zlib.Deflate.Spec.DefAlloc z') ∧
       ∃ copied,
         after.dstates h.nextBlk = some copied ∧
         (∀ b, DeflateOwned h.nextBlk copied b ↔ h.nextBlk ≤ b ∧ b < h.nextBlk + 5) ∧
         LiveChange h after (DeflateOwned h.nextBlk copied) (fun _ => False)))) ∧
  (∀ h source dest oldDest, dest.get h = some oldDest → RefusedDeflate h (some source) →
    C.run (Zlib.Deflate.deflateCopy (some dest) (some source)) h =
      .ok (Z_STREAM_ERROR, dest.put h { oldDest with state := none }))
相关定义与源码 ↗

功能契约(安全之外)

ZlibF.Spec.Public.Goal.deflateCopy

状态:完成 · 结论的状态

/-- `int deflateCopy(z_streamp dest, z_streamp source)`.
Copy the initialized window, hash entries, pending bytes and symbols. Relocate the owned
buffers and tree descriptors. A failure clears destination state and releases every new block. -/
def Goal.deflateCopy : Prop :=
  (∀ h source, C.run (Zlib.Deflate.deflateCopy none source) h = .ok (Z_STREAM_ERROR, h)) ∧
  (∀ h dest z, dest.get h = some z →
    C.run (Zlib.Deflate.deflateCopy (some dest) none) h =
      .ok (Z_STREAM_ERROR, dest.put h { z with state := none })) ∧
  (∀ h source i z s dest oldDest,
    StreamReachable .deflate h source → Zlib.Deflate.Spec.DGood h source i z s →
    Zlib.Deflate.Spec.DefAlloc z → source ≠ dest → dest.get h = some oldDest →
    ∃ rc after,
      C.run (Zlib.Deflate.deflateCopy (some dest) (some source)) h = .ok (rc, after) ∧
      source.get after = some z ∧ after.dstates i = some s ∧ Frame h after (StreamRoot dest) ∧
      ((rc = Z_MEM_ERROR ∧ AllocationFailed h after ∧
        dest.get after = some { oldDest with state := none } ∧
        LiveChange h after (fun _ => False) (fun _ => False)) ∨
       (rc = Z_OK ∧ ∃ copied,
         Zlib.Deflate.Spec.DGood after dest h.nextBlk
           { z with state := some (.deflate h.nextBlk) } copied ∧
         copied = copiedDeflate dest h.nextBlk s copied ∧
         SameBytePrefix h after s.window copied.window s.high_water.toNat ∧
         SameWordPrefix h after s.head copied.head s.hash_size.toNat ∧
         SameWordPrefix h after s.prev copied.prev
           (if s.slid ≠ 0 ∨ s.strstart - s.insert > s.w_size then s.w_size.toNat
            else (s.strstart - s.insert).toNat) ∧
         SameBytePrefix h after s.pending_out copied.pending_out s.pending.toNat ∧
         SameBytePrefix h after s.sym_buf copied.sym_buf s.sym_next.toNat ∧
         (∀ b, DeflateOwned h.nextBlk copied b ↔ h.nextBlk ≤ b ∧ b < h.nextBlk + 5) ∧
         LiveChange h after (DeflateOwned h.nextBlk copied) (fun _ => False))))
相关定义与源码 ↗
ZLIB × LEAN

目录

正在阅读deflateCopy