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

gzdopen

包装已有描述符,不打开或复制它。

完整章节与共同规则 ↗

包装已有描述符,不打开或复制它。

gzFile ZEXPORT gzdopen(int fd, const char *mode);

返回值与后续调用

返回值类型。 gzFile — 拥有资源的句柄或失败标记

返回值说明现有描述符是否已转交给新句柄。此操作不复制描述符。

gzdopen()
返回值 含义与出现条件 调用者接下来
file != NULL
描述符已转交
fd 非负,句柄/诊断路径分配与模式解析成功。新的逻辑位置为零,即使描述符位置不为零。 让句柄独占 fd,直至关闭时关闭 fd。若原描述符须保持打开,应传入副本。
NULL
描述符仍归调用者
fd 为负、mode 为 NULL 或无效,或分配失败。 没有可关闭的句柄。传入的描述符仍归调用者管理。

调用条件与效果

定义域 受限定义域:描述符使用;包括负描述符的拒绝。

效果: 有状态所有权转移,并可能修改描述符标志。

前置条件 普通成功情形中,fd 已打开,且访问权限与模式匹配。 非 NULL 的 mode 满足 gzopen 的字符串要求。 句柄拥有该描述符期间,其他使用者不对它读、写、定位或关闭。

证明目标。

  • 目标。 Goal.gzdopen_safety(Safety/GzCalls.lean);必需。定理:ZlibF.Spec.Public.GzCallSafetyProof.gzdopen_safety(public-gz-call-safety.lean)。它的命题是 GzDopenSafe(Safety/GzSafety.lean),即序列目标中针对这个函数的打开子句。
  • 适用条件(GzDopenSafe):
    1. 堆是库堆(Fresh、Uniq、LibraryGlobals);
    2. 平台大小上界成立(ByteObjectsFit);
    3. 世界是良构的文件系统(FileSystem);
    4. mode 为 NULL,或是以 NUL 结尾的字符串(CString)。
  • 无条件覆盖。 fd 的每个取值:无论是否打开,无论是否为负;mode 为 NULL;每一种模式文本,无论是否合法;每个文件系统世界;每一种分配结果。
  • 保证。
    • 返回。 调用返回,结果是 NULL 或一个句柄。
    • 状态。 世界良构,打开的描述符集合不变(FdsKept):调用不打开也不关闭任何描述符。返回的句柄满足其不变量(GzInv),它的描述符是 fd。
    • 写入。 调用前已有的块都不改变(Frame)。
    • 分配。 返回 NULL 时,已分配的块与调用前相同:失败的打开不留下任何东西。返回句柄时,新块恰好是句柄自己的块,并且不释放任何块(LiveChange)。
  • 不在本目标内。 mode 在其所在对象之内没有以 NUL 结尾:在本目标之外,与 C 中一样。哪些调用返回句柄,以及该句柄的模式、位置和缓冲区:功能目标 Goal.gzdopen(不在计划内;已有定理证明它)。
完整返回条件与边界

返回与保证 成功时创建与 gzopen 相同的新状态,错误名称形式为 <fd:N>。 即使 fd 本身不在零位置,未压缩位置也从零开始。关闭会关闭 fd。 若原描述符必须保持打开,应传入复制得到的描述符。

错误与边缘情形: 负 fd、无效/NULL 模式或分配失败返回 NULL, 描述符所有权仍归调用者。非负但已关闭或权限错误的描述符,不保证在此时被拒绝; 后续 I/O 可能失败。x 不会独占创建或截断已有描述符。 追加会尝试定位到末尾。e/N 尝试改变描述符标志;本入口不报告这些系统调用的失败。

本组共同前提与范围

使用 gzFile 句柄进行带缓冲的 gzip 文件 I/O。打开时取得文件描述符和私有状态; 数据操作按需初始化缓冲区和编解码器状态;即使最终 I/O 失败,关闭也会释放句柄。 读取还可接受透明的未压缩输入:文件中的字节不经解压,直接作为结果交付。

任务 入口
打开或配置 打开路径、打开描述符、缓冲区大小、压缩参数
读取 字节、数据项、字符、回退字节、行
写入 字节、数据项、字符、字符串、格式化文本、刷新
位置 定位、回到起点、未压缩位置、文件偏移
查询或清除状态 文件末尾、透明模式、错误、清除错误
关闭 任意模式、读取句柄、写入句柄

本页的契约依据固定版本的源码(加上列出的补丁)和 zlib.h。

