命名空间
变体
操作

vscanf、vfscanf、vsscanf、vscanf_s、vfscanf_s、vsscanf_s

来自 cppreference.com
< c‎ | io
 
C
 
文件输入/输出
类型和对象
函数
文件访问
直接输入/输出
非格式化输入/输出
(C95)(C95)
(C95)
(C95)(C95)
(C95)
(C95)
(C95)
(C95)
格式化输入
vscanfvfscanfvsscanfvscanf_svfscanf_svsscanf_s
(C99)(C99)(C99)(C11)(C11)(C11)
(C99)(C99)(C99)(C11)(C11)(C11)     
 
在头文件 <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 定义的位置。

1) 从 stdin 读取数据
2) 从文件流 stream 读取数据
3) 从以 null 结尾的字符字符串 buffer 读取数据。到达字符串末尾等同于 fscanf 的文件末尾条件。
4-6) 与 (1-3) 相同，除了 %c、%s 和 %[ 转换说明符都期望两个参数（通常的指针和 rsize_t 类型的值，表示接收数组的大小，当使用 %c 读取到单个 char 时，该值可以为 1），并且除了在运行时检测到以下错误并调用当前安装的 约束处理程序 函数
  • 任何指向指针类型的参数都是空指针
  • format、stream 或 buffer 是空指针
  • %c、%s 或 %[, 写入的字符数，加上终止 null 字符，将超过为每个这些转换说明符提供的第二个 (rsize_t) 参数。
  • 可选地，任何其他可检测的错误，例如未知的转换说明符。
与所有有界检查函数一样，vscanf_s、vfscanf_s 和 vsscanf_s 仅在实现定义了 __STDC_LIB_EXT1__ 并且用户在包含 <stdio.h> 之前将 __STDC_WANT_LIB_EXT1__ 定义为整数常量 1 时才保证可用。

内容

[编辑] 参数

stream - 要从中读取的输入文件流
buffer - 指向要从中读取的以 null 结尾的字符字符串的指针
format - 指向指定如何读取输入的以 null 结尾的字符字符串的指针
vlist - 包含接收参数的可变参数列表。


format 字符串包含

  • 非空白多字节字符，除了 %：格式字符串中的每个此类字符都从输入流中消耗完全相同的字符，或者如果流上的下一个字符不相等，则导致函数失败。
  • 空白字符：格式字符串中的任何单个空白字符都消耗来自输入的所有可用的连续空白字符（通过调用 isspace 在循环中确定）。请注意，"\n"、" "、"\t\t" 或格式字符串中的其他空格之间没有区别。
  • 转换说明符。每个转换说明符都具有以下格式
  • 介绍性 % 字符。
  • (可选) 赋值抑制字符 *。如果存在此选项，则该函数不会将转换结果分配给任何接收参数。
  • (可选) 整数（大于零），指定最大字段宽度，即函数在执行当前转换说明符指定的转换时允许消耗的最大字符数。请注意，%s 和 %[ 如果没有提供宽度，可能会导致缓冲区溢出。
  • (可选) 长度修饰符，指定接收参数的大小，即实际目标类型。这会影响转换精度和溢出规则。默认目标类型因转换类型而异（参见下表）。
  • 转换格式说明符。

以下格式说明符可用

转换
说明符		 解释 参数类型
长度修饰符 →
 hh

(C99)

h (无) l ll

(C99)

j

(C99)

z

(C99)

t

(C99)

L
% 匹配文字 %。 N/A N/A N/A N/A N/A N/A N/A N/A N/A
c
匹配一个字符或一个字符序列。

如果使用宽度说明符，则匹配正好宽度个字符（参数必须是指向具有足够空间的数组的指针）。与 %s 和 %[, 不同，不会将 null 字符追加到数组。

 N/A N/A
char*
wchar_t*
 N/A N/A N/A N/A N/A
s
匹配非空白字符序列（一个字符串）。

如果使用宽度说明符，则匹配最多 width 个字符或直到第一个空白字符，以先出现者为准。始终存储一个空字符，除了匹配的字符（因此参数数组必须至少有 width+1 个字符的存储空间）。

[set]
匹配来自 set 字符集的非空字符序列。

如果字符集的第一个字符是 ^，则匹配字符集中所有未出现的字符。如果字符集以 ] 或 ^] 开头，则 ] 字符也将包含在字符集中。在扫描集中，字符 - 是否在非初始位置表示范围，例如 [0-9]，这是实现定义的。如果使用宽度说明符，则仅匹配最多 width 个字符。始终存储一个空字符，除了匹配的字符（因此参数数组必须至少有 width+1 个字符的存储空间）。

d
匹配一个十进制整数。

数字的格式与 strtol 函数期望的格式相同，其中 base 参数的值为 10。
signed char* 或 unsigned char*
signed short* 或 unsigned short*
signed int* 或 unsigned int*
signed long* 或 unsigned long*
signed long long* 或 unsigned long long*
N/A
i
匹配一个整数。

数字的格式与 strtol 函数期望的格式相同，其中 base 参数的值为 ​0​（基数由解析的第一个字符确定）。

u
匹配一个无符号十进制整数。

数字的格式与 strtoul 函数期望的格式相同，其中 base 参数的值为 10。

o
匹配一个无符号八进制整数。

数字的格式与 strtoul 函数期望的格式相同，其中 base 参数的值为 8。

x, X
匹配一个无符号十六进制整数。

数字的格式与 strtoul 函数期望的格式相同，其中 base 参数的值为 16。

n
返回到目前为止读取的字符数。

不消耗任何输入。不增加赋值计数。如果说明符有抑制赋值的操作符定义，则行为未定义。

a, A(C99)
e, E
f, F(C99)
g, G
匹配一个浮点数。

数字的格式与 strtof 函数期望的格式相同。

 N/A N/A
float*
double*
 N/A N/A N/A N/A
long double*
p
匹配实现定义的字符序列，定义一个指针。

printf 函数族应该使用 %p 格式说明符生成相同的序列。

 N/A N/A
void**
 N/A N/A N/A N/A N/A N/A

对于除 n 之外的所有转换说明符，从流中消耗的最长的输入字符序列，既不超过任何指定的字段宽度，又是转换说明符期望的序列本身或其前缀，将被消耗。第一个字符（如果有）位于此消耗序列之后，将保持未读状态。如果消耗的序列长度为零，或者消耗的序列无法按上述方式转换，则匹配失败，除非文件结束、编码错误或读取错误阻止了从流中的输入，在这种情况下，这是一个输入失败。

除了 [、c 和 n 之外的所有转换说明符，在尝试解析输入之前，都会消耗并丢弃所有前导空白字符（如同调用 isspace 函数确定）。这些消耗的字符不计入指定的最大字段宽度。

转换说明符 lc、ls 和 l[ 执行多字节到宽字符的转换，如同调用 mbrtowc 函数，其中 mbstate_t 对象在第一个字符转换之前被初始化为零。

转换说明符 s 和 [ 始终存储空终止符，除了匹配的字符。目标数组的大小必须至少比指定的字段宽度大一个。使用 %s 或 %[，不指定目标数组大小，与 gets 一样不安全。

对于 定长整数类型（int8_t 等）的正确转换说明符，在头文件 <inttypes.h> 中定义（尽管 SCNdMAX、SCNuMAX 等与 %jd、%ju 等同义）。

在每个转换说明符的操作之后存在一个序列点；这允许将多个字段存储在同一个“接收器”变量中。

当解析以指数结尾但没有数字的非完整浮点数时，例如用转换说明符 "100er" 解析 %f，序列 "100e"（可能是有效浮点数的最长前缀）将被消耗，导致匹配错误（消耗的序列无法转换为浮点数），剩余 "r"。一些现有实现不遵循此规则，并回滚到仅消耗 "100"，留下 "er"，例如 glibc bug 1765。

[edit] 返回值

1-3) 成功分配的接收参数数量，或者如果在第一个接收参数分配之前发生读取失败，则返回 EOF。
4-6) 与 (1-3) 相同，只是如果发生运行时约束违反，也返回 EOF。

[edit] 注释

所有这些函数至少调用一次 va_arg，在返回之后，arg 的值是不确定的。这些函数不调用 va_end，必须由调用者完成。

[edit] 示例

运行此代码
#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

[edit] 参考

  • C11 标准（ISO/IEC 9899:2011）
  • 7.21.6.9 vfscanf 函数（第 327 页）
  • 7.21.6.11 vscanf 函数（第 328 页）
  • 7.21.6.14 vsscanf 函数（第 330 页）
  • K.3.5.3.9 vfscanf_s 函数（第 597-598 页）
  • K.3.5.3.11 vscanf_s 函数（第 599 页）
  • K.3.5.3.14 vsscanf_s 函数（第 602 页）
  • C99 标准（ISO/IEC 9899:1999）
  • 7.19.6.9 vfscanf 函数（第 293 页）
  • 7.19.6.11 vscanf 函数（第 294 页）
  • 7.19.6.14 vsscanf 函数（第 295 页）

[edit] 另请参见

(C11)(C11)(C11)
 从 stdin、文件流或缓冲区中读取格式化的输入。
(函数) [edit]
(C99)(C11)(C11)(C11)(C11)
 将格式化的输出打印到 stdout、文件流或缓冲区。
使用可变参数列表。
(函数) [edit]
C++ 文档 针对 vscanf, vfscanf, vsscanf
Retrieved from "https://cppreference.cn/mwiki/index.php?title=c/io/vfscanf&oldid=125689"