gzread
读取至多 len 个未压缩字节。
完整章节与共同规则 ↗读取至多 len 个未压缩字节。
int ZEXPORT gzread(gzFile file, voidp buf, unsigned len);
返回值与后续调用
返回值类型。 int — 已读取的未压缩字节数,或失败标记
正数表示本次已交付的字节数。零可能表示零长度请求、EOF 或截断;-1 才是该接口的失败标记。
gzread()| 返回值 | 含义与出现条件 | 调用者接下来 |
|---|---|---|
0 < n <= len已交付 n 字节 |
读取、解压或缓冲数据提供了 n 字节;返回不足或已有错误记录时,已交付前缀仍有效。 | 处理这 n 字节;不足请求时查询 gzerror 和 gzeof,再决定是否继续读取。 |
0零长度请求 |
len 为零且已有状态未使调用失败;不消费输入,也不执行待处理定位。 | 按需要发起非零长度读取;不能由此判断 EOF。 |
0EOF 或截断,无输出 |
非零请求没有可交付字节;正常末尾和记录为 Z_BUF_ERROR 的截断都可返回零。 | 查询 gzerror 和 gzeof;Z_BUF_ERROR 不表示完整 gzip 成员已成功结束。 |
-1请求失败或暂时停顿 |
NULL、模式错误、len > INT_MAX、无可交付字节的硬错误,或无输出的非阻塞停顿;已有错误状态也可使零请求失败。 | 对有效句柄查询 gzerror。仅在确认是可重试停顿并处理等待后重试;硬错误须按其原因处理。 |
调用条件与效果
定义域 受限定义域:读取句柄和目标;完整无符号 len 的拒绝范围。
效果: 有状态读取、目标写入,可能分配内存。
前置条件 当 len <= INT_MAX 时,buf 按共享分离规则覆盖 len 个可写字节。
零范围不需要访问任何字节。
证明目标。
- 目标。
Goal.gzread_safety(Safety/GzCalls.lean);必需。定理:ZlibF.Spec.Public.GzCallSafetyProof.gzread_safety(public-gz-call-safety.lean)。这个目标有两个子句:对 NULL 句柄的拒绝;对句柄的一次调用(GzCallSafety,即序列目标的调用子句限制到这个函数的调用上)。 - 适用条件。 拒绝子句没有条件。对句柄的调用要求:
file是一个带有历史的句柄(GzHistory,见安全目标一节);- 参数条件(
GzArguments):len > INT_MAX时没有要求;否则len == 0,或者buf覆盖len个可写字节且在句柄自己的块之外(GzRange)。
- 无条件覆盖。
len的每个取值,包括 0 和大于INT_MAX的值;在这两种情形下buf可取任意值;历史能让句柄处于的每一种状态,读句柄或写句柄,有或没有待处理的错误;每个文件系统世界;每一种分配结果。 - 保证。
- 返回。 句柄为 NULL 时,不论其他参数取什么值,调用都返回
-1。对句柄调用时,在每个世界里,调用都不会以未定义行为或内存错误结束:执行唯一可能的错误是循环燃料耗尽。读取预算成立时(ReadsFinite:描述符还能交付的字节少于2^61)调用返回。即使 C 会立刻返回的情形,也要求这个预算。 - 状态。 对句柄的调用返回之后:世界良构,打开的描述符集合不变(
FdsKept),句柄保持其不变量、模式和描述符(GzStepPost、GzInv)。 - 写入。 句柄为 NULL 时不写任何内容:堆和世界都不变。对句柄调用时,只写句柄自己的块;当
0 < len <= INT_MAX时还有buf处的len个字节。长度为零的读不点名任何调用者区域。 - 分配。 对句柄调用时,按句柄计的精确的分配账本(
LiveChange)。
- 返回。 句柄为 NULL 时,不论其他参数取什么值,调用都返回
- 不在本目标内。 对句柄调用时的返回值,以及由此得到的字节、位置和标志:功能目标
Goal.gzread(不在计划内;未完成)。
完整返回条件与边界
返回与保证 正结果 n <= len 给出接下来的 n 个字节,
在处理任何待处理跳过后,将位置推进 n。格式、成员拼接、透明输入和延迟错误遵循共享读取规则。
错误与边缘情形: NULL、模式错误、无法交付数据的硬错误或 len > INT_MAX 时返回 -1;
超大请求记录 Z_STREAM_ERROR,除非需保留更严重错误。
EOF/截断且无输出时返回零。零请求通常返回零,但已有错误/停顿状态仍可能导致 -1。
应查询 gzerror;截断对应 Z_BUF_ERROR,不表示成功完成 gzip 成员。
后续错误不抹除已交付字节。阻塞描述符可能等待以填满内部读取。
非阻塞停顿可重试,不是 EOF。透明读取时 read 先交付字节然后失败,在未打补丁的 C 中是越界读;补丁 0003 修复了它
(见注意事项)。
本组共同前提与范围
使用 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.gzread_safety
状态:完成 · 结论的状态
/-- `int gzread(gzFile file, voidp buf, unsigned len)`.
**Safety of `gzread`**: a `NULL` handle is refused with nothing changed (its clause of
`Goal.gz_refusal`); and one call on a handle of any history (`GzCallSafety`). -/
def Goal.gzread_safety : Prop :=
(∀ (fs : Fs) (h : Heap) buf len, Zlib.Gzread.gzread none buf len fs h = .ok ((-1, fs), h)) ∧
GzCallSafety (fun | .gzread .. => True | _ => False)相关定义与源码 ↗功能契约(安全之外)
ZlibF.Spec.Public.Goal.gzread
状态:未完成,不在计划内 · 结论的状态
/-- `int gzread(gzFile file, voidp buf, unsigned len)`.
Return bytes, EOF zero, or -1. Requests above INT_MAX fail before touching the output.
Buffered bytes precede a later error; partial output remains part of the result. -/
def Goal.gzread : Prop :=
(∀ h fs p n, Zlib.Gzread.gzread none p n fs h = .ok ((-1, fs), h)) ∧
(∀ h fs i s p n, GzReachable h fs i → GzValid h i s → RegularOs fs →
(n.toNat < 2 ^ 31 → GzRange h i s p n.toNat true) →
∃ rc fs' after s' out,
Zlib.Gzread.gzread (some (.in_gzstate_x i)) p n fs h = .ok ((rc, fs'), after) ∧
ReturnedBytes after p out ∧
ReadEffect h after fs fs' i s s' (if n.toNat < 2 ^ 31 then n.toNat else 0) out [⟨p, out.length⟩] ∧
(rc = -1 ∧ out = [] ∨ 0 ≤ rc.toInt ∧ rc.toInt = (out.length : Int)) ∧
(2 ^ 31 ≤ n.toNat → rc = -1) ∧
(s.mode ≠ GZ_READ → rc = -1 ∧ after = h ∧ fs' = fs))相关定义与源码 ↗