已证明的内容。 句柄每一段历史的安全性:没有未定义行为、没有内存错误、没有泄漏,并且终止(见安全目标)。 各条目描述的返回值、字节和位置属于功能行为:它们读自 C 源码,凡是没有定理陈述的,都尚未由证明确认。 它们不在计划的证明目标之内。哪些目标已完成见进度。

安全目标

本页中默认构建所编译的每个函数,都有自己的必需安全目标 Goal.<function>_safety (Safety/GzCalls.lean),它的条目在证明目标下陈述这个目标。 gzopen_w 只存在于 Windows 上,没有这样的目标。 每个这样的目标都把序列目标 Goal.gz_sequence_safety (GzSafety.lean)的一个子句限制到一个函数的调用上。 接受句柄的函数,其目标还带有 Goal.gz_refusal 中属于该函数的子句,即对 NULL 句柄的拒绝。 序列目标同样是必需的。它多出下表中的不变量子句,这个子句说的是历史,而不是某一次调用。

本节描述序列目标,因为各条目要引用它的历史、参数条件和读取预算。这些目标各有一条类型完全相同的定理。 它们针对打过补丁的源码(见注意事项)。

历史(GzHistory)。 目标覆盖一个句柄的每一段历史。历史从一次成功的 gzopen、gzopen64 或 gzdopen 开始: 堆良构,字节对象都小于 2^63 字节,字符串参数(path、mode)以 NUL 结尾。此后可以接着发生以下任何一种情况:

  • 对该句柄调用一个非关闭的 gz 函数,参数满足下表的条件,并且调用返回,结果不限;
  • 使用一次 gzgetc() 宏;
  • 调用者编辑:对不归句柄所有的存储作任意修改。调用者可以释放自己的缓冲区,包括上一次 gzread 用的缓冲区;
  • 外部世界的一步:文件系统变成任意一个良构状态。别人可以关闭句柄的描述符,或者用同一个编号打开另一个文件。 下一次读写要么得到错误,要么读写到那个文件,与 C 中一样。

目标陈述的内容。

子句 命题
不变量 每段历史之后,世界良构,句柄满足其不变量(GzInv)。
无故障 下一次调用在每个世界里都不会以未定义行为或内存错误结束。它唯一可能的错误是循环燃料耗尽。除参数条件外没有前提。
终止 下一次调用返回。gzread、gzfread、gzgetc、gzgetc_、gzgets 和 gzungetc 为此需要下面的读取预算。其他调用在每个世界里都返回。
帧性质与账本 返回的调用保持打开的描述符集合不变,保持 GzInv、模式和描述符,只写句柄自有的块和下面点名的调用者区域,并且存活块的变化与句柄的账本完全一致(GzStepPost)。账本就是分配账本(见安全性):调用新分配的每个块,调用后都归句柄所有;调用释放的每个块,调用前都归句柄所有。
gzerror 它返回的指针在调用后的堆里是一个可读的、以 NUL 结尾的字符串。在 C 中它是字面量或句柄的消息;目标只陈述它是一个可读的字符串。
关闭 gzclose、gzclose_r 和 gzclose_w 在每个世界里都返回。模式不符的关闭调用拒绝,并且什么都不改变。否则句柄记录和每个自有块都被释放,其余内容不变,描述符被释放,即使系统的 close 失败也是如此。对返回码不作陈述。
打开 gzopen、gzopen64 和 gzdopen 对每个世界和每一种分配结果都返回,并且不改变任何已有的块。返回 NULL 时不留下新块;gzopen 和 gzopen64 此时还保持打开的描述符集合不变。返回的句柄满足 GzInv,恰好拥有新块。gzdopen 不打开也不关闭任何描述符。

参数条件(GzArguments)。 调用者的范围必须在句柄拥有的块之外(GzOwned:句柄记录、路径、消息、缓冲区和编解码器状态)。 gzerror 返回的字符串就是句柄的消息。清除错误的条目在使用自己的缓冲区之前会先释放这条消息:写入类条目在每次通过模式和错误检查的调用中都这样做,读取类条目只在上一次读取停顿之后才这样做 (见偏离记录中的表)。这时把它再传回来,在 C 中可能是释放后使用 (见偏离记录的“Gz 调用者缓冲区”和“Gz printf 字符串”两行)。

