vscanf, vfscanf, vsscanf, vscanf_s, vfscanf_s, vsscanf_s
在标头 <stdio.h> 定义
|
||
int vscanf( const char *restrict format, va_list vlist ); |
(1) | (C99 起) |
int vfscanf( FILE *restrict stream, const char *restrict format, va_list vlist ); |
(2) | (C99 起) |
int vsscanf( const char *restrict buffer, const char *restrict format, va_list vlist ); |
(3) | (C99 起) |
int vscanf_s(const char *restrict format, va_list vlist); |
(4) | (C11 起) |
int vfscanf_s( FILE *restrict stream, const char *restrict format, va_list vlist); |
(5) | (C11 起) |
int vsscanf_s( const char *restrict buffer, const char *restrict format, va_list vlist); |
(6) | (C11 起) |
从各种源读取数据,按照 format
转译并存储结果到 vlist
所定义的位置。
stream
读取数据。buffer
读取数据。抵达字符串结尾等价于 vfscanf
的抵达文件尾条件- 任何指针类型参数为空指针
-
format
、stream
或buffer
为空指针 - %c 、 %s 或 %[ 本会写入的字符数,加上空终止字符,要超过提供给这些转换指示符的第二个(rsize_t)参数
- 可选,任何其他可检测错误,例如未知转换指示符
- 同所有边界检查函数,
vscanf_s
、vfscanf_s
与vsscanf_s
,仅若实现定义 __STDC_LIB_EXT1__ 且用户在包含 <stdio.h> 前定义 __STDC_WANT_LIB_EXT1__ 为整数常量 1 才保证可用。
参数
stream | - | 要读取的输入文件流 |
buffer | - | 指向要读取的空终止字符串的指针 |
format | - | 指向指定读取输入方式的空终止字符串的指针 |
vlist | - | 包含接收各实参的可变实参列表 |
格式字符串由下列内容组成
- 非空白多字节字符,除了
%
:每个格式字符串中的这种字符处理一个来自输入流的完全相同的字符,或若它与流的下个字符比较不相等则导致函数失败。 - 空白字符:任何格式字符串中的单个空白字符处理所有来自输入的可用连续空白字符(如同通过于循环中调用 isspace 确定)。注意,格式字符串中 "\n"、" "、"\t\t" 或其他空白无区别。
- 转换指示:每个转换指示拥有下列格式:
- 引入用 % 字符
- (可选)赋值抑制字符 *。若存在此选项,则此函数不将结果赋值给任何接收用实参。
- (可选)指定最大字段宽度的整数数字(大于零),即函数进行在当前转换指示所指定的转换时,允许处理的最大字符数。注意若不提供宽度,则 %s 和 %[ 可能导致缓冲区溢出。
- (可选)指定接收实参大小的长度修饰符,即实际目标类型。这影响转换准确性和溢出规则。默认目标类型对每个转换类型有所不同(见下表)。
- 转换格式指示符。
下列格式指示符可用:
转换 指示符 |
解释 | 实参类型 | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
长度修饰符 →
|
hh
(C99) |
h
|
(无) | l
|
ll
(C99) |
j
(C99) |
z
(C99) |
t
(C99) |
L
| |
%
|
匹配字面 % 。
|
不适用 | 不适用 | 不适用 | 不适用 | 不适用 | 不适用 | 不适用 | 不适用 | 不适用 |
c
|
若使用了宽度指示符,则匹配恰好宽度个字符(该实参必须是指向有充足空间的数组的指针)。不同于 %s 和 %[ ,它不会在数组后附加空字符。 |
不适用 | 不适用 | char* |
wchar_t* |
不适用 | 不适用 | 不适用 | 不适用 | 不适用 |
s
|
若使用宽度指示符,则至多匹配宽度个字符,或匹配到首个提前出现的空白符前。总是在匹配的字符后存储一个空字符(故实参数组必须有至少宽度 +1个字符的空间)。 | |||||||||
[ 集合]
|
若集合的首字符是 | |||||||||
d
|
该数的格式同 strtol() 以值 10 为 |
signed char* 或 unsigned char* |
signed short* 或 unsigned short* |
signed int* 或 unsigned int* |
signed long* 或 unsigned long* |
signed long long* 或 unsigned long long* |
不适用 | |||
i
|
该数的格式同 strtol() 以值 0 为 | |||||||||
u
|
该数的格式同 strtoul() 以值 10 为 | |||||||||
o
|
该数的格式同 strtoul() 以值 8 为 | |||||||||
x , X
|
该数的格式同 strtoul() 以值 16 为 | |||||||||
n
|
不消耗输出。不增加赋值计数。若此指示符拥有赋值抑制运算符,则行为未定义。 | |||||||||
a , A (C99)e , E f , F g , G
|
该数的格式同 strtof() 所期望者。 |
不适用 | 不适用 | float* |
double* |
不适用 | 不适用 | 不适用 | 不适用 | long double* |
p
|
|
不适用 | 不适用 | void** |
不适用 | 不适用 | 不适用 | 不适用 | 不适用 | 不适用 |
对于每个异于 n 的转换指示符,不超过任何指定字段宽度,且要么恰好是转换指示符所期待,要么是其所期待的前缀的最长输入字符序列,即是从流中消耗的内容。此消耗序列后的首个字符若存在,则保持未读取。若被消耗序列长度为零,或被消耗序列不能转换成上面所指定的项目,则发生匹配失败,除非遇到文件尾、编码错误,或阻止从流输入的读取错误,此情况下此为输入失败。
所有异于 [、c 和 n 的转换指示符,在尝试分析输入前消耗并舍弃所有前导空白字符(如同以调用 isspace 来确定)。这些被消耗的字符不计入指定的最大字段宽度。
转换指示符 lc、ls 和 l[ 进行多字节到宽字符转换,如同如同在转换首字符前,通过用初始化到零的 mbstate_t 对象调用 mbrtowc()。
转换指示符 s 与 [ 始终在匹配字符之后存储一个空字符。目标数组的大小必须至少比指定字段宽度大一。未指定目标数组大小时,对 %s 或 %[ 的使用,与 gets 同样不安全。
定宽整数类型(int8_t
等)的正确的转换指示定义于头文件 <inttypes.h> (虽然 SCNdMAX、SCNuMAX 等就是 %jd、%ju 等的别名)。
在每个转换指示符后有一个序列点;这允许存储多个字段到同一“池”变量中。
在分析以无数字指数为结尾的不完整浮点值,如以转换指示符 %f 分析 "100er" 时,消耗序列 "100e" (可能为合法浮点数的最长前缀),并导致匹配错误(被消耗序列不能转换成浮点数),而留下 "r"。某些既存实现不遵守此规则并回滚,通过消耗 "100" 而留下 "er",例如 glibc 漏洞 1765。
返回值
注解
所有这些函数调用 va_arg 至少一次,返回后 arg
的值不确定。这些函数不调用 va_end ,而这必须由调用方进行。
示例
#include <stdio.h> #include <stdbool.h> #include <stdarg.h> bool checked_sscanf(int count, const char* buf, const char *fmt, ...) { va_list ap; va_start(ap, fmt); int rc = vsscanf(buf, fmt, ap); va_end(ap); return rc == count; } int main(void) { int n, m; printf("Parsing '1 2'..."); if(checked_sscanf(2, "1 2", "%d %d", &n, &m)) puts("success"); else puts("failure"); printf("Parsing '1 a'..."); if(checked_sscanf(2, "1 a", "%d %d", &n, &m)) puts("success"); else puts("failure"); }
输出:
Parsing '1 2'...success Parsing '1 a'...failure
引用
- C11 标准(ISO/IEC 9899:2011):
- 7.21.6.9 The vfscanf function (第 327 页)
- 7.21.6.11 The vscanf function (第 328 页)
- 7.21.6.14 The vsscanf function (第 330 页)
- K.3.5.3.9 The vfscanf_s function (第 597-598 页)
- K.3.5.3.11 The vscanf_s function (第 599 页)
- K.3.5.3.14 The vsscanf_s function (第 602 页)
- C99 标准(ISO/IEC 9899:1999):
- 7.19.6.9 The vfscanf function (第 293 页)
- 7.19.6.11 The vscanf function (第 294 页)
- 7.19.6.14 The vsscanf function (第 295 页)
参阅
(C11)(C11)(C11) |
从stdin、文件流或缓冲区读取格式化输入 (函数) |
(C99)(C11)(C11)(C11)(C11) |
打印格式化输出到stdout、文件流或缓冲区 使用可变参数列表 (函数) |