命名空间
变体
操作

scanf、fscanf、sscanf、scanf_s、fscanf_s、sscanf_s

来自 cppreference.com
< c‎ | io
 
C
 
文件输入/输出
类型和对象
函数
文件访问
直接输入/输出
非格式化输入/输出
(C95)(C95)
(C95)
(C95)(C95)
(C95)
(C95)
(C95)
(C95)
格式化输入
scanffscanfsscanfscanf_sfscanf_ssscanf_s
(C11)(C11)(C11)
(C95)(C95)(C95)(C11)(C11)(C11)    
(C99)(C99)(C99)(C11)(C11)(C11)
(C99)(C99)(C99)(C11)(C11)(C11)     
 
定义在头文件 <stdio.h> 中
(1)
int scanf( const char          *format, ... );
 (直到 C99)
int scanf( const char *restrict format, ... );
 (自 C99 起)
(2)
int fscanf( FILE          *stream, const char          *format, ... );
 (直到 C99)
int fscanf( FILE *restrict stream, const char *restrict format, ... );
 (自 C99 起)
(3)
int sscanf( const char          *buffer, const char          *format, ... );
 (直到 C99)
int sscanf( const char *restrict buffer, const char *restrict format, ... );
 (自 C99 起)
int scanf_s(const char *restrict format, ...);
 (4) (自 C11 起)
int fscanf_s(FILE *restrict stream, const char *restrict format, ...);
 (5) (自 C11 起)
int sscanf_s(const char *restrict buffer, const char *restrict format, ...);
 (6) (自 C11 起)

从各种来源读取数据，根据 format 解释数据，并将结果存储到指定位置。

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) 参数
  • 可选地，任何其他可检测到的错误，例如未知转换说明符
与所有边界检查函数一样，scanf_s、fscanf_s 和 sscanf_s 只有在 __STDC_LIB_EXT1__ 由实现定义，并且用户在包含 <stdio.h> 之前将 __STDC_WANT_LIB_EXT1__ 定义为整数常量 1 时才保证可用。

内容

[编辑] 参数

stream - 要从中读取的输入文件流
buffer - 指向要从中读取的以 null 结尾的字符数组的指针
format - 指向指定如何读取输入的以 null 结尾的字符数组的指针
... - 接收参数。


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 和 %[ 不同，它不会将空字符追加到数组。

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

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

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

如果集合的第一个字符是^，则匹配集合中所有不包含的字符。如果集合以]或^]开头，则]字符也被包含在集合中。是否在扫描集中非初始位置的字符-可以表示一个范围（如[0-9]）是实现定义的。如果使用宽度说明符，则只匹配最多宽度个字符。始终存储一个空字符，除了匹配的字符（因此参数数组必须至少有宽度+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 错误 1765。

如果转换规范无效，则行为未定义。

[编辑] 返回值

1-3) 成功分配的接收参数数（在第一个接收参数被分配之前发生匹配失败的情况下，这可能是零），或者如果在第一个接收参数被分配之前发生输入失败，则为EOF。
4-6) 与(1-3) 相同，除了如果存在运行时约束违规，也会返回EOF。

[编辑] 复杂度

没有保证。值得注意的是，sscanf 的一些实现是O(N)，其中N = strlen(buffer) [1]。

[编辑] 注意

因为大多数转换说明符首先消耗所有连续的空白字符，所以像这样的代码

scanf("%d", &a);
scanf("%d", &b);

将读取两行上输入的两个整数（第二个 %d 将消耗第一个留下的换行符）或用空格或制表符分隔在同一行上（第二个 %d 将消耗空格或制表符）。

不消耗前导空格的转换说明符，例如 %c，可以通过在格式字符串中使用空格字符来使其消耗前导空格。
scanf("%d", &a);
scanf(" %c", &c); // consume all consecutive whitespace after %d, then read a char

[编辑] 示例

运行此代码
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
#include <stddef.h>
#include <locale.h>
 
int main(void)
{
    int i, j;
    float x, y;
    char str1[10], str2[4];
    wchar_t warr[2];
    setlocale(LC_ALL, "en_US.utf8");
 
    char input[] = "25 54.32E-1 Thompson 56789 0123 56ß水";
    /* parse as follows:
       %d: an integer
       %f: a floating-point value
       %9s: a string of at most 9 non-whitespace characters
       %2d: two-digit integer (digits 5 and 6)
       %f:  a floating-point value (digits 7, 8, 9)
       %*d: an integer which isn't stored anywhere
       ' ': all consecutive whitespace
       %3[0-9]: a string of at most 3 decimal digits (digits 5 and 6)
       %2lc: two wide characters, using multibyte to wide conversion  */
    int ret = sscanf(input, "%d%f%9s%2d%f%*d %3[0-9]%2lc",
                     &i, &x, str1, &j, &y, str2, warr);
 
    printf("Converted %d fields:\n"
           "i = %d\n"
           "x = %f\n"
           "str1 = %s\n"
           "j = %d\n"
           "y = %f\n"
           "str2 = %s\n"
           "warr[0] = U+%x\n"
           "warr[1] = U+%x\n",
           ret, i, x, str1, j, y, str2, warr[0], warr[1]);
 
#ifdef __STDC_LIB_EXT1__
    int n = sscanf_s(input, "%d%f%s", &i, &x, str1, (rsize_t)sizeof str1);
    // writes 25 to i, 5.432 to x, the 9 bytes "Thompson\0" to str1, and 3 to n.
#endif
}

可能的输出

Converted 7 fields:
i = 25
x = 5.432000
str1 = Thompson
j = 56
y = 789.000000
str2 = 56
warr[0] = U+df
warr[1] = U+6c34

[编辑] 参考资料

  • C17 标准 (ISO/IEC 9899:2018)
  • 7.21.6.2 fscanf 函数 (p: 231-236)
  • 7.21.6.4 scanf 函数 (p: 236-237)
  • 7.21.6.7 sscanf 函数 (p: 238-239)
  • K.3.5.3.2 fscanf_s 函数 (p: 430-431)
  • K.3.5.3.4 scanf_s 函数 (p: 432)
  • K.3.5.3.7 sscanf_s 函数 (p: 433)
  • C11 标准 (ISO/IEC 9899:2011)
  • 7.21.6.2 fscanf 函数 (p: 317-324)
  • 7.21.6.4 scanf 函数 (p: 325)
  • 7.21.6.7 sscanf 函数 (p: 326)
  • K.3.5.3.2 fscanf_s 函数 (p: 592-593)
  • K.3.5.3.4 scanf_s 函数 (p: 594)
  • K.3.5.3.7 sscanf_s 函数 (p: 596)
  • C99 标准 (ISO/IEC 9899:1999)
  • 7.19.6.2 fscanf 函数 (p: 282-289)
  • 7.19.6.4 scanf 函数 (p: 290)
  • 7.19.6.7 sscanf 函数 (p: 291)
  • C89/C90 标准 (ISO/IEC 9899:1990)
  • 4.9.6.2 fscanf 函数
  • 4.9.6.4 scanf 函数
  • 4.9.6.6 sscanf 函数

[编辑] 参见

(C99)(C99)(C99)(C11)(C11)(C11)
 从 stdin、文件流或缓冲区读取格式化的输入
使用可变参数列表
(函数) [编辑]
 从文件流获取字符串
(函数) [编辑]
(C99)(C11)(C11)(C11)(C11)
 将格式化的输出打印到 stdout、文件流或缓冲区
(函数) [编辑]
C++ 文档 适用于 scanf, fscanf, sscanf
取自 "https://cppreference.cn/mwiki/index.php?title=c/io/fscanf&oldid=140798"