调用 条件
gzread(file, buf, len) len > INT_MAX:无。否则 len == 0,或者 buf 覆盖 len 个可写字节且在句柄的块之外。
gzwrite(file, buf, len) len > INT_MAX:无。否则 len == 0,或者 buf 覆盖 len 个可读字节且在句柄的块之外。
gzfread、gzfwrite size * nitems >= 2^64:无。否则乘积为零,或者 buf 覆盖这么多字节(gzfread 要求可写,gzfwrite 要求可读)且在句柄的块之外。
gzgets(file, buf, len) buf == NULL 或 len < 1:无。否则 buf 覆盖 len 个可写字节且在句柄的块之外。
gzputs(file, s) s 是以 NUL 结尾的字符串,且在句柄的块之外。
gzprintf、gzvprintf 文件以写方式打开且不处于错误状态时,格式串是以 NUL 结尾的字符串,每个指针参数都指向未被释放的块。格式串和每个指针参数都在句柄的块之外。vsnprintf 调用在 C 中有定义、且没有 %n:这是调用者的义务。
gzerror(file, errnum) errnum 为 NULL,或覆盖 4 个可写字节且在句柄的块之外。
其他调用 无:每个标量参数的每个取值都被覆盖。

gzprintf 的条件在每个 gzprintf 步骤上都要求成立。对读句柄或处于错误状态的句柄,C 在读格式串之前就返回,这时条件只要求格式串指针和各指针参数在句柄的块之外。 模型不解析格式串:凡是使 vsnprintf 调用在 C 中有定义、且参数都是整数或字符串的格式串都被覆盖,包括 h 和 hh 修饰符以及 * 宽度。模型的参数类型(VaArg)没有浮点或 void * 的情形,所以浮点转换和 %p 不被覆盖。%n 不被覆盖:带 %n 时,调用会写调用者的内存,而结论的框架不描述这种写入,所以调用者的义务排除了它。与参数不匹配的格式串也不被覆盖,而且模型发现不了它 (见偏离记录的“Gz printf 调用”一行)。

读取预算(ReadsFinite)。 六个读调用的终止子句假设:句柄的描述符还能交付的字节少于 2^61。 这个前提是必要的:一个不断交付空 gzip 成员的数据源,会让 C 中的一次 gzread 永远运行。 它按调用名取用,所以即使 C 会立刻返回(例如在写句柄上,或长度为零)也要求成立。 2^61 是模型的数字,不是 zlib 的:它让循环度量保持在 2^64 次迭代的循环燃料以下 (见安全性)。这个前提还说描述符编号不是负数(HasBudget);库返回的每个句柄都有这样的编号,因为 gzdopen 对负的描述符返回 NULL。 无故障子句以及帧性质与账本子句不使用这个前提。

gzgetc 宏。 zlib.h 把 gzgetc 定义成宏,应用程序通常就是这样调用它的。目标里另有一条针对这个宏 (Zlib.ZlibH.gzgetc)。有缓冲输出(have != 0)时,宏直接从缓冲区取一个字节,不调用库函数,不需要前提就返回。 have == 0 时它调用函数 gzgetc,在读取预算下返回。它的帧性质和账本与函数相同,而函数不写任何调用者区域。 对 NULL 句柄使用宏会读取 file->have,在 C 中是未定义行为;只有函数才拒绝 NULL。

长度为零的读不点名任何区域。 对 len == 0 的 gzread 和乘积为零的 gzfread,帧性质不点名任何调用者区域 (GzWriteRegions),buf 可以是任意指针,包括指向这次调用所释放的块的指针。如果帧性质点名了 buf,它在那种情形下就是假的。 len >= 1 时 gzgets 点名 buf 处的 len 个字节, gzerror 点名 errnum 处的 4 个字节。

NULL 句柄与非空性。 Goal.gz_refusal (GzRefusal.lean)说明:每个接受句柄的 gz 函数在句柄为 NULL 时返回文档规定的值, 堆和世界都不变。每个这样的函数自己的目标都重复了属于它的那个子句。Goal.gz_sequence_nonvacuity 表明前提可以满足:一个带有限读取预算的 gzopen 读句柄加一次一字节的 gzread,以及一个 gzdopen 写句柄加一次一字节的 gzwrite。

功能契约。 逐函数目标 Goal.gzread、Goal.gzwrite 等说明读写了哪些字节、返回了什么值。 它们针对没有外部干扰的普通文件(RegularOs),并依赖一个手工建立的文件系统模型。 它们不在计划内。每个条目说明它的功能目标是否已有定理证明。

