Namespaces
Variants

scanf, fscanf, sscanf, scanf_s, fscanf_s, sscanf_s

From cppreference.net
< c ‎ | io
C
File input/output
Types and objects
Functions
File access
Unformatted input/output
Formatted input
scanf fscanf sscanf scanf_s fscanf_s sscanf_s
(C11) (C11) (C11)
(C95) (C95) (C95) (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) 从以空字符结尾的字符串 buffer 中读取数据。对于 fscanf 而言，到达字符串末尾等同于达到文件结束条件
4-6) 与 (1-3) 相同，不同之处在于： % c 、 % s 和 % [ 转换说明符各需要两个参数（通常的指针和类型为 rsize_t 的值，指示接收数组的大小，当使用 % c 读取到单个 char 时该值可为 1 ），并且以下错误会在运行时被检测到并调用当前安装的 约束处理函数 ：
  • 任何指针类型的参数是空指针
  • format 、 stream 或 buffer 是空指针
  • 由 % c 、 % s 或 % [ 写入的字符数加上终止空字符，将超过为这些转换说明符提供的第二个（ rsize_t ）参数
  • 可选地，任何其他可检测到的错误，例如未知的转换说明符
与所有边界检查函数一样，仅当实现定义了 __STDC_LIB_EXT1__ 且用户在包含 <stdio.h> 之前将 __STDC_WANT_LIB_EXT1__ 定义为整数常量 1 时，才保证 scanf_s 、 fscanf_s 和 sscanf_s 可用。

目录

参数

stream - 用于读取的输入文件流
buffer - 指向以空字符结尾的字符串的指针，用于读取数据
format - 指向以空字符结尾的字符串的指针，指定如何读取输入
... - 接收参数


format 字符串由以下部分组成

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

以下格式说明符可用：

<td class="table-na" style="background: #ececec; color: grey;
转换
说明符 		说明 期望的
参数类型
长度修饰符→ hh h 无 l ll j z t L
仅自 C99 起可用→ 是 是 是 是 是
%
匹配字面量 % 。
不适用 不适用 不适用 不适用 不适用 不适用 不适用 不适用 不适用
c

匹配一个 字符 或一系列 字符 。

  • 如果使用了宽度说明符，则精确匹配 宽度 个字符（参数必须是指向具有足够空间的数组的指针）。
  • 与 %s 和 %[ 不同，不会向数组追加空字符。
不适用 不适用
char *
wchar_t *
不适用 不适用 不适用 不适用 不适用
s

匹配一系列非空白字符（一个 字符串 ）。

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

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

  • 如果集合的第一个字符是 ^ ，则匹配所有不在集合中的字符。
  • 如果集合以 ] 或 ^] 开头，则 ] 字符也会包含在集合中。
  • 在扫描集中非初始位置的字符 - 是否表示范围（如 [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 *
不适用
i

匹配一个 整数 。

  • 数字的格式与 strtol 在 base 参数为 ​ 0 ​ 时所期望的格式相同（基数由解析的第一个字符确定）。
u

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

  • 数字的格式与 strtoul 在 base 参数为 10 时所期望的格式相同。
o

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

  • 数字的格式与 strtoul 在 base 参数为 8 时所期望的格式相同。
x
X

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

  • 数字的格式与 strtoul 在 base 参数为 16 时所期望的格式相同。
n

返回 迄今为止读取的字符数 。

  • 不消耗输入。不增加赋值计数。
  • 如果说明符定义了赋值抑制运算符，则行为未定义。
a (C99)
A (C99)
e
E
f
F (C99)
g
G

匹配一个 浮点数 。

  • 数字的格式与 strtof 所期望的格式相同。
不适用 不适用
float *
double *
不适用

如果转换说明符无效，则行为未定义。

返回值

1-3) 成功赋值的接收参数数量（若在首个接收参数被赋值前发生匹配失败，则该值可能为零），若在首个接收参数被赋值前发生输入失败，则返回 EOF 。
4-6) 与 (1-3) 相同，不同之处在于：如果发生运行时约束违规，也会返回 EOF 。

复杂度

不保证。特别要注意的是，某些 sscanf 的实现具有 O(N) 的时间复杂度，其中 N = strlen ( buffer ) [1] 。

注释

由于大多数转换说明符首先会消耗所有连续的空白字符，因此诸如 

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

将读取分别在不同行输入的两个整数（第二个 % d 会消耗第一个 % d 遗留的换行符），或在同一行以空格或制表符分隔输入的两个整数（第二个 % d 会消耗空格或制表符）。

The conversion specifiers that do not consume leading whitespace, such as % c , can be made to do so by using a whitespace character in the format string: 
scanf("%d", &a);
scanf(" %c", &c); // 消耗 %d 之后的所有连续空白字符，然后读取一个字符

示例

运行此代码 
#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ß水";
    /* 按以下方式解析：
       %d：一个整数
       %f：一个浮点数值
       %9s：最多9个非空白字符的字符串
       %2d：两位整数（数字5和6）
       %f：一个浮点数值（数字7、8、9）
       %*d：一个不存储在任何位置的整数
       ' '：所有连续空白
       %3[0-9]：最多3个十进制数字的字符串（数字5和6）
       %2lc：两个宽字符，使用多字节到宽字符转换 */
    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);
    // 将25写入i，5.432写入x，9字节"Thompson\0"写入str1，3写入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 函数 (页码: 231-236)
  • 7.21.6.4 scanf 函数 (页码: 236-237)
  • 7.21.6.7 sscanf 函数 (页码: 238-239)
  • K.3.5.3.2 fscanf_s 函数 (页码: 430-431)
  • K.3.5.3.4 scanf_s 函数 (页码: 432)
  • K.3.5.3.7 sscanf_s 函数 (页码: 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函数（页码：282-289）
  • 7.19.6.4 scanf函数（页码：290）
  • 7.19.6.7 sscanf函数（页码：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