gzvprintf
格式化 va_list,并接受结果用于输出。
完整章节与共同规则 ↗格式化 va_list,并接受结果用于输出。
int ZEXPORTVA gzvprintf(gzFile file, const char *format, va_list va);
返回值与后续调用
返回值类型。 int — 格式化字节数、零或 zlib 错误码
正值计数已接受的格式化字节。零与负值含义不同,不能视为简单的成功/失败标志。
gzvprintf()| 返回值 | 含义与出现条件 | 调用者接下来 |
|---|---|---|
n > 0已接受格式化字节 |
格式化结果长度严格小于所配置缓冲区大小,且已接受 n 个字节。不包括 NUL 终止符。 | 可继续提交后续输入;输出可能仍在缓冲区中。检查刷新或关闭时的后续输出错误。 |
0未接受格式化字节 |
格式化输出为空、格式化器失败,或输出超出本次调用缓冲区。零不一定记录 gzerror 错误码。 | 区分空输出与格式化/大小失败。修正请求后再提交;此前待处理 I/O 或格式化器效果可能已发生。 |
Z_STREAM_ERROR调用被拒绝 |
句柄为 NULL、模式错误,或有待处理硬错误。 | 使用活跃写入句柄和有效格式化参数。关闭前检查仍存活的句柄;不能推断此前错误已被清除。 |
Z_BUF_ERROR需重试格式化调用 |
非阻塞停顿导致缓冲区空间不足,必须重试本次格式化调用。 | 处理停顿后重试格式化调用。须考虑此前待处理输出及格式化器效果;此结果不保证状态未变。 |
Z_MEM_ERROR / Z_ERRNO / Z_STREAM_ERROR初始化或输出失败 |
缓冲区/编解码器初始化、待处理零填充,或格式化前后写入失败,并返回其错误码。 | 关闭前检查 gzerror,区分系统停顿与硬错误。负结果之前可能已改变状态,也不是安全的字节重试偏移。 |
判读要点。
- 默认每次调用的格式化长度须严格小于 8192 字节;gzbuffer 可更改此限制。
调用条件与效果
定义域 受限定义域:写入句柄、有效参数列表和外部格式化。
效果: 有状态格式化写入,可能产生格式化器的内存效果。
前置条件 满足 gzprintf 的格式、参数和分离要求。
va 已按这些参数初始化;其使用遵循平台的 va_list 生存期和复制规则。
证明目标。
- 目标。
Goal.gzvprintf_safety(Safety/GzCalls.lean);必需,尽管zlib.h把这个函数列为未文档化:gzprintf经由它实现。定理:ZlibF.Spec.Public.GzCallSafetyProof.gzvprintf_safety(public-gz-call-safety.lean)。这个目标有两个子句:对 NULL 句柄的拒绝;对句柄的一次调用(GzCallSafety,即序列目标的调用子句限制到这个函数的调用上)。 - 适用条件。 拒绝子句没有条件。对句柄的调用要求:
- 无条件覆盖。 历史能让句柄处于的每一种状态,读句柄或写句柄,有或没有待处理的错误;每个文件系统世界;每一种分配结果。
- 保证。
- 返回。 句柄为 NULL 时,不论其他参数取什么值,调用都返回
Z_STREAM_ERROR。对句柄调用时,调用在每个世界里都返回。 - 状态。 对句柄的调用返回之后:世界良构,打开的描述符集合不变(
FdsKept),句柄保持其不变量、模式和描述符(GzStepPost、GzInv)。 - 写入。 句柄为 NULL 时不写任何内容:堆和世界都不变。对句柄调用时,只写句柄自己的块。
- 分配。 对句柄调用时,按句柄计的精确的分配账本(
LiveChange)。
- 返回。 句柄为 NULL 时,不论其他参数取什么值,调用都返回
- 不在本目标内。 带
%n的格式串,以及对格式串和参数而言在 C 中没有定义的vsnprintf调用,例如与参数不匹配的转换:对这些调用在 C 中的行为,本目标什么也没说(见偏离记录的“Gz printf 调用”一行)。对句柄调用时的返回值,以及由此得到的字节、位置和标志:功能目标Goal.gzvprintf(不在计划内;未完成)。
完整返回条件与边界
返回与保证 正结果是已接受的格式化字节数,不含终止 NUL。 相应推进位置,数据可能仍被缓冲。格式化长度须严格小于配置的缓冲区大小。 此前待处理定位可在接受任何格式化输出前先输出零字节。
错误与边缘情形: NULL、模式错误或待处理硬错误返回 Z_STREAM_ERROR。
初始化、跳过或写入失败返回相应错误码。
空输出、格式化器失败或输出放不下时返回零;该零不一定记录错误,
此前待处理 I/O 可能已发生。若本次格式化调用必须重试,非阻塞停顿可返回 Z_BUF_ERROR。
不得由负结果推断状态未改变。没有安全有界格式化的构建,可能提供拒绝桩函数或
另行限定范围的不安全实现;两者都不在此默认契约内。
本组共同前提与范围
使用 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.gzvprintf_safety
状态:完成 · 结论的状态
/-- `int gzvprintf(gzFile file, const char *format, va_list va)`.
**Safety of `gzvprintf`**: a `NULL` handle is refused with nothing changed (its clause of
`Goal.gz_refusal`); and one call on a handle of any history (`GzCallSafety`). `zlib.h` lists it
among the undocumented functions; the gz sequence goals range over it, and its own goal is required. -/
def Goal.gzvprintf_safety : Prop :=
(∀ (fs : Fs) (h : Heap) format (va : List VaArg),
Zlib.Gzwrite.gzvprintf none format va fs h = .ok ((Z_STREAM_ERROR, fs), h)) ∧
GzCallSafety (fun | .gzvprintf .. => True | _ => False)相关定义与源码 ↗功能契约(安全之外)
ZlibF.Spec.Public.Goal.gzvprintf
状态:未完成,不在计划内 · 结论的状态
/-- `int gzvprintf(gzFile file, const char *format, va_list va)`.
`text` is the output of the model's formatter; `vsnprintf` is an external call whose result the
world oracle chooses (`printfRet`, `printfOut`), so the bytes written are the ones vsnprintf
produced, which are `text` when the oracle returns its length and writes it. Wrong mode and
serious errors return a negative zlib code; an empty or oversized result returns zero. The C
library may fail on any call (the oracle returns a negative value): then
`(unsigned)len >= state->size`, and the call returns zero having accepted nothing. Safety (the run returns, the state stays valid, the frame) holds on both branches. -/
def Goal.gzvprintf : Prop := PrintContract Zlib.Gzwrite.gzvprintf相关定义与源码 ↗