通用句柄条件

先分清两种位置。逻辑位置以未压缩字节计数;普通读写按已消费或接受的数量推进,定位还可以记下尚未执行的前移。底层文件另有物理偏移,它以文件中的字节计数。gztell 查询前者;gzoffset 报告后者,读取句柄还要减去已从文件读入但尚未使用的压缩输入。库会预读和缓冲,因此两个值通常不同;压缩率也不能用来换算它们。

例如,没有额外定位或字节回退时,读取句柄已向应用交付 1000 个解压字节,逻辑位置就是 1000;为了完成这些输出,底层可能已预读更靠后的压缩字节。相反,写入成功表示库接受了输入,不能据此推断这些字节已全部写入描述符。

后面的参数沿用这套单位:len 和缓冲区配置 size 按字节计;数据项接口中的 size 是每项字节数,nitems 是项数,总请求为 size * nitems 字节。offset 是有符号的未压缩字节位移;whence 指定从起点(SEEK_SET)还是当前位置(SEEK_CUR)计算。INT_MAX 是本构建中有符号 int 能表示的最大值,即 2^31 - 1。

本页把非阻塞停顿与硬错误分开描述。停顿之后,下一次数据调用可以直接重试。硬错误是指不由停顿留下、并使之后的数据调用失败的已记录错误(读取句柄要等已缓冲的字节用完才失败):对写入句柄是任何错误码,对读取句柄是 Z_BUF_ERROR(截断)以外的任何错误码。这个区别说明本次调用怎样返回;它不免除错误后的状态、重试和清理要求。

本页使用默认 x86_64 Linux 构建。int 和 unsigned 为 32 位。 long、z_off_t、z_off64_t 和 z_size_t 为 64 位。大文件声明已启用。 这里普通入口和 *64 入口的偏移范围相同。其他配置需要单独契约。 gzopen_w 仅适用于 Windows,下文另行限定其范围。

受限定义域指满足下列通用要求的普通用法:

  • 非 NULL 句柄由成功打开返回、仍存活且尚未关闭。串行使用它,调用者不修改其私有状态。
  • 读取或写入句柄具有入口指定的访问模式。NULL 和错误模式的拒绝情形分别说明。 已失效或任意指针不在本定义域内;检查模式字段不等于验证指针。
  • 缓冲区覆盖请求的可读或可写范围,并与句柄拥有的内存分离。 字符串具有可读的终止 NUL。调用者保留这些对象的所有权。
  • 位置运算和请求范围能由指定 C 类型表示。下述契约仍包括显式的超大请求和乘法溢出拒绝。
  • 描述符在关闭前属于句柄。调用期间,没有其他操作改变其数据或位置。 操作系统失败和分配失败仍可能发生;成功打开不保证后续 I/O 成功。 前两句只是功能契约的条件。安全目标允许外部世界在两次调用之间改变任何描述符。

每个入口均带定义域标签。“完整标量范围”仅在上述指针和生存期要求下, 适用于所指明的标量参数。 部分读取错误和字节回退形成的负位置都在安全目标之内。

效果。 读、写、打开、定位、控制和关闭均为有状态操作,包括没有调用者输出缓冲区的操作。 位置查询(gztell、gzoffset)和文件末尾查询(gzeof)读取状态;gzerror 还可能写入可选错误码输出。 gzdirect 可读取文件并分配内存,因此也是有状态操作。

stateDiagram-v2
    state "新建句柄" as Fresh
    state "已开始数据处理" as Active
    state "已关闭" as Closed
    [*] --> Fresh: 成功打开
    Fresh --> Active: 首次 I/O 或格式检查
    Active --> Active: 读、写、定位、控制
    Fresh --> Closed: 关闭
    Active --> Closed: 关闭,包括最终 I/O 失败
    Closed --> [*]

格式与缓冲。 打开时不对载荷执行 I/O。缓冲区和编解码器状态按需分配, 默认请求的缓冲区大小为 8192 字节。请求大小是配置量,实际内部存储还包括 gzbuffer 条目所述的双倍缓冲区和编解码器状态。首次使用或后续解压期间都可能分配失败。 即使最终 I/O 失败,关闭也释放拥有的分配。

普通读取句柄根据合理的四字节头部识别 gzip;否则原样返回输入。 空输入属于透明输入。非阻塞输入在获得四字节前停顿时,检测保持等待。 一个 gzip 成员是一段带有自身头部、压缩数据和尾部校验信息的完整流;一个文件可以顺序放置多个成员。读取输出按顺序拼接各成员的未压缩数据。若尝试解码下一个成员时,在格式错误前未产生输出, 则忽略尾随的非成员数据。G 要求 gzip;T 选择透明输出,不能用于读取。

读取结果。 读取按已消费字节数推进未压缩位置,包括最终的部分数据项。 已缓冲字节可能在已记录错误被报告之前返回。gzeof 表示曾尝试读取可用数据之后的内容, 而不只是已交付最后一个字节。gzerror 区分 EOF、损坏(Z_DATA_ERROR)、 截断(Z_BUF_ERROR)、分配失败(Z_MEM_ERROR)和系统失败(Z_ERRNO)。 零长度读取不消费输入,也不执行待处理定位。

写入结果。 成功表示句柄已接受输入;数据仍可能在缓冲区内。 后续刷新或关闭仍可能失败。硬错误可能在消费一个前缀后返回失败; 仅凭返回值不总能确定重试偏移。非阻塞停顿则可能返回至今已消费的数量。

错误通常持续到被清除。已记录的非阻塞停顿允许下次数据 I/O 重试。 定位和回到起点仍拒绝该已记录的 Z_ERRNO。构造错误消息本身可能失败, 并将错误码改为 Z_MEM_ERROR。errno 只对关联的系统失败有意义, 不能普遍解释每个失败的 API 调用。

部分读取之后、压缩器未采用的参数更改之后,或结束失败之后,重试或恢复会得到什么(哪些字节到达文件、报告什么位置), 属于功能行为。它尚未由证明确认。 任何一次调用返回之后,无论结果如何,下一次调用都是安全的,这一点属于安全目标。

源码为 gzlib.c、gzread.c、 gzwrite.c、gzclose.c 和 zlib.h。序列安全目标是 Goal.gz_sequence_safety (GzSafety),各函数的安全目标是 Goal.<function>_safety(GzCalls), NULL 句柄目标是 Goal.gz_refusal(GzRefusal)。 抽象契约是定义在抽象句柄 GzHandle 上的关系 (Functional/Api/Gz.lean)。 功能目标是 Goal.<function> (GzOpen、 GzRead、GzWrite、 GzControl、 GzClose)。

安全目标

ZlibF.Spec.Public.Goal.gzdopen_safety

状态:完成 · 结论的状态

/-- `gzFile gzdopen(int fd, const char *mode)`.
**Safety of `gzdopen`** (`GzDopenSafe`): as `GzOpenSafe`, but no descriptor is opened or closed. -/
def Goal.gzdopen_safety : Prop :=
  GzDopenSafe
相关定义与源码 ↗

功能契约(安全之外)

ZlibF.Spec.Public.Goal.gzdopen

状态:完成 · 结论的状态

/-- `gzFile gzdopen(int fd, const char *mode)`.
Negative descriptors are rejected. No open syscall occurs, and failure retains the caller's
descriptor. A successful handle takes ownership; its path is the formatted descriptor name. -/
def Goal.gzdopen : Prop :=
  (∀ h fs fd mode, fd.toInt < 0 → Zlib.Gzlib.gzdopen fd mode fs h = .ok ((none, fs), h)) ∧
  (∀ h fs fd mode flags,
    Fresh h → Zlib.Gzlib.Spec.Uniq h → LibraryGlobals h → FileSystem fs →
    0 ≤ fd.toInt → (mode ≠ .null → CString h mode flags) →
    ∃ result fs' after, Zlib.Gzlib.gzdopen fd mode fs h = .ok ((result, fs'), after) ∧
      Frame h after (fun _ => False) ∧
      (match result with
       | none => fs'.fds = fs.fds ∧ LiveChange h after (fun _ => False) (fun _ => False) ∧
           (mode = .null ∨ parsedMode flags = none ∨ AllocationFailed h after)
       | some (.in_gzstate_x i) => ∃ s mode level strategy direct,
           parsedMode flags = some (mode, level, strategy, direct) ∧
           OpenState after i s mode level strategy direct fd
             (String.toUTF8 ("<fd:" ++ toString fd.toInt ++ ">")).toList ∧
           OpenWorld h fs fs' [] flags mode (some fd) fd s.start ∧
           LiveChange h after (GzOwned after i s) (fun _ => False)))
相关定义与源码 ↗
ZLIB × LEAN

目录

正在阅读gzdopen